git mv: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

git mv renames or moves a file and stages the move in a single step.

git mv is shorthand for mv + git add + git rm of the old path, keeping rename detection clean.

What it does

git mv renames or relocates a tracked file (or directory) on disk and stages both the removal of the old path and the addition of the new one.

Common usage

Terminal

git mv old.txt new.txt
git mv src/ lib/
git mv -f a.txt b.txt        # overwrite an existing b.txt

Options

Flag	What it does
-f / --force	Overwrite an existing destination
-k	Skip moves that would error, instead of failing
-n / --dry-run	Show what would happen
-v / --verbose	Report names as they are moved

Common errors in CI

fatal: destination exists, source=… (use -f to overwrite). fatal: not under version control, source=… means the file is not tracked - git mv only works on tracked paths; add it first or use a plain mv plus git add.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git mv: Usage, Options & Common CI Errors?