こんにちは。iQeda [@iQeeeda] です。
新しいプロジェクトにジョインしたら、チームの Git 運用ルールを頭に入れると思います。
技術的に尖っている現場だと、最初のコミットはちょっと緊張しますね...
そんな僕が今まで遭遇した (調べた) コミット運用方法をまとめてみました。
紹介する prefix や 絵文字を使ったコミットメッセージ運用は最近よく使われています。
...と知っているだけで、いざというとき心に余裕があるはず。きっと。
一般的なコミット作法をおさえよう
作法は「ただのマナー」です。必ずしも従う必要はありません。
しかし多くの開発者は一般的な Git 作法に従ってチーム作業を効率化しようとしています。
- コミットは出来るだけ細かい粒度で行う
- ...とはいえ中途半端なコミットが多いとレビューが大変なので、以下を意識する
- コミット作成後、即プッシュするのはやめよう (冷静になろう)
- 機能でまとめられそうなコミットは Rebase してからプッシュしよう
- 誤字脱字・インデント修正レベルなら
git commit --amendで前回コミットにまとめよう
- 複数のバグ修正をひとつのコミットにまとめるのはやめよう
- コミットメッセージは英語で書くのが好ましい
「3 行ルール」がコミットメッセージのフォーマット
コミットメッセージのコツは 3 行で書くことです！
1行目：コミット内容の要約（タイトル・概要・issue/チケット番号） 2行目：空行 3行目以降：本文 （内容・詳細・変更理由・issue/チケット番号）
ただし 1 行目の要約で全てが伝わるなら 2 行目以降を省略することもあります。
以下はサンプルです。
feat: allow provided config object to extend other configs BREAKING CHANGE: `extends` key in config file is now used for extending other config files
このコミットメッセージ 3 行ルールを深堀り解説しますね。
一行目
コミット内容の要約
- 英語の場合
- 文頭を大文字にする
- 主語不要、命令形の形式で書く
- 時制は現在系にする
- 50 字以内で書く
- 句読点・ピリオドは不要
prefix (接頭辞) emoji (絵文字) を付けると可読性が上がる
prefix とはコミット内容を表す「ジャンル」のようなものだと思ってください。
これをコミットメッセージの先頭に付けることがあります。
この prefix のメリットは以下のようなものが挙げられます。
- コミットが見やすくなる
- レビューしやすくなる
- コミットログを検索しやすくなる
- prefix を意識すると、順序立てて機能分割・機能作成するようになる
- 1 つのコミットに内容を詰め込みすぎたり、分割しすぎないよう意識するようになる
prefix 一覧
よく使われている prefix をまとめてみました。
チームで相談して使いやすい prefix だけ採用するといいでしょう。
| prefix | 意味 |
|---|---|
|
| バグ修正 |
|
| 新規機能・新規ファイル追加 |
|
| バグではない機能修正 |
|
| 仕様変更による機能修正 |
|
| 整理 (リファクタリング等) |
|
| 無効化 (コメントアウト等) |
|
| ファイル削除、コードの一部を取り除く |
|
| ファイル名の変更 |
|
| ファイル移動 |
|
| バージョンアップ |
|
| 修正取り消し |
|
| ドキュメントのみ修正 |
|
| 空白、セミコロン、行、コーディングフォーマットなどの修正 |
|
| 性能向上する修正 |
|
| テスト追加や間違っていたテストの修正 |
|
| ビルドツールやライブラリで自動生成されたものをコミットするとき |
emoji
コミットメッセージの中では絵文字を使うことができます。
prefix の代わりに絵文字を使うとコミット内容が視覚的に分かりやすくなります。
日々の作業も少し楽しくなるので生産性も上がるはずです！
たとえば 🐛 (メッセージ内では :bug: と入力) という絵文字が付いていたら、
と、ひと目で分かりますね。
コミットメッセージ内で絵文字を表現する方法について
絵文字の名前ですが、以下サイトのチートシートで調べるのが便利ですよ。
コミットのテンプレート作成
毎回 prefix や絵文字を調べるのは手間なので、テンプレートで常に確認できるようにします。
~/.commit_template というファイルを作成してください。
このファイルの中に好きなだけメモしましょう。(絵文字も使えます)
たとえば、こんな感じです。
# ==== Prefix ==== # fix # feat # docs # style # refactor # test # chore # ==== Emojis ==== # :bug: バグ修正 (fix) # :+1: 機能改善 (fix/feat) # :sparkles: 部分的な機能追加 (feat) # :tada: 盛大に祝うべき大きな機能追加 (feat) # :rocket: パフォーマンス改善 (feat) # :lock: 新機能の公開範囲の制限 (feat) # :cop: セキュリティ関連の改善 (feat) # :note: ドキュメント修正 (docs) # :shirt: Lintエラーの修正やコードスタイルの修正 (style) # :recycle: リファクタリング (refactor) # :shower: 不要な機能・使われなくなった機能の削除 (refactor) # :green_heart: テストやCIの修正・改善 (test) # :up: 依存パッケージなどのアップデート (chore)
作ったテンプレートファイルを設定します。
git config --global commit.template ~/.commit_template
これでコミットメッセージ作成時にテンプレートが読み込まれます。
(参考) 上記 ==== prefix ==== は Google の一部プロジェクトでも使われているものです。
二行目
空行にする
二行目を空行にする理由を説明しておきます。
空行がない場合、コマンドライン上の表示で 1 行目と 3 行目が連結されて見にくくなるのです。
GitHub などのコメント表示と差異がないようにするため 2 行目は空行にしておく、
という他ユーザへの配慮が必要なのです。
三行目
本文
- 1 行あたり 72 字以内
- 体言止めは使わない
不具合の管理番号を明示することがある
番号管理された不具合を修正した場合、
コミットメッセージの 3 行目で refs #管理番号 と明示することが運用上あります。
※ プロジェクトによっては 1 行目に書くこともあるみたいです
refs は references (参照) の略です。
ということを表せるのですね。
GitHub Issues
BTS も便利ですが、GitHub の Issues 機能で不具合管理してる場合、
コミットメッセージの中で Issue 番号を明示できます。
- 同じ GitHub リポジトリの Issue 番号を明示する場合
#Issue番号
- 他の GitHub リポジトリの Issue 番号を明示する場合
ユーザー/リポジトリ名#Issue番号
GitHub 上で「コミットメッセージの Issue 番号をクリック」すると、
該当の Issue ページにジャンプできます。
コミットで Issue をクローズできる
また Fix#Issue番号 や Close#Issue番号 のように書くと、
プルリクがマージされたとき Issue を解決することができます。
GitHub にはこういった特定キーワードが用意されているので、
詳しくは公式サイトを参照してみてください。
Closing issues using keywords - User Documentation
クローズキーワードを使うとき、誤字脱字に注意！
こういったクローズキーワードの類は便利ですが、誤字脱字すると動かないので注意してください。
大事な情報はプルリクにまとめる
コミットメッセージに色々と書いてくれるとありがたいのですが...
自分が思っているほど、他人はちゃんと読んでくれません!
超重要なことは「プルリクエスト」の中にまとめておきましょう。
また、プルリクエストでは Markdown 記法を使って見やすくしてあげると親切です。
No comments yet