一. 前言:只是寫個小程式,怎麼多了幾千個檔案? #
拍拍君剛寫好 app.py,準備把專案放上 GitHub。
打開變更清單,卻看到整個 .venv、一堆 __pycache__,還有本機的 .env。
真正寫的程式不到十行,等待加入版本控制的檔案卻有幾千個。
這時候需要的不是一個一個取消勾選,而是一份 .gitignore。
它告訴 Git:這些尚未追蹤的檔案,不要在一般新增流程中收進來。
今天用一個全新的練習資料夾,完成三件事:
- 排除虛擬環境、快取與本機設定。
- 確認規則真的命中,而不是憑感覺。
- 看懂為什麼「已經加入的檔案」不會自己消失。
如果你還沒用過 git add 和 commit,可以先看 Git 基本操作。
這篇不需要連上 GitHub,也不用真的放任何密碼。
二. 先拿到一個可以練習的專案 #
電腦需要裝好 Git 與 Python 3。
Windows 建議用 Git Bash 執行本文的 shell 指令;macOS、Linux 使用終端機即可。
如果你的 Python 指令是 python,把文中的 python3 換掉就好。
先確認工具能執行:
git --version
python3 --version
下載練習包,解壓縮後會得到 gitignore-practice 資料夾。
裡面有產生範例檔案的 prepare.py,以及可對照的 gitignore.example。
先不要把後者複製成 .gitignore,我們要先看看沒有規則時會發生什麼事。
在終端機進入剛解壓縮的資料夾,接著執行:
python3 prepare.py
git init
git status --short --untracked-files=all
準備程式只會在該資料夾建立練習用檔案。
若已存在同名範例檔案,它會停止而不是覆寫。
它不會下載套件;.venv 只是用來示範路徑的假資料夾。
你會看到類似這些項目,實際排列順序可能不同:
?? .env
?? .env.example
?? .venv/demo.txt
?? __pycache__/app.cpython-demo.pyc
?? app.py
另外還有練習包本身的說明檔、腳本與參考規則。
?? 表示 untracked:目前還沒被 Git 追蹤。
這不等於它們已經被送上網路;現在甚至還沒有 remote。
三. 先做出成果:一份小而夠用的 .gitignore #
在練習資料夾根目錄建立 .gitignore,內容如下:
# Python 環境與快取
.venv/
__pycache__/
*.pyc
# 本機環境設定;範本要保留
.env
.env.*
!.env.example
# 編輯器、作業系統產生的雜項
.vscode/
.idea/
.DS_Store
Thumbs.db
可以用任何純文字編輯器建立。
檔名就是 .gitignore,不是 .gitignore.txt。
Windows 若隱藏副檔名,記得確認一下。
也可以把練習包的 gitignore.example 複製成這個檔名。
再看一次狀態:
git status --short --untracked-files=all
這次 .env、.venv 和 __pycache__ 應該不見了。
app.py、.env.example 和 .gitignore 仍會出現。
這正是我們要的結果:自己的程式留下,重新產生的東西與本機設定先排除。
現在先別急著 git add .,下一節把規則讀懂,以後才知道怎麼改。
四. 不必背語法表,先記住這四種寫法 #
1. 一個檔名:.env
#
沒有斜線的這種規則,會比對此 .gitignore 所在範圍內、各層目錄的同名路徑。
所以根目錄的 .env 與 tools/.env 都會被忽略。
它不是「只排除根目錄那一個」的意思。
如果真的只想排除根目錄的那個,可以用 /.env。
本文的規則選擇各層都排除,比較適合這個小型 Python 專案。
2. 結尾有斜線:.venv/
#
結尾的 / 表示只匹配資料夾。
這裡不只根目錄,子目錄下同名的 .venv 資料夾也會被排除。
__pycache__/ 同理,不必為每個 Python 套件各寫一行。
虛擬環境通常可依依賴設定重建,不需要把安裝好的套件整包提交。 如果你還不熟環境與依賴的分工,可以看 Python 虛擬環境比較。
3. 星號:*.pyc
#
* 可以匹配名稱中的一串字元。
因此 app.pyc、helper.pyc 都會匹配。
這裡的 *.pyc 不含斜線,也會在子目錄比對檔名。
不用一開始就研究所有萬用字元。 先能排除具體的環境、快取與設定,已經能解決很多日常問題。
4. 驚嘆號:!.env.example
#
.env.* 會匹配 .env.local,也會匹配 .env.example。
但範本要跟程式一起交給別人,所以再加一行例外:
.env.*
!.env.example
對同一層級的規則,後面匹配的結果可以覆蓋前面。 因此例外要放在較廣的排除規則後面。 範本裡只放設定名稱與假值,別把真的 token 換個檔名塞進去。
還有一個先知道就好的限制:如果父資料夾整個被忽略,通常不能只用子檔案例外把它撈回來。
例如先寫 private/,再寫 !private/example.txt,並不會得到你想像的效果。
今天先不要設計這種多層例外,讓規則保持簡單。
五. 想知道「為什麼沒出現」?請 Git 指出規則 #
只看檔案從清單消失,還不夠安心。
用 check-ignore 問問它:
git check-ignore -v .env
git check-ignore -v .venv/demo.txt
git check-ignore -v __pycache__/app.cpython-demo.pyc
輸出會指出規則來源、行號、匹配的 pattern 和查詢路徑。 其中一行大致長這樣,行號取決於你的註解與空白行:
.gitignore:7:.env .env
如果忽略規則不是自己寫的,這個指令特別好用。
來源可能是其他層的 .gitignore,也可能是個人設定。
先找來源,再改規則,不用一遍遍亂試。
想把被忽略的檔案也顯示出來,可以用:
git status --short --ignored --untracked-files=all
這時候會看到 !! .env 等項目。
!! 的意思是 ignored,不是檔案壞掉,也不是已經被刪除。
檔案仍在你的硬碟上,Python 仍然讀得到。
查例外時要小心一點:
git check-ignore -v .env.example
詳細模式可能顯示 !.env.example 這條否定規則。
有輸出不一定代表被排除,要看 pattern 是否以 ! 開頭。
再搭配 git status,確認 .env.example 仍是可加入的 ?? 項目。
六. 真正加入之前,看清楚要收進來的東西 #
.gitignore 本身也應該被追蹤,讓其他人拿到相同的專案規則。
練習中先只加入三個檔案:
git add .gitignore app.py .env.example
git diff --cached --stat
git diff --cached
--cached 顯示已暫存、準備提交的變更。
這一步可以確認範本沒有真密碼,也沒有意外加入環境資料夾。
想列出目前 index 裡的檔名,可以再用:
git ls-files
到這裡,已經完成最常用的工作流程。 若要建立 commit,沿用你原本的 Git 身分設定即可;本文的練習不要求提交或推送。 不要為了跑範例,把來路不明的名字或 email 寫進全域設定。
七. 為什麼後來寫了規則,檔案還在追蹤? #
這是 .gitignore 最容易讓人誤會的地方:
它主要影響尚未被追蹤的路徑,不會自動把已在 index 裡的檔案移除。
用剛才的練習專案做一個不含秘密的小實驗。
新增 scratch.txt,先把它加入 index,再補忽略規則。
如果你用編輯器操作,內容分別是 demo only 與新增一行 scratch.txt。
以下是 Git Bash、macOS、Linux 可用的相同操作:
printf 'demo only\n' > scratch.txt
git add scratch.txt
printf '\nscratch.txt\n' >> .gitignore
git ls-files -- scratch.txt
最後仍會列出 scratch.txt。
不是規則失效,而是這個檔案已經被追蹤。
若修改它,Git 仍然會顯示變更。
現在用指定檔案的方式停止追蹤:
git rm --cached -- scratch.txt
git add .gitignore
git ls-files -- scratch.txt
最後一行應該不再列出它。
打開檔案總管或執行 cat scratch.txt,會發現本機檔案還在。
--cached 讓這次移除只作用於 index,不是刪掉工作目錄中的檔案。
這個範例的檔案剛加入、還沒有 commit,所以它會回到「本機存在但被忽略」的狀態。 若檔案早已存在於上一個 commit,則會看到一筆 staged deletion,下一個 commit 才正式停止在新版本追蹤它。 它並不會從過去的 commit 消失。
不要直接照抄網路上的「把整個專案全部取消追蹤,再重新加入」配方。
針對真正要處理的檔案操作,檢查暫存差異,通常更容易理解。
如果 git rm --cached 因內容不一致而拒絕,先停下來查看狀態與差異,不要急著加 -f。
八. 團隊規則與自己的雜項,可以分開放 #
不是所有東西都要寫進團隊的 .gitignore。
先問一句:其他人也應該套用這條規則嗎?
| 情境 | 適合放的位置 |
|---|---|
專案的 .venv、快取、本機設定 |
專案 .gitignore,一起追蹤 |
| 只有我在這個 repo 留的筆記 | .git/info/exclude,不提交 |
| 各 repo 都不想看見的個人雜項 | 個人 core.excludesFile 設定 |
例如只是自己的草稿筆記,可在 .git/info/exclude 加入該檔名。
這不會把規則送給同事。
全域排除檔則依你的開發環境設定,不需要為了本文更改它。
編輯器設定不一定都該排除。
本篇的小專案先忽略 .vscode/,但團隊若想共用格式化設定,可以討論後調整。
忽略規則是協作決定,不是看到某個副檔名就永遠不能提交。
九. 最後提醒:忽略不是密碼保險箱 #
.gitignore 不會加密檔案,也不會阻止所有程式讀它。
它不是防火牆;git add -f 也能明確強制加入被忽略的檔案。
因此還是要檢查 staged diff,而不是把安全感全交給一份清單。
如果真密碼已經提交或推送,事後補規則不會撤銷它。 先撤銷或輪替該憑證,再依團隊流程處理 repository 歷史與其他副本。 「現在看不到」不代表之前的值沒有外流。 本文的練習檔案只有假值,不需要拿真密碼做實驗。
關於 .env 裡的值如何載入 Python,可接著看 dotenv 教學。
今天專心處理 Git 要不要收進來,不重做環境設定管理。
結語:讓版本控制留下值得留的東西 #
一份好用的 .gitignore 不需要上百行。
從自己的專案出發,先排除能重建的環境與快取,保留程式和不含秘密的設定範本。
拍拍君的日常順序是:
- 看
git status,知道目前有哪些檔案。 - 寫小而明確的忽略規則。
- 用
check-ignore -v找出命中的原因。 git add後再看 staged diff。- 已被追蹤的檔案,另外決定是否針對性停止追蹤。
現在再打開一次變更清單,應該清爽多了。 真正值得分享的程式,也不會淹沒在幾千個快取檔案裡。