GitHubリポジトリの「お作法ファイル」入門 — .gitignore と README.md を理解する

はじめに

コードは書けるのに、GitHubのリポジトリを見るたびに気になるファイルがある。

my-project/
├── .gitignore   ← これは何？
├── README.md    ← これは何？
└── src/

この2つは「なんとなくあるもの」ではなく、リポジトリを健全に保つためのお作法ファイルだ。それぞれの役割を整理する。

---

.gitignore — 「追跡しなくていいファイル」のリスト

何をするファイルか

Gitに「このファイル（フォルダ）は管理しなくていい」と伝えるための設定ファイル。ここに書いたパターンに一致するファイルは、git add しても無視される。

なぜ必要か

コードを書いていると、リポジトリに入れるべきでないファイルが必ず出てくる。

種類	例	入れたくない理由
依存パッケージ	node_modules/	巨大すぎる。npm install で再生成できる
秘密情報	.env	APIキーやパスワードが漏洩する
ビルド成果物	dist/, *.pyc	ソースから生成できる。差分が汚くなる
エディタ設定	.vscode/, .DS_Store	個人環境の設定を他人に強制しない

.gitignore がないと、これらが全部コミット履歴に入り込んでしまう。

書き方の例

# 依存パッケージ
node_modules/

# 環境変数（秘密情報）
.env
.env.local

# ビルド成果物
dist/
*.pyc
__pycache__/

# OS・エディタが自動生成するファイル
.DS_Store
.vscode/

# で始まる行はコメント。ディレクトリは末尾に / をつけるのが慣習。

テンプレートを使おう

言語・フレームワークごとの .gitignore テンプレートが公式に用意されている。

github/gitignore — Node.js、Python、Java など多数収録

リポジトリ作成時に「Add .gitignore」を選ぶだけで自動生成もできる。

---

README.md — リポジトリの「表紙」

何をするファイルか

GitHubでリポジトリを開いたとき、ファイル一覧の下に自動的に表示されるドキュメント。.md はMarkdown形式の意味で、見出しや箇条書き・コードブロックが使える。

なぜ必要か

コードだけでは「何のプロジェクトか」「どう使うか」が他人（未来の自分も含む）にわからない。README はその説明書になる。

最低限書くべき内容

# プロジェクト名

一行でプロジェクトの概要を書く。

## セットアップ

\`\`\`bash
npm install
npm run dev
\`\`\`

## 使い方

〇〇を実行すると△△ができる。

## 動作環境

- Node.js 20以上
- OS: macOS / Linux / Windows

凝ったものでなくていい。「何か」「どう動かすか」の2点があるだけで、後から見たときに全然違う。

バッジを貼るのも慣習

OSSのREADMEでよく見るこれ：

![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)

ビルド状態やカバレッジを一目で示すためのもの。最初は気にしなくていいが、「こういう意味だったのか」と知っておくと読めるようになる。

---

まとめ

ファイル	役割	ないと困ること
.gitignore	追跡不要ファイルの除外リスト	秘密情報や不要ファイルがリポジトリに混入する
README.md	プロジェクトの説明書	何のリポジトリか誰にもわからない

この2つはリポジトリを作ったら最初に用意するもの、と覚えておけばOK。

---

参考

• github/gitignore — 公式テンプレート集
• Make a README — README の書き方ガイド