docs: improve the example that illustrates git-notes path names
PATCH 1/1 docs: improve the example that illustrates git-notes path names
From: Noam Yorav-Raphael <[email protected]>
The existing git-notes doc says:
Quoted 3 lines
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.
---
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(-)
Documentation/git-notes.txt +1 -1
@@ -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.].
base-commit: 85b4e0a6dc8407de6f69808d9ee6debdf167ced3
Signature · 1 line
gitgitgadget
Quoted 7 lines · Noam Yorav-Raphael via GitGitGadget
From: Noam Yorav-Raphael <[email protected]>
The existing git-notes doc says:
Quoted 3 lines
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.
Quoted 7 lines
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.
Quoted 30 lines
Signed-off-by Noam Yorav-Raphael <[email protected]>---
Improve the example that illustrates git-notes path namesThe 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/692Documentation/git-notes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-notes.txt +0
-0
Documentation/git-notes.txt are taken from notes refs. A notes ref is usually a branch which · line 226
Quoted 5 lines
Documentation/git-notes.txt +1
-1@@ -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.
Quoted 7 lines
Documentation/git-notes.txt +0
-0names 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
Quoted 6 lines · Taylor Blau
Quoted 6 lines
Documentation/git-notes.txt +0
-0@@ -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
Quoted 8 lines
Documentation/git-notes.txt are taken from notes refs. A notes ref is usually a branch which · line 226
Quoted 4 lines
Documentation/git-notes.txt +1
-1they 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 directoryI 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 ...
Quoted 2 lines
Documentation/git-notes.txt are taken from notes refs. A notes ref is usually a branch which · line 228
Quoted 2 lines
Documentation/git-notes.txt +0
-0names 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.
Quoted 17 lines · Junio C Hamano
Quoted 6 lines · Taylor Blau
Quoted 6 lines
Documentation/git-notes.txt +0
-0@@ -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 objectsQuoted 8 lines
Documentation/git-notes.txt are taken from notes refs. A notes ref is usually a branch which · line 226
Quoted 4 lines
Documentation/git-notes.txt +1
-1they 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 directoryI 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.
Quoted 1 line
You can wrap-around to '0' after counting up to 'f', no ;-)?
;-).
Quoted 13 lines
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 ...
Quoted 7 lines
Quoted 2 lines
Documentation/git-notes.txt are taken from notes refs. A notes ref is usually a branch which · line 228
Quoted 2 lines
Documentation/git-notes.txt +0
-0names 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 v2 1/1 docs: improve the example that illustrates git-notes path names
In reply to Noam Yorav-Raphael via GitGitGadgetFrom: Noam Yorav-Raphael <[email protected]>
Make it clear that the filename has only the rest of the object ID, not the entirety of it.
---
Improve the example that illustrates git-notes path names
docs: improve the example that illustrates git-notes path names
Make it clear that the filename has only the rest of the object ID, not the entirety of it.
Changed: improved the commit message, according to comments by Taylor Blau.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-692%2Fnoamraph%2Fclearer-notes-path-doc-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-692/noamraph/clearer-notes-path-doc-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/692
Range-diff vs v1:
1: 76a674871a ! 1: 8b3defb657 docs: improve the example that illustrates git-notes path names
@@ Metadata
## Commit message ##
docs: 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.
+ Make it clear that the filename has only the rest of the object ID,
+ not the entirety of it.
Documentation/git-notes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-notes.txt +1 -1
@@ -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.].
base-commit: 85b4e0a6dc8407de6f69808d9ee6debdf167ced3
Signature · 1 line
gitgitgadget
Hi Noam,
Quoted 4 lines · Noam Yorav-Raphael via GitGitGadget
From: Noam Yorav-Raphael <[email protected]>
Make it clear that the filename has only the rest of the object ID, not the entirety of it.
This looks great, thank you. I left one note below, but I don't think that you should feel obligated to address it.
Quoted 50 lines
Signed-off-by Noam Yorav-Raphael <[email protected]>---
Improve the example that illustrates git-notes path namesdocs: improve the example that illustrates git-notes path names
Make it clear that the filename has only the rest of the object ID, not the entirety of it.
Changed: improved the commit message, according to comments by Taylor Blau.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-692%2Fnoamraph%2Fclearer-notes-path-doc-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-692/noamraph/clearer-notes-path-doc-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/692Range-diff vs v1:
1:
76a674871a! 1:8b3defb657docs: improve the example that illustrates git-notes path names
@@ Metadata
## Commit message ##
docs: 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.
+ 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 <[email protected]>Documentation/git-notes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-notes.txt +0
-0
Documentation/git-notes.txt are taken from notes refs. A notes ref is usually a branch which · line 226
Quoted 5 lines
Documentation/git-notes.txt +1
-1@@ -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
Sorry for not suggesting this earlier, but I think you could just as easily start this with '01' instead of '12'. I don't think that it matters, though, the point that you're trying to illustrate is perfectly clear.
Quoted 7 lines
Documentation/git-notes.txt +0
-0names of two hexadecimal digits each followed by a filename with the rest of the object ID.].base-commit:
85b4e0a6dc8407de6f69808d9ee6debdf167ced3--
gitgitgadget
Thanks,
Taylor
PATCH v3 1/1 docs: improve the example that illustrates git-notes path names
In reply to Noam Yorav-Raphael via GitGitGadgetFrom: Noam Yorav-Raphael <[email protected]>
Make it clear that the filename has only the rest of the object ID, not the entirety of it.
---
Improve the example that illustrates git-notes path names
docs: improve the example that illustrates git-notes path names
Make it clear that the filename has only the rest of the object ID, not the entirety of it.
Changes since v1:
* Improved the commit message, according to comments by Taylor Blau.
* Changed the parts to random hex, so the '...' won't be confusing, according to suggestion by Junio C Hamano.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-692%2Fnoamraph%2Fclearer-notes-path-doc-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-692/noamraph/clearer-notes-path-doc-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/692
Range-diff vs v2:
1: 8b3defb657 ! 1: e973e321d8 docs: improve the example that illustrates git-notes path names
@@ Documentation/git-notes.txt: are taken from notes refs. A notes ref is usually
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 ++'bf'/'fe'/'30'/'...'/'680d5a...': a sequence of directory
names of two hexadecimal digits each followed by a filename with the
rest of the object ID.].
Documentation/git-notes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-notes.txt +1 -1
@@ -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 +'bf'`/`'fe'`/`'30'`/`'...'`/`'680d5a...': a sequence of directory names of two hexadecimal digits each followed by a filename with the rest of the object ID.].
base-commit: 85b4e0a6dc8407de6f69808d9ee6debdf167ced3
Signature · 1 line
gitgitgadget
Quoted 55 lines · Noam Yorav-Raphael via GitGitGadget
From: Noam Yorav-Raphael <[email protected]>
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 <[email protected]>---
Improve the example that illustrates git-notes path namesdocs: improve the example that illustrates git-notes path names
Make it clear that the filename has only the rest of the object ID, not the entirety of it.
Changes since v1:
* Improved the commit message, according to comments by Taylor Blau.
* Changed the parts to random hex, so the '...' won't be confusing, according to suggestion by Junio C Hamano.Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-692%2Fnoamraph%2Fclearer-notes-path-doc-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-692/noamraph/clearer-notes-path-doc-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/692Range-diff vs v2:
1:
8b3defb657! 1:e973e321d8docs: improve the example that illustrates git-notes path names
@@Documentation/git-notes.txt: are taken from notes refs. A notes ref is usually
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 ++'bf'/'fe'/'30'/'...'/'680d5a...': a sequence of directory
names of two hexadecimal digits each followed by a filename with the
rest of the object ID.].Documentation/git-notes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-notes.txt +1
-1@@ -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 +'bf'`/`'fe'`/`'30'`/`'...'`/`'680d5a...': a sequence of directory names of two hexadecimal digits each followed by a filename with the rest of the object ID.].
Quoted 3 lines
base-commit:
85b4e0a6dc8407de6f69808d9ee6debdf167ced3--
gitgitgadget
Looks good to me, but Junio should chime in, too.
Thanks,
Taylor
Quoted 56 lines · Taylor Blau
Quoted 55 lines · Noam Yorav-Raphael via GitGitGadget
From: Noam Yorav-Raphael <[email protected]>
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 <[email protected]>---
Improve the example that illustrates git-notes path namesdocs: improve the example that illustrates git-notes path names
Make it clear that the filename has only the rest of the object ID, not the entirety of it.
Changes since v1:
* Improved the commit message, according to comments by Taylor Blau.
* Changed the parts to random hex, so the '...' won't be confusing, according to suggestion by Junio C Hamano.Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-692%2Fnoamraph%2Fclearer-notes-path-doc-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-692/noamraph/clearer-notes-path-doc-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/692Range-diff vs v2:
1:
8b3defb657! 1:e973e321d8docs: improve the example that illustrates git-notes path names
@@Documentation/git-notes.txt: are taken from notes refs. A notes ref is usually
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 ++'bf'/'fe'/'30'/'...'/'680d5a...': a sequence of directory
names of two hexadecimal digits each followed by a filename with the
rest of the object ID.].Documentation/git-notes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/git-notes.txt +1
-1@@ -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 +'bf'`/`'fe'`/`'30'`/`'...'`/`'680d5a...': a sequence of directory names of two hexadecimal digits each followed by a filename with the rest of the object ID.].
Quoted 7 lines
Quoted 3 lines
base-commit:
85b4e0a6dc8407de6f69808d9ee6debdf167ced3--
gitgitgadgetLooks good to me, but Junio should chime in, too.
Acked-by Taylor Blau <[email protected]>
Yeah, thanks, both.