Description
grit checkout makes a working repository from a server's newest commit without downloading its history. It asks the server for a snapshot: the target branch's tree (the branch the server's HEAD names), cut down to the paths you give, in a single commit. It downloads that snapshot and builds a normal Git repository around it: git and grit work in it as usual.
- With no
--path, the snapshot is the whole tree. - With
--path <dir>(repeatable), it is everything under each path, plus the files directly in every directory above one, the top level included — the same files Git's cone-mode sparse checkout would have. - With a
<slice>name, it is that slice's paths (plus any--path), and the directory defaults to the slice's name.
Download and materialization honor Ctrl+C (and SIGTERM / SIGHUP on Unix) with error: operation cancelled and exit code 130; a checkout directory grit created for this run is removed when materialization fails or is cancelled.
The new repository's history is one commit, Snapshot of <commit>: <subject>, which stands for the real commit on the server. It is at origin/<branch> (which origin/HEAD names), and you are on a new work branch on top of it, named for your user.email and two random words (like alice/amber-brook). The server picks the final name: it numbers it (alice/amber-brook-2) when it already has that branch or has given the name to another checkout, and never gives a name out twice, even across restarts. There is no local copy of the target branch.
origin is the repository URL, set up so that plain git and grit commands stay with the checkout's snapshots:
[remote "origin"]
url = http://127.0.0.1:8080/demo.git
fetch = +refs/checkouts/<id>/target:refs/remotes/origin/main
push = +refs/heads/*:refs/checkouts/<id>/out/heads/*
tagOpt = --no-tags
A plain git fetch or grit fetch brings only the checkout's own snapshots into origin/main, never the real history, other branches or tags. A plain git push or grit push sends your branches to the check-in area that grit checkin grafts from, never onto the server's real branches. grit checkin and grit pull themselves always talk to the server the checkout was made from, even if you point origin somewhere else.
What makes the repository a checkout is a small record in its git directory (grit-checkout.json): the server, the checkout's id, its target branch, its paths and its snapshots, and the tips of branches it checked in that were since integrated into its target branch, whose commits refreshes leave out. Every worktree of the checkout (git worktree add) shares it, so checking in and refreshing work from any of them.
Snapshots are made the same way every time, so everyone who checks out the same paths at the same commit gets the same snapshot commit, and the server makes its download once.
The download resumes: if a checkout is interrupted, run the same command again and it picks up where it stopped (partial downloads are kept in $XDG_CACHE_HOME/grit/checkouts, ~/.cache/grit/checkouts by default). The download has the same display as grit clone's bundle download.
Snapshot checkouts need a server that offers them, such as grit serve. They are served at their own endpoint, <server>/.grit/checkouts/<repository>, separate from Git's. When a server doesn't have it (a plain Git server, or a repository you can't read), grit checkout stops with an error and makes nothing:
error: https://example.com/demo.git offers no grit checkout (no https://example.com/.grit/checkouts/demo endpoint); it may be a plain Git server, or the repository may not exist
Sign in to the server first with grit auth <url>.
Work comes back with grit checkin, which rebuilds your branches on the server's real history. grit integrate <branch> merges one into the target branch, and grit pull refreshes the checkout: the server makes a snapshot of the newest commit of the branch the checkout was made from (even if the server's HEAD has since moved to another branch) on top of your last one, grit pull fetches just the changes in your paths and rebases the current branch onto it. Commits already in the target drop out. A rebase that conflicts stops for you to resolve, then grit rebase --continue; other branches still on an older snapshot are named (see grit pull). grit pull <branch> shows you a branch on the server as your checkout sees it and brings your branch onto it, so checkouts of different paths can work on one branch (see grit pull).
To switch branches, use grit switch (also grit co). Out of Git habit, grit checkout <branch> with no URL (nothing with ://) and no other arguments does the same as grit switch <branch>, hints included.
Options
| Option | Description |
|---|---|
<url> |
The repository, such as http://127.0.0.1:8080/demo.git. |
<slice> |
A slice on the server whose paths to check out. |
-p, --path <path> |
Check out only this path (a directory or file), plus the files in the directories above it. Repeatable. |
--into <dir> |
Directory to check out into. Defaults to the repository's name. It must not exist or must be empty. |
JSON output
Schema: v1
| Field | Type | Meaning |
|---|---|---|
url |
string | The repository URL, configured as origin (with the fetch and push refspecs above), with any user:password@ removed. |
path |
string | Directory the checkout was made in. |
branch |
string | The server's target branch the snapshot was taken from. |
work |
string | The new branch checked out for your work. |
base |
string | The real commit of the target branch the snapshot stands for. |
snapshot |
string | The snapshot commit, the checkout's only commit. |
paths |
array of strings | The paths checked out; empty for the whole tree. |
files |
integer | Files in the snapshot. |
bytes |
integer | Bytes of those files. |
download_bytes |
integer | Size of the download. |
resumed_from |
integer | Bytes an earlier, interrupted checkout had already downloaded. |
id |
string | The server's id for the checkout. |
seconds |
number | Wall-clock seconds. |
Markdown output
Pass --markdown for agent-friendly output.
Schema: v1
Exit status
| Code | Meaning |
|---|---|
0 |
The checkout was made. |
1 |
The server offers no snapshot checkouts for the repository, has no such slice, refused the request (for example a path it doesn't have), the destination is not empty, or the download failed. |