git-notes(1)

SYNOPSIS

'git notes' [list [<object>]]
'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] )
'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace]
'git notes' show [<object>]
'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref>
'git notes' merge --commit [-v | -q]
'git notes' merge --abort [-v | -q]
'git notes' remove [--ignore-missing] [--stdin] [<object>...]
'git notes' prune [-n] [-v]
'git notes' get-ref

DESCRIPTION

オブジェクト自体に触れることなく、オブジェクトに添付のノートを追加、削除、または読み取ります。

デフォルトでは、ノートは refs/notes/commits に保存され、そこから読み取られますが、このデフォルトはオーバーライドできます。以下の「OPTIONS」セクション、「CONFIGURATION」セクション、「ENVIRONMENT」のセクションを参照してください。このrefが存在しない場合、ノートを保存するために最初に必要になったときに黙って作成されます。

ノートの一般的な使用法は、コミット自体を変更せずにコミットメッセージを補足することです。ノートは、元のコミットメッセージとともに git log で表示できます。コミットオブジェクトに格納されているメッセージと区別するために、ノートはメッセージと同様にインデントされます。インデントされていない行には "Notes (<refname>):" (refs/notes/commits の場合は "Notes:") と書かれています。

--notes オプションを使用して、 git format-patch で作成されたパッチにノートを追加することもできます。このようなノートは、3つのダッシュの区切り行の後にパッチの解説として追加されます。

git log で表示されるノートを変更するには、 [CONFIGURATION] の notes.displayRef についての議論を参照してください。

コミットを書き換えるコマンド間でノートを渡す法については、 notes.rewrite.<command> 構成を参照してください。

SUBCOMMANDS

list

指定のオブジェクトのノート・オブジェクトを一覧表示します。オブジェクトが指定されていない場合は、すべてのノート・オブジェクトとそれらが注釈を付けるオブジェクトのリストを表示します("<note-object> <annotated-object>" 形式)。サブ・コマンドが指定されていない場合、これはデフォルトのサブ・コマンドです。

add

指定のオブジェクト(デフォルトはHEAD)にノートを追加します。オブジェクトにすでにノートがある場合は中止(abort)します(既存のノートを上書きするには -f を使用します)。ただし、 add を対話的に使用している場合(エディターを使用してノートの内容を入力する場合)、中止する代わりに、(edit サブコマンドのように、)既存のノートがエディターで開かれます。複数の -m や -F を指定すると、メッセージ間に空行が挿入されます。他の区切りを挿入するには、 --separator オプションを使用します。 -e を使用すると、ノートを追加する前に、 -m や -f オプションで(エディターを使用して)対話的に編集して微調整できます。

copy

最初のオブジェクトのノートを2番目のオブジェクト(デフォルトはHEAD)にコピーします。 2番目のオブジェクトにすでにノートがある場合、または最初のオブジェクトにノートがない場合は中止(abort)します(-f を使用して2番目のオブジェクトの既存のノートを上書きします)。このサブコマンドは git notes add [-f] -C $(git notes list <from-object>) <to-object> と同等です。

--stdin モードでは、以下の形式で行を取得します

<from-object> SP <to-object> [ SP <rest> ] LF

標準入力で、各<from-object>から対応する<to-object>にノートをコピーします。 (オプションの <rest> は無視されるため、コマンドは post-rewrite フックに与えられた入力を読み取ることができます。)

append

-m または -F オプションで指定された新しいメッセージを既存のノートに追加するか、あるいは、存在しない場合は新しいノートとしてオブジェクト(デフォルトは HEAD)に追加します。既存のノートに追加する場合、各々新しいメッセージの前に段落間の区切りとして1行の空行が追加されます。区切りは --separator オプションを使用してカスタマイズできます。 -m や -F オプション指定でノートを追加するとき、更に -e オプションを使用して(エディターを使用して)対話的に編集してからノートを追加できます。

edit

指定のオブジェクトのノートを編集します(デフォルトはHEAD)。

show

指定のオブジェクトのノートを表示します(デフォルトはHEAD)。

merge

