Gitのブランチ管理をスマートにするための命名規則とメモ・コメント・説明書きの設定

この記事は、ジーズアカデミー 技術記事書いてみた編 Advent Calendar 2023の19日目の記事です。

Git操作をしているとブランチを切ることが日常のようにあると思います。

ある日、とあるプロジェクトにおいて自分が切ったブランチ一覧を見ていて「わかりずらいなー」と思ったことがありました。

また、ブランチが大量に存在したままにして「あれ、このブランチって何のために作ったんだっけ？」「どの目的のためのブランチなんだっけ？」という状態に陥ってしまったこともありました。

自分でやった作業のはずなのに自分自身で忘れる→思い出したり、大量のブランチを整理するのに時間をかけてしまうのは本当に無駄でしかありません…

ということで、上の方に書いたような怠惰な自分への戒めもかねて、Gitのブランチ管理をスマートにするための命名規則とブランチごとの説明書きの設定の仕方について、今回の記事にてまとめてみたいと思います！

Gitのブランチ名の命名規則について

まずはGitのブランチ名の命名規則についてです！

Git操作において、ブランチを切るときは最初にブランチ名を設定します。

その名前が適当すぎると、後で見た時にどのブランチが何のために存在しているのか全くわからなくなってしまいます…

ブランチ名だけでブランチごとの細かい目的・内容を完全に把握するのは難しいかもしれませんが、ある程度ルールを決めていたり、統一感のあるものにしておけば、多少なりともカオスな状態から脱することができるはず…!

ということで、ブランチ名をどうつけるべきか？改めて色々な情報も調べながら、考えてみました。

ブランチ名をつける上での大前提の考え方

まず、ブランチ名にある程度の命名規則を設けた方が良い目的を改めて考えてみたいと思います。

それは、「ブランチ名を見ただけでそのブランチが何のために存在しているのかが多少なりともわかること」ではないかと思います！

例えば、

• 新規機能開発のために作られたブランチ? or バグを修正するために作られたブランチ？
• GitHub Issueや課題管理ツールなどでいうどのタスク（Issue）に紐づくブランチ？

この辺りがわかるように命名規則を整えるだけでも、だいぶ違うのではないでしょうか！

なので、ブランチ名をつける上では、

ブランチの目的-どのタスクに紐づいているか

が最低限ブランチ名に反映された状態になっているのが良いのではと考えられます。

上記以外の部分は、プロジェクトの体制や運用方法によって追加していけばいいと思います。

ブランチ名の命名規則事例(ブランチの目的)

では、具体的なブランチ名の命名規則事例です。

先ほど

ブランチの目的-どのタスクに紐づいているか

という内容が命名規則に反映されていればいいのでは？と書かせていただきましたが、まずは「ブランチの目的」について、どう命名規則に反映させていけばいいかを見ていきます！

ブランチの目的を命名表現する際、一般的には以下のような定義が用いられることが多いようです。

• feature・・・新規機能開発用途のブランチ
• hotfix・・・公開されているプロダクトにおいて発見されたバグを対処する用途のブランチ
• bugfix・・・バグ修正の用途のブランチ

例えばブランチを新規で作る際に

git checkout -b feature-●●●

といった形で接頭語として「ブランチの目的」を示す単語をつけるケースが多いようです。（実際僕自身もそうです。が、時々なんでもかんでも癖でfeatureって打ちがち…）

上記以外の用途がある場合はプロジェクトごとにルールを決めていけば良いと思いますが、最低限、上記のようなルールを設定しておけば、どこのプロジェクトにいっても対応できるのではないでしょうか。

※なお、単語間を-（ハイフン）で区切るか、/（スラッシュ）で区切るかはプロジェクトごとに決めていけば良いかと思います。

ブランチ名の命名規則事例(どのタスクに紐づいているか)

次に、「どのタスクに紐づいているか」の部分をどうやってブランチ名に反映させていけば良いか、について見ていきます！

GItHub Issueだったり、Jiraなどの課題管理ツールなどを用いている場合、「タスク」という概念が存在していると思います。

この「タスク」には課題を示す数字やIDが付与されているかと思いますので、シンプルな方法としては、この課題IDなどをブランチ名にそのまま反映させるのが良いのではないかと思います。

具体的には、

git checkout -b feature-task001
（GItHub Issueであればgit checkout -b feature-issue56みたいな感じ）

みたいな感じですね。

万が一…先述したような課題管理ツールなどを用いていない場合（あんまりないと思いますが）や、hotfix対象で特定の課題IDやIssue番号を用いることができないことがあれば、今紹介したような命名規則の代替を何かしら考えないといけないかと思います。

その際は、以下のような内容をブランチ名に反映させるように単語をチョイスすると良さそうです。

• 何の修正をするのかがわかる。あるいはどこのコンポーネントやページの修正をするのかがわかる。
• 作業の性質がわかる。
• （場合により）修正日がわかる。

以上の内容を踏まえると、例えば以下のようなブランチ名の付け方が候補に上がると思います。

bugfix/payment-processing
hotfix/critical-login-error
hotfix/handswriting-valid-check

この辺はケースバイケースというのもありえそうですね。

避けたいブランチ名の命名規則

ここまでは抑えておきたい命名規則について書いてきましたが、逆に「避けるべき命名規則」も存在するかと思います。

以下、当たり前のことを羅列するような感じになってしまいますが、並べていきますね！

• ブランチ名が長すぎる or 短すぎる
• ブランチ名が抽象的すぎる（単語のチョイスがわかりにくい）

この辺りを抑えておけば最低限いいのではないでしょうか！

Gitのブランチごとに説明書きをつける

次に、Gitのブランチごとに説明書きをつける方法についてです。

Gitのブランチ名だけでそのブランチの目的や内容が分かればいいのですが、なかなか現実問題そうもいきません。

ブランチの量が増えていくと、「あれ、このブランチ何のために作ったんだっけ？」となることもあり得ます。（まあ、もう作業が完了したブランチは適宜削除すれば良い話ではあるのですが…）

こんな状況を解消してくれるのが「Gitのブランチごとに説明書き・コメントをつける」です！

Gitには、ブランチごとに説明書きやコメントをつける方法が存在します。この機能を活用することで、「あれ、このブランチ何のために…？」という現象に陥ることを避けることができます。

Gitのブランチごとに説明書きをつける方法

それでは、Gitのブランチごとに説明書きやコメントをつける方法について見ていきましょう！

まずは説明書きをつけたいブランチ名を確認しましょう！

その上で、以下のコマンドを実行します。

git branch --edit-description 説明書きをつけたいブランチ名

すると、上記のような画面（Viの画面）になるので、iを押してINSERTモードにし、ブランチの説明書き・コメントを入力していきます。

入力が終わったら、ESC+:+w+qを順にキーボードで入力していき、入力内容を保存します。

これで、ブランチごとに説明書き・コメントをつける方法は終了です！

ブランチの説明書き・コメントを見る

次に、ブランチにつけた説明書きやコメントを確認する方法を見ていきましょう！

以下のコマンドを実行すればOKです！

git config branch.ブランチ名.description

コメントが付与されている場合は、ちゃんと内容が出てきます！シンプルですよね！

説明書き・コメントをする内容は基本的に自由ですが、例えば課題管理ツールの特定タスクのURLだったりGitHub IssueのIssue番号やURLを付与するなどしておくと、わかりやすくて良さそうですね！

まとめ

ということで、今回は「Gitのブランチ管理をスマートにするための命名規則とメモ・コメント・説明書きの設定」について書いてみました！

僕も絶対ブランチ迷子にならないようにするぞ…