Git
PR

Gitフック入門|pre-commitで自動チェックする書き方とWindowsでの注意点

Gitフック入門|pre-commitで自動チェックする書き方とWindowsでの注意点
hr
記事内に商品プロモーションを含む場合があります

「デバッグ用の print( を消し忘れたままコミットしてしまった」「コミットメッセージの書き方がメンバーごとにばらばら」。こうしたうっかりを、コミットの直前に Git が自動で見つけて止めてくれる仕組みが Git フックです。この記事では、一番よく使う pre-commit フックを中心に、書き方と動かし方を実行結果つきで説明します。

コマンドと実行結果は、Windows 11 の Git Bash と PowerShell 5.1 で、練習用のリポジトリを作って確かめたものです。この PC の Git のバージョンは次のとおりです。

git --version
git version 2.49.0.windows.1

フックの仕様は、Git の公式ドキュメント(githooks、git-config の core.hooksPath、git-commit)の原文で確認しています。Git の基本操作は「Git入門」、シェルスクリプトの基本は「シェルスクリプト入門」で説明しています。

この記事で分かること

  • Git フックとは何か、.git/hooks の .sample ファイルの意味
  • pre-commit で「print( や TODO」「大きすぎるファイル」を止めるスクリプトの書き方
  • commit-msg でコミットメッセージの形式をチェックする方法
  • --no-verify で飛ばせること(強制力はないこと)と、チームで共有する core.hooksPath
  • Windows(Git for Windows)で動かないときの原因(実行権限・文字コード・改行コード)

Git フックとは?

Git フックは、コミットやプッシュなどの決まったタイミングで、Git が自動で実行してくれるプログラムです。「フック(hook)」は「引っかける」という意味で、Git の処理の途中に自分の処理を引っかけるイメージです。

フックの置き場所は、リポジトリの中の .git/hooks フォルダーです(公式ドキュメントでは $GIT_DIR/hooks)。git init したばかりのリポジトリで中身を見てみます。

ls .git/hooks
applypatch-msg.sample
commit-msg.sample
fsmonitor-watchman.sample
post-update.sample
pre-applypatch.sample
pre-commit.sample
pre-merge-commit.sample
pre-push.sample
pre-rebase.sample
pre-receive.sample
prepare-commit-msg.sample
push-to-checkout.sample
sendemail-validate.sample
update.sample

Git 2.49.0 では 14 個の .sample ファイルが入っていました。これは Git に付いてくる見本で、名前の最後に .sample が付いている間は動きません。git-init の公式ドキュメントにも「サンプルのフックはすべて無効になっている。有効にするには名前から .sample を取る」と書かれています。

つまり、.git/hooks/pre-commit のように決まった名前(拡張子なし)のファイルを置くと、その名前のタイミングで Git が実行してくれます。

終了コードで「続ける・止める」が決まる

フックの結果は、スクリプトの終了コード(exit で返す数字)で Git に伝えます。git commit を実行したときは、次の順番で動きます。

git commit を実行すると、まず pre-commit フックが変更を確認し、終了コードが 0 なら commit-msg フックがメッセージを確認し、それも 0 ならコミットが完了する。どちらかのフックが 0 以外で終わると、コミットは中止されて作られない。
図 1:git commit で動くフックの順番と、終了コードによる分かれ道

公式ドキュメントには、pre-commit について「引数は受け取らず、コミットメッセージを用意する前に呼ばれる。0 以外の終了コードで終わると、git commit はコミットを作る前に中止する」と書かれています。commit-msg も同じく、0 以外ならコミットは中止です。実際に、pre-commit が exit 1 で終わるようにすると、commit-msg は呼ばれず、コミットも作られませんでした。

終了コードの考え方は、シェルスクリプトの if や && と同じです。くわしくは「シェルスクリプト入門」の終了ステータスの章を参照してください。

よく使うフック

フックはほかにもたくさんありますが、手元のパソコンでよく使うのは次のものです(説明は公式ドキュメントの要約)。

フック名動くタイミング止められるか使い道の例
pre-commitgit commit の最初(メッセージを書く前)止められる消し忘れ・大きいファイル・書式のチェック
prepare-commit-msgメッセージの下書きができた直後(エディターが開く前)止められるメッセージにブランチ名を入れておく
commit-msgメッセージが決まったあと止められるメッセージの形式チェック
post-commitコミットが終わったあと止められない(通知用)完了のお知らせ
pre-pushgit push の前止められるテストを通してからプッシュ

この記事では、pre-commit と commit-msg を実際に書いて動かします。

まずは同梱の見本を動かしてみる

一番かんたんな試し方は、見本の pre-commit.sample をコピーして .sample を取ることです。

cp .git/hooks/pre-commit.sample .git/hooks/pre-commit

この見本は、公式ドキュメントによると「ASCII 以外の文字を使ったファイル名」と「行末の余分な空白」を止めます。行末に空白が 2 つある memo.txt をステージしてコミットすると、次のように止まりました。

memo.txt:1: trailing whitespace.
+メモ  

日本語の名前のファイル(日本語.txt)をコミットしようとすると、次のように止まりました。日本語のファイル名を使うプロジェクトでは、この見本はそのままでは使いにくいので、メッセージにあるとおり hooks.allownonascii を true にするか、次の章のように自分で書きます。

Error: Attempt to add a non-ASCII file name.

This can cause problems if you want to work with people on other platforms.

To be portable it is advisable to rename the file.

If you know what you are doing you can disable this check using:

  git config hooks.allownonascii true

試し終わったら、次の章に進む前に .git/hooks/pre-commit を消しておきます(.sample のほうは残ります)。

rm .git/hooks/pre-commit

pre-commit フックを自分で書く

例 1:追加した行の print( と TODO を止める

Python のファイル(.py)に、デバッグ用の print( や、やり残しのメモ TODO を足したままコミットしようとしたら止めるフックです。Git Bash でリポジトリの一番上のフォルダーに移動し、次のコマンドを貼り付けて実行すると、.git/hooks/pre-commit ができます(<<'EOF' から EOF までがファイルの中身になります)。

cat > .git/hooks/pre-commit <<'EOF'
#!/bin/sh
# 今回のコミットで追加した .py の行に print( か TODO があれば止める
if git diff --cached -U0 -- '*.py' | grep -E '^\+.*(print\(|TODO)'; then
  echo "pre-commit: print( か TODO が残っています。消してからコミットしてください。" >&2
  exit 1
fi
EOF

中身を 1 行ずつ見ていきます。

  • #!/bin/sh:「sh で実行する」という印(シバン)。1 行目に必ず書く
  • git diff --cached -U0 -- '*.py':ステージした(git add した).py の変更を、前後の行なし(-U0)で出す。追加した行は先頭が + になる
  • grep -E '^\+.*(print\(|TODO)':「+ で始まり、print( か TODO を含む行」を探す。見つかると grep は終了コード 0 を返すので、if の中に入る
  • >&2:メッセージを標準エラーに出す(標準出力・標準エラーとリダイレクト)
  • exit 1:0 以外で終わるので、コミットが中止される。見つからなければ if に入らず、終了コード 0 でコミットが続く

calc.py に # TODO: 負の数のテスト という行を足し、git add calc.py のあと git commit -m "引き算を追加" を実行すると、次のように止まりました。直後に echo $? で git commit の終了コードを見ると 1 でした。

+    # TODO: 負の数のテスト
pre-commit: print( か TODO が残っています。消してからコミットしてください。

TODO の行を消してもう一度 git add すると、コミットできます。README.md のような .py 以外のファイルだけのコミットは、このフックの影響を受けません。

ポイントは、作業フォルダーのファイルではなく、ステージした内容(--cached)を調べることです。コミットされるのはステージした内容なので、作業フォルダーのファイルを調べると、コミットされない変更で止まったり、コミットされる変更を見逃したりします。

例 2:大きすぎるファイルを止める

動画やデータのような大きいファイルをうっかりコミットすると、あとで履歴から消すのは大変です。ステージしたファイルの大きさを調べ、1MB(1,048,576 バイト)を超えたら止める pre-commit の例です。例 1 と同じように .git/hooks/pre-commit に保存します(フックは 1 つの名前に 1 ファイルなので、両方使いたいときは 1 つのファイルにまとめます)。

#!/bin/sh
# ステージしたファイルのうち、1MB を超えるものがあればコミットを止める
limit=1048576
big=$(git -c core.quotePath=false diff --cached --name-only --diff-filter=AM |
  while IFS= read -r f; do
    size=$(git cat-file -s ":$f")
    if [ "$size" -gt "$limit" ]; then
      echo "  $f ($size バイト)"
    fi
  done)
if [ -n "$big" ]; then
  echo "pre-commit: 1MB を超えるファイルがあります。" >&2
  echo "$big" >&2
  exit 1
fi
  • --name-only --diff-filter=AM:ステージした変更のうち、追加(A)と変更(M)のファイル名だけを出す
  • git cat-file -s ":$f":ステージした内容(:ファイル名)の大きさをバイト数で出す
  • -c core.quotePath=false:日本語のファイル名が "\345\213\225..." のような形に変換されないようにする

2,000,000 バイトの「動画.bin」と 1,000 バイトの small.bin を一緒にステージしてコミットすると、次のように止まりました。動画.bin をステージから外す(git restore --staged 動画.bin)と、small.bin だけのコミットは通りました。

pre-commit: 1MB を超えるファイルがあります。
  動画.bin (2000000 バイト)

コミットせずにフックだけ試す

フックを書き直すたびにコミットを試すのは面倒です。git hook run を使うと、フックだけを実行できます(Git 2.49.0 で確認)。

git hook run pre-commit

例 1 のフックで、TODO の行をステージした状態で実行すると、コミットのときと同じメッセージが出て、echo $? は 1 でした。問題がないときは何も表示されず 0 です。

commit-msg でメッセージの形式をチェックする

commit-msg フックは、コミットメッセージが書かれた一時ファイルの名前を 1 つ目の引数($1)で受け取ります。実際に $1 を表示するフックで確かめると、.git/COMMIT_EDITMSG でした。また、サブフォルダーでコミットしても、フックはリポジトリの一番上のフォルダーで実行されていました(公式ドキュメントの説明どおり)。

次の例は、メッセージの 1 行目が「feat: 〜」「fix: 〜」のように「種類: 内容」の形になっていなければ止めます。.git/hooks/commit-msg という名前で保存します。

#!/bin/sh
# 1 行目が「種類: 内容」の形になっているかを確かめる
# $1 はコミットメッセージが書かれた一時ファイルの名前
first=$(head -n 1 "$1")
if ! echo "$first" | grep -qE '^(feat|fix|docs|test|refactor|chore): .+'; then
  echo "commit-msg: 1 行目は「feat: 〜」「fix: 〜」の形で書いてください。" >&2
  echo "  今のメッセージ: $first" >&2
  exit 1
fi

git commit -m "READMEを更新" は次のように止まり、git commit -m "docs: README に使い方の見出しを追加" は通りました。

commit-msg: 1 行目は「feat: 〜」「fix: 〜」の形で書いてください。
  今のメッセージ: READMEを更新

種類の名前(feat・fix など)は一例です。チームで決めた書き方に合わせて、grep の正規表現を直してください。正規表現の書き方は「正規表現の基本」で説明しています。

–no-verify で飛ばせる(強制力はない)

git commit に --no-verify(短く -n)を付けると、pre-commit と commit-msg のフックは実行されません。git-commit の公式ドキュメントにも「pre-commit と commit-msg フックを飛ばす」と書かれています(prepare-commit-msg は –no-verify でも実行される、とも書かれています)。例 1 のフックがある状態で、print(x) を含む debug2.py をステージし、ふつうの git commit が止まるのを確かめてから、次のように実行しました。

git commit --no-verify -m "debug"
[master c5f44fd] debug
 1 file changed, 2 insertions(+)
 create mode 100644 debug2.py

フックは止められずにコミットされました。つまり、手元のフックは「うっかりを防ぐ便利な仕組み」であって、ルールを守らせる仕組みではありません。フックを入れていない人や、--no-verify を付けた人のコミットは、そのまま入ってきます。

チームで必ず守りたいチェック(テスト・書式・秘密情報の混入など)は、GitHub Actions などの CI(プッシュされたあとにサーバー側で自動で動くチェック)でも同じ内容を確かめます。フックは「プッシュする前に手元で早く気づくため」、CI は「最終的な関所」と役割を分けるのがおすすめです。

Windows(Git for Windows)で動かすときのポイント

Windows でも、ここまでの #!/bin/sh のスクリプトはそのまま動きました。Git for Windows には sh(Git Bash と同じもの)が入っているためです。PowerShell から git commit を実行しても、例 1 のフックは同じメッセージを出してコミットを止めました。

ただし、Linux や Mac と違う点がいくつかあります。この PC(Git 2.49.0)で試した結果をまとめます。

試したこと結果
chmod -x で実行権限を外すls -l の表示は rwx のまま変わらず、フックも動いた
1 行目の #!/bin/sh を書かないerror: cannot spawn .git/hooks/pre-commit: No such file or directory でコミットが中止
PowerShell 5.1 の Out-File(既定は UTF-16)で作る同じ cannot spawn のエラーで中止
BOM 付き UTF-8 で作る同じ cannot spawn のエラーで中止
改行コードを CRLF にするこの PC では問題なく動いた

実行権限:Windows では 1 行目の #! が大事

公式ドキュメントには「実行権限(executable bit)が付いていないフックは無視される」とあります。Linux や Mac では chmod +x .git/hooks/pre-commit が必要ですが、Windows のファイルにはこの権限がありません。Git Bash では、1 行目が #! で始まるファイルは実行できるものとして扱われ(ls -l で x が付く)、chmod -x しても変わりませんでした。逆に #! がないと、上の表のとおりエラーになります。

文字コード:PowerShell で作るときは注意

Windows PowerShell 5.1 の Out-File や > は、既定ではファイルを UTF-16 で保存します(ファイルの先頭が FF FE になることを確認)。UTF-16 や BOM 付き UTF-8 だと、1 行目の先頭が #! ではなくなるため、エラーでコミットが一切できなくなります。フックは Git Bash で作るか、エディターで「UTF-8(BOM なし)」を選んで保存しましょう。文字コードの違いは「UTF-8とは」で説明しています。

改行コード:CRLF でも動いたが、LF にそろえる

例 1 のフックを CRLF(Windows の改行)に変えて試したところ、この PC の Git for Windows では、TODO を止める動きも、問題がないときに通す動きも、LF のときと同じでした。ただし、ほかの OS の sh でも同じように動くかは、この記事では確かめていません。チームで共有するフック(次の章)は LF にそろえておくのが安全です。.gitattributes に .githooks/* text eol=lf のように書くと、取り出すときに LF になります(「.gitattributesの使い方」「改行コードCRLFとLFの違い」)。

フックをチームで共有する(core.hooksPath)

.git フォルダーの中身はコミットされないので、.git/hooks に置いたフックはクローンしても配られません。実際に、フックを置いたリポジトリを git clone すると、クローン先の .git/hooks には .sample のファイルしかありませんでした。

そこで、フックをリポジトリの中のフォルダー(例:.githooks)に置いてコミットし、Git の設定 core.hooksPath でそのフォルダーを使うように指定します。git-config の公式ドキュメントによると、core.hooksPath を設定すると $GIT_DIR/hooks の代わりにそのフォルダーでフックを探し、相対パスは「フックが実行されるフォルダー」(ふつうのリポジトリでは一番上のフォルダー)からの位置になります。

.git/hooks に置いたフックは git clone してもクローン先に届かず、クローン先の .git/hooks には sample しかない。.githooks フォルダーに置いてコミットしたフックはクローン先にも届き、core.hooksPath を設定すると動く。
図 2:.git/hooks のフックはクローンで配られない。リポジトリ内のフォルダーなら配られる

手順は次のとおりです。まず、フックを置く人が .githooks フォルダーに pre-commit と commit-msg を作って追加します。

git add .githooks

Windows で追加したファイルは、実行権限のない 100644 として記録されます(git ls-files -s .githooks で確認)。Linux や Mac のメンバーのために、実行権限ありの 100755 に変えてからコミットします。

git update-index --chmod=+x .githooks/pre-commit .githooks/commit-msg
100755 33b8e2c80d0c152dc0057dcf2179c81040a0b775 0	.githooks/commit-msg
100755 0659c9dce2367fe534cec48979864d8bd4c270cc 0	.githooks/pre-commit

(上は実行後の git ls-files -s .githooks の表示です。)コミットしてプッシュすれば、フォルダーごとメンバーに届きます。受け取ったメンバーは、クローンしたあと自分のリポジトリで 1 回だけ次の設定をします。

git config --local core.hooksPath .githooks

クローンしたリポジトリで試すと、設定する前は TODO を含む .py をコミットできましたが、設定したあとは例 1 と同じメッセージで止まりました。--local はこのリポジトリだけの設定という意味です(--global にするとパソコンのすべてのリポジトリに効いてしまいます)。設定されているかは次のコマンドで確かめられます(.githooks と表示されれば OK)。

git config core.hooksPath

注意点が 2 つあります。1 つ目は、core.hooksPath を設定すると .git/hooks のフックは使われなくなることです(.git/hooks にも pre-commit を置いて試すと、動いたのは .githooks のほうだけでした)。2 つ目は、この設定自体はクローンで配られないので、README などに「クローンしたら最初にこのコマンドを実行する」と書いておく必要があることです。この「全員が設定してくれるとは限らない」点も、CI と併用する理由の 1 つです。

pre-commit フレームワークという選択肢

フックの管理を楽にする道具として、pre-commit(フックと同じ名前のツール)があります。公式サイトでは「pre-commit フックのための、多言語対応のパッケージマネージャー」と説明されていて、.pre-commit-config.yaml という設定ファイルに使いたいチェックを書き、pip install pre-commit と pre-commit install でフックを入れる、という流れが紹介されています。

この記事では pre-commit フレームワークはインストールしておらず、動作は確かめていません。使うときは公式サイトの説明を確認してください。シェルスクリプトで書くフックの仕組みを理解しておくと、こうしたツールが裏で何をしているかも分かりやすくなります。

よくある間違い

関係のないコミットまで止まってしまう

最初に、ステージされているすべての .py を調べる git grep --cached -n -E 'print\(|TODO' -- '*.py' でフックを書いたところ、一度 debug.py(print(x) を含む)がコミットされたあとは、README.md だけを変えたコミットまで次のように止まるようになりました。

debug.py:2:print(x)
pre-commit: print( か TODO が残っています。消してからコミットしてください。

すでにコミット済みのファイルまで調べていたためです。例 1 のように「今回のコミットで変わった部分(git diff --cached)」だけを調べると、この問題は起きません。

フックがまったく動かない

  • ファイル名が pre-commit.sample や pre-commit.txt のまま(拡張子なしの決まった名前にする)
  • core.hooksPath が設定されていて、.git/hooks が見られていない(git config core.hooksPath で確認)
  • Linux・Mac で実行権限がない(chmod +x)

cannot spawn と出てコミットできない

Windows で error: cannot spawn .git/hooks/pre-commit: No such file or directory と出るときは、1 行目の #!/bin/sh がない、または文字コードが UTF-16・BOM 付き UTF-8 になっていないかを確かめます。急ぎのときは --no-verify でコミットはできますが、フックのファイルを直すか消すまで毎回この状態になります。

よくある質問

フックはプッシュすればメンバーに届きますか?

.git/hooks に置いたものは届きません。リポジトリ内のフォルダーに置いてコミットし、各メンバーが core.hooksPath を設定する必要があります。

フックで止まったコミットはどうなりますか?

コミットは作られず、ステージした内容はそのまま残ります。ファイルを直してもう一度 git add し、git commit し直せば大丈夫です。止まった直後に git log --oneline を見ても、新しいコミットは増えていませんでした。

まとめ

  • Git フックは .git/hooks に決まった名前で置くスクリプト。.sample のままでは動かない
  • pre-commit・commit-msg は終了コードが 0 以外ならコミットを止める。調べるのはステージした内容(--cached)
  • --no-verify で飛ばせるので、必ず守るチェックは CI でも行う
  • 共有するなら .githooks などに置いてコミットし、git config --local core.hooksPath .githooks
  • Windows では 1 行目の #!/bin/sh と、UTF-8(BOM なし)で保存することが大事

git restore --staged や git config など、この記事で使ったコマンドを用途から探したいときは「Git コマンド検索」も使ってみてください。

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました