[PATCH] Grammar and wording fixes in gitrepository-layout

[PATCH] Grammar and wording fixes in gitrepository-layout

[Ben Walton]

This patch corrects a few grammar issues in gitrepository-layout.txt
and also rewords a few sections for clarity.

Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca>
---
 Documentation/gitrepository-layout.txt |   46 +++++++++++++++----------------
 1 files changed, 22 insertions(+), 24 deletions(-)

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index eb3d040..02a6167 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -23,32 +23,30 @@ objects::
 	Object store associated with this repository.  Usually
 	an object store is self sufficient (i.e. all the objects
 	that are referred to by an object found in it are also
-	found in it), but there are couple of ways to violate
-	it.
+	found in it), but there are a few ways to violate it.
 +
 . You could populate the repository by running a commit walker
-without `-a` option.  Depending on which options are given, you
+without `-a` option.  Depending on the options given, you
 could have only commit objects without associated blobs and
 trees this way, for example.  A repository with this kind of
 incomplete object store is not suitable to be published to the
-outside world but sometimes useful for private repository.
+outside world but is sometimes useful in a private repository.
 . You also could have an incomplete but locally usable repository
-by cloning shallowly.  See linkgit:git-clone[1].
-. You can be using `objects/info/alternates` mechanism, or
-`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
+by creating a shallow clone.  See linkgit:git-clone[1].
+. You could be using the `objects/info/alternates` or
+`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
 objects from other object stores.  A repository with this kind
 of incomplete object store is not suitable to be published for
-use with dumb transports but otherwise is OK as long as
-`objects/info/alternates` points at the right object stores
-it borrows from.
+use with dumb transports but is otherwise OK as long as
+`objects/info/alternates` points at the right object stores.
 
 objects/[0-9a-f][0-9a-f]::
 	Traditionally, each object is stored in its own file.
-	They are split into 256 subdirectories using the first
-	two letters from its object name to keep the number of
-	directory entries `objects` directory itself needs to
-	hold.  Objects found here are often called 'unpacked'
-	(or 'loose') objects.
+	The objects are splayed over 256 subdirectories using
+	the first two characters of the sha1 object name to
+	keep the number of directory entries in `objects`
+	itself to a manageable number. Objects found
+	here are often called 'unpacked' (or 'loose') objects.
 
 objects/pack::
 	Packs (files that store many object in compressed form,
@@ -85,7 +83,7 @@ objects/info/http-alternates::
 
 refs::
 	References are stored in subdirectories of this
-	directory.  The 'git prune' command knows to keep
+	directory.  The 'git prune' command knows to preserve
 	objects reachable from refs found in this directory and
 	its subdirectories.
 
@@ -120,15 +118,15 @@ HEAD::
 HEAD can also record a specific commit directly, instead of
 being a symref to point at the current branch.  Such a state
 is often called 'detached HEAD', and almost all commands work
-identically as normal.  See linkgit:git-checkout[1] for
+as they normally would.  See linkgit:git-checkout[1] for
 details.
 
 branches::
 	A slightly deprecated way to store shorthands to be used
-	to specify URL to 'git fetch', 'git pull' and 'git push'
-	commands is to store a file in `branches/<name>` and
-	give 'name' to these commands in place of 'repository'
-	argument.
+	to specify a URL to 'git fetch', 'git pull' and 'git push'.
+	A file can be stored as `branches/<name>` and then
+	'name' can be givent to these commands in place of
+	'repository' argument.
 
 hooks::
 	Hooks are customization scripts used by various git
@@ -173,9 +171,9 @@ info/exclude::
 	at it.  See also: linkgit:gitignore[5].
 
 remotes::
-	Stores shorthands to be used to give URL and default
-	refnames to interact with remote repository to
-	'git fetch', 'git pull' and 'git push' commands.
+	Stores shorthands for URL and default refnames for use
+	when interacting with remote repositories via 'git fetch',
+	'git pull' and 'git push' commands.
 
 logs::
 	Records of changes made to refs are stored in this
-- 
1.7.4.1

Re: [PATCH] Grammar and wording fixes in gitrepository-layout

[Junio C Hamano]

Ben Walton <bwalton@artsci.utoronto.ca> writes:

> This patch corrects a few grammar issues in gitrepository-layout.txt
> and also rewords a few sections for clarity.

Thanks, Ben.

I notice that there are issues, not introduced with your patch, that we
may want to address further, though.

> Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca>
> ---
>  Documentation/gitrepository-layout.txt |   46 +++++++++++++++----------------
>  1 files changed, 22 insertions(+), 24 deletions(-)
>
> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
> index eb3d040..02a6167 100644
> --- a/Documentation/gitrepository-layout.txt
> +++ b/Documentation/gitrepository-layout.txt
> @@ -23,32 +23,30 @@ objects::
>  	Object store associated with this repository.  Usually
>  	an object store is self sufficient (i.e. all the objects
>  	that are referred to by an object found in it are also
> -	found in it), but there are couple of ways to violate
> -	it.
> +	found in it), but there are a few ways to violate it.
>  +
>  . You could populate the repository by running a commit walker
> -without `-a` option.  Depending on which options are given, you
> +without `-a` option.  Depending on the options given, you
>  could have only commit objects without associated blobs and
>  trees this way, for example.  A repository with this kind of
>  incomplete object store is not suitable to be published to the
> -outside world but sometimes useful for private repository.
> +outside world but is sometimes useful in a private repository.

