Re: [PATCH] doc: clarify that notes can be attached to any type of stored object

[Junio C Hamano]

Sebastian Schuberth  writes:

>>> -It is also permitted for a notes ref to point directly to a tree
>>> -object, in which case the history of the notes can be read with
>>> +It is also permitted for a notes ref to point to any other object in
>>> +the object store besides commit objects, that is annotated tags, blobs
>>> +or trees. For the latter, the history of the notes can be read with
>>>  `git log -p -g `.
>>
>> I do not think this is correct place to patch.  The original is not
>> talking about what objects can have notes attached at all.  What it
>> explains is this.
>
> Thanks for the explanation, I was indeed misreading this. I'll try to
> clarify this section then, too. In order to do so, I think we should
> mention how to actually create a  that directly points to a
> tree instead of a commit for the history of notes. Would you have an
> example how to do that?

Interesting.  This came from 9eb3f816 (Documentation/notes: document
format of notes trees, 2010-05-08):

Documentation/notes: document format of notes trees

Separate the specification of the notes format exposed in
git-config.1 from the description of the option; or in other
words, move the explanation for what to expect to find at
refs/notes/commits from git-config.1 to git-notes.1.

Suggested-by: Thomas Rast 
Signed-off-by: Jonathan Nieder 
Signed-off-by: Junio C Hamano 

but I do not find a corresponding sentence that says a notes ref can
point at a tree in the text before the patch.

I highly suspect that "git notes add" and other Porcelain level
commands that manipulate an existing notes tree would be unhappy if
a notes ref is not a commit, as it is clear from the paragraph
before the one under discussion, i.e.

Every notes change creates a new commit at the specified notes ref.
You can therefore inspect the history of the notes by invoking, e.g.,
`git log -p notes/commits`.  Currently the commit message only records
which operation triggered the update, and the commit authorship is
determined according to the usual rules (see linkgit:git-commit[1]).
These details may change in the future.

that in order to create a "new" commit, setting the current one as
its parent, would require that the current one to be a commit and
not a bare tree.  "git notes list" and others that merely read from
the notes tree would probably work.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: clarify that notes can be attached to any type of stored object

[Junio C Hamano]

Sebastian Schuberth  writes:

> 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.

I'd really hate to see an explicit list of what object types there
are, as it is one more place we'd need to update if we ever add new
object types (and we are unlikely to do so anytime soon, which makes
it even more likely that we would forget there is this explicit list
we'd need to update).

- Adds, removes, or reads notes attached to objects, without touching
- the objects themselves.
+ Adds, removes, or reads notes attached to any object (not limited
+ to commit objects), without touching the objects themselves.

should be sufficient, no?
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: clarify that notes can be attached to any type of stored object

[Sebastian Schuberth]

On Fri, Apr 1, 2016 at 6:47 PM, Junio C Hamano  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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: clarify that notes can be attached to any type of stored object

[Sebastian Schuberth]

On Fri, Apr 1, 2016 at 5:31 PM, Junio C Hamano  wrote:

> Sebastian Schuberth  writes:
>
>> Signed-off-by: Sebastian Schuberth 
>> ---
>>  Documentation/git-notes.txt | 5 +++--
>>  1 file changed, 3 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
>> index 8de3499..5375d98 100644
>> --- a/Documentation/git-notes.txt
>> +++ b/Documentation/git-notes.txt
>> @@ -234,8 +234,9 @@ which operation triggered the update, and the commit 
>> authorship is
>>  determined according to the usual rules (see linkgit:git-commit[1]).
>>  These details may change in the future.
>>
>> -It is also permitted for a notes ref to point directly to a tree
>> -object, in which case the history of the notes can be read with
>> +It is also permitted for a notes ref to point to any other object in
>> +the object store besides commit objects, that is annotated tags, blobs
>> +or trees. For the latter, the history of the notes can be read with
>>  `git log -p -g `.
>
> I do not think this is correct place to patch.  The original is not
> talking about what objects can have notes attached at all.  What it
> explains is this.

Thanks for the explanation, I was indeed misreading this. I'll try to
clarify this section then, too. In order to do so, I think we should
mention how to actually create a  that directly points to a
tree instead of a commit for the history of notes. Would you have an
example how to do that?

-- 
Sebastian Schuberth
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: clarify that notes can be attached to any type of stored object

[Junio C Hamano]

Junio C Hamano  writes:

> Sebastian Schuberth  writes:
>
>> Signed-off-by: Sebastian Schuberth 
>> ---
>>  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 ():" (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." 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 " ").
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 majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc: clarify that notes can be attached to any type of stored object

[Junio C Hamano]

Sebastian Schuberth  writes:

> Signed-off-by: Sebastian Schuberth 
> ---
>  Documentation/git-notes.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index 8de3499..5375d98 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -234,8 +234,9 @@ which operation triggered the update, and the commit 
> authorship is
>  determined according to the usual rules (see linkgit:git-commit[1]).
>  These details may change in the future.
>  
> -It is also permitted for a notes ref to point directly to a tree
> -object, in which case the history of the notes can be read with
> +It is also permitted for a notes ref to point to any other object in
> +the object store besides commit objects, that is annotated tags, blobs
> +or trees. For the latter, the history of the notes can be read with
>  `git log -p -g `.

I do not think this is correct place to patch.  The original is not
talking about what objects can have notes attached at all.  What it
explains is this.

 aka refs/notes/ (where  typically is
"commit") is usually a commit, whose tree is a notes-shaped
tree.  The (normal) history you get by following the parent link
of the commit represents how the entire set of notes evolved.
However, it is OK for the  to point directly to a tree,
which is a notes-shaped one, without an enclosing commit.  You
would lose the normal way to learn how the entire set of notes
evolved, but you could do "git log -p -g ", i.e. by
following its reflog, to pretend as if the history is recorded.

There is no way a blob can be pointed by  there and expect
it to work sensibly at all.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] doc: clarify that notes can be attached to any type of stored object

[Sebastian Schuberth]

Signed-off-by: Sebastian Schuberth 
---
 Documentation/git-notes.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 8de3499..5375d98 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -234,8 +234,9 @@ which operation triggered the update, and the commit 
authorship is
 determined according to the usual rules (see linkgit:git-commit[1]).
 These details may change in the future.
 
-It is also permitted for a notes ref to point directly to a tree
-object, in which case the history of the notes can be read with
+It is also permitted for a notes ref to point to any other object in
+the object store besides commit objects, that is annotated tags, blobs
+or trees. For the latter, the history of the notes can be read with
 `git log -p -g `.
 
 
-- 
2.8.0.windows.1


--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html