Re: [PATCH] gitrepository-layout: No longer first two letters. Also add "down".

[Junio C Hamano <gitster@pobox.com>]

jidanni@jidanni.org writes:

> Signed-off-by: jidanni <jidanni@jidanni.org>

First off, when I tried to respond to your message, I got this:

    Cc: undisclosed-recipients:;

which I had to edit it to point at the list.

I think you did "Bcc: git@vger.kernel.org" without any explicit recipient;
please don't.  It wastes everybody's time.

Second, please realize that the Subject: line is one of the most important
piece of information in your patch submission.  It is used as the summary
of what this change is about in the shortlog output.  2 months from now,
do you think anybody (other than you) can guess what the "first two
letters" is about among 400 other changes?

I would have preferred the Subject: and the commit log message like this
for this patch:

    Subject: [PATCH] Fix description of objects/??/ directories in the repository-layout doc

    These fan-out directories are no longer first two letters.  Also fix
    a sentence that meant to say "keep something down" but forgot "down".

That is, summarize what this patch is about on Subject: line, and explain
why the change is a good idea (in other words, why the current one is bad)
in the commit log message.

I agree with the "down" fix; thanks for catching this grammatical and
semantic error.

I however do not understand the reason behind the former "two letters"
change.

When creating a new object, the filename to hold it when its object name
is e.g. 92b35d66d0e335771c2e4a4a79f95adb844b1f91 (that's a tag object for
v1.6.1 if anybody cares) is computed by taking its first two letters "92"
and using that to choose ".git/object/92" as the containing "fan-out"
directory.  The file in that directory is named using the remainder of the
object name.

The entry in the repository layout document explains what the directories
with two-letter names you find in objects/ directory are, and I do not see
a reason why you want to say "no longer first two letters".  Their names
still are, and very likely continue to be, two-letter long.

Maybe I misunderstood what you wanted to say by "no longer...".  Did you
mean (unlike the sample commit log message I suggested above):

    Subject: [PATCH] Fix description of objects/??/ directories in the repository-layout doc

    Do not say first two letters anymore.  Also fix a sentence that meant
    to say "keep something down" but forgot "down".

If that is the case, please justify why you think it is better not to say
"first two letters" the documentation.

Thanks.