Gitのマジックファイルたち

 (nesbitt.io)
45 ポイント 投稿者 GN⁺ 2026-02-24 | 2件のコメント | WhatsAppで共有
  • Gitはリポジトリ内の特定ファイルを通じて動作を制御し、これらは .git/ 内部の設定ではなく、コミットされてコードとともに移動するファイルである
  • .gitignore, .gitattributes, .lfsconfig, .gitmodules, .mailmap などはそれぞれ、ファイル追跡の除外、属性定義、LFS設定、サブモジュール管理、作者の統合を担う
  • .git-blame-ignore-revs と .gitmessage は、コード整形コミットの無視とコミットメッセージテンプレートを提供し、コラボレーションの品質を高める
  • GitHub、GitLab、Gitea などは .github/, .gitlab/, .gitea/ のようなプラットフォーム別設定フォルダを通じて、CI/CD、レビュアー指定などの機能を拡張する
  • この構造は Git を超えて、EditorConfig、Docker、言語バージョン管理ツールなどにも同様に適用され、ドットファイルベースの自動設定エコシステムを形成している

Gitの主要なマジックファイル

  • Gitは .gitignore, .gitattributes, .lfsconfig, .gitmodules, .mailmap など複数の特殊ファイルを認識して、リポジトリの動作を制御する
    • これらのファイルは .git/ 内部の設定ではなく、コミットされて共有される構成要素であり、共同作業時に一貫した動作を保証する

.gitignore

  • Gitが追跡してはいけないファイルパターンを定義する
    • ワイルドカード(*.log)、ディレクトリ(dist/)、否定(!important.log) などをサポート
    • .gitignore, .git/info/exclude, グローバル設定(~/.config/git/ignore) の順で適用される
  • すでに追跡されているファイルは .gitignore を追加した後も引き続き追跡され、git rm --cached で削除できる
  • GitHub、GitLab、Gitea などでは、無視されたパターンのファイルでも警告なしでコミットできる
  • GitHubは言語別の .gitignore テンプレートを公式リポジトリで提供している

.gitattributes

  • ファイルごとのフィルター、diff、merge、改行、言語検出などを制御する
    • 例: *.psd filter=lfs, *.png binary, *.sh text eol=lf
  • text は改行の正規化、binary は diff/merge の無効化、merge=ours は競合時にローカル版を維持することを意味する
  • GitHub Linguist は .gitattributes を読み取り、言語統計からの除外、生成コードの折りたたみ、ドキュメントの除外などを行う
  • ディレクトリごとの .gitattributes と .git/info/attributes もあわせて認識する

.lfsconfig

  • Git LFS設定をリポジトリとともに共有する
    • LFSサーバーURL、転送の再試行回数などを設定できる
    • 例: 
      [lfs]
    url = https://lfs.example.com/repo
[lfs "transfer"]
    maxretries = 3
  • .gitattributes で LFS 処理対象のファイルを指定し、.lfsconfig はサーバー位置などの詳細設定を担う
  • 既存コミットのファイルを LFS に移行するには git lfs migrate コマンドが必要

.gitmodules

  • サブモジュールの構成情報を保存する
  • git submodule add 時に作成され、git submodule update 時に参照される
  • git clone しても自動ではサブモジュールを取得せず、--recurse-submodules オプションが必要
  • バージョン範囲の追跡ができないことや、ネストした .git ディレクトリが生成されることなどの欠点がある

.mailmap

  • 作者名とメールアドレスを統合管理する
    • 例: 
      Jane Developer <[email protected]> <[email protected]>
  • git log, git shortlog, git blame などで統合後の名前として表示される
  • GitHub のコントリビューターグラフは mailmap を反映しない
  • .mailmap または mailmap.file 設定で場所を指定できる

.git-blame-ignore-revs

  • git blame で無視するコミット一覧を指定する
    • フォーマッタ実行、lint 適用など意味のない変更を除外する
    • 例: 
      # Ran prettier on entire codebase
