A CLI tool that automates the process of backporting commits
Usage no npm install needed!
<script type="module">
import backport from 'https://cdn.skypack.dev/backport';
</script>
README
A CLI tool that automates the process of backporting commits.
How it works
Select a commit to backport
Select a branch to backport to
The commit will be cherrypicked, pushed and a pull request created.
Requirements
Node 16 or higher
git
Install
npm install -g backport
After installation you should add an access token to the global config in ~/.backport/config.json. See the documentation for how the access token is generated.
// .backportrc.json
{
"repoOwner": "elastic",
"repoName": "kibana",
// the branches available to backport to
"targetBranchChoices": ["main", "6.3", "6.2", "6.1", "6.0"],
// Optional: Automatically detect which branches a pull request should be backported to based on the pull request labels.
// In this case, adding the label "backport-to-production" will backport the PR to the "production" branch
"branchLabelMapping": {
"^backport-to-(.+)
backport can be imported as a Node module and interacted with programatically. This can be useful when creating automation around the Backport tool. See for example the Backport Github Action
backportRun
Backport a commit programatically. Commits can be selected via pullNumber or sha.
Arguments:
All of the options listed on configuration.md are valid. The most common options are:
accessTokenstring(Required)
Github access token to authenticate the request
repoNamestring(Required)
Name of repository
repoOwnerstring(Required)
Owner of repository (organisation or username)
pullNumbernumber
Filter commits by pull request number
shastring
Filter commits by commit sha
ciboolean
Enabling this will disable the interactive prompts
A Github Action around The Backport Tool for automatically creating backports when pull requests are merged.
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.
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 perform all git operations 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
ability to see which commits have been backported and to which branches
ability to customize the title, description and labels of the created backport PRs
all git operations are handled in a separate directory to not interfere with unstaged files
Conflicts are handled gracefully, and hints are provided to help the user understand the source of the conflict
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 --source-branch 7.x --branch master (will forwardport from 7.x to master)