Description
A slice names a set of paths so people check out the same part of a repository without listing it each time: grit checkout <url> <slice> checks out a slice's paths (into a directory named after the slice), and --path adds more.
Slices live in .grit/slices.toml on the server's target branch, so they're versioned with the code they describe and every checkout sees the same ones:
[slices.desktop]
description = "The desktop app and its UI package"
paths = ["apps/desktop", "packages/ui"]
Each new, edit or delete is one commit on the target branch, made by the server, by you: the author your own commits get (GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL, then author.* and user.* config, as grit commit has it), or the signed-in user when none is set. The server cleans <, > and line breaks out of the name and email. The paths must exist on the target. Slice changes and integrations take turns on the server, so several at once all land, each on the target the one before left; each is checked again on the target it lands on (a name taken meanwhile is refused). When the server's repository has the target checked out in a worktree, the worktree moves with the commit, keeping uncommitted changes there; changes the commit would overwrite refuse it. Inside a snapshot checkout, grit slice talks to the server the checkout came from; elsewhere, pass --url. Changing slices needs write access; listing them needs read access. A checkout made from a slice keeps its paths when the slice changes later.
Options
| Option | Description |
|---|---|
list |
List the slices. |
new <name> |
Make a slice. Names use letters, digits, -, _ and .. |
edit <name> |
Change a slice's paths or description. |
delete <name> |
Delete a slice. |
-p, --path <path> |
With new: a path in the slice (repeatable, at least one). |
--add <path> |
With edit: add a path (repeatable). |
--remove <path> |
With edit: remove a path (repeatable). |
-d, --description <text> |
With new or edit: what the slice is for. |
--url <url> |
The repository whose slices to use. Defaults to the checkout you are in. |
JSON output
Schema: slice.list v1 · slice.new v1 · slice.edit v1 · slice.delete v1
grit slice list:
| Field | Type | Meaning |
|---|---|---|
url |
string | The server repository, with any user:password@ removed. |
target |
string | The target branch the slices are on. |
head |
string | Where it is. |
slices |
array | Each slice's name, description (when set) and paths. |
grit slice new, edit and delete:
| Field | Type | Meaning |
|---|---|---|
action |
string | new, edit or delete. |
name |
string | The slice's name. |
slice |
object or omitted | The slice as it is now: name, description and paths. Omitted once deleted. |
target |
string | The target branch. |
previous |
string | Where it was. |
head |
string | Where it is: the server's commit changing the slices file (previous when nothing changed). |
Markdown output
Pass --markdown for agent-friendly output.
Schema: slice.list v1 · slice.new v1 · slice.edit v1 · slice.delete v1
Exit status
| Code | Meaning |
|---|---|
0 |
Success. |
1 |
The slice exists (new) or doesn't (edit, delete), a path is not on the target, the name is invalid, uncommitted changes in the server's worktree block the commit, the server offers no snapshot checkouts, or no server was named outside a checkout. |