Re: [PATCH 1/3] git-verify-pack.txt: fix inconsistent spelling of "packfile"

From: Junio C Hamano <gitster@pobox.com>
Date: May 20, 2015, 19:45 UTC
Message-ID: <xmqqd21vnid6.fsf@gitster.dls.corp.google.com>
In-Reply-To: <xmqqmw0znjfc.fsf@gitster.dls.corp.google.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 20 quoted lines

> Jeff King <peff@peff.net> writes:
>
>> On Tue, May 19, 2015 at 12:34:03PM -0700, Junio C Hamano wrote:
>>
>>> A quick "git grep packfile" vs "git grep pack-file" inside
>>> Documentation/ directory indicates that we seem to use 'packfile'
>>> primarily in the lower-level technical documents that are not
>>> end-user facing.  Almost half of them are in the release notes
>>> that we won't bother "fixing", so it might make sense to go the
>>> other way around, consistently using "pack-file" that may be more
>>> familiar to end-users.
>>> 
>>> What do others think?
>>
>> If I saw "pack-file" (outside of this discussion) I would think it was
>> wrong. That's just my opinion, of course.
>
> OK, then let's go with these three patches.
>
> Thanks for sanity checking.

By the way, the way we spell these two entities in the glossary is

 "pack" - that which holds collection of objects tightly packed
 "pack index" - that which allows a random access into a "pack"

We may want to do two things:

 (1) add "packfile" as a synonym to the former; I think the origin
     of "pack file" is that it would clarify which one we refer to
     it as an on-disk entity when contrasting a "pack" and its
     associated "pack index", and I even suspect that originally we
     spelled it as two words, later contracted with dash (as seen in
     the pack-heuristics irc lecture given by Linus).

 (2) describe "pack bitmap", which came long after the original
     glossary entries are made.

And if we are going that route, we should fix the SYNOPSIS sections and usage[] strings of "index-pack" and "unpack-objects" where we say these commands read from "<pack-file>" (we now read from "<packfile>").

I am undecided if we want to touch Documentation/technical/. The irc lecture in pack-heuristics.txt is a historical recording and it may be OK to keep it as it is. pack-protocol.txt consistently uses "packfile" in prose and uses "pack-file" in EBNF. From a quick re-reading of the document, I think it is OK to use "packfile" throughout there.

One related thing is that there are few mentions of "idx file" to refer to "pack index" (e.g. show-index and verify-pack documentation pages); I think this was an attempt to disambiguate "pack index" from "the Index", but as long as we spell it "pack index", I think it should be OK, so while we are at it we may want to fix them. We can leave "pack .idx file" as-is, but rewriting it to "pack index file" or just "pack index" may be OK as long as it is clear from the context.

"git show-index" has this in SYNOPSIS:

	'git show-index' < idx-file

It probably should become

	'git show-index' < <pack-index>