Introduction

Changing only the capitalization of a filename is easy on a case-sensitive filesystem and surprisingly awkward on a case-insensitive one. Git can track case-only renames, but the safest approach is usually to rename through an intermediate filename so both Git and the local filesystem clearly see the change.

Why Case-Only Renames Are Tricky

Git itself stores filenames as case-sensitive paths. The problem usually comes from the operating system.

On many Linux filesystems, Readme.md and README.md are different files. On typical macOS and Windows setups, they are treated as the same path even though the original casing is preserved.

That means a rename like this:

mv readme.md README.md

may not be detected the way you expect, especially if the rename happens outside Git. The safest fix is to let Git manage the rename directly.

The Reliable Two-Step Rename

Use git mv with an intermediate name:

1git mv readme.md readme_tmp.md
2git mv readme_tmp.md README.md
3git status
4git commit -m "Rename readme.md to README.md"

This works well across macOS, Windows, and Linux because the temporary name forces a real path change that both Git and the filesystem can observe.

You can do the same for directories:

git mv src src_tmp
git mv src_tmp Src

After that, review the index with:

git status
git diff --cached --name-status

Those commands confirm that Git is staging a rename rather than an accidental delete and add pair that misses related files.

When git mv in One Step Works

On some systems and repository setups, this can be enough:

git mv -f appconfig.json AppConfig.json

The -f flag forces the rename if Git thinks the destination already exists. This may work fine, especially on case-sensitive filesystems, but the intermediate-name method is still the safest cross-platform habit.

If you are working in a team where some developers use Windows or default macOS volumes, prefer the two-step rename unless you have a good reason not to.

Check core.ignorecase Carefully

Git has a core.ignorecase setting that influences how it notices filename changes on case-insensitive filesystems:

git config core.ignorecase

If it is true, Git is more tolerant of case-insensitive path handling. That usually matches the underlying filesystem and is not something you should casually flip just to force a rename.

You can set it at the repository level:

git config core.ignorecase false

But treat that as a deliberate repository decision, not a quick workaround. If the filesystem is still case-insensitive, mismatching the Git setting can create confusing behavior for you and your teammates.

Rename in IDEs with Caution

Many editors and IDEs can rename files for you, but case-only renames are one place where GUI tooling sometimes hides what is really happening. If the IDE renames outside Git, the filesystem may collapse the change or Git may fail to stage it cleanly.

A practical workflow is:

1. close open file tabs if the editor tends to fight renames
2. run the two-step git mv commands in the terminal
3. reopen the file in the editor
4. update imports if the language or framework cares about path case

That last part matters in JavaScript, TypeScript, and other ecosystems where import paths may break in CI on Linux even if they seemed fine on macOS.

Common Pitfalls

The most common mistake is renaming the file outside Git and expecting git status to notice a case-only change on a case-insensitive filesystem. It often will not.

Another problem is forgetting to update imports, build scripts, or deployment references. A case mistake may go unnoticed locally and then fail in a Linux-based CI runner.

Users also sometimes change core.ignorecase globally without understanding the repository consequences. That can create inconsistent behavior across projects.

Finally, be careful with directories. A case-only directory rename can affect many files at once, so verify the staged result before committing.

Summary

• Git can track case-only renames, but the filesystem may make them awkward.
• The most reliable method is git mv old temp followed by git mv temp NewName.
• One-step git mv -f can work, but it is less predictable across platforms.
• Check staged changes before committing, especially for directories.
• Update imports and references so Linux-based environments do not break later.