企业官网建设流程全解析

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 <file>，Git 会把文件同时从仓库索引和你的文件系统中删除，这显然不是你想要的结果。first-contributions 文档给出的核心命令是：

git rm <file> --cached

这一条命令只把文件从 Git 的**索引（index / staging area）**中移除，磁盘上的文件原封不动。

命令背后的原理：Git 到底"移除"了什么

要理解--cached的作用，需要先明确 Git 中一个文件同时存在的三种状态：

1. 工作区（Working Directory）：磁盘上实际存在的文件；
2. 暂存区 / 索引（Staging Area / Index）：git add后暂存的内容，下一次提交的内容快照；
3. 版本库（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 的区别

这是初学者最容易混淆的地方，原文档专门用一段说明了两者的差异：

⚠️风险提示：省略--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是最常见的搭档，两者的分工如下：

1. 先用git rm --cached解除已跟踪文件的跟踪（即本文主题，参考 removing-a-file.md）；
2. 再把该文件（或其模式）写入.gitignore，防止未来再次被git add误纳入（参考 creating-a-gitignore-file.md 中的基础语法：*通配、/路径、#注释）；
3. 提交并推送上述两步的变更。

如果跳过第 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，另有十余种语言的翻译可供对照。

小结

核心原则只有一句话：只要加上--cached，Git 就只"忘记"文件，而不"删除"文件。掌握这一命令，你就能在任何开源项目（包括本仓库）中安全地管理哪些文件应该进入版本历史。

【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions