Git Notes: Gitの最もクールで最も愛されない機能 (2022)

 (tylercipriani.com)
3 ポイント 投稿者 GN⁺ 2025-06-23 | 1件のコメント | WhatsAppで共有
  • Git notes は、コミットなどにメタデータを付加できる 強力なツール
  • この機能により、コミットメッセージを修正できない場合でも 補足情報を保存 できる
  • コードレビュー履歴 やテスト結果など、さまざまな情報の保存に活用できる
  • 分散コードレビューシステム まで実装できるが、使い勝手と認知度が低い
  • GitHubで無効化されるなどサポートが不足しており、日常的な採用は低調

Git notesとは何か

  • Git notes は、gitで追跡されるあらゆるオブジェクト（コミット、ブロブ、ツリー）に メタデータ を付加できる機能
  • 一般に、一度記録されたコミットメッセージは変更できないが、git notesを使えばコミット本文を変更せずに新しい情報を追加できる
  • たとえば、以下のようにコミットへ notes を追加できる
    • git notes add -m 'Acked-by: <email>'
  • notes は git log で別セクションとして一緒に表示される

実際の活用事例

  • gitプロジェクト自体でも git notes を活用し、コミットとメーリングリスト内の議論スレッドを結び付けている
  • notes の実際の活用例としては、次のような項目がある
    • コミットまたはブランチごとの作業時間の追跡
    • コードレビューやテスト結果ログの保存
    • 完全に分散されたコードレビューシステムの設計

コードレビューとテスト結果の保存

  • コードフォージやレビューシステムが、コードレビューのメタデータをオフライン、つまりgit自体に保存できるよう支援する例が増えている
  • Gerrit の reviewnotes プラグイン は、git log でレビュー実施者やテスト実行履歴を notes として一緒に表示する
    • ユーザーはブラウザを別途開かなくても、ローカルでコードレビュー履歴を確認できる

分散コードレビューシステム

  • Googleで開発された git-appraise のように、git notes を用いて分散コードレビューを実現した事例がある
  • git-appraise は、コードレビュー依頼、変更点へのコメント、レビュー後のマージなど、すべての手順を git notes に記録し、オンラインのコードホスティングサービスに依存せず独立して動作する
  • ローカル環境であらゆる共同作業が可能で、Webインターフェースまで提供している

低い使い勝手と認知度

  • Git notes はインターフェースが使いにくく、一般ユーザーには直感的ではないため、ほとんど使われていない
  • GitHub は2014年以降、コミット notes の表示をやめたため、さらに使われる機会が減った
  • コミットに対する notes の管理だけなら git 設定で多少簡単にできるが、ブロブやツリーオブジェクトに notes を付けるには、git の内部構造（plumbing）への追加理解が必要になる
  • その結果、git notes は依然としてマニア向けで、認知度が非常に低い機能のまま残っている

オープンフォージ（Forge）独立性

  • git 自体は分散バージョン管理とコードレビューを支援できるが、レビュー履歴など多くの付加価値は GitHub のようなホスティングサービスに強く依存する傾向がある
  • Git notes 機能を活用すれば、コード自体の変遷だけでなく、プロジェクト全体の履歴まで分散方式で保存・配布する道が開ける
  • これは完全な分散開発エコシステムと記録保存にとって重要な意味を持つ

関連記事

