Description
Replays commits from another branch (or arbitrary revisions) onto the current branch, like git cherry-pick. Each new commit keeps the original author and message (unless you pass --message / --message-file for a single commit), gets a fresh change-id, and records a normal reflog entry. Textual merges use the histogram diff algorithm, matching Git merge-ort (same as grit merge).
Positional arguments are applied oldest first. Each argument is either:
- a single commit (
feature,abc1234,HEAD~2), or - a two-dot range
A..B(commits reachable fromBbut not fromA, same asgit log A..B).
grit pick stops — leaving Git-compatible sequencer state — when:
- a step has merge conflicts (conflict markers in the worktree,
CHERRY_PICK_HEAD,MERGE_MSG,.git/sequencer/) - a step would be empty and
--empty stop(default) - the worktree is dirty, or the branch has no commits (detached
HEADis allowed, likegit cherry-pick) - a commit is a merge without
--mainline(not yet exposed on the CLI)
Resolve conflicts, then either run grit commit (auto-stages the worktree and finishes the step, keeping the picked author) or stage with grit add and run grit pick --continue. Use grit pick --skip to drop the current step, or grit pick --abort to cancel. If the branch tip moved because you already committed the resolution, --abort clears replay state without moving the branch (Git warns and exits 0 in the same situation).
Pick either completes a step, stops for conflicts or an empty commit, or changes nothing. Pressing Ctrl+C, or sending SIGTERM or SIGHUP on Unix, while files are being checked out stops the pick with error: operation cancelled; HEAD, the index and the work tree are left as they were before the pick started (no CHERRY_PICK_HEAD), no .git/index.lock is left behind, and the same pick can simply be run again. This works the same in a Windows console, where Ctrl+Break counts as Ctrl+C. A second interrupt terminates grit at once, without that cleanup; only SIGKILL skips rollback.
Options
| Option | Description |
|---|---|
<commit>… |
Commits or ranges to replay (oldest first). |
--continue |
Finish the paused pick after conflicts are resolved and staged. |
--abort |
Cancel the in-progress pick and restore the branch tip and worktree (conflict-only files from the other side are removed). Uses sequencer/head when grit wrote a sequencer directory; otherwise resets the index and worktree to the current tip (including after a conflicting git cherry-pick). A stale ORIG_HEAD from an earlier operation is ignored. |
--skip |
Skip the current todo step and continue with the rest; the worktree is reset to the saved tip, including removing conflict-only paths. |
-x, --record-origin |
Append (cherry picked from commit …) to each new message. |
--no-commit |
Apply the patch to the index and worktree without committing. |
--empty |
When a step would not change the tree: stop (default), keep (empty commit), or drop. |
-m, --message |
Replace the message (only with exactly one commit). |
-F, --message-file |
Read the message from a file, or - for stdin (only with exactly one commit). |
--mainline |
Parent number when replaying a merge commit (library support; CLI wiring pending). |
--check |
Predict whether the pick would succeed without changing refs, the index, or the worktree. Exit 0 when every step would apply cleanly; exit 1 when a step would conflict or stop as empty (with --empty stop), including rename/delete conflicts at the new path (same as grit merge). Conflicts with --continue, --abort, --skip, and --dry-run. |
--dry-run |
Print the commits that would be replayed without changing refs or the worktree. Conflicts with --check. |
-X ours|theirs |
Auto-resolve replay conflicts: keep the current branch side (ours) or the picked change (theirs). |
--conflict merge|diff3|zdiff3 |
Conflict marker style when a step stops with conflicts (default from merge.conflictStyle). |
JSON output
Schema: v2
Pass --json for stable, scripting-friendly output:
| Field | Type | Meaning |
|---|---|---|
result |
string | picked, clean, conflicts, empty, aborted, or skipped. |
oid |
string or null | Predicted final tree oid when result is clean (--check only). |
check |
boolean | True when --check was used (nothing was picked). |
commits |
array | Each picked or attempted step: source, oid, change_id, subject. |
dropped |
array | Source commit oids skipped as empty (--empty drop). |
conflicts |
array or null | Conflicted paths when result is conflicts, each {path, kind} with a conflict kind. |
rerere |
array | Rerere events when rerere.enabled is active and the pick stops on conflicts (path, kind as for grit merge). Omitted when empty. |
next_steps |
array or null | Suggested commands when stopped (conflicts or empty). |
alternatives |
array or null | grit pick --abort / --skip when a sequence is paused. |
dry_run |
boolean or null | true when --dry-run was set (no refs or objects were updated). |
On conflicts, exit code is 1 with result: "conflicts" and the same conflict shape as grit merge.
Markdown output
Schema: v2
Pass --markdown for a Pick heading, one bullet per replayed commit, and conflict next steps when stopped.
Exit status
| Code | Meaning |
|---|---|
0 |
Pick completed or --check predicts a clean replay. |
1 |
Conflicts, empty commit, or other failure. |
2 |
Invalid flags (usage). |
See Exit codes.