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

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

[Patrick Steinhardt]

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/git-verify-pack.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt
index 526ba7b..61ca6d0 100644
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.txt
@@ -40,7 +40,7 @@ OUTPUT FORMAT
 -------------
 When specifying the -v option the format used is:
 
-	SHA-1 type size size-in-pack-file offset-in-packfile
+	SHA-1 type size size-in-packfile offset-in-packfile
 
 for objects that are not deltified in the pack, and
 
-- 
2.4.0

[PATCH 2/3] git-unpack-objects.txt: fix inconsistent spelling of "packfile"

[Patrick Steinhardt]

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/git-unpack-objects.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
index 12cb108..894d20b 100644
--- a/Documentation/git-unpack-objects.txt
+++ b/Documentation/git-unpack-objects.txt
@@ -19,8 +19,8 @@ the objects contained within and writing them into the repository in
 "loose" (one object per file) format.
 
 Objects that already exist in the repository will *not* be unpacked
-from the pack-file.  Therefore, nothing will be unpacked if you use
-this command on a pack-file that exists within the target repository.
+from the packfile.  Therefore, nothing will be unpacked if you use
+this command on a packfile that exists within the target repository.
 
 See linkgit:git-repack[1] for options to generate
 new packs and replace existing ones.
-- 
2.4.0

[PATCH 3/3] pack-protocol.txt: fix insconsistent spelling of "packfile"

[Patrick Steinhardt]

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/technical/pack-protocol.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 462e206..812d857 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -502,11 +502,11 @@ MUST NOT send a push-cert command.  When a push-cert command is
 sent, command-list MUST NOT be sent; the commands recorded in the
 push certificate is used instead.
 
-The pack-file MUST NOT be sent if the only command used is 'delete'.
+The packfile MUST NOT be sent if the only command used is 'delete'.
 
-A pack-file MUST be sent if either create or update command is used,
+A packfile MUST be sent if either create or update command is used,
 even if the server already has all the necessary objects.  In this
-case the client MUST send an empty pack-file.   The only time this
+case the client MUST send an empty packfile.   The only time this
 is likely to happen is if the client is creating
 a new branch or a tag that points to an existing obj-id.
 
-- 
2.4.0

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

[Junio C Hamano]

There still are a handful of "pack-file" remaining in the
documentation set, even after applying these three that changes
6 instances of 'pack-file' to 'packfile'.

git-index-pack.txt:'git index-pack' [-v] [-o <index-file>] <pack-file>
git-index-pack.txt:                 [<pack-file>]
git-index-pack.txt:	instead and a copy is then written to <pack-file>. If
git-index-pack.txt:	<pack-file> is not specified, the pack is written to
git-index-pack.txt:	<pack-file> is not specified consider using --keep to
git-unpack-objects.txt:'git unpack-objects' [-n] [-q] [-r] [--strict] < <pack-file>
technical/pack-heuristics.txt:    <linus> Anyway, the pack-file could easily be denser still, but
technical/pack-heuristics.txt:    <linus> In particular, while the pack-file is then compressed,
technical/pack-heuristics.txt:    <linus> Anyway: I'm not even trying to claim that the pack-files
technical/pack-protocol.txt:  update-request    =  *shallow ( command-list | push-cert ) [pack-file]
technical/pack-protocol.txt:  pack-file         = "PACK" 28*(OCTET)
user-manual.txt:[[pack-files]]

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?

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

[Jeff King]

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.

Searching for "packfile" on the list yields 2145 messages. Searching for
"pack-file" yields 764. Searching for "pack file" yields 2007 (maybe
more, as my grep did not take into account line breaks).

-Peff

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

[Junio C Hamano]

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.

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

[Junio C Hamano]

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

> 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>

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

[Jeff King]

On Wed, May 20, 2015 at 12:45:09PM -0700, Junio C Hamano wrote:

> 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>

That makes "pack-file" make more sense to me. It is not "the abstract
concept of a packfile", but "the file with the .pack extension" (just as
"idx-file" is "the file with the .idx extension"). They are the same
thing if you think about it, of course, but you might choose one over
the other depending on the context.

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, May 20, 2015 at 12:45:09PM -0700, Junio C Hamano wrote:
>
>> 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>
>
> That makes "pack-file" make more sense to me. It is not "the abstract
> concept of a packfile", but "the file with the .pack extension" (just as
> "idx-file" is "the file with the .idx extension"). They are the same
> thing if you think about it, of course, but you might choose one over
> the other depending on the context.

Hmm, that is also true.

