Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 78 ยท The Basic Workflow

Moving, Renaming and Removing Files

Learn git rm, git mv and rename detection: delete tracked files, keep them on disk with --cached, rename safely, handle case-only renames and follow history.

Projects are not static. You rename a file when its purpose changes, move modules into new folders, and delete code that nobody uses. Git handles all of this, but it has a surprising approach: Git does not record renames at all. Each commit is a snapshot of the whole tree, and when you look at history Git works out, by comparing two snapshots, that "this deleted file and that new file are really the same file". Understanding that one idea makes git mv, git rm and git log --follow simple.

This lesson covers the two commands for changing the file set (git rm and git mv), why they are only shortcuts, how rename detection works and when it fails, how to rename files whose names differ only in capitalization (a classic trap on Windows and macOS), and how to remove a file from Git while keeping it on disk. It builds on Staging Changes and Undoing Things.

Deleting files: git rm

You can delete a tracked file in two ways. You can remove it with the shell (rm file) and tell Git afterwards, or use git rm file, which does both steps at once: it deletes the file from the working directory and stages the deletion.

Bash rm versus git rm

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The two routes lead to the same state: the first shows D (deleted in the working tree, not yet staged), then D after git add; git rm goes straight to D . Either way the file disappears from the next commit. History is untouched: the old snapshot still has the file, and you can bring it back any time with git restore --source=HEAD~1 old1.txt or git checkout <commit> -- old1.txt.

git rm also works on directories: git rm -r folder/ deletes the whole tree of tracked files. Use -n (--dry-run) to see what would go.

Safety checks

Git protects you from losing work when you use git rm. If the file has uncommitted changes, it refuses:

Bash git rm refuses to lose edits (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The message reads error: the following file has local modifications and suggests two ways forward: --cached to keep the file, or -f to force the removal. It makes a similar complaint when the staged version differs from both the file and HEAD. The check exists because a plain rm followed by git add would silently destroy your edits, while Git can warn you. Use -f only when you really mean "discard these edits too".

Remove from Git but keep the file: git rm --cached

Sometimes you want Git to stop tracking a file, but you want to keep it on your disk, for example a configuration file with local settings that you committed by mistake. git rm --cached removes it from the index only.

Bash git rm --cached keeps the file on disk

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The file is gone from Git's file list but still sits on your disk, and the new .gitignore rule stops it from showing up as untracked (see .gitignore and Untracked Files). Your teammates will get a deletion when they pull, so their copy disappears. Warn them if they keep local settings in it.

Renaming and moving: git mv

git mv old new renames or moves a file (moving a file to a different folder is the same operation as renaming it). It is exactly equivalent to three steps: rename the file with mv, git rm the old path from the index, and git add the new path.

Bash git mv versus mv plus git add

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

With git mv, the status reads R notes.txt -> docs/notes.md: an R for renamed. With a plain mv the status first shows two separate things ( D a.txt and ?? b.txt), because the shell did not tell Git anything. As soon as you stage both with git add -A, Git pairs them up and shows R a.txt -> b.txt too. So git mv is only a convenience; the result is identical. That is the first hint that renames are detected, not stored.

Rename detection: how Git "knows"

When you ask for status, diff or log, Git compares two trees. It finds a path that vanished and a new path that appeared and then measures how similar their contents are. If they are similar enough (50% by default), Git reports a rename instead of a delete plus an add. A pure rename is 100% similar (identical content). A rename combined with edits can still be detected as long as at least half of the content survives.

Bash Rename with edits, and the 50 percent threshold

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

renamed-a.txt lost two of its 20 original lines and gained three new ones, so it is still recognized as a rename by default (the -M10% output shows the measured similarity, R078, meaning 78%). renamed-b.txt has completely new content, so Git sees a deletion plus an addition. You can control this: -M90% asks for at least 90% similarity, so even the first file is treated as delete and add; -M10% is generous. Rename detection also exists for copies (-C), and for files moved with heavy edits it is just a guess.

Because renames are computed on demand, there is no difference in history between "renamed and edited" and "deleted and re-created". Two practical consequences follow:

  1. Commit a rename separately from big edits. If you move a file and rewrite most of it in the same commit, Git may not match the two, and git log --follow and git blame lose the connection. Rename in one commit (Move parser to src/) and edit in the next. This habit makes history much easier to read.
  2. git log does not follow renames by default. git log -- new/path stops at the commit where the file got its new name. Use git log --follow -- new/path (works for one file at a time) to continue across the rename, and git blame follows moves within a file automatically; see blame, grep and Searching History.
Bash History across a rename

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Without --follow, the history of src/parser.txt begins at "Move parser into src" because that is when that path first existed. With --follow, Git detects the rename in that commit and keeps walking back through the old path. The git show --stat output displays parser.txt => src/parser.txt with 0 changes, proving that the content was identical.

Case-only renames

On Windows and macOS the default file systems are case-insensitive (but case-preserving): readme.md and README.md are the same file to the operating system. Git, however, is case-sensitive internally. Renaming readme.md to README.md can leave Git thinking nothing changed, or you can end up with both names in the repository, which then breaks checkouts on those systems.

The reliable way is git mv, which updates the index in a single step. On a case-insensitive file system you may need to use git mv -f or a two-step rename through a temporary name (git mv readme.md tmp && git mv tmp README.md). You can also set git config core.ignorecase false, but think twice before that; Git sets the value itself by testing the file system at git init time. Our Linux sandbox is case-sensitive, so this runs without any problem:

Bash A case-only rename

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The output R readme.md -> README.md is what you want. On macOS or Windows core.ignorecase would be true after git init, which is why you should always rename through git mv and never rely on the file manager.

Moving things around safely

  • Use git mv, or mv plus git add -A, then check git status: you should see R entries and no stray ?? or D.
  • Keep renames in their own commit, with no content changes, so history stays traceable.
  • After moving files, update imports, build scripts, CI configuration, documentation links and .gitignore paths; Git does not do it for you.
  • A big directory reshuffle is a merge hazard. If a teammate edits old/file.c while you move it, Git's merge machinery can usually carry their edit to new/file.c thanks to rename detection (see How Merge, Rebase and Diff Work Inside), but only if enough content stays similar. Tell your team when you plan a mass move.
  • Removing a file removes it from the current snapshot, not from history. Secrets stay in old commits; see Fixing Common Git Mistakes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does git rm --cached config.local do?

    --cached affects only the index, so the file stops being tracked but stays on your disk. History is not changed.
  2. 2. How does Git store a renamed file?

    There is no rename record. Git compares two trees and, if a deleted and an added file are similar enough, reports a rename.
  3. 3. git log -- src/parser.txt stops at the commit that moved the file. How do you follow it back through the rename?

    --follow makes Git continue the history of a single file across renames.
  4. 4. You ran rm old.txt in the shell. What is the state of the repository?

    Git sees a working-directory change only. git add old.txt (or git rm old.txt) stages the deletion.
  5. 5. Why should you commit a rename separately from large edits to that file?

    Rename detection depends on content similarity. A pure rename is 100% similar, which keeps the history connected.

Summary

  • git rm file deletes and stages the deletion; git rm -r dir/ removes a directory; git rm --cached file stops tracking but keeps the file on disk.
  • git rm refuses when it would lose uncommitted edits; -f overrides.
  • git mv old new equals mv followed by git add; both give R in git status.
  • Git does not store renames; it detects them by content similarity (50% by default, adjustable with -M<n>%).
  • Commit renames separately from edits, and use git log --follow -- path to follow a file across renames.
  • For case-only renames, use git mv (via a temporary name if needed) on case-insensitive file systems.

Next: Branches