git replay

Newer, library-friendly cousin of cherry-pick.

🎯 What & why

git replay is the newer, scriptable cousin of cherry-pick/rebase. It replays a range of commits onto a target and emits update-ref lines on stdout instead of touching refs itself -- you decide when (and whether) to commit.

🧠 Mental model

Think of it as a pure function: in goes (commits, newbase), out comes a transcript of ref updates. Pipe that transcript into git update-ref --stdin to apply, or inspect it first. No working tree, no detached HEAD dance.

🛠️ Synopsis

git replay (--onto <newbase> | --advance <branch>) <revision-range>...
git replay [--contained] --onto <newbase> <oldbase>..<branch>

Writes `update-ref` commands to stdout; safe to inspect before applying.

🎚️ Switches & options

Flag	What it does
`--onto <newbase>`	Rebase target -- where the replayed commits should land.
`--advance <branch>`	Cherry-pick style: append commits onto the tip of <branch>.
`--contained`	With `--onto`, also move every branch fully contained in the range.
`(positional) <range>`	Standard revision range, e.g. `main..topic`.
`(stdout) update-ref`	Output is one `update SP <ref> SP <new> SP <old> LF` per line.

💡 Use cases

Server-side or batch rewriting where you cannot afford a working-tree checkout.
Previewing a rebase: capture stdout, eyeball it, then apply (or not).
Moving a stack of dependent branches in one transaction with --contained.
Building higher-level tools (stacked PRs, queue managers) on top of plumbing.

🧪 Examples

Replay topic onto main, dry preview

git replay --onto main main..topic

Apply the replay atomically

git replay --onto main main..topic | git update-ref --stdin

Cherry-pick style append

git replay --advance release origin/main..feature

Move a whole stack of branches

git replay --contained --onto main old-base..tip

🎓 Recommendations

Always run git replay once without piping to inspect the proposed updates.
Pipe into git update-ref --stdin for atomic, transactional ref updates.
Reach for replay when you need scriptability; reach for rebase when you need interactivity.

🪤 Common pitfalls

Output applies nothing on its own -- forgetting the update-ref --stdin step is a no-op.
Conflicts during replay abort the operation; there is no in-tree resolve workflow.
--contained moves every contained branch -- audit the stdout before piping.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.