Description
Renames or moves tracked paths in the working tree and index, preserving object ids and cached stat data. Pathnames in human and --markdown output use the same quoting rules as grit status (see Description there). The last argument is the destination; earlier arguments are sources.
When the destination is an existing directory, each source is moved into that directory under its original base name. A trailing slash on the destination (docs/ or docs//) is accepted and means the same as naming the directory without the slash. Moving a directory renames the whole tree of tracked files. Multiple sources are validated together before anything moves; the index is updated once.
Grit refuses untracked sources, overwriting an existing destination without --force, and moving a directory into one of its own subdirectories.
On case-insensitive volumes with core.ignorecase=true, case-only renames succeed: the worktree spelling updates and the index tracks the destination path. That includes renaming a tracked directory to a case-only spelling (for example Dir to dir), which updates every indexed path under that tree (for example Dir/x.txt becomes dir/x.txt). Single-file case-only renames behave like git mv; upstream Git still fails directory case-only renames on APFS.
When a move leaves a source directory empty, grit leaves that directory on disk (same as git mv).
Options
| Option | Description |
|---|---|
<source>... |
One or more tracked paths to move. |
<destination> |
Final path or existing directory (last argument). |
-f, --force |
Replace an existing file at the destination. |
--dry-run |
List planned renames without changing the index or work tree. |
JSON output
Live --json output follows schema v2. The frozen v1 schema documents the legacy {from, to} shape.
Pass --json for stable, scripting-friendly output:
| Field | Type | Meaning |
|---|---|---|
moves |
array of {from, to} |
Each rename performed or previewed. |
dry_run |
boolean | true when --dry-run was passed. |
Markdown output
Exit status
See Exit codes for shared rules and structured --json kind values.