diff --git a/plugins/git/commands/backport.md b/plugins/git/commands/backport.md new file mode 100644 index 0000000..69ca4e6 --- /dev/null +++ b/plugins/git/commands/backport.md @@ -0,0 +1,115 @@ +--- +description: Backport commits to multiple branches +argument-hint: [branch2...] [--new-branch] +--- + +## Name +git:backport + +## Synopsis +``` +/git:backport [branch2...] [--new-branch|-b] +``` + +## Description +The `git:backport` command helps backport a commit to multiple branches. It automates the process of cherry-picking a commit to one or more target branches, with optional support for creating new branches for each backport (useful for creating pull requests). + +This command provides: +- Automated commit backporting to one or multiple branches +- Validation of commit and branch existence +- Safe state management (saves and restores current branch) +- Conflict detection and user-guided resolution +- Optional new branch creation for PR workflows +- Support for branches with or without remote tracking + +## Implementation +The command executes the following workflow: + +1. **Validates inputs:** + - Checks that at least 2 arguments are provided (commit + at least one branch) + - Parses the `--new-branch` or `-b` flag if present + - Verifies the commit exists using `git cat-file -t ` + - Shows commit details: `git log -1 --oneline ` + - Filters out flag arguments and verifies all remaining target branches exist + +2. **ASK FOR USER PERMISSION:** + - **IMPORTANT: After validating inputs, you MUST present the complete backport plan to the user and ask for explicit permission to proceed** + - Show what will happen: which branches will be checked out, which new branches will be created, and that commits will be made + - Wait for user confirmation before proceeding with any git operations + - Example: "I'm going to checkout release/v1.35, pull latest changes, create branch backport-abc1234-to-release/v1.35, cherry-pick the commit, then repeat for release/v1.34. This will create new branches and commits. Should I proceed?" + +3. **Saves current state (only after user permission):** + - Records the current branch: `git branch --show-current` + - Checks for uncommitted changes: `git status --porcelain` + - If there are uncommitted changes, warns the user and stops + +4. **For each target branch (only after user permission):** + - Shows which target branch is being worked on + - Checks out the target branch: `git checkout ` + - Checks if the branch tracks a remote branch: `git rev-parse --abbrev-ref @{upstream}` + - **If the branch tracks a remote branch:** + - Pulls latest changes to ensure it's up to date: `git pull` + - **If the branch doesn't track a remote branch:** + - Skips pulling and informs the user the branch is local-only + - **If `--new-branch` flag is set:** + - Creates a new branch for the backport: `git checkout -b backport--to-` + - Uses the short commit hash (first 7 chars) in the branch name + - Example: `backport-abc1234-to-release-1.0` + - Attempts to cherry-pick: `git cherry-pick ` + - **If conflicts occur:** + - Shows the conflicting files: `git status` + - Shows the conflicts: `git diff` + - **STOPS and asks the user to resolve conflicts** + - Tells them to run `git cherry-pick --continue` when done, or `git cherry-pick --abort` to skip + - Asks if they want to continue to the next branch or abort the entire operation + - **If successful:** + - Shows success message with the new commit hash + - If a new branch was created, shows the branch name + - Continues to next branch + +5. **Restores original state:** + - Returns to the original branch: `git checkout ` + - Shows final summary of all backports: + - Lists successful backports with their branch names (if `--new-branch` was used) + - Lists failed backports + - If `--new-branch` was used, reminds user they can now create PRs from the new branches + +The command is interactive and waits for user input when conflicts occur and **REQUIRES USER PERMISSION before executing any git operations**. It tracks success/failure for each branch and provides a comprehensive summary at the end. + +## Return Value +- **Claude agent text**: + - Success summary showing which branches were successfully backported + - List of any failed backports + - New branch names (if `--new-branch` flag was used) + - Instructions for next steps (e.g., creating PRs from new branches) + +## Examples + +1. **Basic backport to a single branch**: + ``` + /git:backport abc1234 release-1.0 + ``` + Cherry-picks commit `abc1234` directly to the `release-1.0` branch. + +2. **Backport to multiple branches**: + ``` + /git:backport abc1234 release-1.0 release-1.1 release-1.2 + ``` + Cherry-picks commit `abc1234` to three different release branches. + +3. **Backport with new branch creation (for PRs)**: + ``` + /git:backport abc1234 release-1.0 release-1.1 --new-branch + ``` + Creates new branches `backport-abc1234-to-release-1.0` and `backport-abc1234-to-release-1.1`, each containing the cherry-picked commit. These branches can then be used to create pull requests. + +4. **Using short flag syntax**: + ``` + /git:backport abc1234 main -b + ``` + Same as `--new-branch`, creates a new branch `backport-abc1234-to-main`. + +## Arguments +- $1: Commit hash or reference to backport (required) +- $2+: Target branch names to backport to (space-separated, at least one required) +- `--new-branch` or `-b`: Create a new branch from each target branch before cherry-picking (optional flag)