Here "a commit walker" refers to the "http-fetch" dumb http walker, which
was unclear and confusing even to me, but more importantly, I wonder if we
even want to condone the use of it to break the repository integrity in
such a way that other tools in git toolset do not even give support.

Other items in this list, namely shallow-clone and borrowing objects from
alternates, are supported configurations in which .git/objects do _not_
have all the objects, but "http-fetch without -a" that pulls in commits
without their associated trees and blobs do not even pass "fsck" and worse
yet cannot be "fixed" later by fetching missing objects on top, like
a shallow clone does by allowing deepening it later.

Perhaps we should deprecate http-fetch without -a and drop this item from
the list?

> +. You could be using the `objects/info/alternates` or
> +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
>  objects from other object stores.  A repository with this kind
>  of incomplete object store is not suitable to be published for
> -use with dumb transports but otherwise is OK as long as
> -`objects/info/alternates` points at the right object stores
> -it borrows from.
> +use with dumb transports but is otherwise OK as long as
> +`objects/info/alternates` points at the right object stores.

The last three words in the original are meant to clarify and define what
"the right object stores" are. Was there a compelling reason to drop them?

>  objects/[0-9a-f][0-9a-f]::
>  	Traditionally, each object is stored in its own file.

I would suggest further rewording this to something like:

	A newly created object is stored in its own file.

> @@ -120,15 +118,15 @@ HEAD::
>  HEAD can also record a specific commit directly, instead of
>  being a symref to point at the current branch.  Such a state
>  is often called 'detached HEAD', and almost all commands work
> -identically as normal.  See linkgit:git-checkout[1] for
> +as they normally would.  See linkgit:git-checkout[1] for
>  details.

We may want to reword the sentence that begins with "almost all commands"
further. In the early days after detached HEAD support was introduced, we
may have left cases where the result was _undefined_ for commands that
would not make sense unless you are on a branch, but by now what we have
should behave sensibly by either erroring out when the operation does not
make sense unless you are on a real branch, or doing something useful.

>  branches::
>  	A slightly deprecated way to store shorthands to be used
> -	to specify URL to 'git fetch', 'git pull' and 'git push'
> -	commands is to store a file in `branches/<name>` and
> -	give 'name' to these commands in place of 'repository'
> -	argument.
> +	to specify a URL to 'git fetch', 'git pull' and 'git push'.
> +	A file can be stored as `branches/<name>` and then
> +	'name' can be givent to these commands in place of

s/givent to/given to/

> +	'repository' argument.

We would at least need "See linkgit:..." to say what is expected in this
file and how it is used (the information is in urls-remotes.txt but that
is not a top-level file, so it needs to refer to git-fetch and git-push
instead).

