git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Taylor Blau <me@ttaylorr.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: Taylor Blau <me@ttaylorr.com>,
	Noam Yorav-Raphael via GitGitGadget <gitgitgadget@gmail.com>,
	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 13:13:13 -0400	[thread overview]
Message-ID: <20200803171313.GE50799@syl.lan> (raw)
In-Reply-To: <xmqq7dufwtio.fsf@gitster.c.googlers.com>

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

  reply	other threads:[~2020-08-03 17:13 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
2020-08-03 17:04   ` Junio C Hamano
2020-08-03 17:13     ` Taylor Blau [this message]
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=20200803171313.GE50799@syl.lan \
    --to=me@ttaylorr.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=gitster@pobox.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).