Description
Stages changes so they show up under Staged in grit status. Pathnames in human and --markdown output use the same quoting rules as grit status (see Description there). With no paths, grit add stages everything grit status reports: modified files, deleted files and untracked files. A tracked file replaced by a directory, or a tracked directory replaced by a file, is staged the way Git does it: the old path as a deletion and the new files as additions. With paths, it stages only those files, or everything under those directories.
Paths are relative to your current directory, so from inside src/, grit add main.rs stages src/main.rs. Paths like ../README.md and absolute paths inside the repository work too. Attribute pathspecs such as :(attr:myattr) stage every matching path under the same .gitattributes rules as grit diff and grit status. A path that matches nothing is an error, and nothing is staged. A path that crosses a symlinked directory (for example link/file when link is a symlink) is an error: nothing is staged. Naming a path that exists but is excluded by .gitignore, .git/info/exclude, or core.excludesfile is also an error: nothing is staged and the command lists the ignored paths (pathless grit add still skips ignored files silently, like Git). With core.ignorecase=true, ignore patterns match without regard to case (see grit ignore). On a case-folding work tree (typical macOS and Windows volumes), grit add keeps the spelling already recorded in the index and stores new paths under those directory names; rename a path's case only with grit mv. Explicitly staging an unmerged path fails while Git-style conflict markers remain in the worktree file (the same rule as grit commit auto-staging); remove the markers or use a resolved file, then run grit add again. When a broad pathspec (for example grit add . after a merge) matches both resolved and still-marked unmerged files, Grit stages every path it can and exits with status 1, naming each remaining conflict (path: conflict markers remain; not staged). Git may stage marker-bearing files in the same situation; Grit refuses to record conflict markers in the index.
Files with a filter=<driver> attribute (Git LFS, for example) are staged through the driver's clean filter, which runs through sh the way Git runs it. On Windows that is the sh bundled with Git for Windows, so you don't need it on PATH. If the driver sets filter.<driver>.required=true and the filter fails or cannot be started, grit add fails, says why, and stages nothing. It never stores the unfiltered file. When an optional filter fails, the file is staged unfiltered, as Git does.
Files of at least core.bigFileThreshold bytes (512 MiB unless configured; k, m and g suffixes work) are hashed and compressed as a stream straight into their own pack, as Git does, so staging a multi-gigabyte file takes a few megabytes of memory. This applies to grit commit auto-staging and to the re-hash grit status does after a big file's timestamp changes, too. A file that needs a clean filter, working-tree-encoding or line-ending conversion is read into memory whatever its size.
On filesystems where Grit sets core.filemode=false (typical on Windows), every new file is staged as non-executable (100644) even when it is a script. Use --executable on the paths you ship as runnable scripts so the index and commits record mode 100755. Use --non-executable to clear an explicit executable bit in the index. These flags require at least one path argument.
grit commit stages every change before it records a commit, so you don't need grit add to commit. It's useful for starting to track a new file and checking what will be committed.
Copying or cloning another Git repository into your tree (a directory that contains its own .git) is recorded as a gitlink (mode 160000), not as ordinary files. Clones of your repository get an empty directory at that path. When grit add newly records such a path, human and --markdown output print a warning on stderr; --json includes embedded_gitlinks (omitted when empty). Remove <path>/.git and stage again if you meant to vendor the files inside. A symlink (including one aimed at a repository directory) is staged as mode 120000 and does not trigger this warning.
Touching a tracked file's timestamp without changing its bytes or mode is not a stage: grit add refreshes the index stat cache silently (same as Git) and reports nothing to stage.
A directory that contains an embedded git repository (for example after git init inside the tree, or cargo new in a subdirectory) is staged as a gitlink (mode 160000) when that nested repository has at least one commit checked out on its current branch. When the nested repository has no commits yet, grit add refuses with embedded_repo_without_commit, leaves the index unchanged, and does not record the path as a regular file.
On Unix, explicit path operands must be valid UTF-8. An operand containing invalid UTF-8 bytes is rejected before the command runs, with exit status 2 and no changes to the repository. Human output reports the usage error on stderr; --json writes an error object with kind: "usage" on stdout, and --markdown writes **Error:** on stdout. The argument is never replaced with a similar Unicode filename.
On an interactive terminal (human output, not --json or --markdown), a live Staging line on stderr counts the files hashed into the index; nothing is drawn when stderr is not a TTY.
Options
| Option | Description |
|---|---|
<path>... |
Files or directories to stage. Omit to stage every change. |
-u, --update |
Stage tracked changes only (modified and deleted paths). Untracked files are left alone. With no paths, applies to the whole tree. |
--dry-run |
List paths that would be staged without updating the index or writing objects. |
--hunks |
Stage only the listed hunk ids from grit diff --json (hunks[].id). Comma-separated ids; pass the flag again to add more. Optional -- paths narrow the diff scan. Cannot be combined with --patch-file, -u / --update, or -N / --intent-to-add. |
--lines |
Stage only new-side line ranges from grit diff --json (lines[].new). Use path:start-end or path:line (1-based, inclusive); comma-separate or repeat the flag. Mix with --hunks. Same restrictions as --hunks. |
-U, --unified |
With --hunks only: unified context lines for hunk boundaries (same meaning as grit diff -U; default 3 when omitted). Use the same value as the diff that produced the ids. |
--patch-file |
Apply a unified diff to the index only (like git apply --cached). Use - for stdin. Cannot be combined with --hunks, paths, -u / --update, or -N / --intent-to-add. |
-N, --intent-to-add |
Record intent-to-add entries (empty blob, extended flag) instead of hashing content. |
-f, --force |
Stage ignored paths when named explicitly (instead of erroring with pathspec ignored). |
--pathspec-from-file |
Read additional pathspecs from a file, or - for stdin (same rules as Git). |
--pathspec-file-nul |
With --pathspec-from-file, entries are NUL-separated instead of line-based. |
--executable |
Stage listed regular files with mode 100755 in the index (requires at least one path). |
--non-executable |
Stage listed regular files with mode 100644 in the index (requires at least one path). |
JSON output
Pass --json for stable, scripting-friendly output.
| Field | Type | Meaning |
|---|---|---|
added |
array | Newly staged paths. |
modified |
array | Staged modifications. |
removed |
array | Staged deletions. |
intent_to_add |
array | Paths recorded with intent-to-add. |
dry_run |
boolean | Whether the index was left unchanged. |
count |
number | Total paths touched. |
staged |
number | Same as count for successful staging. |
staged_hunks |
object | Path → hunk ids when --hunks staged something (empty object when unused). |
staged_lines |
object | Path → line ranges when --lines staged something (empty object when unused). |
embedded_gitlinks |
array | Nested repositories newly recorded as gitlinks. Omitted when empty. |
worktree_case_collisions |
array | Case-insensitive path groups that block staging ([{ "paths": [...] }, …]). Omitted when empty. |
When --hunks or --lines staged something, staged_hunks or staged_lines maps path → ids or ranges; otherwise those fields are empty objects.
Grit computes blob object ids with the same plain SHA-1 digests as Git. SHAttered test vectors (for example blobs in the git/git history) stage and commit normally; grit does not reject them during ingestion.
Markdown output
On a case-insensitive volume, when tracked paths collide (for example Readme.TXT and readme.txt sharing one file), grit add with no paths does not print “working tree clean”. Human and --markdown output show the same path-collision warning as grit switch and a hint to use a case-sensitive volume or grit reset --hard. --json includes worktree_case_collisions ([{ "paths": [...] }, …]) when any group blocks staging.
Exit status
grit add reads and writes the index while holding .git/index.lock, so parallel grit add (or git add) runs in one repository never undo each other: every run that exits 0 has its paths in the index. A run that cannot get the lock within core.filesRefLockTimeout (default 100 ms; -1 waits forever) exits 1 with an index.lock error and stages nothing, so a script can simply retry it. grit rm follows the same rule.
With --json, a held index lock returns kind: "lock_held" and lock.path. When a PID sidecar exists, lock.holder.pid identifies the recorded process and lock.holder.running reports whether it was running when checked. Grit leaves both files alone. Retry after the owner finishes, or remove a stale lock after checking that no writer is running.
{"error":"another process holds /work/repo/.git/index.lock; if none is running, remove the stale lock and retry","kind":"lock_held","lock":{"path":"/work/repo/.git/index.lock"}}
See Exit codes for shared rules and structured --json kind values.