**Git のマジックファイル**

以下は、Git の機能拡張に関する投稿の日本語訳です。
意味を正確に伝えつつ、自然な日本語で丁寧に表現しました。

---

.gitignore

Git が追跡しないファイルパターンを定義します。
行ごとに1つのパターンを書き、ワイルドカードやディレクトリマーカーもサポートしています。

node_modules/
*.log
.env
dist/

Git は次の順序で複数の ignore ファイルを確認します：

• 各ディレクトリ内の

  .gitignore

• ローカル限定の無視設定は

  .git/info/exclude

• グローバル ignore ファイル（

  ~/.config/git/ignore

  か

  core.excludesFile

  が指す場所）

OS 固有ファイル（

.DS_Store

や

Thumbs.db

等）はグローバル無視に入れておくと、プロジェクトごとの

.gitignore

を汚染せずに済みます。

パターンマッチはワイルドカード (

*.log

)・ディレクトリマーカー (

dist/

)・否定 (

!important.log

)・文字範囲をサポートし、

**

は入れ子のディレクトリを対象にします。

GitHub・GitLab・Gitea では

.gitignore

を閲覧時にも尊重されますが、既に追跡済みだったファイルは除外されません（

git rm --cached

で追跡解除が必要）。
ウェブエディタでも無視パターンと一致するファイルをコミットできます。
パッケージマネージャは独自の ignore パターン（

node_modules/

、

vendor/

、

target/

等）を持っているため、必ず

.gitignore

に追加してください。

完全な構文は gitignore ドキュメントで確認できます。GitHub は各言語・フレームワーク用のテンプレート集も提供しています。

---

.gitattributes

ファイルごとの取り扱いを指定します。フィルタ、diff ドライバ、マージドライバ、行末正規化、言語検出オーバーライドなどが設定できます。

# Clean/smudge フィルタ
*.psd filter=lfs diff=lfs merge=lfs

# 行末正規化
*.sh  text eol=lf
*.bat text eol=crlf

# バイナリ扱い
*.png binary

# カスタム diff ドライバ
*.json diff=json

# マージ戦略
package-lock.json merge=ours