a1b2c3d4e5f6g7h8i9j0...
  • git config blame.ignoreRevsFile .git-blame-ignore-revs で有効化する
  • GitHub、GitLab(15.4+)、Gitea は自動認識する
  • ファイルが存在しないとエラーになる場合があるため、空ファイルを維持することが推奨される

.gitmessage

  • コミットメッセージテンプレートを定義する
    • 例: 
      # <type>: <subject>
#
# Types: feat, fix, docs, style, refactor, test, chore
  • git config commit.template .gitmessage で設定する必要がある
  • クローン後に手動設定が必要で、一部のチームは husky などで自動化している
  • 代替として commit-msg フックや prepare-commit-msg フックも利用できる

プラットフォーム別の拡張フォルダ

  • GitHub、GitLab、Gitea、Forgejo、Bitbucket などは独自の設定フォルダを使用する
    • .github/, .gitlab/, .gitea/, .forgejo/, .bitbucket/
  • CI/CD ワークフロー、Issue・PR テンプレート、CODEOWNERS ファイルなどを含む
  • Forgejo は .forgejo/ → .gitea/ → .github/、Gitea は .gitea/ → .github/ の順でフォールバックする
  • SourceHut は .build.yml または .builds/*.yml を使用する

その他の慣例的なファイル

  • .gitkeep: Git は空ディレクトリを追跡しないため、ディレクトリ維持用のダミーファイルとして使われる
  • .gitconfig: プロジェクト別 Git 設定の例を提供するが、自動では読み込まれない
  • .gitsigners: GPG/SSH 署名鍵の一覧を管理し、gpg.ssh.allowedSignersFile で指定できる
  • .gitreview: Gerrit コードレビューサーバーの設定ファイル
    • 例: 
      [gerrit]
host=review.opendev.org
port=29418
project=openstack/nova.git
defaultbranch=master
  • .gitlint: コミットメッセージの lint ルールを定義する
    • 例: 
      [general]
ignore=body-is-missing
[title-max-length]
line-length=72
  • .jj/: Git 互換 VCS である Jujutsu の状態ディレクトリで、.git/ と共存できる

Gitを超えたドットファイルエコシステム

  • .editorconfig: エディタ間で一貫したコードスタイルを維持する
    • インデント、改行、エンコーディング、空白削除などを定義する
    • VS Code、Vim、Emacs など主要エディタが対応している
  • .ruby-version, .node-version, .python-version: 言語バージョン管理ツール（rbenv、nodenv、pyenv など）が読み取り、自動で切り替える
  • .tool-versions: asdf の多言語バージョン管理ファイル
  • .dockerignore: Docker ビルド時に除外するファイル一覧を指定する
    • .gitignore と同じパターン文法を使い、ビルド速度向上や機密情報の除外に役立つ

Git連携ツール開発時の考慮事項

  • Git リポジトリを扱うツールは、次のファイルを必ず認識する必要がある
    • .gitignore: ファイル探索時に無視パターンを適用
    • .gitattributes: バイナリ・生成ファイルの判別
    • .mailmap: 作者情報の統合表示
    • .gitmodules: サブモジュール処理
  • Git 設定ファイル形式は [section "subsection"] key = value 構造で、git config コマンドで読み書きできる
  • ほとんどの言語向け Git ライブラリは、この形式をパースする機能を提供している

関連記事

2件のコメント

 
wedding 2026-02-24

gitmessage は知らなかったので、使ってみようと思います
 
GN⁺ 2026-02-24
Hacker News の意見
  • GitHub、GitLab、Gitea はどれも .gitignore を尊重して Web UI に無視されたファイルを表示しないと書かれていたが、それは誤った説明のように思える
    実際には、無視されたファイルが リポジトリに含まれていないから 表示されないだけだ。すでにコミット済みのファイルなら、むしろ表示されるべきだと思う
    • そうではない。すでに push されたファイルを後から .gitignore に追加しても、UI には引き続き表示される。そのファイルは依然として repo の一部 だからだ
      逆に、最初から無視されているファイルを強制的にコミットすることも可能だが、少しコツがいる
    • その通りで、元コメントが間違っている。.gitignore は単に untracked ファイルを隠すかどうか だけを決める。望めば無視されたファイルもコミットできる
    • showinwebui=(true|false) みたいなオプションがあるといいのにと思う 😄
    • こんなミスを人間が自分で書いたとは思えなくて、その箇所で読むのをやめた
  • .git/info/exclude を強調したい。これは ローカル専用の gitignore で、自分だけのための設定だ
    たとえばバグ調査中に一時ファイルを作って、ブランチを切り替えてもそのまま残しておきたいときに便利だ
    私は次のようなシェル alias を作って使っている 
    git-ignore-local () {
  echo "$1" >> .git/info/exclude
}
    こうすると git-ignore-local myfile.ext で簡単に追加できる
    • ルートディレクトリにいなくても動くように、もう少し 魔法っぽいバージョン を作ってみた
      macOS では readlink の部分だけ直せばよい 
      git-ignore-local () {
  root=$(git rev-parse --show-toplevel)
  path=$(readlink -f "$1")
  relpath=$(relpath -m --relative-to="$root" "$path")
  echo "$relpath" >> "${root}.git/info/exclude"
}
      この関数を PATH に git-ignore-local として登録すれば、git ignore-local のように使える
    • .git/info/exclude は .gitignore の説明の最初の部分でも触れられている
    • こういう機能があるのは初めて知った。自分のプロジェクトでもこうした 小さな一時ファイル のせいで PR が煩雑になっていたので、これで解決できそうだ
  • .gitattributes に /test export-ignore を追加すると、本番サーバーへデプロイする際にテストファイルを除外 できる
    Capistrano のようなデプロイツールが git export を使うと自動で適用され、テストファイルがサーバーに上がらなくなる
    開発中には影響せず、ディスク容量の節約にもなる
    • 良い機能だが、たいていの人は git archive 自体をあまり知らない気がする
      基本的な CI ツールでもほとんど使われているのを見ない。Capistrano がこれを活用している最初の例として知った
      ちなみに export-subst オプションを使えば、git describe に近い情報をファイル内へ直接埋め込むこともできる
  • jj を使っていて、.jj フォルダを repo とすべての git 操作から完全に除外 したかった
    git clean -xdf でも消されないようにしたい。今は暫定的に git clean -e .jj alias で対応している
    • .git/info/exclude を使えばよい
  • GitHub の contributor graph は .mailmap をサポートしていない
    関連する議論は GitHub Community Discussion にある
  • package-lock.json merge=ours の設定は危険だと思う
    merge や rebase の際に ours/theirs の意味が曖昧 だからだ
    こうした設定が意味を持つのは、自動化されたマージツール（例: git-annex branch）だけだ
    参考: ours/theirs の意味の説明、git-annex の内部構造
  • .git-blame-ignore-revs は良い機能だが、「その他の慣習」セクションに入れるべきだ
    git クライアントに設定していないと、そのファイルがないリポジトリでは git blame が失敗する
    • git 2.52 からは (:optional) オプションを使って、ファイルがなくてもエラーにならないようにできる
      関連説明は Stack Overflow の回答 にある
  • 全体としてよく整理されたリストだと思う
    ただ、すべてのツールが .mailmap をサポートしていないのは残念だ。たとえば IntelliJ ではまだ関連機能が バグ/機能要望の状態 にある
    また、.git-blame-ignore-revs は単なる慣習にすぎず、手動で設定しないと動作しない
  • 少し話はそれるが、VS Code が .ignore ファイルも認識することを最近知った
    .gitignore だけが適用されると思っていたが、.ignore で ripgrep の設定を変えたら 検索結果が変わった。調べてみると、理にかなった挙動だった
  • 記事の著者は forge-specific repository folders（一種の「マジックフォルダ」）についての続編も公開していた
    リンク: nesbitt.io の記事