# Use 'git mv' to record filename case changes in Git

DevFeed: [Use 'git mv' to record filename case changes in Git](<https://devfeed.tech/articles/use-git-mv-to-record-filename-case-changes-in-git-21727.md>)

Original publisher: [Read original article](<https://oleb.net/2025/git-mv-case-change/>)

Author: Ole Begemann

Published: 2025-12-16T17:11:22Z

Content type: tutorial

Language: en

Sources: [Ole Begemann](<https://devfeed.tech/sources/ole-begemann.md>)

Topics: [Git](<https://devfeed.tech/topics/git.md>), [Filesystems](<https://devfeed.tech/topics/filesystems.md>), [macOS](<https://devfeed.tech/topics/macos.md>), [Windows](<https://devfeed.tech/topics/windows.md>)

Tags: [files](<https://devfeed.tech/tags/files.md>), [git](<https://devfeed.tech/tags/git.md>), [git-commit](<https://devfeed.tech/tags/git-commit.md>), [macos](<https://devfeed.tech/tags/macos.md>), [windows](<https://devfeed.tech/tags/windows.md>)

## AI overview

This tutorial explains that case-only filename changes may not be recorded by Git on case-insensitive, case-preserving filesystems such as default macOS APFS. It demonstrates how using git mv records the new casing correctly and prevents filename mismatches in clones and case-sensitive environments.

## Source excerpt

After my previous post Tracking renamed files in Git, here's another entry in my ongoing series "I thought git mv was useless but I was wrong". This one's especially relevant to users on macOS and Windows, where the file system is case-insensitive by default. More precisely, APFS on macOS is case-insensitive but case-preserving by default. That is, A.TXT and a.txt refer to the same file (and these two cannot coexist in the same directory), but the file system records the filename exactly as you entered it. If you're on a such a file system and change the case of a filename, Git will not record the new name -- unless you use git mv to perform the renaming. Demo 1. Without git mv (bad) Note: I tested this on macOS with the default APFS (case-insensitive) file system. You'll get different results if your file system is case-sensitive. Let's create a fresh repository and commit a single file named A.txt: mkdir testrepo cd testrepo git init echo "Hello" > A.txt git add . git commit -m "Create A" [main (root-commit) 3d73aea] Create A 1 file changed, 1 insertion(+) create mode 100644 A.txt Now we rename the file from A.txt to a.txt: # Rename the file (change case) # Note: not using `git mv` mv A.txt a.txt git status nothing to commit, working tree clean That's interesting. git status says "nothing to commit" because nothing has changed from its perspective. Git is still tracking a file named A.txt, whose contents haven't changed. If we now make edits to the file a.txt (aka A.txt; both names refer to the same file), Git tracks this as a change of the existing file, which is still named A.txt in Git's datastore: echo "World" > a.txt git status Changes not staged for commit: modified: A.txt Let's commit the change: git add . git commit -m "Edit A" [main e86bcb2] Edit A 1 file changed, 1 insertion(+), 1 deletion(-) Now we're in a situation where the recorded filenames on the file system and in Git have diverged. A fresh clone of the repository will create the file with its orig