git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Taylor Blau <me@ttaylorr.com>
To: Noam Yorav-Raphael via GitGitGadget <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, Noam Yorav-Raphael <noamraph@gmail.com>
Subject: Re: [PATCH] docs: improve the example that illustrates git-notes path names
Date: Mon, 3 Aug 2020 11:48:52 -0400	[thread overview]
Message-ID: <20200803154852.GA48612@syl.lan> (raw)
In-Reply-To: <pull.692.git.1596465817121.gitgitgadget@gmail.com>

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

  reply	other threads:[~2020-08-03 15:48 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-03 14:43 Noam Yorav-Raphael via GitGitGadget
2020-08-03 15:48 ` Taylor Blau [this message]
2020-08-03 17:04   ` Junio C Hamano
2020-08-03 17:13     ` Taylor Blau
2020-08-03 16:21 ` [PATCH v2] " Noam Yorav-Raphael via GitGitGadget
2020-08-03 16:31   ` Taylor Blau
2020-08-03 19:10   ` [PATCH v3] " Noam Yorav-Raphael via GitGitGadget
2020-08-03 19:11     ` Taylor Blau
2020-08-03 19:39       ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200803154852.GA48612@syl.lan \
    --to=me@ttaylorr.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=noamraph@gmail.com \
    --subject='Re: [PATCH] docs: improve the example that illustrates git-notes path names' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).