{"id":16949,"library":"backport","title":"Automated Git Backport CLI Tool","description":"Backport is an interactive CLI tool designed to streamline the process of backporting Git commits across multiple release branches. It automates the selection of commits and target branches, handles cherry-picking, pushes changes, and creates pull requests (PRs) on platforms like GitHub. The tool operates in a temporary directory, ensuring it never interferes with a user's local working copy or unstaged changes. Currently at stable version 11.0.2, it sees regular patch and minor releases, maintaining an active development pace. Its key differentiators include an intuitive interactive interface, non-intrusive operation, and a comprehensive workflow from commit selection to PR creation. A GitHub Action wrapping the CLI is also available for CI/CD integration.","status":"active","version":"11.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/sorenlouv/backport","tags":["javascript","backport","backporting","versioning","cherry-pick","git","git-cherry-pick","cli","automation","typescript"],"install":[{"cmd":"npm install backport","lang":"bash","label":"npm"},{"cmd":"yarn add backport","lang":"bash","label":"yarn"},{"cmd":"pnpm add backport","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary programmatic entry point. The package is primarily a CLI tool but exposes a module API. This is ESM-only; CommonJS `require` will not work.","wrong":"const { backportRun } = require('backport')","symbol":"backportRun","correct":"import { backportRun } from 'backport'"},{"note":"TypeScript type for configuring the programmatic `backportRun` function. Use `import type` for type-only imports.","wrong":"import { BackportOptions } from 'backport'","symbol":"BackportOptions","correct":"import type { BackportOptions } from 'backport'"},{"note":"Internal CLI execution function. While available, direct programmatic use of `backportRun` is generally preferred for the module API.","wrong":"import { run } from 'backport'","symbol":"run","correct":"import { run } from 'backport/cli'"}],"quickstart":{"code":"{\n  // .backportrc.json in repository root\n  \"repoOwner\": \"your-org\",\n  \"repoName\": \"your-repo\",\n  \"targetBranchChoices\": [\"main\", \"release/1.0\", \"release/2.0\"],\n  \"autoMerge\": true,\n  \"autoMergeMethod\": \"squash\",\n  \"branchLabelMapping\": {\n    \"^auto-backport-to-(.+)$\": \"$1\"\n  }\n}\n\n// ~/.backport/config.json (global config)\n{\n  \"accessToken\": \"ghp_YOUR_VERY_SECRET_GITHUB_TOKEN\"\n}\n\n// Terminal\nnpm install -g backport\nnpx backport\n","lang":"typescript","description":"Demonstrates global installation, project-specific configuration with .backportrc.json, global access token setup, and interactive CLI execution."},"warnings":[{"fix":"Ensure your Node.js environment is at least v20.0.0. Use a Node Version Manager (like nvm) to switch versions if needed.","message":"Version 10.0.0 introduced a breaking change by upgrading the minimum required Node.js version to 20.","severity":"breaking","affected_versions":">=10.0.0 <10.0.2"},{"fix":"Upgrade your Node.js environment to version 22.0.0 or higher. The package.json `engines` field specifies this requirement.","message":"Versions 10.0.2 and later (including all 11.x releases) bumped the minimum required Node.js version to 22.0.0. Older Node versions will cause execution errors.","severity":"breaking","affected_versions":">=10.0.2"},{"fix":"Generate a GitHub Personal Access Token with appropriate `repo` and `workflow` scopes and add it to `~/.backport/config.json` as `\"accessToken\": \"ghp_YOUR_TOKEN\"`.","message":"The `backport` CLI tool requires a GitHub Personal Access Token (`accessToken`) configured in `~/.backport/config.json`. Without it, operations that interact with GitHub APIs (like creating PRs) will fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be aware that `backport` doesn't modify your local working directory. Monitor GitHub for the created pull requests and merge them as appropriate.","message":"The `backport` tool performs all Git operations in a temporary directory (`~/.backport/repositories/`) to avoid interfering with your local working copy. Changes made by `backport` will not be visible in your local repository until the created PRs are merged and you pull them.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Add a valid `accessToken` to `~/.backport/config.json` with necessary scopes (repo, workflow).","cause":"GitHub Personal Access Token is not configured or is invalid.","error":"Error: Missing access token. Please add a personal access token to ~/.backport/config.json"},{"fix":"Run `npm install -g backport` to install globally, or execute with `npx backport` if installed locally.","cause":"The `backport` package is not installed globally or `npx` is not being used to execute it.","error":"Error: The 'backport' command could not be found. Make sure it's installed globally or run with npx."},{"fix":"Upgrade your Node.js environment to version 22.0.0 or newer. Use a Node Version Manager like `nvm install 22 && nvm use 22`.","cause":"An incompatible Node.js version is being used.","error":"Error: Node.js v18.x is not supported. Please upgrade to Node.js >=22.0.0."}],"ecosystem":"npm","meta_description":null}