--------
[verse]
'git notes' [list [<object>]]
-'git notes' add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
+'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
'git notes' copy [-f] ( --stdin | <from-object> <to-object> )
-'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
-'git notes' edit [<object>]
+'git notes' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
+'git notes' edit [--allow-empty] [<object>]
'git notes' show [<object>]
-'git notes' remove [<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
message, after an unindented line saying "Notes (<refname>):" (or
"Notes:" for `refs/notes/commits`).
+Notes can also be added to patches prepared with `git format-patch` by
+using the `--notes` option. Such notes are added as a patch commentary
+after a three dash separator line.
+
To change which notes are shown by 'git log', see the
"notes.displayRef" configuration in linkgit:git-log[1].
add::
Add notes for a given object (defaults to HEAD). Abort if the
- object already has notes (use `-f` to overwrite an
- existing note).
+ object already has notes (use `-f` to overwrite existing notes).
+ However, if you're using `add` interactively (using an editor
+ to supply the notes contents), then - instead of aborting -
+ the existing notes will be opened in the editor (like the `edit`
+ subcommand).
copy::
Copy the notes for the first object onto the second object.
second object). This subcommand is equivalent to:
`git notes add [-f] -C $(git notes list <from-object>) <to-object>`
+
-In `\--stdin` mode, take lines in the format
+In `--stdin` mode, take lines in the format
+
----------
<from-object> SP <to-object> [ SP <rest> ] LF
show::
Show the notes for a given object (defaults to HEAD).
+merge::
+ Merge the given notes ref into the current notes ref.
+ This will try to merge the changes made by the given
+ notes ref (called "remote") since the merge-base (if
+ any) into the current notes ref (called "local").
++
+If conflicts arise and a strategy for automatically resolving
+conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given,
+the "manual" resolver is used. This resolver checks out the
+conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`),
+and instructs the user to manually resolve the conflicts there.
+When done, the user can either finalize the merge with
+'git notes merge --commit', or abort the merge with
+'git notes merge --abort'.
+
remove::
- Remove the notes for a given object (defaults to HEAD).
- This is equivalent to specifying an empty note message to
+ Remove the notes for given objects (defaults to HEAD). When
+ giving zero or one object from the command line, this is
+ equivalent to specifying an empty note message to
the `edit` subcommand.
prune::
Remove all notes for non-existing/unreachable objects.
+get-ref::
+ Print the current notes ref. This provides an easy way to
+ retrieve the current notes ref (e.g. from scripts).
+
OPTIONS
-------
-f::
-C <object>::
--reuse-message=<object>::
- Take the note message from the given blob object (for
- example, another note).
+ Take the given blob object (for example, another note) as the
+ note message. (Use `git notes copy <object>` instead to
+ copy notes between objects.)
-c <object>::
--reedit-message=<object>::
Like '-C', but with '-c' the editor is invoked, so that
the user can further edit the note message.
+--allow-empty::
+ Allow an empty note object to be stored. The default behavior is
+ to automatically remove empty notes.
+
--ref <ref>::
Manipulate the notes tree in <ref>. This overrides
'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref
- is taken to be in `refs/notes/` if it is not qualified.
+ specifies the full refname when it begins with `refs/notes/`; when it
+ begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed
+ to form a full name of the ref.
+
+--ignore-missing::
+ Do not consider it an error to request removing notes from an
+ object that does not have notes attached to it.
+
+--stdin::
+ Also read the object names to remove notes from from the standard
+ input (there is no reason you cannot combine this with object
+ names from the command line).
-n::
--dry-run::
Do not remove anything; just report the object names whose notes
would be removed.
+-s <strategy>::
+--strategy=<strategy>::
+ When merging notes, resolve notes conflicts using the given
+ strategy. The following strategies are recognized: "manual"
+ (default), "ours", "theirs", "union" and "cat_sort_uniq".
+ This option overrides the "notes.mergeStrategy" configuration setting.
+ See the "NOTES MERGE STRATEGIES" section below for more
+ information on each notes merge strategy.
+
+--commit::
+ Finalize an in-progress 'git notes merge'. Use this option
+ when you have resolved the conflicts that 'git notes merge'
+ stored in .git/NOTES_MERGE_WORKTREE. This amends the partial
+ merge commit created by 'git notes merge' (stored in
+ .git/NOTES_MERGE_PARTIAL) by adding the notes in
+ .git/NOTES_MERGE_WORKTREE. The notes ref stored in the
+ .git/NOTES_MERGE_REF symref is updated to the resulting commit.
+
+--abort::
+ Abort/reset a in-progress 'git notes merge', i.e. a notes merge
+ with conflicts. This simply removes all files related to the
+ notes merge.
+
+-q::
+--quiet::
+ When merging notes, operate quietly.
+
-v::
--verbose::
- Report all object names whose notes are removed.
+ When merging notes, be more verbose.
+ When pruning notes, report all object names whose notes are
+ removed.
DISCUSSION
`git log -p -g <refname>`.
+NOTES MERGE STRATEGIES
+----------------------
+
+The default notes merge strategy is "manual", which checks out
+conflicting notes in a special work tree for resolving notes conflicts
+(`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the
+conflicts in that work tree.
+When done, the user can either finalize the merge with
+'git notes merge --commit', or abort the merge with
+'git notes merge --abort'.
+
+Users may select an automated merge strategy from among the following using
+either -s/--strategy option or configuring notes.mergeStrategy accordingly:
+
+"ours" automatically resolves conflicting notes in favor of the local
+version (i.e. the current notes ref).
+
+"theirs" automatically resolves notes conflicts in favor of the remote
+version (i.e. the given notes ref being merged into the current notes
+ref).
+
+"union" automatically resolves notes conflicts by concatenating the
+local and remote versions.
+
+"cat_sort_uniq" is similar to "union", but in addition to concatenating
+the local and remote versions, this strategy also sorts the resulting
+lines, and removes duplicate lines from the result. This is equivalent
+to applying the "cat | sort | uniq" shell pipeline to the local and
+remote versions. This strategy is useful if the notes follow a line-based
+format where one wants to avoid duplicated lines in the merge result.
+Note that if either the local or remote version contain duplicate lines
+prior to the merge, these will also be removed by this notes merge
+strategy.
+
+
EXAMPLES
--------
------------
$ cc *.c
$ blob=$(git hash-object -w a.out)
-$ git notes --ref=built add -C "$blob" HEAD
+$ git notes --ref=built add --allow-empty -C "$blob" HEAD
------------
+(You cannot simply use `git notes --ref=built add -F a.out HEAD`
+because that is not binary-safe.)
Of course, it doesn't make much sense to display non-text-format notes
with 'git log', so if you use such notes, you'll probably need to write
some special-purpose tools to do something useful with them.
This setting can be overridden through the environment and
command line.
+notes.mergeStrategy::
+ Which merge strategy to choose by default when resolving notes
+ conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
+ `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
+ section above for more information on each strategy.
++
+This setting can be overridden by passing the `--strategy` option.
+
+notes.<name>.mergeStrategy::
+ Which merge strategy to choose when doing a notes merge into
+ refs/notes/<name>. This overrides the more general
+ "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above
+ for more information on each available strategy.
+
notes.displayRef::
Which ref (or refs, if a glob or specified more than once), in
addition to the default set by `core.notesRef` or
notes.rewriteMode::
When copying notes during a rewrite, what to do if the target
commit already has a note. Must be one of `overwrite`,
- `concatenate`, and `ignore`. Defaults to `concatenate`.
+ `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to
+ `concatenate`.
+
This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
environment variable.
'GIT_NOTES_REWRITE_MODE'::
When copying notes during a rewrite, what to do if the target
commit already has a note.
- Must be one of `overwrite`, `concatenate`, and `ignore`.
+ Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.
This overrides the `core.rewriteMode` setting.
'GIT_NOTES_REWRITE_REF'::
If not set in the environment, the list of notes to copy depends
on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
-
-Author
-------
-Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
-Johan Herland <johan@herland.net>
-
-Documentation
--------------
-Documentation by Johannes Schindelin and Johan Herland
-
GIT
---
-Part of the linkgit:git[7] suite
+Part of the linkgit:git[1] suite