docs: improve the example that illustrates git-notes path names
diff mbox series

Message ID pull.692.git.1596465817121.gitgitgadget@gmail.com
State New
Headers show
Series
  • docs: improve the example that illustrates git-notes path names
Related show

Commit Message

Johannes Schindelin via GitGitGadget Aug. 3, 2020, 2:43 p.m. UTC
From: Noam Yorav-Raphael <noamraph@gmail.com>

The existing git-notes doc says:

> Permitted pathnames have the form ab/cd/ef/…​/abcdef…​: a sequence of
> directory names of two hexadecimal digits each followed by a filename
> with the rest of the object ID.

Even though the text says that the filename has the rest of the object ID,
I felt the need to check this, since the example gives the impression that
the filename is the entire object ID (a schema which is quite prevalent).

The new example makes it clear that the filename has only the rest of the
object ID, and not the entire object ID.

Signed-off-by: Noam Yorav-Raphael <noamraph@gmail.com>
---
    Improve the example that illustrates git-notes path names
    
    The existing git-notes doc says:
    
    > Permitted pathnames have the form ab/cd/ef/…​/abcdef…​: a sequence of
    > directory names of two hexadecimal digits each followed by a filename
    > with the rest of the object ID.
    
    Even though the text says that the filename has the rest of the object
    ID, I felt the need to check this, since the example gives the
    impression that the filename is the entire object ID (a schema which is
    quite prevalent).
    
    The new example makes it clear that the filename has only the rest of
    the object ID, and not the entire object ID.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-692%2Fnoamraph%2Fclearer-notes-path-doc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-692/noamraph/clearer-notes-path-doc-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/692

 Documentation/git-notes.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)


base-commit: 85b4e0a6dc8407de6f69808d9ee6debdf167ced3

Comments

Taylor Blau Aug. 3, 2020, 3:48 p.m. UTC | #1
On Mon, Aug 03, 2020 at 02:43:36PM +0000, Noam Yorav-Raphael via GitGitGadget wrote:
> From: Noam Yorav-Raphael <noamraph@gmail.com>
>
> The existing git-notes doc says:
>
> > Permitted pathnames have the form ab/cd/ef/…​/abcdef…​: a sequence of
> > directory names of two hexadecimal digits each followed by a filename
> > with the rest of the object ID.

This part of the commit message is unnecessary, since it can easily be
read off from the diff.

>
> Even though the text says that the filename has the rest of the object ID,
> I felt the need to check this, since the example gives the impression that
> the filename is the entire object ID (a schema which is quite prevalent).
>
> The new example makes it clear that the filename has only the rest of the
> object ID, and not the entire object ID.

Please use the imperative mood here. Instead of the above, consider:

  Make it clear that the filename has only the rest of the object ID,
  not the entirety of it.

> Signed-off-by: Noam Yorav-Raphael <noamraph@gmail.com>
> ---
>     Improve the example that illustrates git-notes path names
>
>     The existing git-notes doc says:
>
>     > Permitted pathnames have the form ab/cd/ef/…​/abcdef…​: a sequence of
>     > directory names of two hexadecimal digits each followed by a filename
>     > with the rest of the object ID.
>
>     Even though the text says that the filename has the rest of the object
>     ID, I felt the need to check this, since the example gives the
>     impression that the filename is the entire object ID (a schema which is
>     quite prevalent).
>
>     The new example makes it clear that the filename has only the rest of
>     the object ID, and not the entire object ID.
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-692%2Fnoamraph%2Fclearer-notes-path-doc-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-692/noamraph/clearer-notes-path-doc-v1
> Pull-Request: https://github.com/gitgitgadget/git/pull/692
>
>  Documentation/git-notes.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index ced2e8280e..9fc1979531 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -223,7 +223,7 @@ are taken from notes refs.  A notes ref is usually a branch which
>  contains "files" whose paths are the object names for the objects
>  they describe, with some directory separators included for performance
>  reasons footnote:[Permitted pathnames have the form
> -'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
> +'12'`/`'34'`/`'56'`/`'...'`/`'789abc...': a sequence of directory

I had to read this twice to figure out why the first 'ab' changed to
'12'. It appears that this is to avoid having to use 'gh...' in the
last directory, since 'g', 'h' and so on aren't hexadecimal digits.

Makes sense.

>  names of two hexadecimal digits each followed by a filename with the
>  rest of the object ID.].
>
>
> base-commit: 85b4e0a6dc8407de6f69808d9ee6debdf167ced3
> --
> gitgitgadget