In any case, even though I merged these three to 'next', I think we
need to either revert 3/3 or do s/pack-file/packfile/ throughout the
pack-protocol documentation.  The original has something like this:

    The pack-file MUST NOT be sent if the only command used is 'delete'.

    A pack-file MUST be sent if either create or update command is used,
    even if the server already has all the necessary objects.  In this
    case the client MUST send an empty pack-file.   The only time this
    is likely to happen is if the client is creating
    a new branch or a tag that points to an existing obj-id.

and these are explicitly referring to what EBNF defines as "pack-file".
Changing them to "packfile" is simply wrong.

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

[Jeff King]

On Wed, May 20, 2015 at 03:37:23PM -0700, Junio C Hamano wrote:

> In any case, even though I merged these three to 'next', I think we
> need to either revert 3/3 or do s/pack-file/packfile/ throughout the
> pack-protocol documentation.  The original has something like this:
> 
>     The pack-file MUST NOT be sent if the only command used is 'delete'.
> 
>     A pack-file MUST be sent if either create or update command is used,
>     even if the server already has all the necessary objects.  In this
>     case the client MUST send an empty pack-file.   The only time this
>     is likely to happen is if the client is creating
>     a new branch or a tag that points to an existing obj-id.
> 
> and these are explicitly referring to what EBNF defines as "pack-file".
> Changing them to "packfile" is simply wrong.

Yeah, I agree they should agree with the EBNF. And my inclination is for
"packfile", as it is refering to the concept of the on-the-wire packfile
data (there is no "file ending in .pack" in this context).

Which I guess argues for a further patch.

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Yeah, I agree they should agree with the EBNF. And my inclination is for
> "packfile", as it is refering to the concept of the on-the-wire packfile
> data (there is no "file ending in .pack" in this context).
>
> Which I guess argues for a further patch.

I'm fine with that, then.

If I had a time machine, I would have used "pack data" (or "pack
stream") vs "pack file" (or ".pack file") to differentiatee (as the
pack-protocol is not about transferring any "file", but just carries
"pack data"), but that is a rename with more cost than warranted for
a minuscule gain at this point.

[PATCH] doc: fix inconsistent spelling of "packfile"

[Patrick Steinhardt]

Fix remaining instances where "pack-file" is used instead of
"packfile".

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
This patch now also fixes instances where we refer to EBNF-style
command line parameters, as discussed by Junio and Peff.

 Documentation/git-index-pack.txt          | 10 +++++-----
 Documentation/git-unpack-objects.txt      |  2 +-
 Documentation/technical/pack-protocol.txt |  4 ++--
 Documentation/user-manual.txt             |  2 +-
 4 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index 7a4e055..49621da 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -9,9 +9,9 @@ git-index-pack - Build pack index file for an existing packed archive
 SYNOPSIS
 --------
 [verse]
-'git index-pack' [-v] [-o <index-file>] <pack-file>
+'git index-pack' [-v] [-o <index-file>] <packfile>
 'git index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>]
-                 [<pack-file>]
+		  [<packfile>]
 
 
 DESCRIPTION
@@ -37,11 +37,11 @@ OPTIONS
 
 --stdin::
 	When this flag is provided, the pack is read from stdin
-	instead and a copy is then written to <pack-file>. If
-	<pack-file> is not specified, the pack is written to
+	instead and a copy is then written to <packfile>. If
+	<packfile> is not specified, the pack is written to
 	objects/pack/ directory of the current Git repository with
 	a default name determined from the pack content.  If
-	<pack-file> is not specified consider using --keep to
+	<packfile> is not specified consider using --keep to
 	prevent a race condition between this process and
 	'git repack'.
 
diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
index 894d20b..07d4329 100644
--- a/Documentation/git-unpack-objects.txt
+++ b/Documentation/git-unpack-objects.txt
@@ -9,7 +9,7 @@ git-unpack-objects - Unpack objects from a packed archive
 SYNOPSIS
 --------
 [verse]
-'git unpack-objects' [-n] [-q] [-r] [--strict] < <pack-file>
+'git unpack-objects' [-n] [-q] [-r] [--strict] < <packfile>
 
 
 DESCRIPTION
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 812d857..fc09c63 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -465,7 +465,7 @@ contain all the objects that the server will need to complete the new
 references.
 
 ----
-  update-request    =  *shallow ( command-list | push-cert ) [pack-file]
+  update-request    =  *shallow ( command-list | push-cert ) [packfile]
 
   shallow           =  PKT-LINE("shallow" SP obj-id LF)
 
@@ -491,7 +491,7 @@ references.
 		      *PKT-LINE(gpg-signature-lines LF)
 		      PKT-LINE("push-cert-end" LF)
 
