On Fri, Apr 1, 2016 at 6:47 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > 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. Done, I'll send a patch shortly. But I wanted to list the supported object types explicitly, in particular as many guide in the net are unclear that only annotated tags are object, and lightweight ones are not. > 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. Done. > 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. After a bit of thinking, I don't believe we should do this. All subcommand docs start with the verb the subcommand is named after. In that sense making the "add" docs start with "Attach" would be inconsistent and probably raise the question why the subcommand is not called "attach" after all. Also, in the description it says "Adds, removes, or reads notes attached to objects", so it includes "[...] removes [...] notes attached to objects", and if you read it like this the word "attach" is not specific to the "add" subcommand. So I left this as-is in my patch. -- Sebastian Schuberth -- 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