first-contributions 指南：使用 git rm --cached 从 Git 仓库移除文件而不删除本地副本

first-contributions 指南使用 git rm --cached 从 Git 仓库移除文件而不删除本地副本【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本指南基于 first-contributions 仓库的进阶文档 docs/additional-material/git_workflow_scenarios/removing-a-file.md 编写。当你误提交了本不该入库的文件如配置文件、构建产物或敏感信息但又不想丢失本地文件时git rm --cached是标准解法。读完本文你将掌握仅从 Git 跟踪中移除文件、批量移除、通配符匹配以及它与.gitignore、提交推送流程的完整配合方式。适用场景什么时候需要只移除跟踪不删除文件在参与开源贡献例如为本仓库 first-contributions 提交贡献或日常开发时你经常会遇到这种情况某个文件已经被git add提交过但现在你不希望它继续被版本控制该文件对你本地开发仍然有用不能从磁盘上删除该文件属于个人配置、环境变量、密钥、构建产物等不应出现在公共仓库中的内容。此时如果直接使用git rm fileGit 会把文件同时从仓库索引和你的文件系统中删除这显然不是你想要的结果。first-contributions 文档给出的核心命令是git rm file --cached这一条命令只把文件从 Git 的**索引index / staging area**中移除磁盘上的文件原封不动。命令背后的原理Git 到底移除了什么要理解--cached的作用需要先明确 Git 中一个文件同时存在的三种状态工作区Working Directory磁盘上实际存在的文件暂存区 / 索引Staging Area / Indexgit add后暂存的内容下一次提交的内容快照版本库Repository / HEAD已经提交的历史版本。git rm file --cached的本质是从索引中删除该文件的记录并把这次删除标记为已暂存的更改。正如原文档所说Git 将不再跟踪该文件的更改对 Git 而言就像你删除了这个文件。但如果你在文件系统中查找会发现它依然还在。也就是说从 Git 的视角看文件不存在了从操作系统的视角看文件从未被动过。与原文档配套的仓库佐证该主题在本仓库并非孤立存在docs/additional-material/git_workflow_scenarios/creating-a-gitignore-file.md.gitignore 指南的 Removing Files from Git Tracking 一节明确把git rm --cached filename定义为解除跟踪但保留本地文件Untrack a single file (but keep it locally)与本指南互为补充——.gitignore 只对尚未跟踪的文件生效已提交文件必须先用本指南的方法解除跟踪这正是两个文档衔接的关键点。带 --cached 与不带 --cached 的区别这是初学者最容易混淆的地方原文档专门用一段说明了两者的差异命令索引跟踪工作区磁盘文件适用场景git rm file --cached✅ 移除❌ 保留文件不再入库但本地继续使用git rm file✅ 移除✅ 同时删除彻底删除文件并停止跟踪⚠️风险提示省略--cached时Git 不仅会停止跟踪该文件还会直接从你的文件系统中删除它。对于误操作了git rm file未加--cached的情况如果改动尚未提交可以用git reset HEAD file之类的操作尝试恢复索引状态但最稳妥的做法始终是先确认文件内容已备份再执行删除类命令。完整操作流程移除 → 提交 → 推送原文档给出了完整的后续步骤组合起来就是一个可复制的标准流程# 1. 将文件移出 Git 跟踪保留本地副本 git rm file --cached # 2. 提交这次删除记录到版本历史 git commit -m Remove file1.js # 3. 推送到远程仓库远程也会移除该文件 git push origin main要点说明提交是必须的git rm --cached只是把变更放入暂存区只有执行git commit后停止跟踪才会成为版本历史中的一次提交之后git push才会让远程仓库同步移除该文件分支名按实际情况填写原文档示例使用git push origin main而部分中文翻译版本写作master。分支名应替换为你当前实际推送的分支可用git branch查看如果使用本仓库的贡献流程则通常是git push origin add-your-name这样的特性分支推送前确认如果该文件此前包含敏感信息密钥、密码仅移除跟踪并不能清除 Git 历史中的旧内容这类情况需要额外的历史重写手段git rm --cached只负责从此不再跟踪。批量操作多文件与通配符原文档的 Additional features 一节提供了两种批量移除方式都值得完整掌握一次移除多个文件git rm file1.js file2.js file3.js --cached把需要解除跟踪的文件名依次列在git rm之后即可适用于文件数量不多、文件名明确的场景。使用通配符*批量匹配git rm *.txt --cached该命令会把当前目录下所有.txt文件一次性移出跟踪。例如在你的本地仓库中如果有一批临时生成的.txt文件被误跟踪一行命令即可全部清理。进阶递归移除目录对于目录及子目录下的文件通常还需要配合-r选项。仓库中的 creating-a-gitignore-file.md 提供了完整示例# 将整个仓库所有已跟踪文件移出跟踪配合 .gitignore 一次性重建跟踪关系 git rm -r --cached . git add . git commit -m Updated .gitignore这是一个非常实用的组合拳当新增了大量.gitignore规则后用git rm -r --cached .清除全部索引记录再git add .按新规则重新跟踪即可让忽略规则全面生效。撤销操作如何反悔执行git rm --cached后如果发现不该移除或想重新跟踪该文件在尚未提交前可以轻松撤销——同样来自仓库文档的说明git add file重新git add会把文件再次加入暂存区、恢复跟踪状态。这也说明git rm --cached本身只作用于索引不触碰文件内容因此可逆性很好。与 .gitignore 配合正确的工作流在 first-contributions 的进阶材料中.gitignore与git rm --cached是最常见的搭档两者的分工如下先用git rm --cached解除已跟踪文件的跟踪即本文主题参考 removing-a-file.md再把该文件或其模式写入.gitignore防止未来再次被git add误纳入参考 creating-a-gitignore-file.md 中的基础语法*通配、/路径、#注释提交并推送上述两步的变更。如果跳过第 1 步只添加.gitignore已跟踪的文件不会自动停止跟踪这也是许多初学者困惑我明明写了 .gitignore 为什么文件还在仓库里的根本原因。在开源贡献流程中的位置本指南属于 first-contributions 仓库的进阶 Git 工作流场景之一与其它进阶主题共同收录在 additional-material.md 索引页中。若你正在参与本仓库的贡献添加自己的名字到 Contributors 列表通常会先在特性分支上操作完成移除文件等清理工作后再走git push发起 Pull Request分支合并后如需清理可参考 removing-branch-from-your-repository.md 删除本地与远程分支。该主题的中文版本见 removing-a-file.zh-cn.md另有十余种语言的翻译可供对照。小结需求命令停止跟踪单个文件、保留本地副本git rm file --cached停止跟踪多个文件git rm file1.js file2.js file3.js --cached按通配符批量停止跟踪git rm *.txt --cached停止跟踪并删除本地文件git rm file慎用提交移除动作git commit -m Remove file1.js同步到远程git push origin branch撤销移除、恢复跟踪git add file与 .gitignore 配合全量重建跟踪git rm -r --cached . git add .核心原则只有一句话只要加上--cachedGit 就只忘记文件而不删除文件。掌握这一命令你就能在任何开源项目包括本仓库中安全地管理哪些文件应该进入版本历史。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考