> @@ -173,9 +171,9 @@ info/exclude::
>  	at it.  See also: linkgit:gitignore[5].
>  
>  remotes::
> -	Stores shorthands to be used to give URL and default
> -	refnames to interact with remote repository to
> -	'git fetch', 'git pull' and 'git push' commands.
> +	Stores shorthands for URL and default refnames for use
> +	when interacting with remote repositories via 'git fetch',
> +	'git pull' and 'git push' commands.

Likewise.

Also I would personally consider "branches" and "remotes" both "slightly
deprecated". "git init", "git clone", and "git remote" stopped populating
these long time ago.

Re: [PATCH] Grammar and wording fixes in gitrepository-layout

[Ben Walton]

Excerpts from Junio C Hamano's message of Mon Aug 22 14:09:36 -0400 2011:

Hi Junio,

> Perhaps we should deprecate http-fetch without -a and drop this item
> from the list?

I don't know much about http-fetch as I've never touched it directly.
It doesn't sound like a good idea to allow creating a broken object
store though.  I'll send a patch shortly that adds the deprecation
warning if -a isn't given.

> > +. You could be using the `objects/info/alternates` or
> > +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
> >  objects from other object stores.  A repository with this kind
> >  of incomplete object store is not suitable to be published for
> > -use with dumb transports but otherwise is OK as long as
> > -`objects/info/alternates` points at the right object stores
> > -it borrows from.
> > +use with dumb transports but is otherwise OK as long as
> > +`objects/info/alternates` points at the right object stores.
> 
> The last three words in the original are meant to clarify and define
> what "the right object stores" are. Was there a compelling reason to
> drop them?

The only reason I dropped them is that I didn't feel they were helping
to clarify the meaning.  The wording was a bit awkward and I thought
'it borrows from' was part the problem.  I see what you're saying
though and think that the following wording is better:

use with dumb transports but is otherwise OK as long as
`objects/info/alternates` points to object stores containing the
missing objects.

> >  objects/[0-9a-f][0-9a-f]::
> >      Traditionally, each object is stored in its own file.
> 
> I would suggest further rewording this to something like:
> 
>     A newly created object is stored in its own file.

Agreed.  This is much better.

> > @@ -120,15 +118,15 @@ HEAD::
> >  HEAD can also record a specific commit directly, instead of
> >  being a symref to point at the current branch.  Such a state
> >  is often called 'detached HEAD', and almost all commands work
> > -identically as normal.  See linkgit:git-checkout[1] for
> > +as they normally would.  See linkgit:git-checkout[1] for
> >  details.
> 
> We may want to reword the sentence that begins with "almost all commands"
> further. In the early days after detached HEAD support was introduced, we
> may have left cases where the result was _undefined_ for commands that
> would not make sense unless you are on a branch, but by now what we have
> should behave sensibly by either erroring out when the operation does not
> make sense unless you are on a real branch, or doing something
> useful.

Ok, how about a full stop after 'detached HEAD' and then the link to
git-checkout?

> >  branches::
> >      A slightly deprecated way to store shorthands to be used
> > -    to specify URL to 'git fetch', 'git pull' and 'git push'
> > -    commands is to store a file in `branches/<name>` and
> > -    give 'name' to these commands in place of 'repository'
> > -    argument.
> > +    to specify a URL to 'git fetch', 'git pull' and 'git push'.
> > +    A file can be stored as `branches/<name>` and then
> > +    'name' can be givent to these commands in place of
> 
> s/givent to/given to/
> 
> > +    'repository' argument.
> 
> We would at least need "See linkgit:..." to say what is expected in this
> file and how it is used (the information is in urls-remotes.txt but that
> is not a top-level file, so it needs to refer to git-fetch and git-push
> instead).

Noted.  The updated patch will address this.

> > @@ -173,9 +171,9 @@ info/exclude::
> >      at it.  See also: linkgit:gitignore[5].
> >  
> >  remotes::
> > -    Stores shorthands to be used to give URL and default
> > -    refnames to interact with remote repository to
> > -    'git fetch', 'git pull' and 'git push' commands.
> > +    Stores shorthands for URL and default refnames for use
> > +    when interacting with remote repositories via 'git fetch',
> > +    'git pull' and 'git push' commands.
> 
> Likewise.
> 
> Also I would personally consider "branches" and "remotes" both "slightly
> deprecated". "git init", "git clone", and "git remote" stopped populating
> these long time ago.

