Description
In a snapshot checkout, your commits sit on a snapshot commit that holds only the checkout's paths. grit checkin sends branches back to the server it came from, which grafts them onto its real history: it replays each commit's changes onto the full tree of the real commit the snapshot stands for, keeping the commit's author, date and message. On the server, the branch is then an ordinary branch whose parent is the real commit, with the whole tree — files outside your checkout's paths stay as the target branch has them.
With no branches named, every local branch with commits on top of the snapshot is checked in; when there is none, grit checkin says there is nothing to check in and succeeds. The branch's commits are first pushed to refs/checkouts/<id>/out/heads/<branch> on the server the checkout was made from (a large push uses the resumable upload), then grafted. That push always goes to the URL the checkout was made from, even if origin now points elsewhere. A plain git push or grit push in a checkout pushes to the same place, so it never puts raw snapshot commits on the server's real branches; run grit checkin to graft what you pushed. Grafts are deterministic: checking the same commits in again changes nothing.
A grafted commit has a new tree and new parents, so a signature (gpgsig) or merged tag (mergetag) it carried no longer holds and is dropped; every other header is kept. A merge commit, such as the one grit pull --no-rebase makes, is grafted onto a three-way merge of its parents' grafts: what the target changed outside your paths since your older snapshot is kept, and inside your paths the merge's own result wins. A file that replaces a directory (or the other way round) checks in like any other change.
The resumable push during check-in can be interrupted with Ctrl+C (or SIGTERM / SIGHUP on Unix); grit exits with error: operation cancelled and code 130 without leaving the server in a half-applied graft state from this command.
Check-ins need write access to the repository.
Change ids
Commits made with grit commit carry a change-id header, and grit rebase keeps it, so the server can tell a rebased copy of one of its commits from new work. Commits made with plain git (by an editor, an agent or a script) have none, so before anything is pushed, grit checkin gives every commit on the branches it checks in, above the snapshot, that lacks one the id derived from its own commit id: the id grit log already shows for it. The branch is rewritten with it (commits on top move to the new parents and keep their ids), and the output says so (· gave 1 commit made with git a change id). Only the header is added (a signature, which no longer holds, is dropped), so trees, the index and the worktree stay as they are. Nothing is rewritten under the snapshot, in remote-tracking refs, in commits that were already integrated, or when grit.changeIds is false, and nothing at all while a rebase, merge, cherry-pick or revert (one paused between its commits too) is in progress in any of the checkout's worktrees; the check-in then sends the commits as they are. The server gives a commit that reaches it without an id the same derived id when it grafts it. Plain git rebase drops the header, so when you share a branch, rebase it with grit rebase, or bring it up to date with grit pull <branch>.
Refused branches
A branch is refused when:
- it is the target branch, in any case (
Maintoo): the branch the checkout was made from, or the branch the server'sHEADnames now. Onlygrit integrateandgrit slicechange the target (the server refuses plain pushes to it too); check your work in on another branch. - a commit changes a path outside your checkout's paths that the target holds differently. A refresh never brings such a path into your checkout, so make that change from a checkout whose paths include it. The same goes for a directory replaced by a file when the target has files there your checkout can't see.
- a merge commit's parents conflict outside your paths, where your checkout can't resolve them.
- the server's branch has commits yours doesn't. Rebase onto the server's branch with
grit pull <branch>and check in again, or pass--forceto replace it. - its name differs only in case from a branch the server has, on a server whose file system can't tell them apart.
- a commit builds on none of your checkout's snapshots, such as one made on the server's own history fetched with plain Git (
not_on_snapshot). Take a branch of the server's withgrit pull <branch>and build on that, or put your commits on the snapshot:grit switch -c <new branch> origin/<target>, thengrit pick <commits>.
When a branch moves
A branch the server already has moves when one of these holds, checked in this order, and the output names the rule (rule in --json):
- fast-forward (
fast_forward): your branch has the server's branch in its history; - this checkout set it last (
own_last_set), so you are replacing your own work after an amend or rebase; - it keeps every commit the server's branch had (
keeps_every_commit), matched by change id: every commit of the server's branch that the target doesn't have is in yours, as a copy with the same id, perhaps rebased and with more on top. Say a teammate rebased the shared branch onto a newermainwithgrit rebaseand force-pushed it, and you then add a commit to your copy: your check-in has every commit theirs had, so it goes through without--force. A copy only counts when it also has what the server's commit changed outside your checkout's paths, which you can't see: if the teammate amended the commit to changedocs/as well and your checkout is ofsrc, your copy would putdocs/back, so the branch is refused as diverged instead; --force(forced), when none of the others holds.
Sharing a branch
Checkouts of different paths can work on one branch. The server keeps a graft log of which real commit each checkout commit stands for: every check-in adds the commits it grafts, and so does grit pull <branch>, which shows you the server's branch cut down to your paths. A commit you build on one of those grafts onto the real commit it stands for, so files outside your paths keep the other checkout's changes. Say Alice has builtin/ and Documentation/, and Bob has Documentation/ and t/:
- Alice commits to
builtin/andDocumentation/onblame-docsand runsgrit checkin blame-docs. - Bob runs
grit pull blame-docs. He sees herDocumentation/change; herbuiltin/change is on the server but not in his files. - Bob commits to
Documentation/andt/on top and runsgrit checkin blame-docs: a fast-forward, his commit on top of her real one, sobuiltin/keeps her change. - Alice runs
grit pull blame-docsand gets hisDocumentation/change on top of her own commit, which comes back as it is. Hist/change stays out of her files.
When someone else checks in to a branch you have too, your next check-in of it is refused as diverged; grit pull <branch> rebases your commits onto theirs, and the check-in after that is a fast-forward. A branch you pulled and haven't added to is left as it is (unchanged) when the server's has moved on since, so a plain grit checkin of your other work still succeeds (· theirs has nothing new: the server's is ahead, at e32980a); only --force would take the server's back to yours. The log also means checking a branch in again replays only its new commits. A check-in whose grafts the server can't record (say its disk is full) still sets the branch; the server logs the failure, and later grafts of those commits walk the history again.
When several checkouts check in the same branch at once, they take turns: the first sets it, and the others are refused because the server's branch now has commits they don't. On a server whose repository keeps reflogs (Git's default when it has a worktree), every branch a check-in sets gets a checkin: from checkout <id> reflog entry.
Options
| Option | Description |
|---|---|
<branch>... |
Branches to check in. Defaults to every branch with commits on top of the snapshot. |
-f, --force |
Replace a server branch even where that drops commits it has. |
JSON output
Schema: v1
| Field | Type | Meaning |
|---|---|---|
url |
string | The server repository, with any user:password@ removed. |
gave_change_ids |
integer | Commits made with plain git that were given a change id before the check-in (their branches were rewritten); 0 when none needed one. |
branches |
array | One entry per branch (empty when there was nothing to check in): name, status (created, updated, unchanged or refused; unchanged when the server's branch was at the graft already or ahead of it), grafted (the server commit the branch became), previous (where the server's branch was), commits (commits replayed), rule for an updated branch, and for a refused branch message (why, in words) and reason. |
branches[].rule |
string or omitted | What let an updated branch move: fast_forward, own_last_set (this checkout set it last), keeps_every_commit (a rebase that keeps every commit the server's branch had, by change id) or forced. |
branches[].reason |
string | The kind of refusal: target_branch, conflict (a path the target holds differently), merge_conflict, diverged (the server's branch has commits yours doesn't), case_conflict, not_on_snapshot, not_pushed, invalid_name or invalid_tip. |
refused |
boolean | Whether any branch was refused; the exit status is then 1. |
Markdown output
Pass --markdown for agent-friendly output.
Schema: v1
Exit status
| Code | Meaning |
|---|---|
0 |
Every branch was checked in (or was already there), or there was nothing to check in. |
1 |
A branch was refused, or this is not a snapshot checkout. |