Cherry-Picking Branches into Master with Full Auditability

2023-07-03

The Problem

A plain git cherry-pick copies commits with new SHAs, breaking the link to the original branch. This makes it hard to trace where work came from and why it was included.

Recommended Approaches

1. Cherry-pick with `-x` (minimum auditability)

git cherry-pick -x <commit>

The -x flag appends (cherry picked from commit <sha>) to the commit message, creating a traceable reference back to the original.

2. Cherry-pick an entire branch with a merge commit (best auditability)

Instead of cherry-picking individual commits, create a merge commit that references the source branch:

git checkout master
git merge --no-ff feature-branch

--no-ff forces a merge commit even if fast-forward is possible. This preserves:

The full branch history
A single point showing when/why the branch was integrated
A clear parent link back to every commit on the branch

3. Cherry-pick a range, then record it

If you truly need to cherry-pick (not merge), cherry-pick the full range:

git cherry-pick -x first_commit^..last_commit

This picks every commit in order and annotates each one with -x.

4. Use `git merge --squash` + detailed message

git checkout master
git merge --squash feature-branch
git commit -m "Integrate feature-branch (squashed)

Source branch: feature-branch
Original commits: abc1234..def5678
PR: #42"

This collapses the branch into one commit but lets you write an explicit audit trail in the message. The branch itself still exists for reference.

Auditability Checklist

Technique	Preserves original SHAs	Links to source	Preserves full history	Single integration point
`merge --no-ff`	Yes	Yes (parent)	Yes	Yes
`cherry-pick -x`	No (new SHAs)	Yes (message)	Yes (per commit)	No
`merge --squash`	No (squashed)	Manual	No	Yes
Plain `cherry-pick`	No	No	Yes (per commit)	No

Best Practice: `merge --no-ff` + Branch Preservation

# 1. Merge with a no-ff merge commit
git checkout master
git merge --no-ff feature-branch -m "Merge feature-branch: add user auth

Reviewed in PR #42. All tests passing."

# 2. Keep the branch around (don't delete it immediately)
# Or tag it before deleting:
git tag archive/feature-branch feature-branch
git branch -d feature-branch

This gives you:

git log --merges — shows every integration event
git log --first-parent master — clean linear history of integrations
git log master..archive/feature-branch — see original branch work
git blame — traces back through the merge to original commits

When You Must Cherry-Pick

If merging isn't an option (e.g., you only want some commits from a branch):

# Always use -x to record the source
git cherry-pick -x abc1234 def5678

# Document what you did and why in a wrapper commit or PR description
# Consider tagging the source branch for future reference
git tag cherry-picked/feature-branch feature-branch