--------
[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' merge [-v | -q] [-s <strategy> ] <notes_ref>
+'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref>
'git notes' merge --commit [-v | -q]
'git notes' merge --abort [-v | -q]
-'git notes' remove [<object>]
+'git notes' remove [--ignore-missing] [--stdin] [<object>...]
'git notes' prune [-n | -v]
'git notes' get-ref
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
any) into the current notes ref (called "local").
+
If conflicts arise and a strategy for automatically resolving
-conflicting notes (see the -s/--strategy option) is not given,
+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.
'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::
-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::
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.
'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).
------------
$ 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