Skip to content
A CLI tool for automating the tedious process of backporting changes
TypeScript JavaScript Other
Branch: master
Clone or download
Latest commit 67475e7 Aug 13, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Show existing backports (#138) Jul 18, 2019
docker Update documentation Apr 22, 2019
docs Add `editor` option (#142) Aug 13, 2019
src Add `editor` option (#142) Aug 13, 2019
test Add `editor` option (#142) Aug 13, 2019
.eslintrc.js Show existing backports (#138) Jul 18, 2019
.gitignore Show existing backports (#138) Jul 18, 2019
.istanbul.yml Add support for project config “.backportrc.json” (#29) Dec 5, 2017
.prettierrc Initial commit Sep 28, 2017
.travis.yml Show existing backports (#138) Jul 18, 2019
CHANGELOG.md Create CHANGELOG.md Aug 28, 2018
CONTRIBUTING.md Add options to disable fork mode (#141) Aug 8, 2019
LICENSE.txt Add License and Travis config Oct 18, 2017
README.md Add `editor` option (#142) Aug 13, 2019
jest.config.js Show existing backports (#138) Jul 18, 2019
package.json
tsconfig.json Convert to Typescript (#79) Aug 28, 2018
yarn.lock

README.md

backport

Build Status NPM version dependencies Status Coverage Status

A simple CLI tool that automates the process of backporting commits

Demonstration gif

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 that will ask you which commit(s) to backport and to which branch(es) and then cherry-pick accordingly, and create pull requests. It will always perform the git operation in a temporary folder (~/.backport/repositories/) separate from your working directory, thus never interfering with any unstages changes your might have.

Requirements

  • Node 8 or higher
  • git

OR

  • Docker

Install with Node (recommended)

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.

Run via Docker

If you don't have Node.js or git installed locally, you can run backport via Docker.

Click to expand The easiest way is to add the following snippet to your bash profile:
backport() {
    BACKPORT_CONFIG_DIR=~/.backport
    GIT_CONFIG_FILE=~/.gitconfig

    docker run -it --rm -v $(pwd):/app:ro -v $BACKPORT_CONFIG_DIR:/root/.backport -v $GIT_CONFIG_FILE:/etc/gitconfig sqren/backport "$@"
}

Where:

  • BACKPORT_CONFIG_DIR: This can be ANY empty folder on your local machine. Upon running the docker container for the first time, a config.json will be created automatically. This must be filled out with username and accessToken or these must be passed as CLI arguments: backport --username <username> --accessToken <accessToken>
  • GIT_CONFIG_FILE: Must point to a local .gitconfig file that contains the user's name and email.

You can now use backport as if it was installed on the host machine.

Usage

Run the CLI in your project folder (must contain a .backportrc.json file):

> backport

or run this from anywhere:

> backport --upstream elastic/kibana

The above commands will start an interactive prompt. You can use the arrow keys to choose options, <space> to select checkboxes and <enter> to proceed.

CLI arguments

Option Description Default Type
--accesstoken Github access token string
--all Show commits from other than me false boolean
--api-hostname Hostname for the Github API api.github.com string
--author Filter commits by author Current user string
--branch Branch to backport to string
--commits-count Number of commits to choose from 10 number
--editor Editor (eg. code) to open and solve conflicts string
--fork Create backports in fork (true) or origin repo (false) true boolean
--git-hostname Hostname for Git remotes github.com string
--labels Pull request labels string
--multiple Select multiple commits/branches false boolean
--pr-description Pull request description suffix string
--pr-title Pull request title pattern [{baseBranch}] {commitMessages} string
--sha Sha of commit to backport string
--upstream Name of organization and repository string
--username Github username string
--help Show help
-v, --version Show version number

All of the CLI arguments can also be configured via the configuration options in the config files.

Contributing

See CONTRIBUTING.md

You can’t perform that action at this time.