Ok, I've added the note about this being legacy to both of the
sections in question.

Updated patch to follow shortly.

Thanks
-Ben
--
Ben Walton
Systems Programmer - CHASS
University of Toronto
C:416.407.5610 | W:416.978.4302

[PATCH] Documentation: Grammar correction, wording fixes and cleanup

[Ben Walton]

Correct a few grammar issues in gitrepository-layout.txt and also
rewords a few sections for clarity.

Remove references to using http-fetch without -a to create a broken
repository.

Mark a few areas of the repository structure as legacy.

Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca>
---
 Documentation/gitrepository-layout.txt |   60 +++++++++++++++-----------------
 1 files changed, 28 insertions(+), 32 deletions(-)

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index eb3d040..5023ea9 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -23,32 +23,25 @@ objects::
 	Object store associated with this repository.  Usually
 	an object store is self sufficient (i.e. all the objects
 	that are referred to by an object found in it are also
-	found in it), but there are couple of ways to violate
-	it.
+	found in it), but there are a few ways to violate it.
 +
-. You could populate the repository by running a commit walker
-without `-a` option.  Depending on which options are given, you
-could have only commit objects without associated blobs and
-trees this way, for example.  A repository with this kind of
-incomplete object store is not suitable to be published to the
-outside world but sometimes useful for private repository.
-. You also could have an incomplete but locally usable repository
-by cloning shallowly.  See linkgit:git-clone[1].
-. You can be using `objects/info/alternates` mechanism, or
-`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
+. You could have an incomplete but locally usable repository
+by creating a shallow clone.  See linkgit:git-clone[1].
+. You could be using the `objects/info/alternates` or
+`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
 objects from other object stores.  A repository with this kind
 of incomplete object store is not suitable to be published for
-use with dumb transports but otherwise is OK as long as
-`objects/info/alternates` points at the right object stores
-it borrows from.
+use with dumb transports but is otherwise OK as long as
+`objects/info/alternates` points to object stores containing the
+missing objects.
 
 objects/[0-9a-f][0-9a-f]::
-	Traditionally, each object is stored in its own file.
-	They are split into 256 subdirectories using the first
-	two letters from its object name to keep the number of
-	directory entries `objects` directory itself needs to
-	hold.  Objects found here are often called 'unpacked'
-	(or 'loose') objects.
+	A newly created object is stored in its own file.
+	The objects are splayed over 256 subdirectories using
+	the first two characters of the sha1 object name to
+	keep the number of directory entries in `objects`
+	itself to a manageable number. Objects found
+	here are often called 'unpacked' (or 'loose') objects.
 
 objects/pack::
 	Packs (files that store many object in compressed form,
@@ -85,7 +78,7 @@ objects/info/http-alternates::
 
 refs::
 	References are stored in subdirectories of this
-	directory.  The 'git prune' command knows to keep
+	directory.  The 'git prune' command knows to preserve
 	objects reachable from refs found in this directory and
 	its subdirectories.
 
@@ -119,16 +112,17 @@ HEAD::
 +
 HEAD can also record a specific commit directly, instead of
 being a symref to point at the current branch.  Such a state
-is often called 'detached HEAD', and almost all commands work
-identically as normal.  See linkgit:git-checkout[1] for
-details.
+is often called 'detached HEAD.'  See linkgit:git-checkout[1]
+for details.
 
 branches::
 	A slightly deprecated way to store shorthands to be used
-	to specify URL to 'git fetch', 'git pull' and 'git push'
-	commands is to store a file in `branches/<name>` and
-	give 'name' to these commands in place of 'repository'
-	argument.
+	to specify a URL to 'git fetch', 'git pull' and 'git push'.
+	A file can be stored as `branches/<name>` and then
+	'name' can be given to these commands in place of
+	'repository' argument.  See the REMOTES section in
+	linkgit:git-fetch[1] for details.  This mechanism is legacy
+	and not likely to be found in modern repositories.
 
 hooks::
 	Hooks are customization scripts used by various git
@@ -173,9 +167,11 @@ info/exclude::
 	at it.  See also: linkgit:gitignore[5].
 
 remotes::
-	Stores shorthands to be used to give URL and default
-	refnames to interact with remote repository to
-	'git fetch', 'git pull' and 'git push' commands.
+	Stores shorthands for URL and default refnames for use
+	when interacting with remote repositories via 'git fetch',
+	'git pull' and 'git push' commands.  See the REMOTES section
+	in linkgit:git-fetch[1] for details.  This mechanism is legacy
+	and not likely to be found in modern repositories.
 
 logs::
 	Records of changes made to refs are stored in this
-- 
1.7.4.1

Re: [PATCH] Documentation: Grammar correction, wording fixes and cleanup

[Drew Northup]

On Mon, 2011-08-22 at 20:48 -0400, Ben Walton wrote:

> +. You could be using the `objects/info/alternates` or
> +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
>  objects from other object stores.  A repository with this kind
>  of incomplete object store is not suitable to be published for
> -use with dumb transports but otherwise is OK as long as
> -`objects/info/alternates` points at the right object stores
> -it borrows from.
> +use with dumb transports but is otherwise OK as long as
> +`objects/info/alternates` points to object stores containing the
> +missing objects.

Umm, I'm not prepared to call this an improvement. The objects aren't
_missing_, they just aren't present in the most immediate object store.
I'm a minimalist when it comes to this sort of edit and would have just
excised the word "right" from the awkward segment.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH] Documentation: Grammar correction, wording fixes and cleanup