-  pack-file         = "PACK" 28*(OCTET)
+  packfile          = "PACK" 28*(OCTET)
 ----
 
 If the receiving end does not support delete-refs, the sending end MUST
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 68978f5..7147519 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3164,7 +3164,7 @@ objects.  (Note that linkgit:git-tag[1] can also be used to create
 "lightweight tags", which are not tag objects at all, but just simple
 references whose names begin with `refs/tags/`).
 
-[[pack-files]]
+[[packfiles]]
 How Git stores objects efficiently: pack files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.4.1

Re: [PATCH] doc: fix inconsistent spelling of "packfile"

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> Fix remaining instances where "pack-file" is used instead of
> "packfile".
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> This patch now also fixes instances where we refer to EBNF-style
> command line parameters, as discussed by Junio and Peff.

Thanks.

> diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
> index 7a4e055..49621da 100644
> --- a/Documentation/git-index-pack.txt
> +++ b/Documentation/git-index-pack.txt
> @@ -9,9 +9,9 @@ git-index-pack - Build pack index file for an existing packed archive
>  SYNOPSIS
>  --------
>  [verse]
> -'git index-pack' [-v] [-o <index-file>] <pack-file>
> +'git index-pack' [-v] [-o <index-file>] <packfile>
>  'git index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>]
> -                 [<pack-file>]
> +		  [<packfile>]

Hmm.  The former is taking a concrete *.pack file on disk, and the
latter is optionally writing the pack stream out to a *.pack file on
disk.  If we follow "'packfile' for the concept, 'pack-file' to
refer to a file with .pack ending" guideline, I'd think both should
be 'pack-file'.

	Side note: because these invocations, especially the latter
	form, can take any filename, you could do:

        	git index-pack foo.tmp && mv foo.tmp $realfilename.pack

	in which case the arguments may not be files whose names end
	with ".pack"; it is just a file that holds pack data stream,
	so it could be argued that "packfile" is not incorrect.  But
	the reason why you are doing the above is to ultimately
	create a *.pack file, and I'd say "pack-file" would be more
	correct.

> @@ -37,11 +37,11 @@ OPTIONS
>  
>  --stdin::
>  	When this flag is provided, the pack is read from stdin
> -	instead and a copy is then written to <pack-file>. If

Likewise; we are writing to a *.pack file, "written to" is not
talking about what (i.e. "packfile", the pack data stream) is
written but what accepts and holds that data stream in the end.

> -	<pack-file> is not specified, the pack is written to
> +	instead and a copy is then written to <packfile>. If
> +	<packfile> is not specified, the pack is written to
>  	objects/pack/ directory of the current Git repository with
>  	a default name determined from the pack content.  If
> -	<pack-file> is not specified consider using --keep to
> +	<packfile> is not specified consider using --keep to
>  	prevent a race condition between this process and
>  	'git repack'.

All of the above talk about that same entity on the filesystem that
receives the pack data stream.

> diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
> index 894d20b..07d4329 100644
> --- a/Documentation/git-unpack-objects.txt
> +++ b/Documentation/git-unpack-objects.txt
> @@ -9,7 +9,7 @@ git-unpack-objects - Unpack objects from a packed archive
>  SYNOPSIS
>  --------
>  [verse]
> -'git unpack-objects' [-n] [-q] [-r] [--strict] < <pack-file>
> +'git unpack-objects' [-n] [-q] [-r] [--strict] < <packfile>

This feeds the pack data stream to the command from its standard
input, so would be a good change.

	Side note: if you have an on-disk file to feed this command
	from its standard input, it is more than likely that the
	file is a *.pack file, i.e. a "pack-file".  But in practice,
	the command is more often than not fed an output of another
	command via pipe, and it only cares about it being a pack
	data stream.  So in that sense, both are correct but the
	updated one is more correct.

> diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
> index 812d857..fc09c63 100644
> --- a/Documentation/technical/pack-protocol.txt
> +++ b/Documentation/technical/pack-protocol.txt
> @@ -465,7 +465,7 @@ contain all the objects that the server will need to complete the new
>  references.

All changes to this file are good.

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 68978f5..7147519 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -3164,7 +3164,7 @@ objects.  (Note that linkgit:git-tag[1] can also be used to create
>  "lightweight tags", which are not tag objects at all, but just simple
>  references whose names begin with `refs/tags/`).
>  
> -[[pack-files]]
> +[[packfiles]]

Isn't this a xref target?  Can you change it without changing all
the referrers?


