gitignore：排除檔案的完整指南

更新日期： 2025 年 1 月 26 日

在使用 Git 進行版本控制時，並非所有檔案都需要加入儲存庫。

一些特定的檔案，例如暫存檔、環境設定檔或第三方依賴，通常只與本地開發相關，不需要與其他開發者共享。

這時候，我們可以使用 .gitignore 檔案來排除這些檔案。

本文將為新手介紹如何設定 .gitignore，並列出常見需要排除的檔案類型，幫助您更有效地管理專案。

什麼是 .gitignore？

.gitignore 是一個特殊的檔案，放置於 Git 儲存庫的根目錄中，用來指定哪些檔案或目錄應該被 Git 忽略。

當 Git 執行版本控制時，會根據 .gitignore 中的規則自動排除符合條件的檔案。

為什麼需要 .gitignore？

1. 減少專案雜亂
   排除不必要的檔案，使儲存庫保持簡潔，方便管理。
2. 保護敏感資訊
   防止上傳含有敏感資訊的檔案（如 API 金鑰、密碼設定檔）。
3. 提高專案效能
   排除無用的檔案或目錄（如第三方依賴），減少版本控制的負擔。

排除這些檔案的主要理由

1. 提升專案可移植性：確保專案只包含核心內容，便於其他開發者快速搭建環境。
2. 避免版本庫膨脹：減少不必要檔案的提交，保持版本庫乾淨。
3. 減少協作衝突：避免因環境差異導致檔案衝突。

透過適當設定 .gitignore 文件，可以有效維護專案的整潔性和高效性。

常見需要排除的檔案

資料庫檔案

• 功能：資料庫檔案用於存儲應用程式，執行期間生成的數據。例如開發環境中的測試數據。
• 生成機制：這些檔案通常由開發者，在本地環境中執行程式時自動生成，例如 SQLite 資料庫檔案。
• 為何需要排除：
  • 資料庫檔案通常體積龐大，占用大量儲存空間。
  • 與開發者的本地環境緊密相關，其他開發者可能無法直接使用。
  • 可透過資料庫遷移檔（如 Django 的 migrations）重新生成。
• 範例：
  • db.sqlite3
• 如何排除：在 .gitignore 中添加相關檔案名稱，例如：

# Ignore SQLite database files
db.sqlite3

虛擬環境檔案

• 功能：虛擬環境用於隔離專案的依賴程式庫，避免全域環境衝突。
• 生成機制：開發者使用工具（如 virtualenv 或 venv）建立虛擬環境時，會在專案中生成一個目錄（通常命名為 venv 或其他名稱），存放虛擬環境相關的執行檔和依賴。
• 為何需要排除：
  • 虛擬環境會根據開發者本地的作業系統和 Python 版本生成，無法直接移植到其他環境。
  • 依賴項可由環境設定檔（如 requirements.txt 或 Pipfile.lock）重新安裝，無需同步虛擬環境目錄。
• 範例：
  • venv/
• 如何排除：在 .gitignore 中添加虛擬環境目錄名稱，例如： # Ignore virtual environments venv/

第三方依賴

• 功能：此類檔案目錄，用於存儲專案依賴的第三方模組。例如 Node.js 的 node_modules。
• 生成機制：當開發者使用包管理工具（如 npm 或 yarn）安裝依賴時，會生成一個目錄以存放所有第三方模組。
• 為何需要排除：
  • 此目錄通常非常龐大，占用大量儲存空間。
  • 模組版本已被記錄在依賴檔（如 package.json 和 package-lock.json）中，可以通過執行 npm install 或 yarn install 重新生成。
• 範例：
  • node_modules/
• 如何排除：在 .gitignore 中添加以下規則：

# Ignore virtual environments
venv/

編譯檔與暫存檔

• 功能：此類檔案是程式碼編譯或程式執行期間生成的中間產物，通常用於提升執行效能或暫存數據。
• 生成機制：
  • 編譯過程中生成的二進位檔（如 .class 或 .o）。
  • 執行期間生成的日誌檔案（如 .log）或臨時檔案（如 .tmp）。
• 為何需要排除：
  • 這些檔案不會對專案的核心功能造成影響，且會隨著程式重新執行或編譯而更新。
  • 提交到版本庫會增加不必要的負擔。
• 範例：
  • *.log
  • *.tmp
  • *.cache
• 如何排除：在 .gitignore 中添加相應的檔案類型規則：