The patch looks fine, but the commit message needs some tweaking.
Thanks.

Thanks,
Taylor
Junio C Hamano Aug. 3, 2020, 5:04 p.m. UTC | #2
Taylor Blau <me@ttaylorr.com> writes:

>> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
>> index ced2e8280e..9fc1979531 100644
>> --- a/Documentation/git-notes.txt
>> +++ b/Documentation/git-notes.txt
>> @@ -223,7 +223,7 @@ are taken from notes refs.  A notes ref is usually a branch which
>>  contains "files" whose paths are the object names for the objects
>>  they describe, with some directory separators included for performance
>>  reasons footnote:[Permitted pathnames have the form
>> -'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
>> +'12'`/`'34'`/`'56'`/`'...'`/`'789abc...': a sequence of directory
>
> I had to read this twice to figure out why the first 'ab' changed to
> '12'. It appears that this is to avoid having to use 'gh...' in the
> last directory, since 'g', 'h' and so on aren't hexadecimal digits.

You can wrap-around to '0' after counting up to 'f', no ;-)?

Having '/.../' between '56' and '789' to indicate "there are more
levels possible here" is somewhat misleading with the new example.
We could argue that the original objectname does not have to be
"123456789abc.." but then the whole exercise becomes somewhat
pointless as the objectname could have been 'abcdef...abcdef...'.

Another minor nit: it probably makes it read more natural to start
counting from '0' when writing hexadecimal, if we really want to
use sequence of ascending hexdigits.

Using a seemingly random example 85/b4/.../808d9ee6debdf167ced3
might be less confusing, because ...

>>  names of two hexadecimal digits each followed by a filename with the
>>  rest of the object ID.].

... I think these two lines is pleanty clear than any example, so I
am OK with either the old or the updated example, but I think a
seemingly random example as long as the leaf level does not share
the leading hexdigits as the pathname would work the best.
Taylor Blau Aug. 3, 2020, 5:13 p.m. UTC | #3
On Mon, Aug 03, 2020 at 10:04:15AM -0700, Junio C Hamano wrote:
> Taylor Blau <me@ttaylorr.com> writes:
>
> >> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> >> index ced2e8280e..9fc1979531 100644
> >> --- a/Documentation/git-notes.txt
> >> +++ b/Documentation/git-notes.txt
> >> @@ -223,7 +223,7 @@ are taken from notes refs.  A notes ref is usually a branch which
> >>  contains "files" whose paths are the object names for the objects
> >>  they describe, with some directory separators included for performance
> >>  reasons footnote:[Permitted pathnames have the form
> >> -'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
> >> +'12'`/`'34'`/`'56'`/`'...'`/`'789abc...': a sequence of directory
> >
> > I had to read this twice to figure out why the first 'ab' changed to
> > '12'. It appears that this is to avoid having to use 'gh...' in the
> > last directory, since 'g', 'h' and so on aren't hexadecimal digits.
>
> You can wrap-around to '0' after counting up to 'f', no ;-)?

;-).

> Having '/.../' between '56' and '789' to indicate "there are more
> levels possible here" is somewhat misleading with the new example.
> We could argue that the original objectname does not have to be
> "123456789abc.." but then the whole exercise becomes somewhat
> pointless as the objectname could have been 'abcdef...abcdef...'.
>
> Another minor nit: it probably makes it read more natural to start
> counting from '0' when writing hexadecimal, if we really want to
> use sequence of ascending hexdigits.
>
> Using a seemingly random example 85/b4/.../808d9ee6debdf167ced3
> might be less confusing, because ...
>
> >>  names of two hexadecimal digits each followed by a filename with the
> >>  rest of the object ID.].
>
> ... I think these two lines is pleanty clear than any example, so I
> am OK with either the old or the updated example, but I think a
> seemingly random example as long as the leaf level does not share
> the leading hexdigits as the pathname would work the best.

I agree with your reasoning (it didn't occur to me as a problem before,
but seeing it spelled out in front of me I could understand how such an
example might be confusing).

Thanks,
Taylor

Patch
diff mbox series

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index ced2e8280e..9fc1979531 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -223,7 +223,7 @@  are taken from notes refs.  A notes ref is usually a branch which
 contains "files" whose paths are the object names for the objects
 they describe, with some directory separators included for performance
 reasons footnote:[Permitted pathnames have the form
-'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
+'12'`/`'34'`/`'56'`/`'...'`/`'789abc...': a sequence of directory
 names of two hexadecimal digits each followed by a filename with the
 rest of the object ID.].