How to fix fatal: not under version control, source=file.txt in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 195 views

This error occurs when you try to use git mv on a file that Git is not tracking. Either add the file to Git first, or use regular mv followed by git add instead.

Quick fix

Fixes fatal: not under version control, source=file.txt

git status
  1. Check if the file is tracked by Git
  2. Option A: Track the file first, then move it
  3. Option B: Use regular mv and git add (recommended for untracked files)
  4. Handle multiple files at once
git — error
git status
fatal: not under version control, source=file.txt

What this error means

The `git mv` command is a convenience wrapper that combines moving/renaming a file with updating Git's index. When you run `git mv source destination`, Git performs three operations under the hood: it moves the file on disk, runs `git rm` on the old path, and runs `git add` on the new path. For this to work, the source file must already be tracked by Git. If the file has never been added to the repository (it's "untracked"), Git cannot record the rename in its history because there's no history to preserve. That's when you see the "fatal: not under version control" error. This commonly happens when you create a new file and immediately try to move it before committing, or when you're working with files that were intentionally left untracked (like build artifacts or local config files). The solution is simple: either track the file first with `git add` and then use `git mv`, or just use the regular `mv` command since there's no Git history to preserve anyway.

Typical symptoms

  • git mv fails immediately with 'fatal: not under version control, source=...'
  • Error occurs on files you just created that haven't been committed yet
  • Error occurs on files listed as 'untracked' in git status
  • Moving the same file with regular mv command works fine
  • The file exists on disk but Git doesn't recognize it as tracked

Common causes

  1. The file has never been added to Git with git add (most common)
  2. The file was previously removed from Git tracking with git rm --cached
  3. The file is listed in .gitignore and was never force-added
  4. You're in a different branch where the file doesn't exist in the index
  5. The file path has case sensitivity issues (e.g., 'File.txt' vs 'file.txt' on Windows/macOS)
  6. The file has unresolved merge conflicts and is in a special Git state

How to fix "fatal: not under version control, source=file.txt"

1Check if the file is tracked by Git

First, verify the file's status in Git:

bash
git status

Look for your file. If it appears under "Untracked files:", that's why git mv fails. If it doesn't appear at all, it might be ignored.

To check if a file is tracked:

bash
git ls-files --error-unmatch file.txt

If this returns an error, the file is not tracked.

2Option A: Track the file first, then move it

If you want to preserve Git history (useful if you've already committed the file before), add it first:

bash
git add file.txt
git mv file.txt new-location/file.txt

Note: This only works for files that are staged. If you want to track AND move in one go, you'll need to commit first or use Option B.

3Option B: Use regular mv and git add (recommended for untracked files)

For files that have never been tracked, there's no Git history to preserve. Just use regular shell commands:

bash
mv file.txt new-location/file.txt
git add new-location/file.txt

This is often the simplest solution. The end result is the same: the file ends up tracked in its new location.

4Handle multiple files at once

When moving many untracked files, use regular mv with git add --all:

bash
mv *.txt new-directory/
git add --all

Or for a more targeted approach:

bash
mv file1.txt file2.txt new-directory/
git add new-directory/

Git will figure out they are new files and stage them.

5Check if the file is ignored

If your file should be tracked but isn't, it might be in .gitignore:

bash
git check-ignore -v file.txt

If this shows a .gitignore rule, you can force-add the file:

bash
git add -f file.txt
git mv file.txt new-location/file.txt
6Fix case sensitivity issues (Windows/macOS)

On case-insensitive filesystems, Git might not recognize path differences. If you're renaming with only case changes:

bash
# Two-step rename to work around case sensitivity
git mv file.txt file-temp.txt
git mv file-temp.txt File.txt

Or use the force flag (Git 2.0.1+):

bash
git mv file.txt File.txt

Modern Git handles case-only renames automatically.

7Use git mv -k to skip problematic files

If you're moving multiple files and some are untracked, use the -k flag to skip errors:

bash
git mv -k *.txt destination/

This will move all tracked .txt files and silently skip any untracked ones. You can then move the untracked files separately with regular mv.

8Force overwrite with git mv -f

If the destination file already exists and is tracked, git mv will refuse to overwrite it. Use -f to force:

bash
git mv -f source.txt destination.txt

Caution: This will overwrite the destination file. Make sure you don't need its contents before using this flag.

Advanced notes

### Understanding git mv Internals

git mv is essentially equivalent to:

bash
mv old new
git rm old
git add new

Git doesn't actually store renames in its data model. Instead, it uses heuristics to detect renames when you look at history. This means using mv + git add produces the exact same result in terms of Git history as git mv.

### Why Use git mv at All?

1. Convenience: One command instead of three
2. Safety: Won't overwrite destination without -f flag (unlike regular mv)
3. Case-only renames: Better detection of case changes on case-insensitive systems
4. Submodule handling: Properly updates submodule configuration when moving submodules

### Merge Conflict Edge Case

As of Git 2.29, if a file has unresolved merge conflicts, git mv will show the "not under version control" error even though the file is technically tracked. This is a misleading error message. Resolve the merge conflict first:

bash
git status  # Check for conflicts
# Resolve conflicts in the file
git add file.txt
git mv file.txt new-location/file.txt

### Bulk Operations

For large-scale restructuring, consider using a combination:

bash
# Move tracked files with git mv
git mv src/*.js lib/

# Move remaining untracked files with regular mv
mv src/*.js lib/ 2>/dev/null || true

# Stage everything
git add --all

### Dry Run

To preview what git mv would do without making changes:

bash
git mv -n source.txt destination.txt

The -n (or --dry-run) flag shows what would happen.

Frequently asked questions

What does "fatal: not under version control, source=file.txt" mean?
The git mv command is a convenience wrapper that combines moving/renaming a file with updating Git's index. When you run git mv source destination, Git performs three operations under the hood: it moves the file on disk, runs git rm on the old path, and runs git add on the new path. For this to work, the source file must already be tracked by Git.
How do I fix "fatal: not under version control, source=file.txt"?
This error occurs when you try to use git mv on a file that Git is not tracking. Either add the file to Git first, or use regular mv followed by git add instead.
What causes "fatal: not under version control, source=file.txt"?
The file has never been added to Git with git add (most common) The file was previously removed from Git tracking with git rm --cached The file is listed in .gitignore and was never force-added
Is the "fatal: not under version control, source=file.txt" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading