Documentation: Grammar correction, wording fixes and cleanup

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index eb3d040783e8202f502d05e8b4dc4e3b39736779..5c891f1169b35e53bccc19f0423b5b7e98db720b 100644 (file)
--- 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
        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 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]::
 
 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,
 
 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
 
 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.
 
        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
 +
 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
 
 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
 
 hooks::
        Hooks are customization scripts used by various git


@@ -173,9 +167,11 @@ info/exclude::
        at it.  See also: linkgit:gitignore[5].
 
 remotes::
        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
 
 logs::
        Records of changes made to refs are stored in this