# git mv: Usage, Options & Common CI Errors

> git mv moves or renames a tracked file and stages the change. Reference for -f, -k, and the "destination exists" and "not under version control" errors.

Source: https://latchkey.dev/learn/command-reference/git-mv  
Updated: 2026-06-25

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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git mv: Usage, Options & Common CI Errors?

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt