Git 删除远程文件、本地保留并取消跟踪

Git 删除远程文件、本地保留并取消跟踪

背景

有时需要将某个文件从 Git 仓库中移除（不再版本控制），但保留本地文件不删除。典型场景：误提交了配置文件、密钥、编译产物等。

操作步骤

1. 将文件添加到 .gitignore

echo "path/to/file" >> .gitignore

目录同理：

echo "path/to/dir/" >> .gitignore

2. 从暂存区移除跟踪（不删除本地文件）

# 单个文件
git rm --cached path/to/file

# 目录（递归）
git rm -r --cached path/to/dir/

3. 提交变更

git add .gitignore
git commit -m "remove file from tracking, keep local"

4. 推送到远程

git push

执行完成后：远程仓库中该文件被删除，本地文件完整保留，后续修改也不会被 git 跟踪。

原理说明

Git 三个区域

工作区 (Working Directory)  →  暂存区 (Index/Cache)  →  仓库 (Repository)
       实际文件                     git 跟踪的快照             提交历史

–cached 参数的含义

--cached 表示只操作暂存区，不动工作区的实际文件。

注意事项

• 操作前建议先确认 .gitignore 规则已正确配置，否则下次 git add . 会把文件重新加回来。
• 如果文件包含密钥或敏感信息，仅删除远程文件不够——历史提交中仍有记录，需用 git filter-branch 或 git filter-repo 彻底清除历史。
• 团队协作时，其他成员 pull 后本地该文件会被删除，需提前告知。