↓快轉到主要內容
  1. 教學文章/

.gitignore 怎麼寫?別把暫存檔和密碼一起傳上 GitHub

·7 分鐘· loading · loading · ·
Git Gitignore Python 開發工具
每日拍拍
作者
每日拍拍
科學家 X 科技宅宅
目錄
版本控制: Git - 本文屬於一個選集。
§ 23: 本文

一. 前言:只是寫個小程式,怎麼多了幾千個檔案?
#

拍拍君剛寫好 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 不需要上百行。 從自己的專案出發,先排除能重建的環境與快取,保留程式和不含秘密的設定範本。

拍拍君的日常順序是:

  1. 看 git status,知道目前有哪些檔案。
  2. 寫小而明確的忽略規則。
  3. 用 check-ignore -v 找出命中的原因。
  4. git add 後再看 staged diff。
  5. 已被追蹤的檔案,另外決定是否針對性停止追蹤。

現在再打開一次變更清單,應該清爽多了。 真正值得分享的程式,也不會淹沒在幾千個快取檔案裡。

延伸閱讀
#

版本控制: Git - 本文屬於一個選集。
§ 23: 本文

相關文章

Git log Pickaxe:用 -S / -G 追查程式碼變更來源
·7 分鐘· loading · loading
Git Git Log Pickaxe Debugging Code Archaeology Developer-Tools
Git bundle 離線交接:完整封裝、增量更新與還原驗收
·8 分鐘· loading · loading
Git Git Bundle Offline Backup Prerequisites Developer-Tools
Git attributes 實戰:LF/CRLF、Binary 與可審核正規化
·7 分鐘· loading · loading
Git Gitattributes LF CRLF Binary Renormalize Developer-Tools
Git Partial Clone 實戰:blob:none、按需下載與離線驗證
·8 分鐘· loading · loading
Git Partial Clone Blob:none Promisor Remote Lazy Fetch Offline Developer-Tools
Git maintenance 實戰:用 Commit-Graph、MIDX 與排程加速大型 Repo
·10 分鐘· loading · loading
Git Git Maintenance Commit-Graph Multi-Pack-Index Performance Developer-Tools
Git sparse-checkout 實戰:大型 Monorepo 的部分取出與安全切換
·7 分鐘· loading · loading
Git Sparse-Checkout Monorepo Cone Mode Partial Clone Worktree Developer-Tools