Introduction
During day-to-day development and maintenance, I noticed a recurring but easily underestimated pain point: once a release branch is fork from trunk, every hotfix over the next week or two must be cherry-picked back to the release branch. This sounds simple, but in practice it is tedious and prone to human error: missed picks, duplicate picks, or incorrect ordering can all leave the release branch in an inconsistent state.
Existing tools are usually tied to the APIs of specific platforms (GitHub, GitLab). This means your automation depends on platform-specific features, and moving to another platform requires rebuilding it.
This article documents how I built a pure Bash git release backport tool from scratch — pickle. It depends only on git: no platform dependencies, no configuration files, no state files, just a single script.
Understanding the problem
What challenges can release automation run into?
- Which commits should be selected? Not every commit on the trunk should be backported to the release branch—usually only hotfixes. But how do you determine whether a commit is a hotfix?
- How do you avoid duplicates? A scheduled job may run several times a day, and the same commit must not be picked twice. But cherry-picking produces a new SHA and a different commit message, so how do you identify that “this patch is already on the release branch”?
- How should conflicts be handled? As the two branches evolve independently, a patch may no longer apply cleanly.
- Does ordering matter? If fix
#4depends on fix#2, skipping#2and applying#4directly can produce a release that compiles but behaves incorrectly.
| Tool | Problem |
|---|---|
| GitHub backport bot | Works only on GitHub; requires a label to trigger it; creates a PR rather than pushing directly |
| release-please | Focuses on versioning and changelogs, not hotfix backports |
| Custom shell scripts | Each team writes its own, with inconsistent quality and no reuse |
Design decisions
Core philosophy: automate only git operations
pickle depends only on the git command, without using any platform APIs. This means:
- The same command works in GitHub Actions, GitLab CI, Jenkins, Drone, or on a local laptop
- Migrating to another CI platform requires no code changes
- No complicated authorization or platform-specific issues
- Deployment takes just one file:
curl ... -o /usr/local/bin/pickle && chmod +x
Configuration: command-line flags + environment variables
There is no configuration file; configuration already lives in the version-controlled CI YAML. Every flag has a corresponding environment variable with the PICKLE_ prefix, because setting environment variables in a CI matrix is easier than constructing command-line arguments.
Selection rules: Conventional Commits first
Selection is based on the widely used Conventional Commit types, with only fix selected by default. Developers need no additional discipline: the commit metadata is already in the subject line.
# Select only fix commits by defaultpickle sync --target release/1.2 --from main
# Customize the selectionpickle sync --target release/1.2 --types fix,perfpickle sync --target release/1.2 --include '^\[HOTFIX\]' --exclude 'WIP'
# Or fully customize it: use any git log command as the selection rulegit log --format=%H --grep=URGENT --author=oncall main \ | pickle pick --target release/1.2 -Conflict handling: stop and let a human fix
- Keep commits that have already been successfully applied and pushed
- Abort the conflicting cherry-pick
- Return a nonzero exit code so CI fails
- Print ready-to-copy commands for resolving the conflict
Actual CI output
Below is the complete output from a real pickle sync run that encountered a conflict. There were three commits on the trunk
, and the middle one conflicted with changes on the release branch:
pickle main → release/1.2
6903689c fix(A): clean one → picked 6d52e8c8 fix(B): conflicting → CONFLICT — needs a human fc323f83 fix(C): clean two → not attempted (run stopped above)
1 picked, 0 skipped, 1 conflicted, 1 not attempted pushed release/1.2 to origin
✗ conflict picking 6d52e8c8 fix(B): conflicting c.txt
the branch was left clean; nothing half-applied was pushed.
resolve it locally: git fetch origin git switch release/1.2 git cherry-pick -x 6d52e8c8 # fix the conflict, then: git add -A && git cherry-pick --continue git push origin release/1.2
keep the -x flag: it records where the commit came from, which is how the next run knows not to try again.fix(A)had no conflict and was still pushed to the release branchfix(C)is marked “not attempted”, indicating that an earlier issue must be resolved first- The conflicting filenames are listed directly
- The exit code is 1, so the failed CI run signals that human intervention is needed
Resolution workflow
Here is what happens when a person copies and pastes the commands:
# 1. Switch to the release branch and cherry-pick the conflicting commitgit switch release/1.2git cherry-pick -x 6d52e8c8# → CONFLICT (content): Merge conflict in c.txt
# 2. Resolve the conflict manually (edit c.txt and choose which content to keep)vim c.txt
# 3. Mark it as resolved and continuegit add -A && git cherry-pick --continue# → Done; the -x trailer is automatically preserved in the message
# 4. Pushgit push origin release/1.2After pushing, the commit message will end with this line:
fix(B): conflicting
(cherry picked from commit 6d52e8c8)The next time pickle sync runs, the second deduplication layer recognizes that this commit is already on the release branch and skips it:
$ pickle sync --target release/1.2 --from main
fc323f83 fix(C): clean two → picked 6d52e8c8 fix(B): conflicting → skip (backported by hand, -x trailer)
1 picked, 1 skipped pushed release/1.2 to originThere are no rules to memorize—the commands you need are printed right when the conflict occurs, and the -x trailer ensures that the resolved commit will not be picked again.
Conflict handling: how to avoid duplicate picks
This is the most critical part of the tool, because sync may run hundreds of times against the same branch. pickle uses three deduplication layers:
Layer 1: patch-id
git patch-id calculates an identifier from a commit’s diff, normalizing whitespace and line numbers. As a result, even if cherry-picking produces a new commit SHA, or the commit message, author, or date changes, identical changes will generally still produce the same patch-id.
pickle builds its own patch-id set to determine which changes already exist on the target branch, rather than using git cherry directly. This is because it needs to handle merge commits in addition to comparing ordinary commits: it uses the first parent as the baseline to extract the changes corresponding to git cherry-pick -m 1. Computing the IDs itself also gives pickle explicit control over commit traversal order.
First, collect the patch-ids on the target branch since the common ancestor:
base=$(git merge-base "$FROM" "$TARGET")
git log -p --no-merges --no-renames --format='commit %H' "$base..$TARGET" \ | git patch-id --stableNext, calculate the patch-id for an individual candidate commit:
git diff-tree -p -m --first-parent --no-commit-id --no-renames --root "$sha" \ | git patch-id --stableWith the target branch’s patch-id set in hand, pickle checks candidate commits in topological order, from oldest to newest:
git rev-list --reverse --topo-order --no-merges "$TARGET..$FROM"Each candidate commit is compared against the set. If its patch-id already exists, the same change is already on the target branch and can be skipped; otherwise, it proceeds to the remaining checks.
Layer 2: the -x trailer
The one case patch-id misses is when someone has resolved a conflict, causing the applied diff to differ from the original.
git cherry-pick -x records (cherry picked from commit ...) in the message. pickle scans the release branch for this trailer to identify those commits:
base=$(git merge-base "$FROM" "$TARGET")git log --format=%B "$base..$TARGET" \ | sed -n 's/^[[:space:]]*(cherry picked from commit \([0-9a-f]\{7,40\}\)).*/\1/p'Layer 3: pickle skip
If a hotfix is deliberately excluded from the release (for example, because it depends on a feature absent from that release), neither of the signals above will apply. pickle skip writes an empty commit with a trailer:
pickle skip --target release/1.2 abc1234 --reason "depends on a feature not in 1.2"This leaves an auditable record in the history documenting that “a human made this decision intentionally.”
Agent Skill
pickle can be used through skills/pickle/. This skill teaches an agent:
- What the commands and exit codes mean
- The habit of using
--dry-runfirst - How to resolve conflicts without losing the
-xtrailer
npx skills add riceball-tw/pickle # Any agent: Claude Code, Cursor…cp -r skills/pickle ~/.claude/skills/ # Or copy it directlyIt can also be installed as a Claude Code plugin: /plugin marketplace add riceball-tw/pickle.
Further reading
- pickle — GitHub
- git patch-id and git cherry-pick documentation
- Conventional Commits