# Ignore compiled and temporary files
*.log
*.tmp
*.cache

個人設定檔

• 功能：此類檔案包含開發工具或編輯器的個人化設定，僅與當前使用者的開發環境相關。
• 生成機制：開發工具（如 VSCode、IntelliJ IDEA）會自動生成設定檔，儲存使用者的快捷鍵、自訂樣式等資訊。
• 為何需要排除：
  • 個人設定檔僅對特定開發者有用，提交後會干擾其他團隊成員。
  • 專案的設定應由團隊統一管理，與個人偏好分離。
• 範例：
  • .vscode/
  • .idea/
• 如何排除：在 .gitignore 中添加相關規則：

# Ignore personal editor configurations
.vscode/
.idea/

作業系統產生的檔案

• 功能：這些檔案由作業系統自動生成，通常用於存儲目錄資訊或縮圖緩存。
• 生成機制：
  • macOS 生成 .DS_Store 檔案，用於存儲目錄顯示設定。
  • Windows 生成 Thumbs.db，用於縮圖緩存。
• 為何需要排除：
  • 與專案內容無關，對開發無任何幫助。
  • 提交後會增加版本庫的噪音。
• 範例：
  • .DS_Store
  • Thumbs.db
• 如何排除：在 .gitignore 中添加以下規則：

# Ignore OS-generated files
.DS_Store
Thumbs.db

Python 快取檔案

• 功能：Python 為提升效能會在執行程式時自動生成 .pyc 檔案，並存放於 __pycache__/ 資料夾中。
• 生成機制：
  • 當 Python 解譯器執行 .py 檔案時，會將其編譯為 .pyc 檔案並存放於 __pycache__/ 資料夾。
  • .pyc 是 Python 程式碼的字節碼編譯版本，用於減少重複編譯的時間。
• 為何需要排除：
  • 自動生成：這些檔案由 Python 自動生成，無需手動管理。
  • 環境依賴：不同環境可能會生成不同版本，提交後會導致不一致。
  • 版本污染：提交此類檔案會增加無意義的檔案數量。
• 範例：
  • __pycache__/
  • *.pyc
• 如何排除：在 .gitignore 中添加以下規則：

# Ignore Python cache files
__pycache__/
*.pyc
*.pyo

如何建立 .gitignore？

1. 在專案根目錄建立一個名為 .gitignore 的檔案：

touch .gitignore

2. 在檔案中新增要忽略的規則：

# 排除資料庫檔案
db.sqlite3

# 排除虛擬環境
venv/

# 排除第三方依賴
node_modules/

# 排除日誌檔案
*.log

.gitignore 文件範例

以下是一個範本 .gitignore 文件，包含了各種常見需要排除的檔案和目錄，適用於大多數軟體專案的基本需求。如果需要，您也可以根據專案特性進行自定義調整。

# =====================
# 資料庫檔案
# =====================
db.sqlite3

# =====================
# 虛擬環境檔案
# =====================
venv/
.virtualenv/

# =====================
# 第三方依賴檔案
# =====================
node_modules/
bower_components/

# =====================
# 編譯檔與暫存檔
# =====================
*.log
*.tmp
*.cache
*.out
*.class
*.o
*.so

# =====================
# 個人設定檔
# =====================
.vscode/
.idea/
*.iml

# =====================
# 作業系統產生的檔案
# =====================
.DS_Store
Thumbs.db
Desktop.ini

# =====================
# Python 快取檔案
# =====================
__pycache__/
*.pyc
*.pyo

# =====================
# 特定框架或工具相關檔案
# =====================

# Flask 或其他框架的 .env 檔案（存放機密資訊）
.env

# =====================
# 前端建置產物
# =====================
dist/
build/
*.min.js
*.min.css

# =====================
# 其他常見工具
# =====================
# 忽略 Mac 的 Spotlight 搜索資料
.Spotlight-V100
.Trashes

# 忽略特定 IDE 的暫存檔
*.swp
*.swo
*.bak

# 忽略壓縮檔案和備份檔案
*.zip
*.tar.gz
*.7z
*.bak

小結

.gitignore 是專案中不可或缺的工具，能幫助您有效管理檔案並保護儲存庫的整潔。

通過排除不必要的檔案，您可以專注於管理專案的核心內容，避免敏感資訊洩漏。

建議在專案初期就設定 .gitignore，並根據專案需求定期更新。

希望本文能幫助您更好地理解和使用 .gitignore！