跳至主要内容

Git: Add Empty Folder

如何在 Git 中提交空資料夾？

問題背景​

最近專案中不斷被問起這件事，為了日後管理維護方便，案主期待 Git 裡面能夠預先建立對應的資料夾樹。

而 Git 設計是無法提交空資料夾，雖然網路上可以找到一些 hack 的方式可以在 Git 裡加入空資料夾，但可能因不同 Git 版本關係，在 checkout 時無法建立對應資料夾。

通用解法是在該資料夾底下新增一個不影響程式運行的檔案。常見的有 .gitignore、.gitkeep、README.md。

解決方案​

1. 使用 .gitignore​

適用情境：該資料夾不該保存任何程式資源，只是為了專案特殊需求而必須存在資料夾。

# 建立資料夾並新增 .gitignore
mkdir <NEW_FOLDER>
cd <NEW_FOLDER>
touch .gitignore

.gitignore 檔案內容：

# Ignore everything in this directory
*
# Except this file
!.gitignore

優點：

  • 往後在該資料夾放任何檔案，commit 時都不會被加入 Git 倉儲
  • checkout 時也不會產生衝突或影響
  • 適合當作不同環境會有所不同的開發測試資源、臨時資料夾等

2. 使用 .gitkeep​

適用情境：需要保存資料夾結構，且日後會有檔案增減。

# 建立資料夾並新增 .gitkeep
mkdir <NEW_FOLDER>
cd <NEW_FOLDER>
touch .gitkeep

特點：

  • 雖然命名很像 Git 的系統檔案，但其實不是，它只是個普通檔案
  • 這個方式可以保存資料夾，日後資料夾有檔案增減時，亦會被提交到專案倉儲
  • .gitkeep 會被視為系統隱藏檔，大部分開發工具都會忽略它的存在

📝 題外話：在 GitLab Web 上新增資料夾時，GitLab 也是新增 .gitkeep 檔來處理空白資料夾的提交。

3. 使用 README.md​

適用情境：多人協作開發，需要說明資料夾用途。

# 建立資料夾並新增 README.md
mkdir <NEW_FOLDER>
cd <NEW_FOLDER>
touch README.md

README.md 檔案內容範例：

# <FOLDER_NAME>

## 目的
說明這個資料夾的作用和目的。

## 使用方式
描述如何使用這個資料夾。

## 注意事項
列出使用時需要注意的事項。

優點：

  • 和 .gitkeep 一樣可以保存空資料夾
  • 為團隊提供資料夾用途說明，提高協作效率
  • 可以記錄資料夾的使用規範和注意事項

注意事項：

  • README.md 是一般檔案，要注意開發工具會不會因為它而出錯

最佳實踐​

  1. 優先選擇 .gitkeep：簡單且不會干擾開發環境
  2. 多人協作選擇 README.md：提供文件說明，提高團隊協作效率
  3. 臨時資料夾選擇 .gitignore：避免意外提交不需要的檔案

參考資料​