2022/11/21

simple-git-hooksでもブランチ名からIssue番号抽出をやりたくて、わちゃわちゃした話

開発関連技術

shell, Git

こんにちは、よしです。
今回は記事リハビリということで、ちょっとした小ネタ記事を書いてみました。

今回やりたかったこと#

簡潔に言うと
「simple-git-hooks を使った Git フック設定で、ブランチ名から Issue 番号を抽出してコミットメッセージへ自動付与するようにしたい」
というやつです。

背景はいいから実際の設定方法見せてくれや、という方は設定方法の結論へどうぞ。

もうちょっと背景を説明してみる#

Git フック#

皆さんおなじみの Git に Git フックという機能があります。

Git - Git フック

https://git-scm.com

他のバージョンコントロールシステムと同じように、Git にも特定のアクションが発生した時にカスタムスクリプトを叩く方法があります。
このようなフックは、クライアントサイドとサーバーサイドの二つのグループに分けられます。
クライアントサイドフックはコミットやマージといったクライアントでの操作の際に、サーバーサイドフックはプッシュされたコミットの受け取りといったネットワーク操作の際に、それぞれ実行されます。
これらのフックは、さまざまな目的に用いることができます。

公式にも書いてある通り、Git の特定のアクションが発生した時にカスタムスクリプトを叩く仕組みのことです。
（詳細やフックの種類は当記事では説明しないので、公式ページをご参照ください）

この Git フックを使った設定としてよくあるのが…

コミット前に Linter、フォーマッターでコード整形する
ブランチ名から Issue 番号を抽出して、コミットメッセージに自動で付与する

など。

前提として、コミットメッセージに Issue 番号を書いておくと、自動的にその Issue と紐づけをしてくれるのもおなじみですね。（PR なんかでもそうですが）
自分は以前から手動で Issue 番号を書いていたので、これを Git フックで自動化したいなぁと思ったのでした。

Git フックに関するパッケージ#

Git フックを設定となると、多くの方はそれを扱いやすくしてくれるパッケージを利用しているのではないでしょうか。
割と有名なものだと Husky とか。

Husky | GitHub

Git hooks made easy

https://typicode.github.io

自分が Git フックを活用するようになった頃、ちょうど Husky はライセンス問題でごたごたしていた時だったので、自分は simple-git-hooks の方を採用したのでした。
Husky に対して、こちらは Zero dependency かつ軽量版なやつ。

GitHub - toplenboren/simple-git-hooks: A simple git hooks manager for small projects

A simple git hooks manager for small projects. Contribute to toplenboren/simple-git-hooks development by creating an account on GitHub.

https://github.com

じゃあ、simple-git-hooks で今回やりたい仕組みを設定しよう！となったわけですが、ググっても Husky の記事ばかりヒットしまして。
基本的な設定方法はおおよそ同じとは思いつつ、実際にやってみるといろいろハマったので、せっかくなら記事にするかとなった次第です。

前提#

simple-git-hooks を初期設定済み

動作確認環境.

Windows：Git Bash × GNU sed
Mac：iTerm × BSD sed

設定方法の結論#

使用する Git フック#

検索でヒットした多くの記事は commit-msg フックを使用して、コミットメッセージの先頭か末尾に番号を付与しているような感じでした。
ただ、自分の場合はコミットメッセージの一行目末尾に Issue 番号をつけたくて。

commit-msg フックだとちょっとめんどくさくね…？
一行目だけ抽出して末尾に番号付けて、残りの行を結合するとかやらないけなくね…？

ということで、prepare-commit-msg フックを使用する方向に。
あらかじめコミットメッセージテンプレに置換用の文字を入れておき、コミットメッセージ入力前にブランチ名から抽出した Issue 番号に置換する、ということをやることにしました。

このやり方は、こちらの記事を参考にさせていただきました。

コミットメッセージにブランチ名を自動挿入する - Mobile Factory Tech Blog