In any case, after doing the above two side notes, I am not sure if
readers would appreciate our careful choice of words between
"packfile" and "pack-file" when they read the documentation.

Re: [PATCH] doc: fix inconsistent spelling of "packfile"

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 5679 bytes --]

On Thu, May 21, 2015 at 09:37:14AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > Fix remaining instances where "pack-file" is used instead of
> > "packfile".
> >
> > Signed-off-by: Patrick Steinhardt <ps@pks.im>
> > ---
> > This patch now also fixes instances where we refer to EBNF-style
> > command line parameters, as discussed by Junio and Peff.
> 
> Thanks.
> 
> > diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
> > index 7a4e055..49621da 100644
> > --- a/Documentation/git-index-pack.txt
> > +++ b/Documentation/git-index-pack.txt
> > @@ -9,9 +9,9 @@ git-index-pack - Build pack index file for an existing packed archive
> >  SYNOPSIS
> >  --------
> >  [verse]
> > -'git index-pack' [-v] [-o <index-file>] <pack-file>
> > +'git index-pack' [-v] [-o <index-file>] <packfile>
> >  'git index-pack' --stdin [--fix-thin] [--keep] [-v] [-o <index-file>]
> > -                 [<pack-file>]
> > +		  [<packfile>]
> 
> Hmm.  The former is taking a concrete *.pack file on disk, and the
> latter is optionally writing the pack stream out to a *.pack file on
> disk.  If we follow "'packfile' for the concept, 'pack-file' to
> refer to a file with .pack ending" guideline, I'd think both should
> be 'pack-file'.
> 
> 	Side note: because these invocations, especially the latter
> 	form, can take any filename, you could do:
> 
>         	git index-pack foo.tmp && mv foo.tmp $realfilename.pack
> 
> 	in which case the arguments may not be files whose names end
> 	with ".pack"; it is just a file that holds pack data stream,
> 	so it could be argued that "packfile" is not incorrect.  But
> 	the reason why you are doing the above is to ultimately
> 	create a *.pack file, and I'd say "pack-file" would be more
> 	correct.
> 
> > @@ -37,11 +37,11 @@ OPTIONS
> >  
> >  --stdin::
> >  	When this flag is provided, the pack is read from stdin
> > -	instead and a copy is then written to <pack-file>. If
> 
> Likewise; we are writing to a *.pack file, "written to" is not
> talking about what (i.e. "packfile", the pack data stream) is
> written but what accepts and holds that data stream in the end.
> 
> > -	<pack-file> is not specified, the pack is written to
> > +	instead and a copy is then written to <packfile>. If
> > +	<packfile> is not specified, the pack is written to
> >  	objects/pack/ directory of the current Git repository with
> >  	a default name determined from the pack content.  If
> > -	<pack-file> is not specified consider using --keep to
> > +	<packfile> is not specified consider using --keep to
> >  	prevent a race condition between this process and
> >  	'git repack'.
> 
> All of the above talk about that same entity on the filesystem that
> receives the pack data stream.
> 
> > diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
> > index 894d20b..07d4329 100644
> > --- a/Documentation/git-unpack-objects.txt
> > +++ b/Documentation/git-unpack-objects.txt
> > @@ -9,7 +9,7 @@ git-unpack-objects - Unpack objects from a packed archive
> >  SYNOPSIS
> >  --------
> >  [verse]
> > -'git unpack-objects' [-n] [-q] [-r] [--strict] < <pack-file>
> > +'git unpack-objects' [-n] [-q] [-r] [--strict] < <packfile>
> 
> This feeds the pack data stream to the command from its standard
> input, so would be a good change.
> 
> 	Side note: if you have an on-disk file to feed this command
> 	from its standard input, it is more than likely that the
> 	file is a *.pack file, i.e. a "pack-file".  But in practice,
> 	the command is more often than not fed an output of another
> 	command via pipe, and it only cares about it being a pack
> 	data stream.  So in that sense, both are correct but the
> 	updated one is more correct.
> 
> > diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
> > index 812d857..fc09c63 100644
> > --- a/Documentation/technical/pack-protocol.txt
> > +++ b/Documentation/technical/pack-protocol.txt
> > @@ -465,7 +465,7 @@ contain all the objects that the server will need to complete the new
> >  references.
> 
> All changes to this file are good.
> 
> > diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> > index 68978f5..7147519 100644
> > --- a/Documentation/user-manual.txt
> > +++ b/Documentation/user-manual.txt
> > @@ -3164,7 +3164,7 @@ objects.  (Note that linkgit:git-tag[1] can also be used to create
> >  "lightweight tags", which are not tag objects at all, but just simple
> >  references whose names begin with `refs/tags/`).
> >  
> > -[[pack-files]]
> > +[[packfiles]]
> 
> Isn't this a xref target?  Can you change it without changing all
> the referrers?

