SubmittingPatches: document how to reference previous commits

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 310f0a5e8c1819f1f49e00b78aacface36ac21ad..9c4fd6812cc07b8537fb28a12f4119354a2dc5c8 100644 (file)
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -9,10 +9,10 @@ SYNOPSIS
 --------
 [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 --commit [-v | -q]
@@ -101,7 +101,7 @@ merge::
        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.
@@ -155,10 +155,16 @@ OPTIONS
        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
@@ -179,6 +185,7 @@ OPTIONS
        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.
 
@@ -243,6 +250,9 @@ 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).
 
@@ -287,7 +297,7 @@ arbitrary files using 'git hash-object':
 ------------
 $ 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`
@@ -306,6 +316,20 @@ core.notesRef::
        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
@@ -327,7 +351,8 @@ environment variable.
 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.
@@ -364,7 +389,7 @@ does not match any refs is silently ignored.
 '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'::
@@ -377,4 +402,4 @@ on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
 
 GIT
 ---
-Part of the linkgit:git[7] suite
+Part of the linkgit:git[1] suite