1件のコメント

 
GN⁺ 2025-06-23
Hacker Newsのコメント

  • あまり知られていない機能として Git trailer があるという情報共有。trailer はコミット作成時に key-value 形式のメタデータを挿入でき、Gerrit で Change-Id を付与するのに活用されている。関連記事リンク

    • PostgreSQL にも COMMENT という似た機能があるという情報共有。COMMENT はデータベースオブジェクトにテキストを追加できる。PostgreSQL が key-value 形式の構造化メタデータを編集する機能も提供してくれるとよいのだが。関連ドキュメントリンク

    • オープンソースの upstream 作業時に、単体テストが完了したコミットを示すために git notes を使った経験の共有。git rebase -i でブランチを整えるときに便利だったが、今では trailer のほうがより良い方法に見える。Change-Id のような機能が git 自体に含まれていれば、ツールがそれをもっとよく理解できそうだ。コミットメッセージでコミットを区別するのは微妙に脆弱で、コミット id は一意性の点では優れているが、同じ変更を別のコミットの上に移すと識別子としての有用性が下がる。修正: trailer はコミットの一部なので、notes を完全には置き換えられないだろう

    • 最近 GitHub が [skip ci] の代わりに別個の trailer を使っていることを知った。おそらくコミットメッセージから簡単に切り出せるようにするためだろう。GitHub がなぜ最後の trailer だけを要求するのかははっきりしないが、おそらく正規表現の処理の都合ではないかと推測している。関連ドキュメントリンク

    • trailer 機能を初めて知った。Conventional Commits のファンとして、こうしたメタデータ追加には trailer のほうが向いていそうだ。コミットメッセージに手動で追加するのと --trailer フラグを使うのとで、機能的に同じなのか気になる

    • 自然に issue tracking system と連携したくなるが、trailer のような場所にそれを入れるのは issue tracker から離れすぎていて非効率だ。issue tracker はトレンドの後追いになりがちで、さまざまな機能の追加も遅い。チケット名から派生したブランチ名を PR タイトルとして必ず使わなければならないルールも不便で、別のメタデータでコミットと issue をつなげて PR タイトルをもっと意味のあるものにしたい。簡単に変えられる話ではないので、インターネットで愚痴るしかない話題だ

  • Forgejo が今年 1 月にリリースされた 10 バージョンから trailer のサポートを始めたという情報共有。リリースノート プルリクエスト

  • git notes と history rewriting（amend、rebase など）の相互作用についての疑問。notes はコミット / ツリー / blob ID に結び付いているので、新しいコミットに置き換えられたときに notes がコピーされるのか、それとも消えるのかが気になる。interactive rebase で複数コミットをまとめるときはどうなるのかも気になる。notes がファイル / ディレクトリの「内容」に付くという点で、期待とは違うという認識の共有。たとえば Hello world! という文字列の blob に note を付けたら、同じ内容を持つすべてのファイルに note が付くのか、ファイルが変更されたら notes を失うのかが気になる

    • git rebase などでの notes のコピーは、デフォルトでコピーされるように設定できる。git-config(1) の notes.rewrite オプションを参照

  • 現在の職場で git notes を積極的に使っている。目的は、コミットメッセージを複雑にしたり、すべての変更に対して PR を作ったりせずに、内部のコードレビュー記録を管理すること。各コミットがどのチケットに対応しているか、インフラ上の制約、修正であれば incident スレッドへのリンクなど、ブランチにコンテキストを残している。この情報を repo に保存することで、slack や jira を検索しなくても、なぜその 1 行が変わったのかを把握しやすくなる。大規模に活用すれば、platform UI の必要性を確実に減らせる。reproducibility はビルドだけでなく「意図」にも必要だという意見

    • こうした情報はコミットメッセージに入っていたほうがよいのではないか、それとも「このコミットがバグ #123 を生んだ」のような将来方向へのリンクまで意図しているのかが気になる

  • git notes は、コミット後に追加情報が必要になったときにだけ本当に有用だという意見。Acked-By やメーリングリストでの議論へのリンクのような例は、コミット時点ですでに分かっている情報なので、コミットメッセージに追加すればよい。むしろ git note の本当の利点は、あとから revert されたコミットなどに補足説明を付けられる点だと思う

    • commit message がバグを直したと豪語しているのに、実際には直っていないことはよくある。そのせいでバグが連鎖し、同僚たちが最初の作成意図を無視して適当に通り過ぎてしまうケースも多かった。怒った顧客やバグ再発を経験してからは、bug fix には慎重である必要を感じるようになった。ときには複数のバグを一度に直したり、リファクタリングによって性能改善や新機能の機会が開けたりもする

    • Acked-By、レビュー、議論は、コミット後に続くものにならざるを得ない。コミットされる時点ではまだ分からない。revert された事例は、むしろコミットメッセージに追加するのが有用だ。blame 機能が最新の変更を表示するので、revert されたコミットにも自然に追跡機能が提供される

    • コミット後にも議論が続くことは多い

  • code agent に追加コンテキストを与える目的で、notes 機能を探ってみる価値がある興味深いポイントだと思う

  • これは知識不足ではなく UI の問題だ。GitHub の UI が notes をきちんと表示してくれれば、すぐにもっと使われるようになるはずだ

    • GitHub で notes がサポートされてほしい

  • git には bisect、pickaxe、reflog、range-diff、archive、annotated tags など、「最もクールで愛されていない機能」がたくさんあるが、たいていの人は google drive のようなものとしか見ていないので使わない

    • git notes は、どうせ別のプロジェクト管理ツール（例: Jira）で feature、roadmap などの非技術的コンテキストを追跡しているので重複しているように感じる。Unix 哲学に従って、それぞれが自分の役割に集中すべきだ

    • pickaxe という機能は初耳で予想外だった。あまり自信過剰になるべきではなさそうだ

    • こうした装飾的な機能は、実際にはそれほど有用でないことが多い。本質の周囲にある小技にすぎないという見方

  • git notes は本当に「クールな」 unloved feature ではなく、特定のごく限られた状況でだけ役に立ったという意見。本当に必要な情報はすべてコミットメッセージに入れて、ほかのシステム（例: JIRA）から参照するパターンのほうがむしろ利点だ。JIRA のようなシステムは、開発者ではない business analyst や support 担当者とのコミュニケーション窓口として機能する。開発者ではない人が repo やコードへのアクセス権を持っていないのも合理的だ。複数のサービス / レポを同時に扱う状況では、notes 程度では feature 参照は現実的に不可能で、外部システムとの連携が必要になる

    • business analyst がコードやリポジトリにアクセスできないのは非効率だという指摘。実際にはコード 1 行を見れば分かることでも毎回質問される状況がある。技術的な素養を持つ analyst もいるが、文化は簡単には変わらないという現実的な限界への言及

  • man ページを通じて notes を 2020 年ごろに初めて知った。基本的に notes はローカル repo にしか適用されないので、実際に活用した経験はない。push / fetch を別途設定してチーム単位で使うか決める必要があるが、自分のチームでは採用しなかった