こんにちは、新卒エンジニアの id:kaoru-k_0106 です何をしたか私のチームでは、コミットメッセージの先頭にチケット番号を入れるルールがあります。例えば、PROJECTNAME-123 〇〇の処理を変更しただと、PROJECTNAME-123の部分がチケット番号です。最初はこれを手動で入力していたのですが、時々入力を忘れることがあり自動挿入しようと思いました。ちょうど、トピックブランチ名がチケット番号だったので、ブランチ名を使う方針で実装をしました。導入手順その1 Gitのコミットテンプレートを設定する Gitのコミットテンプレートとは、コミットメッセージエディタを開い…

https://tech.mobilefactory.jp

コミットメッセージテンプレ#

使用するコミットメッセージテンプレの1行目に置換用のテキストを入れておきます。

.gitmessage

(#Issue)

prepare-commit-msg フックのスクリプト#

prepare-commit-msg はコミットメッセージを入力する前に実行されるフックです。
後述しますが、sed コマンドが GNU でも BSD でも動作するように組んでます。

ブランチ名の前部分がブランチ種別/Issue番号という命名だと抽出する仕組み。
ブランチ種別部分は一旦以下の3つにしました。

feature
bugfix
release

ブランチ名の例.

feature/1
feature/1-test

.githooks/prepare-commit-msg

#!/bin/sh

## sed コマンドが GNU か BSD か確認
GNU_SED=true
sed --version 1>/dev/null 2>/dev/null || GNU_SED=false
echo $GNU_SED

## コミットメッセージ入力前に、ブランチ名から Issue 番号を抽出して置換する
COMMIT_MSG_FILE=$1
MESSAGE=$(cat "$COMMIT_MSG_FILE")

ISSUE_NUMBER=$(git rev-parse --abbrev-ref HEAD | grep -Eo "^(feature|bugfix|release)/[0-9]+" | grep -Eo "[0-9]+")
if [ -n "$ISSUE_NUMBER" ]; then
  if [ "$GNU_SED" == "true" ]; then
    sed -i "s/(#Issue)/(#$ISSUE_NUMBER)/" $COMMIT_MSG_FILE
  else
    sed -i "" "s/(#Issue)/(#$ISSUE_NUMBER)/" $COMMIT_MSG_FILE
  fi
  exit 0
fi

## Issue 番号が抽出できなかった + そのまま続行する場合は、置換用文字列を除去する
read -p "Issue 番号がブランチ名にないので置換できませんが、続行しますか？ (y/N): " YM < /dev/tty
case "$YM" in
  [yY]*)
    if [ "$GNU_SED" == "true" ]; then
      sed -i "s/(#Issue)//" $COMMIT_MSG_FILE
    else
      sed -i "" "s/(#Issue)//" $COMMIT_MSG_FILE
    fi;;
  *) echo "abort." ; exit 1 ;;
esac

Mac の場合は、ファイル作成時に実行権限がつかない？ようだったので実行権限を付与しておく必要がありました。

chmod a+x .githooks/prepare-commit-msg

simple-git-hooks の設定#

前述のカスタムのフックスクリプトを実行するように書けばいいわけですが、\"$@\"で引数を渡すのを忘れずに（引数に関しては後述も参照）

pakcage.json

// 抜粋
"simple-git-hooks": {
  "prepare-commit-msg": "./.githooks/prepare-commit-msg \"$@\""
},

これらの内容で、simple-git-hooks の設定を反映。
以降は、コミットしてコミットメッセージ入力前にフックスクリプトが動作して、置換用テキストがブランチ名から抽出した Issue 番号に指し変わっているはずです。

躓いたところと補足説明#

たったこれだけの設定をするだけでも、意外といろんなところに躓きました。
（普段、シェル書き慣れてないのもあるかも😇）

せっかくなので、どのあたりに躓いたのかと、その補足説明も書いておこうかと。

引数が入らない？#

最初、いろんな記事を読んでみたところ、フックスクリプトの引数$1にコミットメッセージファイルの情報が入ってくることがわかりました。
なので、$1を使うようなシェルを書いていったわけですが、いざ実行するとなぜか値が入ってこない…。
引数の数が入る$#を確認すると0。

どういうこと??? simple-git-hooks だとなんか引数の渡り方が違うんか???と混乱。
原因としては、simple-git-hooks の設定定義時に引数を渡すような書き方をしていなかったせいでした。

// 誤
"prepare-commit-msg": "./.githooks/prepare-commit-msg"

