github/gitignore 詳細教學

物件：github/gitignore — GitHub 官方維護的 .gitignore 模板倉庫規模：174k stars / 82k forks / 312 個 .gitignore 模板 / CC0-1.0 公共領域適用對象：所有用 git 的工程師（不分語言）

§1 一句話定位

github/gitignore 是 GitHub 官方在 2010 年 11 月建立、由社群協力維護的 .gitignore 模板集合，是事實上的「全世界 .gitignore 規則來源」。

當你在 GitHub.com 介面建立新 repo 時看到的「Add .gitignore」下拉選單（裡面有 Python / Node / Go / Rust … 上百個選項），就是直接從本 repo 即時載入。GitLab、Bitbucket、Codeberg、VS Code 的「產生 .gitignore」功能、gibo CLI 工具等等，幾乎都是本 repo 的下游。

授權是 CC0-1.0（公共領域） — 完全免費、無 attribution 義務、可商用、可內部專案、可專利相關文件。可以放心複製貼上任何模板到任何專案。

§2 怎麼用（4 種方法）

方法 A：GitHub UI（最簡單，給新手）

建立新 repo 時：

勾選「Add .gitignore」
下拉選單選對應的語言（Python / Node / Go / …）
GitHub 自動把對應模板放進 repo

限制：只能挑「root 163 個主流模板」之一，無法組合多個（如 Python + macOS + VS Code）。

方法 B：curl 直抓（給已存在的 repo）

1# Python 專案
2curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore -o .gitignore
3
4# Python + macOS + VS Code（手動合併）
5curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore > .gitignore
6echo "" >> .gitignore
7curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Global/macOS.gitignore >> .gitignore
8echo "" >> .gitignore
9curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Global/VisualStudioCode.gitignore >> .gitignore

方法 C：gibo CLI（推薦長期使用）

gibo (gitignore.io 改寫的 native CLI) 把整個 repo cache 到本機，支援一行組合多語言：

 1# 安裝
 2brew install gibo                # macOS
 3# 或 npm i -g gibo               # 跨平台
 4# 或 git clone https://github.com/simonwhitaker/gibo.git ~/.gibo 並加 alias
 5
 6# 同步本 repo 到本機 cache
 7gibo update
 8
 9# 列出所有支援的模板
10gibo list | head -30
11
12# 組合：Python + Node + macOS + VS Code + JetBrains
13gibo dump Python Node macOS VisualStudioCode JetBrains > .gitignore
14
15# 查單一模板內容（不輸出）
16gibo show Rust

方法 D：clone 整個 repo（給需要客製的人）

1git clone --depth 1 https://github.com/github/gitignore.git ~/gitignore-templates
2# 自己挑檔組合
3cat ~/gitignore-templates/Python.gitignore \
4    ~/gitignore-templates/Global/macOS.gitignore \
5    ~/gitignore-templates/Global/Linux.gitignore \
6    > .gitignore

§3 倉庫架構（含 Mermaid 圖）

倉庫採三層分類：root（主流語言）/ Global/（跨環境工具）/ community/（特殊框架）。