[Junio C Hamano]

Drew Northup <drew.northup@maine.edu> writes:

> On Mon, 2011-08-22 at 20:48 -0400, Ben Walton wrote:
>
>> +. You could be using the `objects/info/alternates` or
>> +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
>>  objects from other object stores.  A repository with this kind
>>  of incomplete object store is not suitable to be published for
>> -use with dumb transports but otherwise is OK as long as
>> -`objects/info/alternates` points at the right object stores
>> -it borrows from.
>> +use with dumb transports but is otherwise OK as long as
>> +`objects/info/alternates` points to object stores containing the
>> +missing objects.
>
> Umm, I'm not prepared to call this an improvement. The objects aren't
> _missing_, they just aren't present in the most immediate object store.
> I'm a minimalist when it comes to this sort of edit and would have just
> excised the word "right" from the awkward segment.

Yeah, "points at the object stores it borrows objects from" sounds
readable and technically correct.

[PATCH] Documentation: Grammar correction, wording fixes and cleanup

[Ben Walton]

Correct a few grammar issues in gitrepository-layout.txt and also
rewords a few sections for clarity.

Remove references to using http-fetch without -a to create a broken
repository.

Mark a few areas of the repository structure as legacy.

Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca>
---
 Documentation/gitrepository-layout.txt |   58 +++++++++++++++-----------------
 1 files changed, 27 insertions(+), 31 deletions(-)

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index eb3d040..5c891f1 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -23,32 +23,25 @@ objects::
 	Object store associated with this repository.  Usually
 	an object store is self sufficient (i.e. all the objects
 	that are referred to by an object found in it are also
-	found in it), but there are couple of ways to violate
-	it.
+	found in it), but there are a few ways to violate it.
 +
-. You could populate the repository by running a commit walker
-without `-a` option.  Depending on which options are given, you
-could have only commit objects without associated blobs and
-trees this way, for example.  A repository with this kind of
-incomplete object store is not suitable to be published to the
-outside world but sometimes useful for private repository.
-. You also could have an incomplete but locally usable repository
-by cloning shallowly.  See linkgit:git-clone[1].
-. You can be using `objects/info/alternates` mechanism, or
-`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
+. You could have an incomplete but locally usable repository
+by creating a shallow clone.  See linkgit:git-clone[1].
+. You could be using the `objects/info/alternates` or
+`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
 objects from other object stores.  A repository with this kind
 of incomplete object store is not suitable to be published for
 use with dumb transports but otherwise is OK as long as