// 正
"prepare-commit-msg": "./.githooks/prepare-commit-msg \"$@\""

simple-git-hooks は設定したフックの種類に応じて、.git/hooks配下にフックファイルを作成します。
（今回だと.git/hooks/prepare-commit-msg）
そのフックファイルの中で、simple-git-hooks 設定で設定したコマンドを実行する、というような仕組みになっているのです。

.git/hooks/prepare-commit-msg

#!/bin/sh
./git-hook/commit-msg "$@"

そのため、元々のフックファイルへ渡されるようになっている引数をカスタムのフックの方でも使用したい場合は、そのまま引数を渡してあげれば OK。

引数渡してないんだから、そりゃあ引数ないってなるやん。

read の処理で止まってくれない#

ブランチ名から Issue 番号を抽出するにあたり、もし番号が見つからなかった場合は、そのまま続行してよいか応答処理を入れるようにしました。

BASHシェルスクリプトで「キー入力待ち」プロンプトを実装する | DevelopersIO

BASHシェルスクリプト実行中に、例えば下記のように表示させたい場面はよくあります。ここで人間が「y（あるいはYes）」と入力しないと先に進まない、問題があればNと入力して終了したり、CTRL+Cで強制終了させたり。 …

https://dev.classmethod.jp

こちらの記事を見て、シェルで応答処理を実現するには read を使えばいいらしいぞとわかり、書いてみて動作確認。
すると、本来はユーザの入力待ち状態になり止まってくれるはずなのですが、止まってくれない…。
どうもユーザ入力部分が勝手に入力されて、y でも Y でもないので続行しない方の処理に進んでしまっているようでした。

この件を調べてみると、ループ処理の中で read を使っているとそういうことがあるという記事がいくつかヒット。
今回はループ処理の中ではないんだけどなと思いつつ。
コンソールからの入力しか受け付けないようにするには< /dev/ttyをつけるとよいとのことだったので、つけたところ止まってくれるようになりました。

unixコマンドについてご教授下さい。 - 以下の処理をしたいのですが、どのように記述するのでしょうか。●5秒毎にファイルの... - Yahoo!知恵袋

unixコマンドについてご教授下さい。以下の処理をしたいのですが、どのように記述するのでしょうか。●5秒毎にファイルの中身を出力するように、while分を使いシェルスクリプトにしました。これを5秒毎ではなく、一時停止に処理を変更したい。Enterキーを押すと、次の処理へ進むようにしたい。「Sample.txt」というテキストファイルがある。※テキストファイルの中身は下記$catSample.txt1...

https://detail.chiebukuro.yahoo.co.jp

sed コマンドの違い#

Windows（Git Bash）でも Mac でも使用できる sed コマンドですが、どうも2種類あって、微妙に挙動が違うらしいとわかり。
種類としては以下の2つ。

Windows（Git Bash）or Linux：GNU sed
Mac：BSD sed

今回使用している、ファイル上書きの-iオプションも挙動が違うものの1つでして。
BSD sed の方では、-iオプションの後ろにバックアップファイルの拡張子をつける必要があるとのこと。
（バックアップファイルを作りたくない場合は、空文字にすると作られません）

# GNU sed
sed -i "s/(#Issue)/(#$ISSUE_NUMBER)/" $COMMIT_MSG_FILE

# BSD sed
sed -i "" "s/(#Issue)/(#$ISSUE_NUMBER)/" $COMMIT_MSG_FILE

そのため、できればどちらでも動作するようなスクリプトにしたいなぁと試行錯誤でわちゃわちゃして。
結果的に、sed --versionコマンドの実行結果でどちらの sed なのか判断するフラグ変数を作り、それで分岐させるようにしました。
BSD sed の場合は、--versionオプションが存在しないのでエラーになることを利用したものです。

それとsed --versionの実行結果を出力はしたくなかったので、1>/dev/null 2>/dev/nullで出力しないようにしています。

bashで標準出力、エラーを捨てるとか、ファイルディスクリプタ - Qiita

1. bashで標準出力、エラーを捨てるとか、ファイルディスクリプタ引用元ファイルディスクリプタ0:stdin1:stdout2:stderr標準出力と標準エラー出力をまとめて file…