.gitattributesの使い方|改行コード・差分・Shift_JIS・LFSを解説
Git で「Windows とサーバーで改行コードがそろわない」「画像や自動生成のファイルの差分が長すぎて読めない」「Shift_JIS のファイルの差分が文字化けする」と困ったことはないでしょうか。こうした「ファイルごとの扱い方」を Git に教えるのが .gitattributes です。この記事では、その書き方とよくある使い方を実行結果つきで説明します。
コマンドと実行結果は、Windows 11 の Git Bash(Git 2.49.0)と PowerShell 5.1 で、練習用のリポジトリを作って確かめたものです。書き方の規則は、Git の公式ドキュメント(gitattributes、git-archive)で確認しています。Git の基本操作は「Git入門」で説明しています。
この記事で分かること
- .gitattributes の書き方(パターンと属性)と、.gitignore との違い
- 改行コード(text・eol)、差分を出さない(binary)、差分を読みやすくする(diff=markdown)設定
- Shift_JIS のファイルの差分を読めるようにする方法(working-tree-encoding と textconv)
- GitHub の言語の割合(linguist)、配布用 zip からの除外(export-ignore)、Git LFS の行の意味
- 設定が効いているかを
git check-attrで確かめる方法
.gitattributes とは?
.gitattributes は、「このパターンに当てはまるファイルは、こう扱ってほしい」という設定(属性)を 1 行に 1 つずつ書くテキストファイルです。リポジトリの一番上のフォルダーに置いてコミットすると、メンバー全員に同じ設定が効きます。
個人のパソコンの設定(git config)は人によって違いますが、.gitattributes はリポジトリと一緒に配られるのが大きな違いです。例えば、次のような .gitattributes を置くと、改行コード・差分の表示・配布用 zip の中身をリポジトリ単位で決められます。
* text=auto
*.sh text eol=lf
*.bat text eol=crlf
*.md diff=markdown
*.min.js binary
tests/ export-ignore
.gitattributes の書き方
1 行は「パターン」と「属性」を空白(スペースかタブ)で区切って書きます。属性は空白で区切って何個でも並べられます。# で始まる行はコメントです。
パターン 属性1 属性2 ...
*.md text diff=markdown
属性の 4 つの状態
公式ドキュメントでは、属性はファイルごとに次の 4 つのどれかの状態になると説明されています。
| 書き方 | 状態 | check-attr の表示 | 例 |
|---|---|---|---|
| 名前だけ | Set(オン) | set | text |
先頭に - | Unset(オフ) | unset | -diff |
名前=値 | 値を指定 | その値 | eol=lf、diff=markdown |
先頭に !、または何も書かない | Unspecified(指定なし。Git の既定の動き) | unspecified | !diff |
同じファイルに複数の行が当てはまるときは、あとに書いた行が優先されます。*.txt text のあとに *.txt -text を書いた .gitattributes で確かめると、n.txt の text は unset になりました。
.gitignore と同じところ・違うところ
パターンの規則(*・**・/ の意味)は .gitignore と同じです(くわしくは「.gitignoreの書き方と、無視されないときの確認方法・直し方」)。ただし、公式ドキュメントには次の 2 つの違いが書かれています。
| 書き方 | .gitignore | .gitattributes |
|---|---|---|
!keep.log(否定のパターン) | 無視を取り消す | 使えない(警告が出て無視される) |
vendor/(末尾の /) | フォルダーの中身ごと無視 | 中のファイルには効かない。vendor/** と書く |
実際に、vendor フォルダー(中に b.js と lib/a.js)がある状態で、次の .gitattributes を置いて確かめました。
vendor/ linguist-vendored
*.log -diff
!keep.log
git check-attr linguist-vendored diff -- vendor/b.js vendor/lib/a.js keep.log
warning: Negative patterns are ignored in git attributes
Use '\!' for literal leading exclamation.
vendor/b.js: linguist-vendored: unspecified
vendor/b.js: diff: unspecified
vendor/lib/a.js: linguist-vendored: unspecified
vendor/lib/a.js: diff: unspecified
keep.log: linguist-vendored: unspecified
keep.log: diff: unset
!keep.log は警告が出て無視され、keep.log は unset のままです。vendor の中のファイルにも属性が付いていません。1 行目を vendor/** linguist-vendored に直すと、b.js と lib/a.js の両方が set になりました。特定のファイルだけ外したいときは、あとの行で keep.log !diff のように書き直します。
置き場所と優先順位
.gitattributes は、一番上のフォルダーだけでなく、サブフォルダーにも置けます。公式ドキュメントによると、優先順位は次のとおりです(上ほど強い)。
| 場所 | 効く範囲 | 共有されるか |
|---|---|---|
| .git/info/attributes | そのリポジトリ(自分だけ) | されない |
| ファイルと同じフォルダー、その親…一番上の .gitattributes | そのフォルダーより下(近いほど強い) | コミットすれば共有される |
| core.attributesFile(既定は ~/.config/git/attributes) | 自分のすべてのリポジトリ | されない |
一番上に *.md diff=markdown、docs フォルダーに *.md -diff と書くと、docs/guide.md だけ diff: unset になりました。
改行コードをそろえる(text・eol)
.gitattributes で一番よく使われるのが改行コードの設定です。基本の形は次の 3 行です。
| 行 | 意味 |
|---|---|
* text=auto | Git がテキストと判断したファイルは、リポジトリの中では LF で記録する |
*.sh text eol=lf | シェルスクリプトは、取り出すときも LF にする |
*.bat text eol=crlf | バッチファイルは、取り出すときに CRLF にする |
CRLF で保存した run.sh と、LF で保存した run.bat を、この .gitattributes のあるリポジトリに追加して git ls-files --eol で見ると、次のようになりました(i/ は Git の中、w/ は手元のファイル、attr/ は付いている属性です)。
i/lf w/lf attr/text eol=crlf run.bat
i/lf w/crlf attr/text eol=lf run.sh
どちらも Git の中では LF で記録され、次に取り出すときに run.sh は LF、run.bat は CRLF になります。注意したいのは、* text=auto だけで eol を書かないファイルは、Windows では 取り出すときに CRLF になることです。手元もすべて LF にしたいなら * text=auto eol=lf と書きます。core.autocrlf との関係や、すでにコミットしたファイルを直す方法は「改行コードCRLFとLFの違いと確認・変換方法」で説明しています。

差分を出さない(binary・-diff)
PNG 画像のように NUL(0x00)のバイトを含むファイルは、Git が自動でバイナリと判断し、差分は Binary files a/logo.png and b/logo.png differ の 1 行だけになります。困るのは、中身はテキストだけれど、人が読む意味のないファイルです。圧縮済みの JavaScript(app.min.js)や自動生成のファイルは、差分が巨大になり、見たい変更が埋もれます。そこで .gitattributes に次の 1 行を書きます。
*.min.js binary
すると、app.min.js の差分も Binary files a/app.min.js and b/app.min.js differ だけになり、git diff --stat の表示も次のように変わりました。
README.md | 2 +-
app.min.js | Bin 45 -> 45 bytes
logo.png | Bin 16 -> 16 bytes
3 files changed, 1 insertion(+), 1 deletion(-)
binary は、公式ドキュメントで [attr]binary -diff -merge -text と定義されている「まとめ属性(マクロ)」です。git check-attr -a で見ると、次の 4 つが付いていることが分かります。
git check-attr -a -- app.min.js
app.min.js: binary: set
app.min.js: diff: unset
app.min.js: merge: unset
app.min.js: text: unset
| 属性 | 効果 |
|---|---|
| -diff | 差分を「Binary files … differ」だけにする |
| -merge | マージで両方が変更していたら、中身を混ぜずに衝突にする |
| -text | 改行コードを変換しない |
改行コードの変換は残したまま差分だけを隠したいなら、binary ではなく -diff だけを書きます。なお、GitHub のプルリクエストで自動生成のファイルを折りたたみたいときは、あとで説明する linguist-generated も使えます。
差分を読みやすくする(diff ドライバー)
git diff の @@ -17,4 +17,4 @@ の行の右側には、変更の場所を示す見出し(関数名など)が表示されます。Git の既定では、行頭が英字などで始まる行を見出しとして使うため、Markdown の ## 設定 のような見出しは拾われません。README.md の「設定」の章の最後の行を変えたときの差分は次のとおりです。
@@ -17,4 +17,4 @@
項目4 の説明です。
項目5 の説明です。
項目6 の説明です。
-タイムアウトは30秒です。
+タイムアウトは60秒です。
.gitattributes に *.md diff=markdown と書くと、同じ差分の 1 行目が次のように変わり、どの章の変更かがひと目で分かるようになりました。
@@ -17,4 +17,4 @@ ## 設定
Git に組み込まれている diff ドライバーの名前は、Git for Windows 2.49.0 に付属の公式ドキュメント(gitattributes)に次の 25 個が載っています。git-scm.com の最新版のドキュメントには、これに swift が加わっていました。組み込みでも自動では効かないので、.gitattributes で指定します。
ada, bash, bibtex, cpp, csharp, css, dts, elixir, fortran, fountain, golang,
html, java, kotlin, markdown, matlab, objc, pascal, perl, php, python,
ruby, rust, scheme, tex
例えば Python では、class App: の中の def run(self): にある行を変えたとき、既定では見出しが @@ -6,4 +6,4 @@ class App: でしたが、*.py diff=python を書くと @@ -6,4 +6,4 @@ def run(self): になり、どのメソッドの変更かが分かるようになりました。2 つのファイルをその場で見比べたいだけなら、ブラウザで使える「テキスト差分比較ツール」でも違いを色分けして確認できます。
Shift_JIS のファイルの差分を読めるようにする
Windows の現場では、古いシステムの設定ファイルや CSV が Shift_JIS(Windows では CP932)のまま、ということがよくあります。Git は UTF-8 として表示しようとするので、差分が文字化けします。「受付時間:9時~17時」を「18時」に変えた Shift_JIS のファイルの差分を、記号に置き換えて(cat -v)表示すると、次のようになりました。
-M-^NM-sM-^UtM-^NM-^^M-^JM-TM-^AF9M-^NM-^^M-^A`17M-^NM-^^^M
+M-^NM-sM-^UtM-^NM-^^M-^JM-TM-^AF9M-^NM-^^M-^A`18M-^NM-^^^M
読めるようにする方法は 2 つあります。文字コードの基本は「文字コードとは?UTF-8・Shift_JIS・EUC-JPの違い」と「Shift_JISとは?」で説明しています。
| 方法 | Git の中の文字コード | 向いている場面 |
|---|---|---|
| working-tree-encoding | UTF-8 に変えて記録する | 新しく作るリポジトリで、GitHub の画面でも読めるようにしたい |
| diff の textconv | Shift_JIS のまま | 今あるリポジトリの中身は変えず、手元の差分だけ読みたい |

working-tree-encoding:Git の中は UTF-8、手元は Shift_JIS
working-tree-encoding を指定すると、Git は追加するときに指定の文字コードから UTF-8 に変換して記録し、取り出すときに元の文字コードに戻します。公式ドキュメントでは、あいまいさを避けるため eol も一緒に指定するよう勧めています。新しいリポジトリに次の .gitattributes を置き、Shift_JIS・CRLF の memo.txt をコミットしました。
*.txt text working-tree-encoding=CP932 eol=crlf
ファイルを書き換えて git diff を実行すると、文字化けせずに表示されました。
@@ -1,2 +1,2 @@
-受付時間:9時〜17時
+受付時間:9時〜18時
担当:田中
git show HEAD:memo.txt で Git の中の記録を見ると UTF-8・LF になっていて、手元のファイルを削除して取り出し直すと、元の Shift_JIS・CRLF のバイト列に戻りました。注意点は次の 4 つです。
- 文字コード名は CP932 にする:
working-tree-encoding=Shift_JIS(SJIS も同じ)で「①」を含むファイルを追加すると、fatal: failed to encode 'a.txt' from Shift_JIS to UTF-8で止まりました。①や髙などの Windows の機種依存文字は Shift_JIS の規格にないためです。CP932 なら追加できました - 波ダッシュの変換:この PC の Git では、CP932 の「~」が Git の中で U+301C の「〜」として記録されました(取り出すと元の「~」に戻ります)
- すべてのメンバーの Git が対応している必要がある:公式ドキュメントには、古い Git(2018 年 3 月時点のもの)や、JGit・libgit2 などの別の実装は対応していないと書かれています。対応していないツールで取り出すと UTF-8 のファイルになってしまいます
- すでにコミットしたファイルは自動では変わらない:Shift_JIS のままコミット済みのリポジトリに .gitattributes を追加しても、
git statusには何も出ませんでした。git add --renormalize .を実行すると memo.txt が「変更あり」になり、コミットすると UTF-8 で記録し直されます
公式ドキュメントも「UTF-8 で保存できないときだけ使う」よう勧めています。
textconv:中身は変えず、差分だけ UTF-8 で見る
diff ドライバーに「表示する前に通すコマンド」(textconv)を設定する方法です。.gitattributes に次の 1 行を書きます(sjis は自分で付ける名前)。
*.txt diff=sjis
次に、このリポジトリの設定として、Git Bash に入っている iconv で CP932 から UTF-8 に変換するよう登録します。
git config diff.sjis.textconv "iconv -f CP932 -t UTF-8"
これで git diff memo.txt が「-受付時間:9時〜17時」「+受付時間:9時〜18時」と読める形で表示されました。Git の中のファイルは Shift_JIS のままです。git config の設定はリポジトリと一緒に配られないので、メンバーそれぞれが同じコマンドを実行する必要があります。
GitHub の言語の割合を直す(linguist)
GitHub のリポジトリの画面にある「Languages」の割合は、Linguist というライブラリが計算しています。Linguist のドキュメントによると、割合は既定のブランチのファイルのバイト数で計算され、バイナリ・外部のライブラリ(vendored)・自動生成・ドキュメントと判断したファイルは除かれます。判断がずれているときは .gitattributes で直せます(overridesで確認)。
| 属性 | 効果 | 例 |
|---|---|---|
| linguist-vendored | 外部のライブラリとして割合から除く | third_party/** linguist-vendored |
| linguist-generated | 自動生成として割合から除き、差分でも折りたたむ | api_pb2.py linguist-generated |
| linguist-documentation | ドキュメントとして割合から除く | docs/** linguist-documentation |
| linguist-language=名前 | 指定した言語として数える | *.inc linguist-language=PHP |
| linguist-detectable | ふだん数えない種類も割合に入れる | *.kicad_pcb linguist-detectable |
これらは GitHub の画面だけに効く属性で、手元の Git の動きは変わりません。ドキュメントには、.gitattributes をコミットするまで反映されないとも書かれています。この記事では GitHub 上での表示の変化までは確かめていません。
配布用の zip からファイルを除く(export-ignore)
git archive は、コミットの中身を zip や tar にまとめるコマンドです。テストや開発用の設定ファイルを配布物に入れたくないときは、export-ignore を使います。
src/app.py・tests/test_app.py・README.md・.gitignore をコミットしたリポジトリでは、何も設定しないと zip に 4 つすべてが入りました。そこで、次の .gitattributes を作ります。
tests/ export-ignore
.gitattributes export-ignore
.gitignore export-ignore
ここで同じコマンドを実行しても、zip の中身は変わりませんでした。git-archive の公式ドキュメントにあるとおり、属性はまとめる対象のコミットの中の .gitattributes から読まれるためです。.gitattributes をコミットしてからもう一度作ると、次のようになりました。
git add .gitattributes
git commit -m "配布物から tests を除く"
git archive --format=zip -o ../after.zip HEAD
README.md
src/
src/app.py
コミットする前に結果を試したいときは、--worktree-attributes を付けると手元の .gitattributes も読まれ、同じ結果になりました。
git archive はフォルダーそのものの属性も調べるので、tests/ でフォルダーごと除かれました(tests/** だと空の tests/ フォルダーが残りました)。
Git LFS の行の意味(入り口だけ)
Git LFS(Large File Storage)は、Photoshop のファイルや動画のような大きなファイルの本体を別の場所に置き、リポジトリには小さな「目印のファイル」だけを記録する Git の拡張機能です。この PC の Git for Windows には Git LFS が入っていました。
git lfs version
git-lfs/3.6.1 (GitHub; windows amd64; go 1.23.3; git ea47a34b)
練習用のリポジトリで「.psd ファイルを LFS で管理する」設定をすると、.gitattributes に 1 行が追加されました。
git lfs track "*.psd"
*.psd filter=lfs diff=lfs merge=lfs -text
filter=lfs は「追加・取り出しのときに LFS の変換を通す」、diff=lfs と merge=lfs は差分とマージを LFS に任せる、-text は改行コードを変換しない、という意味です。LFS はサーバー側の容量や料金にもかかわるので、使い始めるときは利用するサービスの説明を確認してください。
効いているかを確かめる(git check-attr)
「書いたのに効かない」ときは、まず git check-attr で、ファイルにどの属性が付いているかを見ます。-a で付いている属性をすべて、属性名を書けばその属性だけを表示します。ファイル名の前の -- は「ここからはファイル名」という区切りです。
git check-attr text eol diff -- run.sh README.md
run.sh: text: set
run.sh: eol: lf
run.sh: diff: unspecified
README.md: text: auto
README.md: eol: unspecified
README.md: diff: markdown
unspecified なら、どの行も当てはまっていません。パターン・置き場所・ファイルの保存形式(次の章)を見直します。改行コードなら git ls-files --eol も便利です。
よくある間違い
PowerShell で作った .gitattributes が効かない
Windows PowerShell 5.1 は、既定の設定では > や Out-File でファイルを UTF-16 で保存します。Out-File -Encoding unicode(UTF-16)で *.md diff=markdown を書いて確かめると、エラーも出ずに README.md は diff: unspecified でした。.gitattributes は VS Code などのエディターで UTF-8 で保存するか、PowerShell なら次のように文字コードを指定します。
'*.md diff=markdown' | Set-Content -Encoding ascii .gitattributes
.gitattributes を追加したのに、コミット済みのファイルが変わらない
text・eol・working-tree-encoding は追加・取り出しのときに効くので、コミット済みのファイルには git add --renormalize . で入れ直すまで反映されません。作業中の変更をコミットしてから実行しましょう。
よくある質問
.gitattributes と .gitignore はどう使い分けますか?
.gitignore は「管理しないファイル」を、.gitattributes は「管理するファイルの扱い方」を決めます。
まとめ
- .gitattributes は「パターン 属性…」を 1 行ずつ書き、コミットしてチームで共有する。否定(
!)と末尾の/は .gitignore と違うので注意 - 改行は text・eol、差分を隠すなら binary か -diff、見出しを出すなら diff=markdown など
- Shift_JIS は working-tree-encoding=CP932(Git の中は UTF-8)か textconv(中身はそのまま)
- 効かないときは
git check-attr -a -- ファイル名で確かめる
git ls-files や git archive のようなコマンドを用途から探したいときは、「Git コマンド検索」も使ってみてください。
関連する記事・ツール
- Gitコマンド検索
- テキスト差分比較ツール
- 改行コードCRLFとLFの違いと確認・変換方法|Gitのautocrlf設定も解説
- .gitignoreの書き方と、無視されないときの確認方法・直し方を実行結果つきで解説
- Git入門:インストール後の初期設定から最初のコミットまでを実行結果つきで解説
- 文字コードとは?UTF-8・Shift_JIS・EUC-JPの違いと文字化けの原因・直し方
- Shift_JISとは?特徴と文字化け・機種依存文字・5C問題の注意点