Building an automated release branch sync tool with Bash

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?

  1. 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?
  2. 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”?
  3. How should conflicts be handled? As the two branches evolve independently, a patch may no longer apply cleanly.
  4. Does ordering matter? If fix #4 depends on fix #2, skipping #2 and applying #4 directly can produce a release that compiles but behaves incorrectly.
ToolProblem
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 scriptsEach 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.

Terminal window
# Select only fix commits by default
pickle sync --target release/1.2 --from main
# Customize the selection
pickle sync --target release/1.2 --types fix,perf
pickle sync --target release/1.2 --include '^\[HOTFIX\]' --exclude 'WIP'
# Or fully customize it: use any git log command as the selection rule
git 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:

Terminal window
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 branch
  • fix(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:

Terminal window
# 1. Switch to the release branch and cherry-pick the conflicting commit
git switch release/1.2
git 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 continue
git add -A && git cherry-pick --continue
# → Done; the -x trailer is automatically preserved in the message
# 4. Push
git push origin release/1.2

After 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:

Terminal window
$ 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 origin

There 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:

Terminal window
base=$(git merge-base "$FROM" "$TARGET")
git log -p --no-merges --no-renames --format='commit %H' "$base..$TARGET" \
| git patch-id --stable

Next, calculate the patch-id for an individual candidate commit:

Terminal window
git diff-tree -p -m --first-parent --no-commit-id --no-renames --root "$sha" \
| git patch-id --stable

With the target branch’s patch-id set in hand, pickle checks candidate commits in topological order, from oldest to newest:

Terminal window
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:

Terminal window
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:

Terminal window
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-run first
  • How to resolve conflicts without losing the -x trailer
Terminal window
npx skills add riceball-tw/pickle # Any agent: Claude Code, Cursor…
cp -r skills/pickle ~/.claude/skills/ # Or copy it directly

It can also be installed as a Claude Code plugin: /plugin marketplace add riceball-tw/pickle.

Further reading