.gitkeepとは？Gitで空ディレクトリを管理する方法

結論

.gitkeepは、空のディレクトリをGitで追跡するためのダミーファイル。Gitは空ディレクトリを管理できないため、中身のないフォルダ構造を維持したい場合に使う。

Gitが空ディレクトリを追跡できない理由

Gitはファイル単位で変更を追跡する。ディレクトリ自体はGitの管理対象ではなく、ファイルが存在する場所として認識される。つまり、ファイルが1つもないディレクトリは、Gitにとって「存在しない」のと同じ。

# 空ディレクトリを作成
mkdir uploads

# git statusで確認しても表示されない
git status
# → uploads/ は表示されない

.gitkeepの使い方

基本的な使い方

空のディレクトリに.gitkeepファイルを作成する。

# uploadsディレクトリを作成
mkdir uploads

# .gitkeepを作成（中身は空でOK）
touch uploads/.gitkeep

# これでgit addできる
git add uploads/.gitkeep
git commit -m "Add uploads directory"

.gitignoreとの組み合わせ

よくあるパターンとして、「ディレクトリ構造は維持したいが、中身は除外したい」というケースがある。

# ディレクトリの中身は除外
uploads/*

# ただし.gitkeepは追跡する
!uploads/.gitkeep

この設定により、uploads/ディレクトリ内にどんなファイルを置いても無視されるが、ディレクトリ構造自体はリポジトリに含まれる。

実際の使用例

プロジェクトで顧問先ごとにデータを分離する構造を作った際の例。

tests/data/client_001/
├── inbox/           # スキャン待ちレシート
│   └── .gitkeep
├── batches/         # 処理済みバッチ
│   └── .gitkeep
├── exports/         # 出力済みファイル
│   └── .gitkeep
└── receipts.db      # DBファイル（.gitignoreで除外）

.gitignoreの設定はこうなる。

# データディレクトリ（中身は除外、構造は維持）
tests/data/client_*/inbox/*
tests/data/client_*/batches/*
tests/data/client_*/exports/*
!tests/data/client_*/**/.gitkeep

# DBファイルは除外
*.db

.gitkeepという名前について

.gitkeepはGitの公式機能ではなく、慣習的に使われている名前。他にも.keepや.placeholderという名前が使われることもある。

重要なのは「空ディレクトリにファイルを1つ置く」こと自体であり、ファイル名に特別な意味はない。ただし、.gitkeepという名前は「Gitで管理するために置いている」という意図が伝わりやすいため、広く使われている。

まとめ

Gitは空ディレクトリを追跡できない
.gitkeepファイルを置くことで、ディレクトリ構造をリポジトリに含められる
.gitignoreと組み合わせて「構造は維持、中身は除外」ができる
.gitkeepは慣習的な名前であり、Git公式の機能ではない