Skip to content

A simple CLI tool that automates the process of backporting commits on a GitHub repo

License

Notifications You must be signed in to change notification settings

cauemarcondes/backport

 
 

Repository files navigation

backport

Build Status NPM version dependencies Status Coverage Status

A simple CLI tool that automates the process of backporting commits on a GitHub repo.

backport-demo

Requirements

  • Node 10 or higher
  • git

Install

npm install -g backport

After installation you should update the global config in ~/.backport/config.json with your Github username and a Github access token. See the documentation for how the access token is generated.

Quick start

Add a project config to the root of your repository:

// .backportrc.json
{
  "upstream": "elastic/kibana",
  "targetBranchChoices": [{ "name": "6.x", "checked": true }, "6.3", "6.2", "6.1", "6.0"],
}

Install locally:

npm install backport

Run:

npx backport

This will start an interactive prompt. You can use your keyboards arrow keys to choose options, <space> to select checkboxes and <enter> to proceed.

Config options

See configuration.md

CLI options

Option Description Default Type
--accesstoken Github access token string
--all Show commits from other than me false boolean
--author Filter commits by author Current user string
--branch Target branch to backport to string
--dry-run Perform backport without pushing to Github false boolean
--editor Editor (eg. code) to open and solve conflicts string
--fork Create backports in fork (true) or origin repo (false) true boolean
--labels Pull request labels string
--mainline Parent id of merge commit 1 number
--max-number Number of commits to choose from 10 number
--multiple Select multiple commits/branches false boolean
--path Only list commits touching files under a specific path string
--pr Pull request to backport number
--pr-filter List commits from PRs filtered by a given query string
--pr-description Pull request description suffix string
--pr-title Pull request title pattern string
--reset-author Set yourself as commit author boolean
--sha Sha of commit to backport string
--source-branch The branch to source commits from string
--upstream Name of organization and repository string
--username Github username string
--help Show help
-v, --version Show version number

The CLI options will override the configuration options.

What is backporting?

Backporting is the action of taking parts from a newer version of a software system [..] and porting them to an older version of the same software. It forms part of the maintenance step in a software development process, and it is commonly used for fixing security issues in older versions of the software and also for providing new features to older versions.

Source: https://en.wikipedia.org/wiki/Backporting

Who is this tool for?

This tools is for anybody who is working on a codebase where they have to maintain multiple versions. If you manually cherry-pick commits from master and apply them to one or more branches, this tool might save you a lot of time.

backport is a CLI tool that will let you backport commit(s) interactively and then cherry-pick and create pull requests automatically. backport will always perform the git operation in a temporary folder (~/.backport/repositories/) separate from your working directory, thereby never interfering with any unstages changes your might have.

Features:

  • interactively backport one or more commits to one or more branches with an intuitive UI
  • will never run git reset --hard or other git commands in your working directory - all git operations are handled in a separate directory
  • backport a commit by specifying a PR: backport --pr 1337
  • list and backport commits by a particular user: backport --author john
  • list and backport commits by a particular path: backport --path src/plugins/chatbot
  • list PRs filtered by a query: backport --pr-filter label:backport-v2 (will list commits from PRs with the label "backport-v2")
  • forward port commits: backport --sourceBranch 7.x --branch master (will forwardport from 7.x to master)
  • backport merge commits: backport --mainline
  • ability to see which commits have been backported and to which branches
  • customize the title, description and labels of the created backport PRs

Contributing

See CONTRIBUTING.md

About

A simple CLI tool that automates the process of backporting commits on a GitHub repo

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • TypeScript 98.4%
  • Other 1.6%