Ben Walton <bwalton@xxxxxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxx> > --- > 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html