gritHEAD → docs/mv
Commands / Making changesMarkdown

grit mv

Rename or move tracked paths.

grit mv [-f|--force] [--dry-run] <source>... <destination>

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

Code Meaning
0 Success (success).
1 Command failed (failure).
2 Invalid flags or arguments (usage).

See Exit codes for shared rules and structured --json kind values.