-`objects/info/alternates` points at the right object stores
-it borrows from.
+`objects/info/alternates` points at the object stores it
+borrows from.
 
 objects/[0-9a-f][0-9a-f]::
-	Traditionally, each object is stored in its own file.
-	They are split into 256 subdirectories using the first
-	two letters from its object name to keep the number of
-	directory entries `objects` directory itself needs to
-	hold.  Objects found here are often called 'unpacked'
-	(or 'loose') objects.
+	A newly created object is stored in its own file.
+	The objects are splayed over 256 subdirectories using
+	the first two characters of the sha1 object name to
+	keep the number of directory entries in `objects`
+	itself to a manageable number. Objects found
+	here are often called 'unpacked' (or 'loose') objects.
 
 objects/pack::
 	Packs (files that store many object in compressed form,
@@ -85,7 +78,7 @@ objects/info/http-alternates::
 
 refs::
 	References are stored in subdirectories of this
-	directory.  The 'git prune' command knows to keep
+	directory.  The 'git prune' command knows to preserve
 	objects reachable from refs found in this directory and
 	its subdirectories.
 
@@ -119,16 +112,17 @@ HEAD::
 +
 HEAD can also record a specific commit directly, instead of
 being a symref to point at the current branch.  Such a state
-is often called 'detached HEAD', and almost all commands work
-identically as normal.  See linkgit:git-checkout[1] for
-details.
+is often called 'detached HEAD.'  See linkgit:git-checkout[1]
+for details.
 
 branches::
 	A slightly deprecated way to store shorthands to be used
-	to specify URL to 'git fetch', 'git pull' and 'git push'
-	commands is to store a file in `branches/<name>` and
-	give 'name' to these commands in place of 'repository'
-	argument.
+	to specify a URL to 'git fetch', 'git pull' and 'git push'.
+	A file can be stored as `branches/<name>` and then
+	'name' can be given to these commands in place of
+	'repository' argument.  See the REMOTES section in
+	linkgit:git-fetch[1] for details.  This mechanism is legacy
+	and not likely to be found in modern repositories.
 
 hooks::
 	Hooks are customization scripts used by various git
@@ -173,9 +167,11 @@ info/exclude::
 	at it.  See also: linkgit:gitignore[5].
 
 remotes::
-	Stores shorthands to be used to give URL and default
-	refnames to interact with remote repository to
-	'git fetch', 'git pull' and 'git push' commands.
+	Stores shorthands for URL and default refnames for use
+	when interacting with remote repositories via 'git fetch',
+	'git pull' and 'git push' commands.  See the REMOTES section
+	in linkgit:git-fetch[1] for details.  This mechanism is legacy
+	and not likely to be found in modern repositories.
 
 logs::
 	Records of changes made to refs are stored in this
-- 
1.7.4.1

Re: [PATCH] Documentation: Grammar correction, wording fixes and cleanup

[Drew Northup]

On Tue, 2011-08-23 at 20:32 -0400, Ben Walton wrote:
> Correct a few grammar issues in gitrepository-layout.txt and also
> rewords a few sections for clarity.
> 
> Remove references to using http-fetch without -a to create a broken
> repository.
> 
> Mark a few areas of the repository structure as legacy.
> 
> Signed-off-by: Ben Walton <bwalton@artsci.utoronto.ca>
> ---

Thanks Ben.
Looks good to me. I haven't tried applying it yet (it might not apply to
my bowl of breakfast cereal so well, but then again I should not be
surprised).

