Junio C Hamano <gitster@xxxxxxxxx> writes:
> Sebastian Schuberth <sschuberth@xxxxxxxxx> writes:
>
>> Signed-off-by: Sebastian Schuberth <sschuberth@xxxxxxxxx>
>> ---
>> Documentation/git-notes.txt | 5 +++--
>> 1 file changed, 3 insertions(+), 2 deletions(-)
>>
> I do not think this is correct place to patch.
So,... where is the right place?
Let's disect what we have in the DESCRIPTION section.
DESCRIPTION
-----------
Adds, removes, or reads notes attached to objects, without touching
the objects themselves.
This says "notes attached to objects" and "the objects themselves".
They do not limit the target of attaching a note to "commits".
So this may be the place to add " Note that notes can be attached
to any kind of objects, not limited to commits" or something, if
we really wanted to.
By default, notes are saved to and read from `refs/notes/commits`, but
this default can be overridden. See the OPTIONS, CONFIGURATION, and
ENVIRONMENT sections below. If this ref does not exist, it will be
quietly created when it is first needed to store a note.
A typical use of notes is to supplement a commit message without
changing the commit itself. Notes can be shown by 'git log' along with
the original commit message. To distinguish these notes from the
message stored in the commit object, the notes are indented like the
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.
This paragraph _might_ be confusing to new readers. The "added to"
sounds as if you are attaching a note to a non-object which is a
patch. But this "add" is about "inserting the contents of the note
attached to the commit being formatted" and corresponds to "can be
shown by" in the previous paragraph. We may want to avoid the verb
"add" when talking about the use of data stored in an existing note
to somewhere else like this.
To change which notes are shown by 'git log', see the
"notes.displayRef" configuration in linkgit:git-log[1].
See the "notes.rewrite.<command>" configuration for a way to carry
notes across commands that rewrite commits.
SUBCOMMANDS
-----------
list::
List the notes object for a given object. If no object is
given, show a list of all note objects and the objects they
annotate (in the format "<note object> <annotated object>").
This is the default subcommand if no subcommand is given.
add::
Add notes for a given object (defaults to HEAD). Abort if the
And this "Add notes for " should probably be reworded to "Attach
notes to" to match the first sentence in the description.
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).
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html