# CLI conventions

> Shared rules for grit command paths, limits, dry-run, messages, pathspecs, and force flags — enforced by the cli_contract tests in grit-cli.

Grit's CLI is intentionally small, but the flags that appear on many commands follow one contract. The `grit-cli` crate encodes that contract in `cli_contract.rs`: every **leaf command path** in the clap tree is classified, and tests fail when a new command is added without a classification or when a rule is broken without a tracked exception.

This page states the rules in grit's own words. It does **not** change runtime behavior; later roadmap steps align commands that still have exceptions.

## Command kinds

Each leaf path (for example `stash.list`, `gc.repack`, or top-level `commit`) has exactly one kind:

| Kind | Meaning |
| --- | --- |
| **List** | Prints a bounded collection. Must expose `-n` as a **limit** (see below). |
| **Mutation** | Changes refs, the index, the working tree, config, or remote state. Must expose long-only `--dry-run` to preview, except where noted. |
| **Query** | Read-only inspection (diff, show, status, fsck, …). |
| **Plumbing** | Wire protocols or credential plumbing (`upload-pack`, `receive-pack`, `manager`). |
| **Generator** | Emits shell completion scripts or the agent skill (`completions`, `skill`). |

Parent commands that run without a subcommand (for example bare `grit stash` for push, `grit remote` for list) are separate leaf paths alongside explicit subcommands such as `stash.push`.

## Limit (`-n`)

On **every** command, `-n` always means **limit** — never “dry-run” or anything else. **List** commands must also expose that limit flag (see below).

- The short flag is `-n`.
- The long name is `--limit`, or `--max-count` when `--limit` is registered as a long alias (as on [`grit log`](https://grit-scm.com/docs/log/index.md) and [`grit revs`](https://grit-scm.com/docs/revs/index.md) today).
- No other argument on the same command may use `-n` for a different meaning.

## Dry-run (`--dry-run`)

On **mutation** commands, preview mode is long-only **`--dry-run`** (no `-n` shortcut). Mutations that support partial selection (`add`, `restore`, `commit` with hunks, …) use `--dry-run` the same way.

If you pass unknown `-n` on **`add`**, **`rm`**, **`mv`**, **`clean`**, or **`push`**, grit prints a usage hint pointing at **`--dry-run`** instead of clap’s misleading “pass `-n` as a value” tip.

**`grit clean`** is a mutation with different defaults: without `-f` / `--force`, it only prints what would be removed. Passing **`--force`** performs the deletion. That is the documented special case instead of an exception entry.

## Message input (`-m`, `-F`)

Commands classified with **takes message** accept:

- `-m` / `--message` for inline text, and
- `-F` / `--message-file` for a file path (`-` reads stdin),

with the two flags mutually exclusive. [`grit merge`](https://grit-scm.com/docs/merge/index.md) uses the shared message group for merge commits; history subcommands such as [`grit history reword`](https://grit-scm.com/docs/history/index.md) follow the same pattern where a message is optional or required per subcommand.

## Pathspecs (`--` paths)

Commands classified with **takes paths** accept:

- trailing `-- <paths>` arguments, plus
- `--pathspec-from-file` and `--pathspec-file-nul` (Git-compatible path lists),

shared via the same Rust argument group in the CLI. [`grit status`](https://grit-scm.com/docs/status/index.md), [`grit log`](https://grit-scm.com/docs/log/index.md), [`grit revs`](https://grit-scm.com/docs/revs/index.md), [`grit diff`](https://grit-scm.com/docs/diff/index.md), and [`grit show`](https://grit-scm.com/docs/show/index.md) use that group.

## Force (`-f`)

Every **`--force`** flag exposes short **`-f`**, unless the command page and `EXCEPTIONS` in `cli_contract.rs` document a deliberate deviation.

## Enforcement and exceptions

Two tests guard the contract:

- `cli_contract_conventions` — every leaf path is classified; clap flags match the rules unless listed in `EXCEPTIONS`.
- `cli_contract_exceptions_are_live` — each exception still describes a real violation; remove the row when the command is fixed.

Exception rows name an **owner** (a later plan step such as `s4 limit`, `s5 dry-run`, or a roadmap bucket like `workspace-extras`). When you fix a violation, delete its exception and rely on the convention test.

Adding a command requires a new row in `COMMAND_CONTRACTS` inside `grit-cli/src/cli_contract.rs`. CI fails with a message that names the path and the rule if you omit it.

## Three layers

Each `grit` command is split into three layers. Later roadmap steps move command logic into this shape; the render layer landed first.

| Layer | Location (today) | Responsibility |
| --- | --- | --- |
| **Parse** | `grit-cli/src/main.rs` (per-command args land in step 2) | Clap parsing, global flags, revision/pathspec helpers. Produces plain Rust input structs — no I/O. |
| **Outcome** | Command modules under `grit-cli/src/commands/` and small `*_args.rs` helpers | Open `grit_lib::repo::Repository` handles, call library APIs, map errors. Returns a typed **outcome** (structs with `Serialize` for `--json`). |
| **Render** | `grit-cli/src/render/` | Turn outcomes into human text, Markdown, or filtered JSON. **No** `Repository`, `context`, or `commands::` imports (see `render_layer_is_repository_free` in `grit-cli`). |

**JSON DTO rule:** serde shapes on outcomes stay in the CLI. They are `From<&LibOutcome>` field mappings (or thin wrappers), not new public `grit-lib` types. The committed v1 JSON schemas remain the contract.

`make cli-layer-ratchet-check` tracks line counts for `render/`, `args/`, `dispatch` (`main.rs`), and the rest of `grit-cli/src`. Non-render layers may not grow without updating `grit-cli/layer-ratchet.toml`.

## See also

- [Scripting with grit](https://grit-scm.com/docs/scripting/index.md) — `--json`, exit codes, and stdout discipline.
- [Agent guide](https://grit-scm.com/docs/agents/index.md) — non-interactive use and schema links.
- [Global options](https://grit-scm.com/docs/global-options/index.md) — `--json`, `--markdown`, `--filter`, `--threads`, and the repository options `-C`, `-c`, `--git-dir`, `--work-tree`.