指定のノートrefを現在のノートrefにマージします。これにより、マージベース(存在する場合)以降に指定されたnote参照(「remote」と呼ばれる）によって行われた変更が現在のノートref(「local」と呼ばれる)にマージされます。

競合が発生し、競合するノートを自動的に解決するための戦略(「NOTES MERGE STRATEGIES」セクション参照)が指定されていない場合は、「manual」(手動)リゾルバーが使用されます。このリゾルバーは、特別なワークツリー(.git/NOTES_MERGE_WORKTREE)内の競合するノートをチェックアウトし、そこで競合を手動で解決するようにユーザーに指示します。完了したら、ユーザーは git notes merge --commit を使用してマージを完了するか、 git notes merge --abort を使用してマージを中止(abort)できます。

remove

指定のオブジェクトのノートを削除します(デフォルトはHEAD)。コマンドラインから0個または1個のオブジェクトを指定する場合、これは edit サブコマンドに空のノートメッセージを指定することと同じです。

prune

存在しない(non-existing)/到達できない(unreachable) オブジェクトのすべてのノートを削除します。

get-ref

現在のノート ref を出力します。これにより、現在のノートrefを(スクリプトなどから)簡単に取得する方法が提供されます。

OPTIONS

-f
--force: すでにノートがあるオブジェクトにノートを追加する場合は、(中止するのではなく、)既存のノートを上書きします。
-m <msg>
--message=<msg>: (プロンプトを表示する代わりに、)指定のノートメッセージ <msg> を使用します。複数の -m オプションが指定されている場合、それらの値は個別の段落として連結されます(訳注:段落間は1行の空行。変更は --separator 参照)。 # で始まる行と、段落間の2行以上の空行は削除されます。そのままの内容を保持したい場合は、 --no-stripspace を使用してください。 (訳注: 手元の 2.47.1.404.ge66fd72e97 では # で始まる <msg> は削除されなかった。訳者の指定方法が悪いのかもしれず)。
-F <file>
--file=<file>: 指定のファイルからノート・メッセージを取得します。 - を使用すると、標準入力からノート・メッセージを読み取ります。 # で始まる行と、段落間の2行以上の空行は削除されます。そのままの内容を保持したい場合は --no-stripspace を使用してください。
-C <object>
--reuse-message=<object>: 指定の BLOB オブジェクト(たとえば別のノート)をノート・メッセージとして受け取ります。 (オブジェクト間でノートをコピーするには、これの代わりに git Notes copy <object> を使用してください。) デフォルトでは、メッセージはそのままコピーされますが、 # で始まる行や段落間の2行以上の空行を削除したい場合、 --stripspace オプションとともに使用します。
-c <object>
--reedit-message=<object>: -C と同様ですが、 -c を使用するとエディターが呼び出されるため、ユーザーはノート・メッセージをさらに編集できます。
--allow-empty: 空のノートオブジェクトを保存できるようにします。デフォルトの動作では、空のノートは自動的に削除されます。
--[no-]separator, --separator=<paragraph-break>: カスタムの段落間区切りとして使用する文字列を指定します (必要に応じて末尾に改行(newline)が追加されます)。 --no-separator の場合、段落間に区切りは追加されません。これのデフォルトは1行の空行です。
--[no-]stripspace: ノート・メッセージの先頭と末尾から空白(whitespace)を削除します。また、段落間の2行以上の空行も削除します。 # で始まる行は、 -m や -F や -C などの非エディターの場合には削除されますが、 git Notes edit や -c などのエディターの場合は削除されません。
--ref <ref>: <ref>のノートツリーを操作します。これは、 GIT_NOTES_REF と、 core.notesRef 構成をオーバーライドします。 refは、 refs/notes/ で始まる完全なref名を指定します。 notes/ で始まる場合、 refs/ が接頭辞として付けられ、それ以外の場合は refs/notes/ が接頭辞として付けられ、refのフルネームを形成します。
--ignore-missing: ノートが添付されていないオブジェクトからノートの削除を要求することをエラーと見なさないでください。
--stdin: 標準入力からノートを削除するオブジェクト名も読み込みます(コマンドラインからのオブジェクト名と組み合わせられます)。
-n
--dry-run: 何も削除しないでください。ノートが削除されるオブジェクト名を報告するだけです。
-s <strategy>
--strategy=<strategy>: ノートをマージするときは、指定の戦略を使用してノートの競合を解決します。次の戦略が認識されます: manual(デフォルト)、 ours 、 theirs 、 union 、 cat_sort_uniq 。このオプションは、 notes.mergeStrategy 構成設定をオーバーライドします。各ノートマージ戦略の詳細については、以下の「NOTES MERGE STRATEGIES」セクションを参照してください。
--commit: 進行中の git notes merge を完了させます。 .git/NOTES_MERGE_WORKTREE に保存されている git notes merge の競合を解決した場合は、このオプションを使用します。これにより、 .git/NOTES_MERGE_WORKTREE にノートを追加することで、 git notes merge (.git/NOTES_MERGE_PARTIAL に保存)によって作成された部分的なマージコミットが修正されます。 .git/NOTES_MERGE_REF symref に保存されているノートrefは、結果のコミットに更新されます。
--abort: 進行中の git notes merge を中止(abort)/リセットします。つまり、ノートのマージは競合を伴います。これにより、ノートのマージに関連するすべてのファイルが削除されます。
-q
--quiet: ノートをマージするときは、黙って作業します。
-v
--verbose: ノートをマージするときは、よりおしゃべりになります。ノートを刈り込む(prune)ときは、ノートが削除されたすべてのオブジェクト名を報告してください。

DISCUSSION

コミットノートは、オブジェクトに関する追加情報(通常はコミットのメッセージを補足する情報)を含むブロブです。これらのブロブは、ノートrefから取得されます。ノートrefは通常、パスが記述されたオブジェクトのオブジェクト名である「ファイル」を含むブランチであり、パフォーマンス上の理由からいくつかのディレクトリ区切り文字が含まれています。
[ 許可されるパス名の形式は bf/fe/30/.../680d5a... です。2桁の16進数のディレクトリ名のシーケンスそれぞれの後に、残りのオブジェクトIDを含むファイル名が続きます。 ]

ノートを変更するたびに、指定したノート参照に新しいコミットが作成されます。したがって、たとえば git log -p notes/commits を実行することで、ノートの履歴を調べることができます。現在のところ、コミットメッセージには更新のきっかけとなった操作が記録されているだけで、コミットの作者は通常のルールに従って決定されます(git-commit(1) 参照)。これらの詳細は、将来的に変更される可能性があります。

ノートrefがツリーオブジェクトを直接指すことも許可されています。その場合、ノートの履歴は git log -p -g <refname> で読み取ることができます。

NOTES MERGE STRATEGIES

デフォルトのノートマージ戦略は「manual」です。これは、ノートの競合を解決するために特別な作業ツリー(.git/NOTES_MERGE_WORKTREE)で競合するノートをチェックアウトし、そのワークツリーで競合を解決するようにユーザーに指示します。完了したら、ユーザーは git notes merge --commit を使用してマージを完了するか、 git notes merge --abort を使用してマージを中止できます。

ユーザーは、-s/--strategy オプションを使用するか、 notes.mergeStrategy を適宜構成して、以下の中から自動マージ戦略を選択できます:

「ours」は、競合するノートを自動的に解決して、ローカルバージョン(つまり、現在のノートref)を優先します。

「theirs」は、リモートバージョンを優先してノートの競合を自動的に解決します(つまり、指定されたノートrefが現在のノートrefにマージされます)。

「union」は、ローカルバージョンとリモートバージョンを連結することにより、ノートの競合を自動的に解決します。

「cat_sort_uniq」は union に似ていますが、この戦略は、ローカルバージョンとリモートバージョンを連結することに加えて、結果の行を並べ替え、結果から重複する行を削除します。これは、 cat | sort | uniq シェルパイプラインをローカルバージョンとリモートバージョンに適用するのと同じです。この戦略は、ノートが行ベースの形式に従っていて、マージ結果で行が重複しないようにする場合に役立ちます。ローカルバージョンまたはリモートバージョンのいずれかにマージ前に既に重複行が含まれている場合、これらもこのノートマージ戦略によって削除されることに注意してください。

EXAMPLES

あなたはノートを使用して、コミットが書き込まれた時点では利用できなかった情報を含む注釈を追加できます。

$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
$ git show -s 72a144e
[...]
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Notes:
    Tested-by: Johannes Sixt <j6t@kdbg.org>

原則として、ノートは通常のGitブロブであり、あらゆる種類の形式(または非形式)が受け入れられます。 git hash-object を使用して、任意のファイルから安全にノートを作成できます:

$ cc *.c
$ blob=$(git hash-object -w a.out)
$ git notes --ref=built add --allow-empty -C "$blob" HEAD

(これはバイナリセーフ(binary-safe)ではないため、単純に git notes --ref=built add -F a.out HEAD を使用することはできません。) もちろん、テキスト形式以外のノートを git log で表示することはあまり意味がありません。なので、あなたがそのようなノートを使用する場合は、それらを使用して何か便利なことを行うために、あなたはおそらくいくつかの特別な目的のツールを作成する必要があります。

CONFIGURATION

core.notesRef: refs/notes/commits の代わりに読み取りおよび操作するノートref。省略されていないref名である必要があります。この設定は、環境およびコマンドラインから上書きできます。

このセクションのこの行より上にあるものはすべて、 git-config(1) ドキュメントには含まれていません。以下の内容に関しては、git-config(1) ドキュメントにあるものと同一です。

notes.mergeStrategy: ノートの競合を解決するときにデフォルトで選択するマージ戦略。 manual 、` ours`、 theirs、` union` 、cat_sort_uniq のいずれかである必要があります。デフォルトは manual です。各戦略の詳細については、 git-notes(1) の「NOTES MERGE STRATEGIES」セクションを参照してください。

この設定は、 --strategy オプションを git-notes(1) に渡すことでオーバーライドできます。
notes.<name>.mergeStrategy: refs/notes/<name> にノートをマージするときに、どのマージ戦略を選択するか。これは、より一般的な notes.mergeStrategy をオーバーライドします。利用可能な戦略の詳細については、 git-notes(1) の「NOTES MERGE STRATEGIES」セクションを参照してください。
notes.displayRef: git log 系のコマンドでコミット・メッセージを表示する際に、 core.notesRef や GIT_NOTES_REF で設定したデフォルトに加えて、どのref (グロブ、または複数回指定されている場合は複数ref)からノートを読み込むかを指定します。

この設定は、 GIT_NOTES_DISPLAY_REF 環境変数でオーバーライドでき、環境変数はコロンで区切られたrefまたはグロブ(glob)のリストである必要があります。

存在しないrefsに対しては警告が発行されますが、どのrefsにもマッチしないグロブは黙って無視されます。

この設定は、コマンドの git log 系の --no-notes オプション、またはこれらのコマンドで受け入れられる --notes=<ref> オプションによって無効にすることができます。

core.notesRef の有効な値(GIT_NOTES_REFによってオーバーライドされる可能性があります)も、表示されるrefのリストに暗黙的に追加されます。
notes.rewrite.<command>: <command> (現在は amend または rebase)でコミットを書き換え、そして、この変数が false に設定されている場合、git はノートを元のコミットから書き換えられたコミットにコピーしません。デフォルトは true です。下記 notes.rewriteRef も参照してください。

この設定は、 GIT_NOTES_REWRITE_REF 環境変数でオーバーライドでき、環境変数はコロンで区切られたrefまたはグロブ(glob)のリストである必要があります。
notes.rewriteMode: 書き換え時にノートをコピーする場合(notes.rewrite.<command> オプション参照)、ターゲットコミットにすでにノートがある場合の対処方法を決定します。 overwrite 、 concatenate 、 cat_sort_uniq 、 ignore のいずれかである必要があります。デフォルトは concatenate です。

この設定は、 GIT_NOTES_REWRITE_MODE 環境変数でオーバーライドできます。
notes.rewriteRef: 書き換え中にノートをコピーする場合は、ノートをコピーする(完全修飾された)refを指定します。グロブと見なしたら、マッチするすべてのrefのノートがコピーされます。この構成を複数回指定することもできます。

デフォルト値はありません。ノートの書き換えを有効にするには、この変数を構成する必要があります。デフォルトのコミットノートの書き換えを有効にするには、これを refs/notes/commits に設定します。

GIT_NOTES_REWRITE_REF 環境変数でオーバーライドできます。その形式の詳細については、上記 notes.rewrite.<command> を参照してください。

ENVIRONMENT

GIT_NOTES_REF: refs/notes/commits の代わりに、どのrefからノートを操作するか。これは core.notesRef 設定を上書きします。
GIT_NOTES_DISPLAY_REF: コロンで区切られた ref または glob のリスト。コミットメッセージを表示する際に、デフォルトの core.notesRef または GIT_NOTES_REF に加えて、どの ref からノートを読み込むかを指定します。これは notes.displayRef の設定よりも優先されます。

存在しないrefに対して警告が発行されますが、どのrefとも一致しないグロブ(glob)は黙って無視されます。
GIT_NOTES_REWRITE_MODE: 書き換え中にノートをコピーするときに、ターゲットコミットにすでにノートがある場合の対処方法。 overwrite 、concatenate 、 cat_sort_uniq 、ignore のいずれかである必要があります。これは core.rewriteMode 設定を上書きします。
GIT_NOTES_REWRITE_REF: コミットを書き換える場合、元のコミットから書き換えられたコミットにコピーするためのノート。refまたはグロブ(glob)のコロンで区切られたリストである必要があります。

環境で設定されていない場合、コピーするノートのリストは、 notes.rewrite.<command> および notes.rewriteRef の設定によって異なります。

GIT

Part of the git(1) suite

git-notes(1) Manual Page

NAME