gritHEAD → docs/slice
Commands / RemotesMarkdown

grit slice

Name sets of paths to check out together, kept on the server's target branch.

grit slice list [--url <url>]
grit slice new <name> -p|--path <path>... [-d|--description <text>] [--url <url>]
grit slice edit <name> [--add <path>]... [--remove <path>]... [-d|--description <text>] [--url <url>]
grit slice delete <name> [--url <url>]

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.