I did not find any referrers pointing to this, so I just changed
it. I do not know if there are any referrers from outside, so I
guess I'll just revert that back to [[pack-files]] as it is not
seen by users anyway.

> In any case, after doing the above two side notes, I am not sure if
> readers would appreciate our careful choice of words between
> "packfile" and "pack-file" when they read the documentation.

Exactly my thought by now. While it sure is nice to have the
technically most-correct terms in use I guess the user will not
realize that we are talking about different things when referring
to "pack-files" as opposed to "packfiles". I doubt it will hurt
though as the user will certainly just skim over it without
realizing that we sometimes use one or the other, as long as they
are not used together in a single paragraph.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

[PATCH v2] doc: fix inconsistent spelling of "packfile"

[Patrick Steinhardt]

Fix remaining instances where "pack-file" is used instead of
"packfile". Some places remain where we still use "pack-file",
This is the case when we explicitly refer to a file with a
".pack" extension as opposed to a data source providing a pack
data stream.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/git-unpack-objects.txt      | 2 +-
 Documentation/technical/pack-protocol.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
index 894d20b..07d4329 100644
--- a/Documentation/git-unpack-objects.txt
+++ b/Documentation/git-unpack-objects.txt
@@ -9,7 +9,7 @@ git-unpack-objects - Unpack objects from a packed archive
 SYNOPSIS
 --------
 [verse]
-'git unpack-objects' [-n] [-q] [-r] [--strict] < <pack-file>
+'git unpack-objects' [-n] [-q] [-r] [--strict] < <packfile>
 
 
 DESCRIPTION
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 812d857..fc09c63 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -465,7 +465,7 @@ contain all the objects that the server will need to complete the new
 references.
 
 ----
-  update-request    =  *shallow ( command-list | push-cert ) [pack-file]
+  update-request    =  *shallow ( command-list | push-cert ) [packfile]
 
   shallow           =  PKT-LINE("shallow" SP obj-id LF)
 
@@ -491,7 +491,7 @@ references.
 		      *PKT-LINE(gpg-signature-lines LF)
 		      PKT-LINE("push-cert-end" LF)
 
-  pack-file         = "PACK" 28*(OCTET)
+  packfile          = "PACK" 28*(OCTET)
 ----
 
 If the receiving end does not support delete-refs, the sending end MUST
-- 
2.4.1

Re: [PATCH v2] doc: fix inconsistent spelling of "packfile"

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> Fix remaining instances where "pack-file" is used instead of
> "packfile". Some places remain where we still use "pack-file",
> This is the case when we explicitly refer to a file with a
> ".pack" extension as opposed to a data source providing a pack
> data stream.


Thanks.

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

[Patrick Steinhardt]

[-- Attachment #1: Type: text/plain, Size: 1906 bytes --]

On Tue, May 19, 2015 at 12:34:03PM -0700, Junio C Hamano wrote:
> There still are a handful of "pack-file" remaining in the
> documentation set, even after applying these three that changes
> 6 instances of 'pack-file' to 'packfile'.
> 
> git-index-pack.txt:'git index-pack' [-v] [-o <index-file>] <pack-file>
> git-index-pack.txt:                 [<pack-file>]
> git-index-pack.txt:	instead and a copy is then written to <pack-file>. If
> git-index-pack.txt:	<pack-file> is not specified, the pack is written to
> git-index-pack.txt:	<pack-file> is not specified consider using --keep to
> git-unpack-objects.txt:'git unpack-objects' [-n] [-q] [-r] [--strict] < <pack-file>
> technical/pack-heuristics.txt:    <linus> Anyway, the pack-file could easily be denser still, but
> technical/pack-heuristics.txt:    <linus> In particular, while the pack-file is then compressed,
> technical/pack-heuristics.txt:    <linus> Anyway: I'm not even trying to claim that the pack-files
> technical/pack-protocol.txt:  update-request    =  *shallow ( command-list | push-cert ) [pack-file]
> technical/pack-protocol.txt:  pack-file         = "PACK" 28*(OCTET)
> user-manual.txt:[[pack-files]]
> 
> 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?

I was aware of the other instances of 'pack-file'. The only case
where 'pack-file' does occur after my patches, though,  was as
command line parameters, where I didn't want to change it. If
that's desired I can whip up another patch.

Patrick

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]