# GitHub Linguist 用言語検出オーバーライド
vendor/* linguist-vendored
*.gen.go linguist-generated
docs/*  linguist-documentation

text

属性は行末を正規化し、

binary

は diff/merge を行わず1つのバージョンだけを採用します。

merge=ours

はマージ時に常に自分側の変更を保持します。

GitHub Linguist は

.gitattributes

を読み取り言語統計を上書きできます。
ベンダーコードは

linguist-vendored

、生成ファイルは

linguist-generated

、ドキュメントは

linguist-documentation

でマークします。

.gitignore

同様に Git は各ディレクトリの

.gitattributes

と

.git/info/attributes

（ローカル限定）を確認します。
すべての属性については gitattributes ドキュメント、GitHub Linguist のドキュメントで詳細が記載されています。

---

.lfsconfig

Git LFS の設定ファイルです。リポジトリと共にコミットされ、LFS エンドポイント URL や転送設定などを定義します。

[lfs]
    url = https://lfs.example.com/repo
[lfs "transfer"]
    maxretries = 3

Git LFS は LFS コマンド実行時に自動で

.lfsconfig

を読み込みます。
これをコミットすれば、リポジトリを利用する全員が同じ設定を使用できます。
設定ファイルなしでは各開発者が手動でローカル LFS 設定を行う必要があります。

LFS は

.gitattributes

で対象ファイル（例：

*.psd filter=lfs diff=lfs merge=lfs

）を指定します。

.lfsconfig

は LFS 固有の設定（サーバー位置など）を扱います。
既にコミット済みのファイルに LFS パターンを追加した場合は

git lfs migrate

を実行して履歴を書き換え、LFS に移動させる必要があります。

利用可能なオプションは Git LFS 設定ドキュメントで確認できます。

---

.gitmodules

サブモジュールの設定ファイルです。

git submodule add

で作成され、

git submodule update

で読み込まれます。

[submodule "vendor/lib"]
    path = vendor/lib
    url  = https://github.com/example/lib.git
    branch = main

各サブモジュールはパス・URL、追跡ブランチを持つエントリが追加されます。
ファイルはリポジトリのルートに配置します。

サブモジュールは他の Git リポジトリを依存として埋め込むために使われます。

git clone

だけではサブモジュール内容は取得できないので、

git submodule update --init --recursive

または

--recurse-submodules

を付与してクローンします。

バージョニングが不十分（コミット単位で追跡される）やネストされた

.git

ディレクトリを作成し、更新忘れが混乱を招く欠点があります。
しかし、自前のコードベンダリングやモノレポ構造で「一部だけチェックアウトしたい」場合には有効です。

Git サブモジュールドキュメントにワークフロー全体、

.gitmodules

のファイル形式が記載されています。

---

.mailmap

著者名とメールアドレスを正規化された識別子へマッピングします。

git log

・

git shortlog

・

git blame

で出力される際に使用されます。

Proper Name <[email protected]>   Commit Name <[email protected]>

Git はコミットの著者情報と一致するエントリを検索し、出力を書き換えます。

git shortlog -sn

,

git log

,

git blame

すべてが mailmap を参照します。
ただし GitHub の貢献者グラフは mailmap を利用しないため、Web 上では重複エントリが残ります。

mailmap が無いと、メールアドレス変更や名前のタイプミスを行ったコントリビュータが別人として扱われます。
正規化するとすべてのコミットが同一人物に集約されます。

ファイル形式は gitmailmap ドキュメントで説明されています。

.mailmap

をリポジトリルートに置くか、

mailmap.file

で別場所を指定できます。

---

.git-blame-ignore-revs

git blame

がスキップすべきコミット SHA を列挙します。
大量のフォーマッタ変更や lint 実行などノイズとなるコミットを除外し、実際にロジックを書いた作者を明らかにします。

# .git-blame-ignore-revs
# Ran prettier on entire codebase
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

# Migrated to ESLint flat config
b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1

git config blame.ignoreRevsFile .git-blame-ignore-revs

で Git に設定します。
GitHub・GitLab (15.4+)・Gitea は自動的に読み取ります。
グローバル設定にすると、ファイルが無いリポジトリでは

git blame

が失敗するため、各リポジトリで個別に設定するか空ファイルを置く必要があります。

フォーマッタ実行で全コードベースの変更が記録されると

git blame

が意味不明になる問題を解決します。
ファイル形式は1行に1つのコミット SHA、コメントは

#

で付けられます。詳細は git blame ドキュメント参照。

---

.gitmessage

コミットメッセージ用テンプレートです。

git config commit.template .gitmessage

を設定すると、エディタに自動入力されます。

# .gitmessage
# <type>: <subject>
#
# <body>
#
# <footer>
#
# Types: feat, fix, docs, style, refactor, test, chore

他のファイルとは異なり、クローン後に手動で設定が必要です。
チームはセットアップスクリプトや husky などを使い、インストール時にローカル設定を自動化することがあります。
そのため多くのプロジェクトではコミットメッセージの検証用フック（commit‑msg hook）を優先します。

git commit ドキュメントでテンプレートファイルが紹介されており、

prepare-commit-msg

フックは動的にテンプレートを生成する別の方法です。

---

Forge‑Specific Folders

Git フォージ（ホスティングサービス）はリポジトリに独自のフォルダを追加します。

.github/

,

.gitlab/

,

.gitea/

,

.forgejo/

,

.bitbucket/

などです。
これらは Git の機能ではなく、コードと共に移動する設定用フォルダです。

各フォルダには CI/CD ワークフロー、Issue／PR テンプレート、

CODEOWNERS

（レビュアーを指定）等が配置されます。
Forgejo と Gitea にはフェールオーバーチェーンがあります：Forgejo は

.forgejo/ → .gitea/ → .github/.

を順に探し、Gitea は

.gitea/ → .github/.

を探します。
これにより GitHub 向け設定を複数プラットフォームで上書きできます。

SourceHut は

.build.yml

（ルート）または

.builds/*.yml

で CI を定義し、専用フォルダは使用していません。

---

Other Conventions

• .gitkeep – 空ディレクトリを保持するための慣習。

  .gitkeep

  は任意の名前でも可。
• .gitconfig – 推奨設定ファイルとしてプロジェクトに含めるケースがありますが、Git は自動読み込みしません。
  

  git config include.path ../.gitconfig

  等で手動で参照させます。
  モノレポや特定の Git 設定を統一したい場合に使われます。
• .gitsigners – GPG/SSH キーを記載し、trusted signer を管理します。Linux カーネルなどで使用。
  

  git config gpg.ssh.allowedSignersFile

  にファイルパスを設定すると

  git log --show-signature

  が検証に利用します。
• .gitreview – Gerrit コードレビュー統合用設定です。

  [gerrit]
  host=review.opendev.org
  port=29418
  project=openstack/nova.git
  defaultbranch=master
  

  git review

  はこのファイルを読み取り、Gerrit にプッシュします。
• .gitlint – commit メッセージの lint 用設定。

  [general]
  ignore=body-is-missing
  
  [title-max-length]
  line-length=72
  

  Gitlint はこれを読み取りルールを適用します。
• .jj/ – Jujutsu のワーキングコピー状態ディレクトリ。
  Jujutsu は Git と互換性があり、

  .git/

  と同時に

  .jj/

  を持ちます。
  

  .gitignore

  ,

  .gitattributes

  ,

  .mailmap

  等は同様に機能します。

---

Beyond Git

このパターンは Git のみならず、多くのツールで採用されています。
リポジトリ内に dotfile を置くだけで自動検出され、挙動が変わります。

• .editorconfig – チーム全体でエディタ設定を統一します。

  root = true
  
  [*]
  indent_style = space
  indent_size  = 2
  end_of_line  = lf
  charset      = utf-8
  trim_trailing_whitespace = true
  
  [*.md]
  trim_trailing_whitespace = false
  

  VS Code、Vim、Emacs、Sublime 等はネイティブまたはプラグインで対応。詳細は editorconfig.org。
• .ruby-version,

  .node-version

  ,

  .python-version

  – バージョンマネージャが使用言語バージョンを決定します。
  rbenv、nodenv、pyenv、nvm、asdf 等が

  cd

  時に自動切替え。
• .tool-versions – asdf の複数言語版管理ファイル。

  ruby    3.3.0
  nodejs  20.11.0
  python  3.12.0
  

• .dockerignore – Docker ビルドコンテキストの除外設定。

  .git
  node_modules
  *.log
  .env
  

  docker build

  時に送信されるファイルを減らし、イメージに機密情報が含まれないようにします。構文は

  .gitignore

  と同様です。

---

これらのファイルを扱う際の注意点

ツール開発時には以下を尊重するとよいでしょう：

• リポジトリ走査時に

  .gitignore

  を読み込む

• .gitattributes

  を参照し、バイナリ・ベンダー・生成ファイル等を判定する
• 著者情報表示時に

  .mailmap

  を利用する
• サブモジュール処理が必要なら

  .gitmodules

  を読み込む

Git 設定形式（

.gitmodules

等）は

[section "subsection"] key = value

で、Git 自体の

git config

コマンドで読めます。多くの言語には Git config パーサーが用意されています。

他に Git の「魔法ファイル」があれば、ぜひ Mastodon などで共有するか GitHub でプルリクエストを送ってください。