Git の改行コード変換

Git は、リポジトリ境界でテキストを LF に正規化しつつ、ワークツリーでは LF または CRLF として提示できます。安定した .gitattributes ポリシーにより、 プラットフォーム依存のコミットを回避し、エディターにはチェックアウトされた形式の 管理だけを担わせることができます。

HEAD、インデックス、ワークツリーのバイト列を区別する #

追跡対象のパスには、関連する表現が 3 つあります。

1. HEAD は現在のコミットに格納された blob を指します。
2. インデックスは次のコミットに含める予定の blob を保持します。
3. ワークツリーはエディターやビルドツールが使用するバイト列を保持します。

正規化対象のテキストでは、git add が CRLF から LF への clean 変換を実行します。 チェックアウト時には、インデックス内の LF から選択されたワークツリーの改行コード への smudge 変換が実行されます。既存のコミットは書き換えられません。

git ls-files --eol -- path/to/file
git show HEAD:path/to/file | od -An -t x1
git check-attr -a -- path/to/file

git ls-files --eol は、インデックス、ワークツリー、および実効属性の形式を 報告します。変換警告に対処する前に、それらの形式を確認してください。

.gitattributes でリポジトリポリシーを宣言する #

すべての clone でポリシーを共有できるように、属性をコミットします。

*       text=auto
*.sh    text eol=lf
*.py    text eol=lf
*.bat   text eol=crlf
*.png   binary
*.pdf   binary

text=auto を指定すると、Git が未指定のパスを分類します。text は正規化を強制し、 -text は正規化を無効にします。また、binary は -diff -merge -text を表す 組み込み属性マクロです。明示的な eol=lf または eol=crlf はパスをテキストとして 指定し、チェックアウト時の形式を制御します。変換によってバイト列が変化するため、 アーカイブ、画像、生成されたバイナリ形式、署名済み成果物は非テキストとして 指定してください。

設定はフォールバックとしてのみ使用する #

core.autocrlf と core.eol は、属性によってより具体的な処理が決まらないパスに 影響します。

core.eol は、明示的な eol 属性がない正規化対象テキストに対して、lf、crlf、 または native を選択します。core.safecrlf=true は不可逆な変換を拒否し、 warn はそれを報告します。どちらの設定も、コミットされた属性ポリシーの代わりには なりません。

git config --show-origin --get core.autocrlf
git config --show-origin --get core.eol
git config --show-origin --get core.safecrlf

安全に再正規化する #

属性を追加または修正した後は、クリーンなワークツリーから始めるか、未コミットの 作業を退避します。その後、意図した正規化をステージし、内容を確認します。

git add --renormalize .
git diff --cached --check
git diff --cached

改行コードの正規化は、セマンティックな編集とは別にコミットしてください。 専用のコミットに分けることで、レビュー、blame、ロールバックの精度を維持できます。 この操作はインデックスを更新しますが、無視対象または未追跡のファイルは変更しません。

特に CRLF を強制するファイルでは、エディターの設定をチェックアウトポリシーに 合わせてください。エディター設定はワークツリーのバイト列に影響し、 .gitattributes はバージョン管理の境界を定義します。実験目的で、重要な 未コミットファイルに対して追加とチェックアウトを繰り返さないでください。 先に実効属性を確認し、作業を保存してください。