.envは無視して.env.exampleはコミットしたい時の.gitignoreの正しい設定とトラブルシューティング

はじめに

モダンなWebアプリケーション開発、特にDockerを使った環境構築では、docker-compose.ymlと.envファイルを使ってデータベースのパスワードやAPIキーなどの設定を管理するのが一般的です。

このとき、開発チームで必ず直面するのが「機密情報が入った.envファイルはGitの管理下に置きたくない。でも、どんな環境変数が必要かという情報共有のために、テンプレートとなる.env.exampleファイルはGitで共有したい」という要件です。

これは多くの初学者がつまずきやすいポイントであり、設定を間違えるとエディタ上でファイルが無視されてコミットできなくなる、といった問題が発生します。

この記事では、実際の開発で起きたトラブルシューティングの事例を基に、この問題を解決するための正しい.gitignoreの設定方法と、問題発生時の原因特定方法を解説します。

なぜ.envと.env.exampleを分けるのか？

まず、なぜこの2つのファイルが必要なのかを理解することが重要です。

• .envファイル: 実際のパスワードやAPIキーなど、絶対に外部に漏れてはいけない機密情報を記述するファイルです。このファイルはローカル環境でのみ使用し、Gitリポジトリには絶対に含めてはいけません。
• .env.exampleファイル: .envファイルのテンプレート（雛形）です。どのような環境変数が必要かをチームメンバーに知らせる役割を持ちます。実際の値の代わりにダミーの値を記述し、こちらはGitリポジトリに含めてチームで共有します。

プロジェクトに新しく参加した開発者は、リポジトリをクローンした後に以下のコマンドを実行するだけで、自分のローカル用.envファイルを簡単に準備できます。

cp .env.example .env

---

.gitignoreの正しい設定方法

.envだけを無視し、.env.exampleは無視しないようにするための.gitignoreの記述は非常にシンプルです。

悪い例 👎

初心者がやりがちな間違いは、ワイルドカード * を使ってしまうことです。

# この書き方だと .env.example も無視されてしまう
.env*

この書き方では、.envで始まるすべてのファイル（.env.example, .env.developmentなど）が無視対象となってしまいます。

良い例 👍

無視したいファイル名を正確に、ピンポイントで指定するのが最も確実で安全な方法です。

# .env ファイルだけを無視する
.env

たったこれだけです。この1行を.gitignoreファイルに記述すれば、Gitは.envという名前のファイルのみを追跡対象から外し、.env.exampleは通常通り追跡対象として扱います。

---

トラブルシューティング事例

まさに自分がこの問題に直面したので解決までの道のりを事例として紹介します。

状況：エディタ上でファイルが無視される

.gitignoreに.envを追記し、リポジトリで共有すべき.env.exampleファイルを作成したところ、エディタ（VS Code）上でファイル名の横に🚫のような「無視（Ignored）」を示すマークが表示され、git addができない状態になりました。

原因の調査と特定

「.gitignoreには.envとしか書いていないのになぜ？」と混乱してしまいがちですが、こういう時はGitのコマンドを使って原因を正確に特定するのが近道です。

ターミナルで以下のコマンドを実行すると、どのファイル」の「どの行」のルールによって、指定したファイルが無視されているかをGitが直接教えてくれます。

git check-ignore -v .env.example

もし、チャット履歴のケースのように.env*という記述がどこかに残っていた場合、実行結果は以下のようになります。

# 実行結果の例
.gitignore:10:.env* .env.example

この結果は、「.gitignoreファイルの10行目にある.env*というルールが、.env.exampleを無視している原因です」ということを明確に示しています。

解決策

原因が特定できれば、あとは簡単です。
.gitignoreファイルを開き、原因となっていた.env*のような広範囲なルールを削除し、前述した「良い例」である.envという1行だけを残すように修正します。

ファイルを保存すれば、エディタ上の🚫マークが消え、無事に.env.exampleをgit addできるようになります。

---

まとめ：推奨される作業フロー

最後に、一連の正しい作業フローをまとめます。

1. プロジェクトに必要な環境変数を洗い出し、ダミーの値を入れた .env.exampleファイルを作成します。
2. .gitignoreファイルを作成（または追記）し、以下の1行を記述します。

   .env
   

3. 作成した2つのファイルをコミットします。これでチームメンバー全員が同じ設定を共有できます。

   git add .env.example .gitignore
   git commit -m "feat: Add environment template and gitignore settings"
   

4. ローカルの開発環境で、テンプレートをコピーして**.envファイルを作成**します。このファイルはGitに追跡されないので安全です。

   cp .env.example .env
   

5. 作成した.envファイルに、自分のローカル環境用の実際のキーやパスワードを記述して開発を始めます。

この.envと.env.exampleを使い分ける方法は、チーム開発における基本であり、セキュリティを保つ上で非常に重要です。もしトラブルに遭遇したら、まずはgit check-ignore -vコマンドを思い出してください。