有一回我把项目里的readme.md改成README.md想着让命名更规范一点。改完顺手执行git status结果屏幕上干干净净一行变化都没有。那一瞬间我以为是 Git 出了什么问题甚至怀疑自己是不是改错了文件。后来翻了半天资料才明白这既不是 Git 的 bug也不是我操作失误而是 Git 在不区分大小写的文件系统上为了能正常工作而做了一次自我妥协。这个问题在网上被反复搜了很多年关键词永远绕不开git 文件名称大小写、跟踪不到在 Windows 和 macOS 这两个主力开发平台上几乎每个开发者早晚都会遇到一次。这篇文章就把来龙去脉拆开讲清楚Git 为什么会看不见大小写变更最稳的几种解决思路分别怎么做Windows 和 macOS 上还有哪些文件系统层面的处理办法最后是我自己沉淀下来的一套预防习惯和五分钟排查顺序新手和已经在这上面浪费过半天时间的同学都能直接照着操作。1. 改了却看不到变化Git 的大小写盲区究竟卡在哪1.1 先分清文件系统身上的大小写性格要搞清楚这个问题首先要接受一个事实同一套文件名大小写规则在不同的操作系统上根本不是一回事。我们可以把主流平台分成三种性格下面这张表我用了很多年每次给同事讲这个问题都先甩出这张表平台常见文件系统默认是否区分大小写是否保留大小写Linuxext4 / xfs / btrfs区分—WindowsNTFS不区分保留macOSAPFS / HFS不区分保留先看 Linux。ext4 这类文件系统在路径层面就把readme.md和README.md当成两个完全不同的文件所以你可以理直气壮地把两个文件同时放进同一个目录。Windows 的 NTFS 则完全是另一套逻辑它默认不区分大小写也就是说readme.md和README.md在系统眼里是同一个文件你不可能让它们同时存在。但它有一个很容易被人忽略的特性保留大小写。系统虽然不区分大小写却会记住你创建文件时写下的大小写形式并在资源管理器里始终用这个形式展示给你。macOS 的默认 APFS 和旧的 HFS 表现跟 NTFS 几乎一样同样是不区分、但保留。这个差异直接决定了后面 Git 的每一步表现。你可以做一个最简单的小实验来验证在 Linux 上执行mkdir test touch test/readme.md touch test/README.md两个文件能成功创建换到 Windows 的 CMD 里执行同样的命令第二句会直接报文件已存在。这就是文件系统性格差异最直观的体现。1.2 core.ignorecaseGit 在初始化时就悄悄做的决定Git 在设计上其实是一套大小写敏感的系统因为它的诞生环境就是 Linux 这种天然区分大小写的世界。但为了能在 Windows 和 macOS 上正常干活Git 做了一个自我妥协在git init或git clone的时候主动探测当前文件系统是否区分大小写如果不区分它就在仓库本地的.git/config里写上一行配置ignorecase true这行配置的意思非常直白Git 在比较文件路径时忽略大小写差异。默认情况下它是跟随文件系统走的——在 Linux 上初始化的仓库core.ignorecase基本都是false或者干脆不写这一项在 Windows、macOS 上初始化的仓库它十有八九是true。你可以在任意仓库里执行下面这条命令确认当前值git config core.ignorecase如果输出true那你遇到文件名大小写变更不被跟踪就一点都不奇怪了Git 把readme.md和README.md当作同一个路径你在工作区把前者改成后者在 Git 眼里路径压根没变git status自然什么都不显示。Git 不是偷懒它是在用路径比对不区分大小写这种方式换取在大小写不敏感文件系统上的基本可用性。1.3 为什么 Git 的重命名检测也失灵了有经验的同学可能会追问就算忽略大小写我把readme.md重命名成README.md的过程中文件内容完全没变Git 不是应该通过内容相似度把这识别成一次 rename 吗答案是在core.ignorecase true的情况下Git 做路径比对时先就把新旧路径当成同一个文件了根本没有进入旧文件消失、新文件出现的判断流程。连 rename 的候选对象都不存在相似度检测自然无从谈起。具体到现象上就是那几种非常经典的迷惑现场git status一片空白什么都没显示用git status --porcelain看同样为空在 Windows 上执行git mv readme.md README.md直接报fatal: destination exists你以为 commit 能带上去结果git commit告诉你nothing to commit, working tree clean。这些现象本质上都指向同一个原因你的仓库被配置成了一个大小写不敏感的比对环境而你又试图在其中有意识地制造一个大小写敏感的变更。方向拧了结果就是卡住。下面几节就针对这个局面给出不同场景下的解决方案。2. 先别动配置两段式 git mv 一次搞定大小写重命名2.1 直接 git mv 为什么会失败知道了机制再看为什么看上去最正规的git mv命令在 Windows 上常常直接报错就很好理解了。在 Linux 上执行git mv readme.md README.md一切正常Git 会直接完成重命名并把变更放入暂存区。原因很简单ext4 认为README.md是一个全新的路径根本不存在所以没有任何冲突。但在 Windows 或 macOS 上文件系统不区分大小写git mv执行时会先去检查目标路径README.md是否存在。这个存在的判断同样是大小写无关的所以它会发现readme.md已经存在于是抛出fatal: destination exists, sourcereadme.md, destinationREADME.md。你可能会觉得这是误报但对 Git 来说它没有能力突破文件系统层面的限制。某些 Git 版本加了-f参数后能强行通过但不是所有环境都可靠所以我不推荐把它当首选方案。2.2 两段式重命名的完整操作解决方案其实非常朴素既然目标路径看似存在那就先让目标路径真实地不存在再把大小写改对。具体做法是借用第三个临时名字把一个单步操作拆成两步git mv readme.md readme.tmp git mv readme.tmp README.md先看第一步git mv readme.md readme.tmp目标readme.tmp在文件系统和索引里都不存在所以必定成功。此时工作区里已经没有readme.md只有readme.tmp。再看第二步git mv readme.tmp README.md此刻无论从文件系统还是 Git 索引来看README.md都不存在所以也必定成功。两步走完索引里的路径被更新成了README.md文件内容完好无损。执行完再看一眼状态git status你会看到类似下面的结果renamed: readme.md - README.md注意是renamed不是deleted加new file因为 Git 在状态展示里做了重命名检测识别出文件内容没有变化、只是路径变了。这里再补一条很实用的小经验临时名字别乱起要跟新旧文件名保持足够的差异。比如你在改AppConfig.ts和appConfig.ts之间来回折腾时临时名别选appconfig.tmp这种依然跟原文件名存在大小写歧义的名字直接用aaa_temp_rename.tmp这种绝对不冲突的名字最省心。2.3 目录名的大小写同样适用如果你要改的不是文件而是目录比如想把src/Utils改成src/utils两段式逻辑完全一样git mv src/Utils src/utils.tmp git mv src/utils.tmp src/utils第一句先把目录整体挪到一个中性的临时名字第二句再把目录挪到正确的大小写形式。Git 会把目录下的所有文件一并处理状态里会显示一批文件路径的变化。这一步在 Windows 上比文件重命名更容易翻车因为目录下的文件数量多任何一层路径判断出问题都会连坐所以拆成两步格外重要。不要想着一步到位省下的那点操作时间往往会在排查问题时加倍还回去。2.4 已经在文件管理器里改过名了怎么办还有一种极其常见的情况你没有用git mv而是在资源管理器或者 IDE 的文件树里直接把文件改成了新的大小写。此时磁盘上的文件名已经变了但 Git 索引里还保留着旧路径。这时候不需要再git mv用删索引、再重新添加的办法更直接git rm --cached readme.md git add README.md第一句git rm --cached并不是删除磁盘文件它只是把名为readme.md的这条路径从 Git 索引里摘掉第二句git add README.md则把磁盘上现存的README.md以新路径加回索引。两步之后git status就能看到 rename 或者 delete/add 的变化接着正常 commit 就可以。这里有个细节值得多写一句git rm --cached后面跟的文件名必须跟索引里存的原始路径一致尤其是大小写。如果你索引里存的是readme.md你写git rm --cached README.md在core.ignorecase true的情况下它也可能匹配上但为了稳妥建议先执行git ls-files | grep -i readme看一眼索引里到底存的什么名字再决定怎么写。这个习惯能帮你避免删了一个空路径啥变化都没有的尴尬。3. core.ignorecase 到底能不能改配置层面的利与弊3.1 先把当前配置和索引里的真实路径摸清楚动手之前先执行三条命令把现场情况摸清git config core.ignorecase git config --show-origin --get core.ignorecase git ls-files | grep -i readme第一条输出当前仓库的core.ignorecase值第二条能看出这个配置是写在仓库本地的.git/config里还是来自~/.gitconfig方便你判断改动的影响范围第三条会列出索引中所有包含 readme忽略大小写的路径让你明确 Git 眼中这个文件名到底是什么样。三条命令在整个排查过程中可以反复使用心里有数之后再动手比盲改配置强得多。3.2 设成 false 之后会出现什么局面网上很多答案会让你直接把core.ignorecase改成falsegit config core.ignorecase false这个操作在特定场景下确实有效但它的表现可能跟你预期的不太一样。假设索引里存的是readme.md磁盘上是已经改好的README.md改成false之后执行git status你会看到两段内容deleted: readme.md Untracked files: README.md这个输出说明 Git 从此把readme.md和README.md当成两个完全不同的路径索引里的旧路径在磁盘上找不到了于是判定为删除磁盘上出现了一个索引里从未有过的新路径于是判定为新增。接下来你只要执行git add -A把删除和新增一起暂存Git 会自行完成重命名检测最终状态里大概率显示为renamed: readme.md - README.md。但我还是要把丑话说在前面不建议把core.ignorecase false当成永久配置。原因有三个。第一在大小写不敏感的文件系统上一旦 Git 开始区分大小写、而操作系统依然不区分就会出现Git 认为存在两个文件、文件系统却只允许一个文件的荒诞局面。轻则每次git status都报告一堆奇怪的变化重则某些命令直接卡在文件已存在的报错里。第二如果你的仓库历史里恰好有一个先提交小写、后来某次提交又改成了大写的旧记录那么切换配置会导致过去所有相关提交的 diff 突然变大git log看历史时会出现大量莫名删除再添加非常干扰后续排查。第三这个配置是写在仓库本地的。如果你把core.ignorecase false的经验传给团队里 Windows 上的其他成员而他们不完全理解后果很容易在合并时制造出一堆大小写冲突。3.3 正确的手术刀式用法临时改、用完改回我的实际建议是把core.ignorecase当手术刀用而不是当日常配置穿在身上。一次典型的手术流程是这样的# 1. 临时关闭大小写忽略 git config core.ignorecase false # 2. 确认变更内容 git status # 3. 把重命名/删除/新增全部暂存 git add -A # 4. 检查暂存区里的最终效果 git status # 5. 提交 git commit -m chore: normalize file name case # 6. 提交完成后恢复原来的配置 git config core.ignorecase true为什么要提交完成之后再改回true因为提交行为发生的那一刻索引已经写入了正确的大小写路径后面的所有常规操作又回到了大小写无关的模式。这样既完成了目标又不影响长期的日常使用。如果你的仓库是克隆出来用于长期开发的恢复配置之后再执行一次git status确认工作区干净就可以彻底收尾了。4. Windows 用户的新思路让目录真正区分大小写4.1 fsutil 命令开启目录级大小写敏感Windows 10 从 1803 版本开始NTFS 支持按目录设置大小写敏感标志Windows 11 同样支持。换句话说你不需要给整个系统改设置只要针对某个仓库目录开启这个标志该目录下的文件就会像 ext4 那样区分大小写。设置命令非常简单但需要管理员权限。以管理员身份打开 CMD 或 PowerShell执行fsutil.exe file SetCaseSensitiveInfo D:\work\my-repo enable验证是否生效fsutil.exe file queryCaseSensitiveInfo D:\work\my-repo输出Enabled中文系统可能是已启用就说明成功了。这里有一个硬性条件必须记住执行这条命令时目标目录必须为空否则会直接报错。所以如果你要对一个已经 clone 好的仓库目录开启得先把目录里的内容临时挪到别处开启成功后再挪回来。挪回来的文件在目录被标记为大小写敏感之后就会按照它们真实的文件名大小写来存续。4.2 开启之后 Git 会怎么表现开启目录大小写敏感之后在这个目录里的体验就跟 Linux 几乎一致了。但要注意一个前置动作如果这个仓库此前已经有core.ignorecase true的配置需要同步改掉否则 Git 内部仍然用大小写无关的方式比对绕过了文件系统的敏感特性git config core.ignorecase false然后你可以直接在资源管理器或命令行把readme.md改成README.md再执行git statusren readme.md README.md git status这时候 Git 会敏感地察觉到变化显示deleted: readme.md和未跟踪的README.md再执行git add -A就能正常暂存并提交。也可以直接跨过改名动作用git mv readme.md README.md在这个目录下目标路径在文件系统层面是真实不存在的所以命令不会报destination exists。不过还有两点提醒。第一这个功能有个不太起眼的副作用系统更新、个别同步工具或杀毒软件可能会重置目录标志导致之前开启的大小写敏感失效。你如果发现某天 Git 又开始对大小写变更视而不见优先检查一下这个标志还在不在。第二开启标志的目录里如果某个应用是这个目录的常客而它没有考虑到大小写敏感文件系统的存在可能出现文件明明在但程序引用不到的怪问题。总体而言这个方案适合你明确知道这个目录就是给 Git 仓库专用、并且长期要搞大小写规范化的时候使用。4.3 WSL 场景下的补充思路顺带说一个 Windows 环境里很容易被忽略的场景WSL。如果你的开发环境主要是 WSLWindows Subsystem for Linux问题其实更简单。WSL 里的发行版文件系统是 ext4天生区分大小写你在 Linux 侧的路径比如~/projects/...里操作 Git 仓库git mv直接一步到位根本不存在这里讨论的坑。容易踩的反而是跨盘操作从 Windows 侧比如/mnt/c/...也就是 C 盘访问文件时走的是 drvfs行为跟 NTFS 一致而在 Linux 侧~/...访问时行为跟 ext4 一致。如果你一会儿在/mnt/c/...下跑 Git一会儿又切到~/下跑 Git同一个仓库在两种语义下可能给出完全不同的状态输出。我的建议很明确只要你的仓库主要靠 Git 管理就把它放在 WSL 的 Linux 侧Windows 侧的文件夹留给不讲究大小写的日常资料。5. macOS 同样有坑APFS 镜像与跨平台文件冲突5.1 macOS 默认的 APFS 也是保留大小写但不敏感macOS 的情况比 Windows 更隐蔽因为从外观上你几乎感觉不到它不区分大小写。APFS 的默认格式就叫APFS在这个格式下文件系统不区分大小写但保留大小写只有你手动选择APFS区分大小写这个变体它才会表现出跟 ext4 类似的语义。绝大多数 Mac 用户根本不会注意磁盘格式的差异所以这个问题在 macOS 上同样高发而且因为 Finder 对大小写表现得过于自然很多人甚至意识不到自己踩了坑。macOS 上的解决方案跟前面通用方案完全一致两段式git mv或rm --cached之后再add。举个例子git mv appconfig.ts appconfig.tmp git mv appconfig.tmp appConfig.ts或者你已经用 Finder 改好了名git rm --cached appconfig.ts git add appConfig.ts这两套操作在 macOS 上的表现跟在 Windows 上没有本质区别所以这里不再复述。重点说一个 macOS 用户更容易忽略的长期方案。5.2 不需要重装系统做一个区分大小写的磁盘镜像如果你经常跟一些对大小写敏感的开源项目打交道这类项目数量相当多尤其是涉及构建脚本、资源文件路径的项目又不想为了迁就文件系统把整个 Mac 重新格式化一个很实用的办法是用磁盘工具创建一个大小写敏感的稀疏磁盘镜像专门用来放 Git 仓库。操作路径打开磁盘工具→ 菜单栏文件→ 新建镜像 → 空白镜像。在弹出的窗口里重点设置两个地方格式选择APFS区分大小写。如果你的 macOS 版本较旧没有这个选项就选Mac OS 扩展区分大小写。大小按项目规模来比如 20GB建议勾选稀疏镜像这样镜像文件不会一次性占满磁盘用多少涨多少。创建完成后把它挂载到桌面Finder 里就会出现一个新的磁盘卷。把你的仓库 clone 到这个卷里之后在这个卷里执行任何 Git 操作都不用担心大小写问题。我自己就在这个镜像里同时放了好几个前端项目日常编译、重命名、跨分支合并都没有再被大小写坑过。5.3 跨平台协作的隐藏雷区仓库里真的存在两个大小写同名文件上面所有讨论都是你想把文件从一种大小写改成另一种但还有一种更隐蔽的坑值得单独提一下如果仓库里通常是 Linux 上的成员提交进去的同时存在Utils.ts和utils.ts这两个文件Windows 和 macOS 的开发者在 clone 这个仓库时会非常难受。因为文件系统不区分大小写这两个文件在本地会互相覆盖最终只会留下其中一个更糟的情况下Git 在 checkout 阶段就会因为目标已存在而失败。处理这个问题的唯一正确姿势是回到一个大小写敏感的环境Linux、WSL、或者前面说的 macOS 大小写敏感镜像里把其中一个文件重命名提交一个消除大小写冲突的修复提交然后再让 Windows/macOS 的同事重新拉取。只要仓库本身不再有这种大小写重名文件跨平台协作才能稳定下来。6. 把功夫花在平时文件名规范与自查清单6.1 一个最简单却最有效的约定文件名全小写回顾我自己踩坑和被同事拉去救火的经历解决这类问题的成本其实远高于预防成本。最省心的一条约定就是新项目从第一天开始统一约定文件名规则。社区里大量开源项目选择全小写加连字符的命名方式如user-profile.ts、api-client.js不是为了好看而是从根本上杜绝了两个文件只有大小写不同这种局面的出现。文件系统不区分大小写的平台上全小写规则不会引发任何歧义区分大小写的平台上它也是能直接照搬的统一标准。如果你的项目已经有了一定历史短期内没办法全部重命名那至少约定一条红线任何人不得只修改文件大小写而不通知团队。大小写的变更必须配套一次独立的 commit并且在这个 commit 里明确说明目的方便在 Windows/macOS 上开发的成员第一时间感知避免合并时出现我改了文件名怎么什么都没发生的混乱。这条红线我用实践验证过非常有效。6.2 我的排查顺序从配置到索引再到操作最后分享一套我自己反复在用的排查流程。遇到文件名改了但 Git 没反应时按下面这个顺序走五分钟内能定位执行git config core.ignorecase确认当前仓库是否运行在大小写不敏感模式。输出true就说明命中了本文讨论的场景。执行git ls-files | grep -i 文件名看清楚索引里存储的原始路径到底是什么。别凭记忆猜磁盘上的显示和索引里的存储不一定一致。执行git status --porcelain确认是否有其他未被察觉的变更。如果输出为空问题基本可以锁定在大小写跟踪上。根据操作方式选方案还没改名的用两段式git mv已经用资源管理器改好名的用git rm --cachedgit add。解决后顺手检查一下是否有团队其他成员可能受影响的文件有的话在提交信息里写清楚避免别人在合并时重复踩坑。这套流程我发给过项目组里好几个新同事反馈都是原来不是 Git 坏了。它不涉及任何复杂命令核心就是先弄清楚Git 到底在用什么规则看路径再决定怎么动手。最后再补一条个人心得如果项目有 CONTRIBUTING 文档我会顺手在开头写一句文件名一律使用小写禁止仅大小写不同的重命名。别小看这句话它能在未来的几百次提交里帮你把今天这篇文章里的坑绝大部分都挡在门外。
Git无视文件名大小写变更？一文讲透原理与解决方案
有一回我把项目里的readme.md改成README.md想着让命名更规范一点。改完顺手执行git status结果屏幕上干干净净一行变化都没有。那一瞬间我以为是 Git 出了什么问题甚至怀疑自己是不是改错了文件。后来翻了半天资料才明白这既不是 Git 的 bug也不是我操作失误而是 Git 在不区分大小写的文件系统上为了能正常工作而做了一次自我妥协。这个问题在网上被反复搜了很多年关键词永远绕不开git 文件名称大小写、跟踪不到在 Windows 和 macOS 这两个主力开发平台上几乎每个开发者早晚都会遇到一次。这篇文章就把来龙去脉拆开讲清楚Git 为什么会看不见大小写变更最稳的几种解决思路分别怎么做Windows 和 macOS 上还有哪些文件系统层面的处理办法最后是我自己沉淀下来的一套预防习惯和五分钟排查顺序新手和已经在这上面浪费过半天时间的同学都能直接照着操作。1. 改了却看不到变化Git 的大小写盲区究竟卡在哪1.1 先分清文件系统身上的大小写性格要搞清楚这个问题首先要接受一个事实同一套文件名大小写规则在不同的操作系统上根本不是一回事。我们可以把主流平台分成三种性格下面这张表我用了很多年每次给同事讲这个问题都先甩出这张表平台常见文件系统默认是否区分大小写是否保留大小写Linuxext4 / xfs / btrfs区分—WindowsNTFS不区分保留macOSAPFS / HFS不区分保留先看 Linux。ext4 这类文件系统在路径层面就把readme.md和README.md当成两个完全不同的文件所以你可以理直气壮地把两个文件同时放进同一个目录。Windows 的 NTFS 则完全是另一套逻辑它默认不区分大小写也就是说readme.md和README.md在系统眼里是同一个文件你不可能让它们同时存在。但它有一个很容易被人忽略的特性保留大小写。系统虽然不区分大小写却会记住你创建文件时写下的大小写形式并在资源管理器里始终用这个形式展示给你。macOS 的默认 APFS 和旧的 HFS 表现跟 NTFS 几乎一样同样是不区分、但保留。这个差异直接决定了后面 Git 的每一步表现。你可以做一个最简单的小实验来验证在 Linux 上执行mkdir test touch test/readme.md touch test/README.md两个文件能成功创建换到 Windows 的 CMD 里执行同样的命令第二句会直接报文件已存在。这就是文件系统性格差异最直观的体现。1.2 core.ignorecaseGit 在初始化时就悄悄做的决定Git 在设计上其实是一套大小写敏感的系统因为它的诞生环境就是 Linux 这种天然区分大小写的世界。但为了能在 Windows 和 macOS 上正常干活Git 做了一个自我妥协在git init或git clone的时候主动探测当前文件系统是否区分大小写如果不区分它就在仓库本地的.git/config里写上一行配置ignorecase true这行配置的意思非常直白Git 在比较文件路径时忽略大小写差异。默认情况下它是跟随文件系统走的——在 Linux 上初始化的仓库core.ignorecase基本都是false或者干脆不写这一项在 Windows、macOS 上初始化的仓库它十有八九是true。你可以在任意仓库里执行下面这条命令确认当前值git config core.ignorecase如果输出true那你遇到文件名大小写变更不被跟踪就一点都不奇怪了Git 把readme.md和README.md当作同一个路径你在工作区把前者改成后者在 Git 眼里路径压根没变git status自然什么都不显示。Git 不是偷懒它是在用路径比对不区分大小写这种方式换取在大小写不敏感文件系统上的基本可用性。1.3 为什么 Git 的重命名检测也失灵了有经验的同学可能会追问就算忽略大小写我把readme.md重命名成README.md的过程中文件内容完全没变Git 不是应该通过内容相似度把这识别成一次 rename 吗答案是在core.ignorecase true的情况下Git 做路径比对时先就把新旧路径当成同一个文件了根本没有进入旧文件消失、新文件出现的判断流程。连 rename 的候选对象都不存在相似度检测自然无从谈起。具体到现象上就是那几种非常经典的迷惑现场git status一片空白什么都没显示用git status --porcelain看同样为空在 Windows 上执行git mv readme.md README.md直接报fatal: destination exists你以为 commit 能带上去结果git commit告诉你nothing to commit, working tree clean。这些现象本质上都指向同一个原因你的仓库被配置成了一个大小写不敏感的比对环境而你又试图在其中有意识地制造一个大小写敏感的变更。方向拧了结果就是卡住。下面几节就针对这个局面给出不同场景下的解决方案。2. 先别动配置两段式 git mv 一次搞定大小写重命名2.1 直接 git mv 为什么会失败知道了机制再看为什么看上去最正规的git mv命令在 Windows 上常常直接报错就很好理解了。在 Linux 上执行git mv readme.md README.md一切正常Git 会直接完成重命名并把变更放入暂存区。原因很简单ext4 认为README.md是一个全新的路径根本不存在所以没有任何冲突。但在 Windows 或 macOS 上文件系统不区分大小写git mv执行时会先去检查目标路径README.md是否存在。这个存在的判断同样是大小写无关的所以它会发现readme.md已经存在于是抛出fatal: destination exists, sourcereadme.md, destinationREADME.md。你可能会觉得这是误报但对 Git 来说它没有能力突破文件系统层面的限制。某些 Git 版本加了-f参数后能强行通过但不是所有环境都可靠所以我不推荐把它当首选方案。2.2 两段式重命名的完整操作解决方案其实非常朴素既然目标路径看似存在那就先让目标路径真实地不存在再把大小写改对。具体做法是借用第三个临时名字把一个单步操作拆成两步git mv readme.md readme.tmp git mv readme.tmp README.md先看第一步git mv readme.md readme.tmp目标readme.tmp在文件系统和索引里都不存在所以必定成功。此时工作区里已经没有readme.md只有readme.tmp。再看第二步git mv readme.tmp README.md此刻无论从文件系统还是 Git 索引来看README.md都不存在所以也必定成功。两步走完索引里的路径被更新成了README.md文件内容完好无损。执行完再看一眼状态git status你会看到类似下面的结果renamed: readme.md - README.md注意是renamed不是deleted加new file因为 Git 在状态展示里做了重命名检测识别出文件内容没有变化、只是路径变了。这里再补一条很实用的小经验临时名字别乱起要跟新旧文件名保持足够的差异。比如你在改AppConfig.ts和appConfig.ts之间来回折腾时临时名别选appconfig.tmp这种依然跟原文件名存在大小写歧义的名字直接用aaa_temp_rename.tmp这种绝对不冲突的名字最省心。2.3 目录名的大小写同样适用如果你要改的不是文件而是目录比如想把src/Utils改成src/utils两段式逻辑完全一样git mv src/Utils src/utils.tmp git mv src/utils.tmp src/utils第一句先把目录整体挪到一个中性的临时名字第二句再把目录挪到正确的大小写形式。Git 会把目录下的所有文件一并处理状态里会显示一批文件路径的变化。这一步在 Windows 上比文件重命名更容易翻车因为目录下的文件数量多任何一层路径判断出问题都会连坐所以拆成两步格外重要。不要想着一步到位省下的那点操作时间往往会在排查问题时加倍还回去。2.4 已经在文件管理器里改过名了怎么办还有一种极其常见的情况你没有用git mv而是在资源管理器或者 IDE 的文件树里直接把文件改成了新的大小写。此时磁盘上的文件名已经变了但 Git 索引里还保留着旧路径。这时候不需要再git mv用删索引、再重新添加的办法更直接git rm --cached readme.md git add README.md第一句git rm --cached并不是删除磁盘文件它只是把名为readme.md的这条路径从 Git 索引里摘掉第二句git add README.md则把磁盘上现存的README.md以新路径加回索引。两步之后git status就能看到 rename 或者 delete/add 的变化接着正常 commit 就可以。这里有个细节值得多写一句git rm --cached后面跟的文件名必须跟索引里存的原始路径一致尤其是大小写。如果你索引里存的是readme.md你写git rm --cached README.md在core.ignorecase true的情况下它也可能匹配上但为了稳妥建议先执行git ls-files | grep -i readme看一眼索引里到底存的什么名字再决定怎么写。这个习惯能帮你避免删了一个空路径啥变化都没有的尴尬。3. core.ignorecase 到底能不能改配置层面的利与弊3.1 先把当前配置和索引里的真实路径摸清楚动手之前先执行三条命令把现场情况摸清git config core.ignorecase git config --show-origin --get core.ignorecase git ls-files | grep -i readme第一条输出当前仓库的core.ignorecase值第二条能看出这个配置是写在仓库本地的.git/config里还是来自~/.gitconfig方便你判断改动的影响范围第三条会列出索引中所有包含 readme忽略大小写的路径让你明确 Git 眼中这个文件名到底是什么样。三条命令在整个排查过程中可以反复使用心里有数之后再动手比盲改配置强得多。3.2 设成 false 之后会出现什么局面网上很多答案会让你直接把core.ignorecase改成falsegit config core.ignorecase false这个操作在特定场景下确实有效但它的表现可能跟你预期的不太一样。假设索引里存的是readme.md磁盘上是已经改好的README.md改成false之后执行git status你会看到两段内容deleted: readme.md Untracked files: README.md这个输出说明 Git 从此把readme.md和README.md当成两个完全不同的路径索引里的旧路径在磁盘上找不到了于是判定为删除磁盘上出现了一个索引里从未有过的新路径于是判定为新增。接下来你只要执行git add -A把删除和新增一起暂存Git 会自行完成重命名检测最终状态里大概率显示为renamed: readme.md - README.md。但我还是要把丑话说在前面不建议把core.ignorecase false当成永久配置。原因有三个。第一在大小写不敏感的文件系统上一旦 Git 开始区分大小写、而操作系统依然不区分就会出现Git 认为存在两个文件、文件系统却只允许一个文件的荒诞局面。轻则每次git status都报告一堆奇怪的变化重则某些命令直接卡在文件已存在的报错里。第二如果你的仓库历史里恰好有一个先提交小写、后来某次提交又改成了大写的旧记录那么切换配置会导致过去所有相关提交的 diff 突然变大git log看历史时会出现大量莫名删除再添加非常干扰后续排查。第三这个配置是写在仓库本地的。如果你把core.ignorecase false的经验传给团队里 Windows 上的其他成员而他们不完全理解后果很容易在合并时制造出一堆大小写冲突。3.3 正确的手术刀式用法临时改、用完改回我的实际建议是把core.ignorecase当手术刀用而不是当日常配置穿在身上。一次典型的手术流程是这样的# 1. 临时关闭大小写忽略 git config core.ignorecase false # 2. 确认变更内容 git status # 3. 把重命名/删除/新增全部暂存 git add -A # 4. 检查暂存区里的最终效果 git status # 5. 提交 git commit -m chore: normalize file name case # 6. 提交完成后恢复原来的配置 git config core.ignorecase true为什么要提交完成之后再改回true因为提交行为发生的那一刻索引已经写入了正确的大小写路径后面的所有常规操作又回到了大小写无关的模式。这样既完成了目标又不影响长期的日常使用。如果你的仓库是克隆出来用于长期开发的恢复配置之后再执行一次git status确认工作区干净就可以彻底收尾了。4. Windows 用户的新思路让目录真正区分大小写4.1 fsutil 命令开启目录级大小写敏感Windows 10 从 1803 版本开始NTFS 支持按目录设置大小写敏感标志Windows 11 同样支持。换句话说你不需要给整个系统改设置只要针对某个仓库目录开启这个标志该目录下的文件就会像 ext4 那样区分大小写。设置命令非常简单但需要管理员权限。以管理员身份打开 CMD 或 PowerShell执行fsutil.exe file SetCaseSensitiveInfo D:\work\my-repo enable验证是否生效fsutil.exe file queryCaseSensitiveInfo D:\work\my-repo输出Enabled中文系统可能是已启用就说明成功了。这里有一个硬性条件必须记住执行这条命令时目标目录必须为空否则会直接报错。所以如果你要对一个已经 clone 好的仓库目录开启得先把目录里的内容临时挪到别处开启成功后再挪回来。挪回来的文件在目录被标记为大小写敏感之后就会按照它们真实的文件名大小写来存续。4.2 开启之后 Git 会怎么表现开启目录大小写敏感之后在这个目录里的体验就跟 Linux 几乎一致了。但要注意一个前置动作如果这个仓库此前已经有core.ignorecase true的配置需要同步改掉否则 Git 内部仍然用大小写无关的方式比对绕过了文件系统的敏感特性git config core.ignorecase false然后你可以直接在资源管理器或命令行把readme.md改成README.md再执行git statusren readme.md README.md git status这时候 Git 会敏感地察觉到变化显示deleted: readme.md和未跟踪的README.md再执行git add -A就能正常暂存并提交。也可以直接跨过改名动作用git mv readme.md README.md在这个目录下目标路径在文件系统层面是真实不存在的所以命令不会报destination exists。不过还有两点提醒。第一这个功能有个不太起眼的副作用系统更新、个别同步工具或杀毒软件可能会重置目录标志导致之前开启的大小写敏感失效。你如果发现某天 Git 又开始对大小写变更视而不见优先检查一下这个标志还在不在。第二开启标志的目录里如果某个应用是这个目录的常客而它没有考虑到大小写敏感文件系统的存在可能出现文件明明在但程序引用不到的怪问题。总体而言这个方案适合你明确知道这个目录就是给 Git 仓库专用、并且长期要搞大小写规范化的时候使用。4.3 WSL 场景下的补充思路顺带说一个 Windows 环境里很容易被忽略的场景WSL。如果你的开发环境主要是 WSLWindows Subsystem for Linux问题其实更简单。WSL 里的发行版文件系统是 ext4天生区分大小写你在 Linux 侧的路径比如~/projects/...里操作 Git 仓库git mv直接一步到位根本不存在这里讨论的坑。容易踩的反而是跨盘操作从 Windows 侧比如/mnt/c/...也就是 C 盘访问文件时走的是 drvfs行为跟 NTFS 一致而在 Linux 侧~/...访问时行为跟 ext4 一致。如果你一会儿在/mnt/c/...下跑 Git一会儿又切到~/下跑 Git同一个仓库在两种语义下可能给出完全不同的状态输出。我的建议很明确只要你的仓库主要靠 Git 管理就把它放在 WSL 的 Linux 侧Windows 侧的文件夹留给不讲究大小写的日常资料。5. macOS 同样有坑APFS 镜像与跨平台文件冲突5.1 macOS 默认的 APFS 也是保留大小写但不敏感macOS 的情况比 Windows 更隐蔽因为从外观上你几乎感觉不到它不区分大小写。APFS 的默认格式就叫APFS在这个格式下文件系统不区分大小写但保留大小写只有你手动选择APFS区分大小写这个变体它才会表现出跟 ext4 类似的语义。绝大多数 Mac 用户根本不会注意磁盘格式的差异所以这个问题在 macOS 上同样高发而且因为 Finder 对大小写表现得过于自然很多人甚至意识不到自己踩了坑。macOS 上的解决方案跟前面通用方案完全一致两段式git mv或rm --cached之后再add。举个例子git mv appconfig.ts appconfig.tmp git mv appconfig.tmp appConfig.ts或者你已经用 Finder 改好了名git rm --cached appconfig.ts git add appConfig.ts这两套操作在 macOS 上的表现跟在 Windows 上没有本质区别所以这里不再复述。重点说一个 macOS 用户更容易忽略的长期方案。5.2 不需要重装系统做一个区分大小写的磁盘镜像如果你经常跟一些对大小写敏感的开源项目打交道这类项目数量相当多尤其是涉及构建脚本、资源文件路径的项目又不想为了迁就文件系统把整个 Mac 重新格式化一个很实用的办法是用磁盘工具创建一个大小写敏感的稀疏磁盘镜像专门用来放 Git 仓库。操作路径打开磁盘工具→ 菜单栏文件→ 新建镜像 → 空白镜像。在弹出的窗口里重点设置两个地方格式选择APFS区分大小写。如果你的 macOS 版本较旧没有这个选项就选Mac OS 扩展区分大小写。大小按项目规模来比如 20GB建议勾选稀疏镜像这样镜像文件不会一次性占满磁盘用多少涨多少。创建完成后把它挂载到桌面Finder 里就会出现一个新的磁盘卷。把你的仓库 clone 到这个卷里之后在这个卷里执行任何 Git 操作都不用担心大小写问题。我自己就在这个镜像里同时放了好几个前端项目日常编译、重命名、跨分支合并都没有再被大小写坑过。5.3 跨平台协作的隐藏雷区仓库里真的存在两个大小写同名文件上面所有讨论都是你想把文件从一种大小写改成另一种但还有一种更隐蔽的坑值得单独提一下如果仓库里通常是 Linux 上的成员提交进去的同时存在Utils.ts和utils.ts这两个文件Windows 和 macOS 的开发者在 clone 这个仓库时会非常难受。因为文件系统不区分大小写这两个文件在本地会互相覆盖最终只会留下其中一个更糟的情况下Git 在 checkout 阶段就会因为目标已存在而失败。处理这个问题的唯一正确姿势是回到一个大小写敏感的环境Linux、WSL、或者前面说的 macOS 大小写敏感镜像里把其中一个文件重命名提交一个消除大小写冲突的修复提交然后再让 Windows/macOS 的同事重新拉取。只要仓库本身不再有这种大小写重名文件跨平台协作才能稳定下来。6. 把功夫花在平时文件名规范与自查清单6.1 一个最简单却最有效的约定文件名全小写回顾我自己踩坑和被同事拉去救火的经历解决这类问题的成本其实远高于预防成本。最省心的一条约定就是新项目从第一天开始统一约定文件名规则。社区里大量开源项目选择全小写加连字符的命名方式如user-profile.ts、api-client.js不是为了好看而是从根本上杜绝了两个文件只有大小写不同这种局面的出现。文件系统不区分大小写的平台上全小写规则不会引发任何歧义区分大小写的平台上它也是能直接照搬的统一标准。如果你的项目已经有了一定历史短期内没办法全部重命名那至少约定一条红线任何人不得只修改文件大小写而不通知团队。大小写的变更必须配套一次独立的 commit并且在这个 commit 里明确说明目的方便在 Windows/macOS 上开发的成员第一时间感知避免合并时出现我改了文件名怎么什么都没发生的混乱。这条红线我用实践验证过非常有效。6.2 我的排查顺序从配置到索引再到操作最后分享一套我自己反复在用的排查流程。遇到文件名改了但 Git 没反应时按下面这个顺序走五分钟内能定位执行git config core.ignorecase确认当前仓库是否运行在大小写不敏感模式。输出true就说明命中了本文讨论的场景。执行git ls-files | grep -i 文件名看清楚索引里存储的原始路径到底是什么。别凭记忆猜磁盘上的显示和索引里的存储不一定一致。执行git status --porcelain确认是否有其他未被察觉的变更。如果输出为空问题基本可以锁定在大小写跟踪上。根据操作方式选方案还没改名的用两段式git mv已经用资源管理器改好名的用git rm --cachedgit add。解决后顺手检查一下是否有团队其他成员可能受影响的文件有的话在提交信息里写清楚避免别人在合并时重复踩坑。这套流程我发给过项目组里好几个新同事反馈都是原来不是 Git 坏了。它不涉及任何复杂命令核心就是先弄清楚Git 到底在用什么规则看路径再决定怎么动手。最后再补一条个人心得如果项目有 CONTRIBUTING 文档我会顺手在开头写一句文件名一律使用小写禁止仅大小写不同的重命名。别小看这句话它能在未来的几百次提交里帮你把今天这篇文章里的坑绝大部分都挡在门外。
