.gitignoreが機能しないときの原因と対処法を徹底解説

.gitignoreファイルが期待どおりに動作せず、トラブルシューティングに悩まされるケースは少なくありません。

.gitignoreファイルはGitリポジトリにおいて重要な役割を担っています。もし.gitignoreが正しく機能していないと、非公開にしておくべき変更まで誤って追跡されてしまう可能性があります。その中にはAPIキーなどの機密情報が含まれていることもあるため、放置は危険です。

.gitignoreファイルがうまく機能しない原因として、主に次の2つが挙げられます。

• ファイルをコミットした後に.gitignoreへ追加している
• .gitignore内でファイル名やパスを間違えて指定している

この記事では、これら2つの問題とそれぞれの解決方法について詳しく解説します。

.gitignoreファイルとは？

.gitignoreファイルには、Gitリポジトリに保存したくないファイルの一覧を記述します。このファイルは主に、設定ファイルや環境変数ファイルなどをリポジトリの管理外に置くために使われます。こうしたファイルにはプライベートな情報が含まれていることが多く、リモートリポジトリに含めるべきではありません。

ファイル名は必ず.gitignoreという名前で保存してください。このプレーンテキストファイルに、Gitに追跡させたくないファイルやディレクトリのパスを記述していきます。ここに追加されたものはすべてGitが無視し、追跡ツリーには登録されません。

以下は.gitignoreファイルの内容の例です。

node_modules/
.env

この例では、Gitに対して特定のファイルとフォルダを無視するよう指示しています。.envはAPIキーなどが格納されることが多い環境変数ファイルで、node_modules/はインストール済みのNPMパッケージが格納されるフォルダです。

一般的に無視すべきファイルとしては、.DS_Storeファイル、.envファイル、設定ファイルなどが挙げられます。.DS_StoreファイルはmacOS上で生成されることが多く、Gitリポジトリに含める必要はありません。

.gitignoreファイルは通常、リポジトリのルートディレクトリに配置します。

シナリオA：コミット後に.gitignoreへ追加した場合

「無視するはずだったファイルを誤ってコミットしてしまった」——そんな経験はありませんか？ 後から.gitignoreに追加しても、Gitはすでにそのファイルを追跡し続けているため、「gitignoreが効かない」という事態になります。

これは、.gitignoreへの追加はファイルをコミットする前に行う必要があるためです。すでに追跡されているファイルを追跡対象から外すには、次のコマンドを実行します。

git rm -rf --cached <path>

git rmは指定した<path>を削除するコマンドです。--cachedフラグを付けると、インデックス（ステージングエリア）からのみ削除され、ローカルディレクトリにはファイルが残ります。rはディレクトリを再帰的に削除するオプション、fは強制実行のオプションです。単一のファイルだけを扱い、ローカルには残したい場合は次のようにします。

git rm --cached <file>

これで、指定したファイルやフォルダをGitの追跡対象から外せます。この操作を行えば、.gitignoreは本来どおりに機能するようになります。なお、.gitignoreを機能させるには、無視したいファイルやフォルダを必ず明示的に指定する必要がある点も忘れないでください。

シナリオB：コミット前に作成したのにファイルが追跡される場合

.gitignoreを作成済みなのにファイルが追跡される場合は、指定方法そのものに問題がないか確認しましょう。解決策は非常にシンプルです。.gitignoreファイルには、無視したいファイルを正確に指定する必要があります。スペルミスや誤ったパス名があれば、手動で修正しなければなりません。

次の例を見てみましょう。

*.pyyc

この.gitignoreは「すべての.pyycファイルを無視する」という意味になりますが、本来無視したいのは.pycファイル（Pythonプログラムに関連するファイル）です。.gitignoreはこちらの意図を汲み取ってくれないため、ルールを修正する必要があります。

*.pyc

これで、リポジトリはすべての.pycファイルを無視するようになります。

また、ファイルやフォルダの宣言の先頭・末尾に余分な空白が入っていないかも確認してください。目に見えない空白ひとつで、パターンが一致しなくなることがあります。

まとめ

この記事では、gitignoreが期待どおりに動作しない場合のさまざまなシナリオと解決策を紹介しました。最も重要なポイントは、ファイルやディレクトリの場所を正しく把握し、適切なパスを指定することです。

また、無視したいファイルは作成した時点でできるだけ早く.gitignoreに追加しましょう。万が一誤ってコミットしてしまった場合でも、git rm -rf --cached <path>コマンドを使えばファイルをGitの管理対象から外せます。その後、改めて.gitignoreに追加すれば、ファイルは無視されるようになります。

補足：状況によってはgit resetコマンドが役立つこともあります。git resetは「元に戻す」「時間を巻き戻す」ような操作なので、コミット履歴ごとやり直したい場合などに有効です。

さらにGitについて学びたい方は、ぜひ当サイトのGit学習ガイドも参考にしてください。Gitの効果的な学習方法や、おすすめの学習リソースをご紹介しています。