>  Documentation/gitrepository-layout.txt |   58 +++++++++++++++-----------------
>  1 files changed, 27 insertions(+), 31 deletions(-)
> 
> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
> index eb3d040..5c891f1 100644
> --- a/Documentation/gitrepository-layout.txt
> +++ b/Documentation/gitrepository-layout.txt
> @@ -23,32 +23,25 @@ objects::
>  	Object store associated with this repository.  Usually
>  	an object store is self sufficient (i.e. all the objects
>  	that are referred to by an object found in it are also
> -	found in it), but there are couple of ways to violate
> -	it.
> +	found in it), but there are a few ways to violate it.
>  +
> -. You could populate the repository by running a commit walker
> -without `-a` option.  Depending on which options are given, you
> -could have only commit objects without associated blobs and
> -trees this way, for example.  A repository with this kind of
> -incomplete object store is not suitable to be published to the
> -outside world but sometimes useful for private repository.
> -. You also could have an incomplete but locally usable repository
> -by cloning shallowly.  See linkgit:git-clone[1].
> -. You can be using `objects/info/alternates` mechanism, or
> -`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
> +. You could have an incomplete but locally usable repository
> +by creating a shallow clone.  See linkgit:git-clone[1].
> +. You could be using the `objects/info/alternates` or
> +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
>  objects from other object stores.  A repository with this kind
>  of incomplete object store is not suitable to be published for
>  use with dumb transports but otherwise is OK as long as
> -`objects/info/alternates` points at the right object stores
> -it borrows from.
> +`objects/info/alternates` points at the object stores it
> +borrows from.
>  
>  objects/[0-9a-f][0-9a-f]::
> -	Traditionally, each object is stored in its own file.
> -	They are split into 256 subdirectories using the first
> -	two letters from its object name to keep the number of
> -	directory entries `objects` directory itself needs to
> -	hold.  Objects found here are often called 'unpacked'
> -	(or 'loose') objects.
> +	A newly created object is stored in its own file.
> +	The objects are splayed over 256 subdirectories using
> +	the first two characters of the sha1 object name to
> +	keep the number of directory entries in `objects`
> +	itself to a manageable number. Objects found
> +	here are often called 'unpacked' (or 'loose') objects.
>  
>  objects/pack::
>  	Packs (files that store many object in compressed form,
> @@ -85,7 +78,7 @@ objects/info/http-alternates::
>  
>  refs::
>  	References are stored in subdirectories of this
> -	directory.  The 'git prune' command knows to keep
> +	directory.  The 'git prune' command knows to preserve
>  	objects reachable from refs found in this directory and
>  	its subdirectories.
>  
> @@ -119,16 +112,17 @@ HEAD::
>  +
>  HEAD can also record a specific commit directly, instead of
>  being a symref to point at the current branch.  Such a state
> -is often called 'detached HEAD', and almost all commands work
> -identically as normal.  See linkgit:git-checkout[1] for
> -details.
> +is often called 'detached HEAD.'  See linkgit:git-checkout[1]
> +for details.
>  
>  branches::
>  	A slightly deprecated way to store shorthands to be used
> -	to specify URL to 'git fetch', 'git pull' and 'git push'
> -	commands is to store a file in `branches/<name>` and
> -	give 'name' to these commands in place of 'repository'
> -	argument.
> +	to specify a URL to 'git fetch', 'git pull' and 'git push'.
> +	A file can be stored as `branches/<name>` and then
> +	'name' can be given to these commands in place of
> +	'repository' argument.  See the REMOTES section in
> +	linkgit:git-fetch[1] for details.  This mechanism is legacy
> +	and not likely to be found in modern repositories.
>  
>  hooks::
>  	Hooks are customization scripts used by various git
> @@ -173,9 +167,11 @@ info/exclude::
>  	at it.  See also: linkgit:gitignore[5].
>  
>  remotes::
> -	Stores shorthands to be used to give URL and default
> -	refnames to interact with remote repository to
> -	'git fetch', 'git pull' and 'git push' commands.
> +	Stores shorthands for URL and default refnames for use
> +	when interacting with remote repositories via 'git fetch',
> +	'git pull' and 'git push' commands.  See the REMOTES section
> +	in linkgit:git-fetch[1] for details.  This mechanism is legacy
> +	and not likely to be found in modern repositories.
>  
>  logs::
>  	Records of changes made to refs are stored in this
-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH] Documentation: Grammar correction, wording fixes and cleanup

[Ben Walton]

Excerpts from Drew Northup's message of Wed Aug 24 07:27:25 -0400 2011:

> Thanks Ben.

No problem.  Your fix was simpler and better.  I missed the forest for
the trees on that change.

Thanks
-Ben
--
Ben Walton
Systems Programmer - CHASS
University of Toronto
C:416.407.5610 | W:416.978.4302