.gitignore 沒生效？已追蹤檔案要先從 Git 暫存區移除

2026-10-27

工具推薦

Git

/

DevOps

/

開發工具

/

疑難排解

把 local settings.txt 寫進 .gitignore，修改後卻仍出現在 git status，先確認檔案是否已被追蹤。.gitignore 控制未追蹤檔案的忽略規則，不會讓既有 tracked file 自動離開 Git。 規則可能完全正確，只是作用對象不符。

如果目標是讓後續版本不再包含這個檔案，同時保留自己的本機副本，應對確認過的確切路徑使用 git rm --cached，再審查暫存區。不要為了一個檔案重建整個 index。

.gitignore 規則與追蹤狀態分開查#

以下在出問題的 repository 根目錄執行，將範例路徑換成自己的檔案；空白路徑要保留引號：

1
git status --short -- 'local settings.txt'
2
git ls-files --error-unmatch -- 'local settings.txt'
3
git check-ignore -v --no-index -- 'local settings.txt'

ls-files --error-unmatch 找到路徑時會輸出它並成功結束；找不到時會回傳非零狀態。前者表示它已在 index，這時增加忽略規則不會讓修改消失。

依 check-ignore 文件，預設不顯示已追蹤檔案，因為那些檔案不受忽略規則控制。--no-index 讓你針對規則進行檢查，-v 顯示規則檔、行號與 pattern。這個選項只是診斷，不會修改 index。

若輸出 pattern 以 ! 開頭，代表否定規則；不能只因為有輸出，就說它會被忽略。沒有輸出時，檢查規則位置、大小寫與路徑，不要直接用強制參數掩蓋問題。gitignore 官方文件也說明，多個目錄層級的規則會參與判斷。

逐檔停止追蹤，先預覽再操作#

確認這個檔案應該從後續版本移除，並已備妥自己的副本後，才執行：

1
git rm --cached --dry-run -- 'local settings.txt'
2
git rm --cached -- 'local settings.txt'
3
git diff --cached --name-status -- 'local settings.txt'
4
git diff --cached -- 'local settings.txt'

git rm 文件說明，--cached 僅從 index 移除路徑，保留工作目錄的檔案。暫存差異出現 D 是預期結果：下一次包含這項變更的 commit 將不再追蹤它，並不代表這次指令刪掉本機副本。

如果 Git 因暫存內容與其他版本不一致而拒絕，先保存工作檔與暫存版本，再分別閱讀差異。不要立刻加 -f，也不要對整個 repository 執行遞迴移除。index 與工作檔案可能各有尚未提交的內容，可先用 git diff 三種比較辨識哪一份需要保留。

審查時也要確認 .gitignore 的規則有被納入預定提交。真正提交前檢閱全部已暫存檔案，避免把原本就存在的其他 staged 修改一起帶入；本文不提供一條包辦所有檔案的提交命令。

在暫存 repository 重現「本機還在，Git 已不追蹤」#

以下是完整 Bash 實驗，僅使用自行建立的 OS 暫存目錄與假資料，不操作目前專案。存成 ignore-check.sh 後執行 bash ignore-check.sh；需要 Git、rg 與 mktemp，完成後保留 fixture 供檢查。

1
#!/usr/bin/env bash
2
set -eu
3
fixture=$(mktemp -d)
4
git init -q "$fixture"
5
cd "$fixture"
6
git config user.name 'Fixture'
7
git config user.email 'fixture@example.invalid'
8
git config commit.gpgsign false
9

10
printf 'original\n' > 'local settings.txt'
11
git add -- 'local settings.txt'
12
git -c core.hooksPath=/dev/null commit -qm 'track fixture'
13
printf '/local settings.txt\n' > .gitignore
14
printf 'local edit\n' >> 'local settings.txt'
15

16
git ls-files --error-unmatch -- 'local settings.txt' > /dev/null
17
git check-ignore -v --no-index -- 'local settings.txt'
18
git rm --cached --dry-run -- 'local settings.txt'
19
git rm --cached -- 'local settings.txt'
20

21
test -f 'local settings.txt'
22
test "$(cat 'local settings.txt')" = "$(printf 'original\nlocal edit')"
23
if git ls-files --error-unmatch -- 'local settings.txt' > /dev/null 2>&1; then
24
  printf 'FAIL: still tracked\n' >&2
25
  exit 1
26
fi
27
git diff --cached --name-status -- 'local settings.txt' | rg '^D[[:space:]]'
28
git check-ignore -q -- 'local settings.txt'
29
# 停止追蹤尚未提交；舊 commit 的檔案仍可讀取。
30
test "$(git show 'HEAD:local settings.txt')" = original
31
printf 'PASS: local file kept; index removal staged; history unchanged\n'
32
printf 'Fixture: %s\n' "$fixture"