graph TD
    Root["github/gitignore
312 個 .gitignore 模板
CC0-1.0"]

    Root --> RootLevel["根目錄: 163 個
主流語言/框架"]
    Root --> GlobalDir["Global/: 76 個
跨語言環境"]
    Root --> CommunityDir["community/: 73 個
社群專業領域"]
    Root --> Meta[".github/workflows/stale.yml
README / CONTRIBUTING / LICENSE"]

    RootLevel --> Lang1["主流程式語言
Python / Node / Go / Rust
Java / Kotlin / Scala / Clojure
C / C++ / Swift / Ruby / PHP
R / Julia / Haskell / OCaml / Elixir"]
    RootLevel --> Lang2["主流框架
Angular / Drupal / Symfony
Laravel / Rails / CakePHP / Hugo"]
    RootLevel --> Lang3["遊戲/移動/桌面
Unity / UnrealEngine / Godot
Android / iOS via Swift"]
    RootLevel --> Lang4["DevOps/Infra
Terraform / AppEngine
Autotools / bun"]

    GlobalDir --> G1["作業系統
macOS / Windows / Linux"]
    GlobalDir --> G2["編輯器/IDE
VS Code / JetBrains / Vim
Emacs / Sublime / Eclipse
Xcode / NetBeans"]
    GlobalDir --> G3["新 AI IDE & Agents
Cursor / Agents.gitignore
(claude-* / AGENTS.md)"]
    GlobalDir --> G4["雲端同步/備份
Dropbox / Backup
Archives / SynologyWorkstation"]
    GlobalDir --> G5["其他 VCS
Bazaar / CVS / Mercurial / SVN"]

    CommunityDir --> C1["子目錄
AWS/ DotNet/ Elixir/
Golang/ Java/ JavaScript/
Linux/ Microsoft/ Python/ Ruby/"]
    CommunityDir --> C2["特殊框架
Bazel / Beef / FreeCAD
Hexo / AltiumDesigner
Alteryx / Exercism / Gretl"]

    classDef root fill:#1f6feb,color:#fff,stroke:#1f6feb
    classDef level fill:#f0f6fc,color:#0d1117,stroke:#1f6feb
    classDef leaf fill:#fff,color:#0d1117,stroke:#8b949e
    class Root root
    class RootLevel,GlobalDir,CommunityDir,Meta level
    class Lang1,Lang2,Lang3,Lang4,G1,G2,G3,G4,G5,C1,C2 leaf

三層分工的設計邏輯

層級	數量	用途	範例
root	163	「一個專案的主語言/框架」應該獨佔一個檔	`Python.gitignore`、`Node.gitignore`
Global/	76	「跨所有專案、跟你的 OS/編輯器有關」應該放使用者 global gitignore	`macOS.gitignore`、`VisualStudioCode.gitignore`
community/	73	「太新 / 太專業 / 還在等是否升 root」的暫存區	`community/AWS/`、`community/Bazel.gitignore`

規則衍生：CONTRIBUTING.md 明確說 OS-specific 規則（如 .DS_Store）只能進 Global/macOS.gitignore，不能塞進 Python.gitignore。原因：避免 macOS 使用者「污染」整個社群共用模板。

§4 維護工具（Helper 檔案）

本 repo 沒有 Makefile / 自動化測試 / lint 腳本 — 它純粹是模板倉庫，靠人工 review。但有兩個關鍵維護機制：

.github/workflows/stale.yml（唯一 workflow）

每天 16:20 UTC 跑一次
PR 90 天無更新 → 標 stale
標 stale 後 365 天無更新 → 自動關閉
例外 label：keep（明確不想被關閉的 PR）
用 actions/stale@v9.1.0 (pinned SHA 5bef64f...)，符合 OpenSSF 強化建議

CONTRIBUTING.md（規則本身）

這份文件可以視為「.gitignore 設計準則」教材，重點：

一個 PR 只改一個模板（避免 review 爆炸）
OS-specific 規則只進 Global/
不重複規則（在多模板出現的同樣規則 → 應該抽到 Global/）
規則要附文件（連結官方 docs 證明這檔該被忽略）
不為單一使用者 / 單一團隊客製

§5 應用場景

場景 A：Python 資料分析專案（pandas + Jupyter）

1gibo dump Python macOS Linux VisualStudioCode JetBrains > .gitignore
2# 加客製：本專案的 data/ 資料夾要排除
3echo -e "\n# Project-specific\ndata/raw/\ndata/cache/\n*.parquet\n*.feather" >> .gitignore

場景 B：Node.js + TypeScript monorepo（pnpm workspace）

 1gibo dump Node macOS VisualStudioCode > .gitignore
 2# Node.gitignore 已涵蓋 node_modules / .next / dist
 3# 加 pnpm-specific（root 模板沒涵蓋）
 4cat >> .gitignore <<EOF
 5
 6# pnpm workspace
 7.pnpm-store/
 8.turbo/
 9.changeset/
10EOF

場景 C：Rust binary 專案

1curl -fsSL https://raw.githubusercontent.com/github/gitignore/main/Rust.gitignore > .gitignore
2# Rust.gitignore 預設 Cargo.lock 被 commented（lib 才 ignore）
3# binary 專案：保留 commented 行（commit Cargo.lock）
4gibo dump macOS VisualStudioCode >> .gitignore

場景 D：本知識庫 root（multi-language + LLM agent + research 工作目錄）

 1gibo dump Python Node macOS Linux VisualStudioCode Agents > .gitignore
 2# Agents.gitignore（新！）已涵蓋 .claude/ / AGENTS.md / claude-* 等
 3# 加本專案特有
 4cat >> .gitignore <<EOF
 5
 6projects/research-*/
 7projects/meeting-*/
 8graphify-out/
 9quarkdown-out/
10inbox/notebooklm/
11*.zip
12EOF

§6 資安與風險討論

🟢 本 repo 資安風險極低 — 純文字模板，無可執行程式碼、無 dependency、無 build step。唯一一個 workflow (stale.yml) 採 pinned SHA + 限制 permissions，符合最佳實踐。

但有一個廣泛被誤解的觀念值得正名：

⚠️ .gitignore 不是機密保護機制

.gitignore 只阻擋「還沒被 tracked 的檔」進 staging。它做不到下列事情：

不阻擋已 commit 過的檔：如果你今天先 commit 了 .env、明天才加進 .gitignore，過去的 commit 仍永久保留該檔。git log -p .env 可拿回內容；GitHub UI 的 Blame / History 也看得到。
不阻擋已 tracked 的檔：對已 git add 過的檔，必須 git rm --cached <file> 後 .gitignore 才開始生效。
無法阻擋本機檔被誤推：.gitignore 規則錯誤 / 被遺漏的話，敏感檔仍會進 commit。

真正移除已 commit 機密的方法

 1# 方法 1：git filter-repo（官方推薦，比 filter-branch 安全）
 2pip install git-filter-repo
 3git filter-repo --invert-paths --path .env
 4git push --force-with-lease origin main
 5# ⚠️ 強制 push 會改寫歷史，所有 collaborator 必須重 clone
 6
 7# 方法 2：BFG Repo-Cleaner（更快、語法更友善）
 8brew install bfg
 9bfg --delete-files .env
10git reflog expire --expire=now --all && git gc --prune=now --aggressive
11git push --force-with-lease origin main

正確做法：機密一律放 .env（從 day 1 就在 .gitignore 內）、密鑰用 secrets manager（GitHub Actions secrets / AWS Secrets Manager / 1Password CLI），絕不依賴 .gitignore 當最後一道防線。

§7 FAQ

Q1：global gitignore vs project gitignore 差在哪？

Project：<repo>/.gitignore — 對全世界生效（commit 進 repo，所有 collaborator 共享）
Global：~/.gitignore_global — 只對你自己的這台機器生效（不進 repo）

規則：跟你本機環境有關的（.DS_Store / .vscode/ 個人 cache / .idea/ …）應該進 global；跟專案語言有關的（node_modules/ / __pycache__/ …）應該進 project。

設定 global：

1git config --global core.excludesfile ~/.gitignore_global
2gibo dump macOS Linux Windows VisualStudioCode JetBrains Vim Cursor > ~/.gitignore_global

Q2：怎麼開始 ignore 一個已經被 track 的檔？

1git rm --cached secrets.txt          # 從 index 移除（保留 working dir）
2echo "secrets.txt" >> .gitignore
3git commit -m "stop tracking secrets.txt"

Q3：如何 ignore 整個資料夾但保留一個檔？

1build/                # 全部 ignore
2!build/.keep          # 但保留 .keep（讓 git 知道資料夾存在）

Q4：.gitignore 規則的 negation (!) 不生效？

規則：!pattern 無法 un-ignore 一個「父目錄已被 ignore 的檔」。

1build/                # 整個 build/ 被 ignore — 此時下面 !build/important.txt 無效
2!build/important.txt  # ❌ 無法救回

修正：父層用 * 而非整個 dir：

1build/**              # 用 ** 而非 /
2!build/important.txt  # ✅ 這樣 negation 才生效

Q5：模板裡的 commented 行（如 # Cargo.lock）什麼意思？

那是「有條件採用」的規則。Rust.gitignore 把 Cargo.lock commented 的原因：lib crate 該 ignore（讓下游決定版本）、binary crate 該 commit（鎖定建置結果）。你拿到模板後，依專案類型決定是否取消註解。

§8 進階用法

多語言組合 + 去重

1gibo dump Python Node Go Rust macOS VisualStudioCode JetBrains \
2  | awk '!seen[$0]++' \
3  > .gitignore
4# awk 去掉重複行（多模板共有的 .DS_Store 等只留一行）

Negation 的進階寫法

1# 全部 ignore，只保留特定副檔名
2*
3!*.py
4!*.md
5!/.gitignore         # 不要把 .gitignore 自己 ignore 掉
6!/docs/
7!/docs/**            # 子目錄要顯式遞迴

Wildcard 與目錄

1*.log                # 任何位置的 .log
2/build               # 只 ignore root 的 build（不 ignore 子目錄的 build）
3build/               # 任何位置的 build/ 資料夾
4**/cache/            # 任何深度的 cache/
5docs/**/*.tmp        # docs 下任何深度的 .tmp

用 git check-ignore debug 規則

1git check-ignore -v path/to/file
2# 回答「這個檔被哪一行 .gitignore 規則 ignore」

把本 repo 包成自家內網模板服務

1# 內部 GitLab 環境
2git clone --bare https://github.com/github/gitignore.git
3git push --mirror git@internal-gitlab:devops/gitignore.git
4# 之後內部 PR / CI 可以引用內網版本（避免外網依賴）

§9 與本知識庫的整合

本知識庫（260416 AI-knowledge_template v1）多層 layer 涉及機密 / 大檔 / 不想分享的內容。建議：

Layer-level .gitignore 建議

Layer	工作目錄	建議 .gitignore 規則
`meeting-intel`	`projects/research-*/` + Discord 副本	`*`（research 對外分享需逐檔白名單）
`paper-tutorial`	`projects/research-paper-*/`	`` + 顯式 `!README.md` `!.html`
`graphify`	`graphify-out/`	加進 root .gitignore
`quarkdown`	`quarkdown-out/`	加進 root .gitignore
`ai-notebooklm`	`inbox/notebooklm/`	加進 root .gitignore（雲端來源檔不重要）

本專案 root .gitignore 建議內容

基於 gibo dump Python Node macOS Linux VisualStudioCode Agents，額外加：

 1# === AI Knowledge Template specific ===
 2
 3# 內部分享 only（meeting-intel / paper-tutorial）
 4projects/research-*/
 5
 6# 大型生成檔
 7graphify-out/
 8quarkdown-out/
 9**/inbox/notebooklm/
10**/inbox/autofetch/*.zip
11*.docling.json
12
13# 暫存
14*.tmp
15.cache/
16
17data/raw/
18data/cache/
19*.parquet

§10 重點摘要

是什麼：GitHub 官方維護的 .gitignore 模板倉庫，174k stars，CC0-1.0，312 個模板（163 root + 76 Global + 73 community）。
怎麼用：GitHub UI（最簡）/ curl / gibo CLI（推薦）/ clone repo。
三層結構：root 主語言、Global/ 跨環境工具、community/ 特殊框架。OS-specific 規則只進 Global/。
.gitignore ≠ 機密保護：只阻擋未 tracked；已 commit 的需 git filter-repo 移除。
進階規則：negation ! 不救父目錄已 ignore 的檔；用 git check-ignore -v debug。
接 .gitignore 就接 github/gitignore — 沒有比這個更穩定的單一來源。

§11 進一步閱讀

官方 repo：https://github.com/github/gitignore
Pro Git book — Ignoring Files：https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring
gitignore(5) man page：https://git-scm.com/docs/gitignore
gibo CLI：https://github.com/simonwhitaker/gibo
git filter-repo：https://github.com/newren/git-filter-repo
BFG Repo-Cleaner：https://rtyley.github.io/bfg-repo-cleaner/
GitHub help — Ignoring files：https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files
OpenSSF SCM hardening（pinned SHA 規範）：https://openssf.org/

github/gitignore 詳細教學 — 從模板選擇到多語言組合的完整指南

Contents

github/gitignore 詳細教學

§1 一句話定位

§2 怎麼用（4 種方法）

方法 A：GitHub UI（最簡單，給新手）

方法 B：curl 直抓（給已存在的 repo）

方法 C：gibo CLI（推薦長期使用）

方法 D：clone 整個 repo（給需要客製的人）

§3 倉庫架構（含 Mermaid 圖）

三層分工的設計邏輯

§4 維護工具（Helper 檔案）

.github/workflows/stale.yml（唯一 workflow）

CONTRIBUTING.md（規則本身）

§5 應用場景

場景 A：Python 資料分析專案（pandas + Jupyter）

場景 B：Node.js + TypeScript monorepo（pnpm workspace）

場景 C：Rust binary 專案

場景 D：本知識庫 root（multi-language + LLM agent + research 工作目錄）

§6 資安與風險討論

⚠️ .gitignore 不是機密保護機制

真正移除已 commit 機密的方法

§7 FAQ

Q1：global gitignore vs project gitignore 差在哪？

Q2：怎麼開始 ignore 一個已經被 track 的檔？

Q3：如何 ignore 整個資料夾但保留一個檔？

Q4：.gitignore 規則的 negation (!) 不生效？

Q5：模板裡的 commented 行（如 # Cargo.lock）什麼意思？

§8 進階用法

多語言組合 + 去重

Negation 的進階寫法

Wildcard 與目錄

用 git check-ignore debug 規則

把本 repo 包成自家內網模板服務

§9 與本知識庫的整合

Layer-level .gitignore 建議

本專案 root .gitignore 建議內容

§10 重點摘要

§11 進一步閱讀

Comments

github/gitignore 詳細教學 — 從模板選擇到多語言組合的完整指南

Contents

github/gitignore 詳細教學

§1 一句話定位

§2 怎麼用（4 種方法）

方法 A：GitHub UI（最簡單，給新手）

方法 B：curl 直抓（給已存在的 repo）

方法 C：gibo CLI（推薦長期使用）

方法 D：clone 整個 repo（給需要客製的人）

§3 倉庫架構（含 Mermaid 圖）

三層分工的設計邏輯

§4 維護工具（Helper 檔案）

.github/workflows/stale.yml（唯一 workflow）

CONTRIBUTING.md（規則本身）

§5 應用場景

場景 A：Python 資料分析專案（pandas + Jupyter）

場景 B：Node.js + TypeScript monorepo（pnpm workspace）

場景 C：Rust binary 專案

場景 D：本知識庫 root（multi-language + LLM agent + research 工作目錄）

§6 資安與風險討論

⚠️ .gitignore 不是機密保護機制

真正移除已 commit 機密的方法

§7 FAQ

Q1：global gitignore vs project gitignore 差在哪？

Q2：怎麼開始 ignore 一個已經被 track 的檔？

Q3：如何 ignore 整個資料夾但保留一個檔？

Q4：.gitignore 規則的 negation (!) 不生效？

Q5：模板裡的 commented 行（如 # Cargo.lock）什麼意思？

§8 進階用法

多語言組合 + 去重

Negation 的進階寫法

Wildcard 與目錄

用 git check-ignore debug 規則

把本 repo 包成自家內網模板服務

§9 與本知識庫的整合

Layer-level .gitignore 建議

本專案 root .gitignore 建議內容

§10 重點摘要

§11 進一步閱讀

Related Posts

Comments