{"thread":{"id":"28172","subject":"[PATCH] Grammar and wording fixes in gitrepository-layout","startedAt":"2011-08-20T02:43:07Z","lastAt":"2011-08-24T12:54:10Z","messageCount":9,"participants":["Ben Walton","Junio C Hamano","Drew Northup"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"173908","messageId":"1313808187-1666-1-git-send-email-bwalton@artsci.utoronto.ca","threadId":"28172","inReplyTo":null,"subject":"[PATCH] Grammar and wording fixes in gitrepository-layout","fromName":"Ben Walton","fromEmail":"bwalton@artsci.utoronto.ca","sentAt":"2011-08-20T02:43:07Z","receivedAt":"2011-08-20T02:43:07Z","isPatch":true,"sender":{"key":"bdwalton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/396061?v=4"},"body":"This patch corrects a few grammar issues in gitrepository-layout.txt\nand also rewords a few sections for clarity.\n\nSigned-off-by: Ben Walton \n---\n Documentation/gitrepository-layout.txt | 46 +++++++++++++++----------------\n 1 files changed, 22 insertions(+), 24 deletions(-)\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex eb3d040..02a6167 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -23,32 +23,30 @@ objects::\n \tObject store associated with this repository. Usually\n \tan object store is self sufficient (i.e. all the objects\n \tthat are referred to by an object found in it are also\n-\tfound in it), but there are couple of ways to violate\n-\tit.\n+\tfound in it), but there are a few ways to violate it.\n +\n . You could populate the repository by running a commit walker\n-without `-a` option. Depending on which options are given, you\n+without `-a` option. Depending on the options given, you\n could have only commit objects without associated blobs and\n trees this way, for example. A repository with this kind of\n incomplete object store is not suitable to be published to the\n-outside world but sometimes useful for private repository.\n+outside world but is sometimes useful in a private repository.\n . You also could have an incomplete but locally usable repository\n-by cloning shallowly. See linkgit:git-clone[1].\n-. You can be using `objects/info/alternates` mechanism, or\n-`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'\n+by creating a shallow clone. See linkgit:git-clone[1].\n+. You could be using the `objects/info/alternates` or\n+`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'\n objects from other object stores. A repository with this kind\n of incomplete object store is not suitable to be published for\n-use with dumb transports but otherwise is OK as long as\n-`objects/info/alternates` points at the right object stores\n-it borrows from.\n+use with dumb transports but is otherwise OK as long as\n+`objects/info/alternates` points at the right object stores.\n \n objects/[0-9a-f][0-9a-f]::\n \tTraditionally, each object is stored in its own file.\n-\tThey are split into 256 subdirectories using the first\n-\ttwo letters from its object name to keep the number of\n-\tdirectory entries `objects` directory itself needs to\n-\thold. Objects found here are often called 'unpacked'\n-\t(or 'loose') objects.\n+\tThe objects are splayed over 256 subdirectories using\n+\tthe first two characters of the sha1 object name to\n+\tkeep the number of directory entries in `objects`\n+\titself to a manageable number. Objects found\n+\there are often called 'unpacked' (or 'loose') objects.\n \n objects/pack::\n \tPacks (files that store many object in compressed form,\n@@ -85,7 +83,7 @@ objects/info/http-alternates::\n \n refs::\n \tReferences are stored in subdirectories of this\n-\tdirectory. The 'git prune' command knows to keep\n+\tdirectory. The 'git prune' command knows to preserve\n \tobjects reachable from refs found in this directory and\n \tits subdirectories.\n \n@@ -120,15 +118,15 @@ HEAD::\n HEAD can also record a specific commit directly, instead of\n being a symref to point at the current branch. Such a state\n is often called 'detached HEAD', and almost all commands work\n-identically as normal. See linkgit:git-checkout[1] for\n+as they normally would. See linkgit:git-checkout[1] for\n details.\n \n branches::\n \tA slightly deprecated way to store shorthands to be used\n-\tto specify URL to 'git fetch', 'git pull' and 'git push'\n-\tcommands is to store a file in `branches/` and\n-\tgive 'name' to these commands in place of 'repository'\n-\targument.\n+\tto specify a URL to 'git fetch', 'git pull' and 'git push'.\n+\tA file can be stored as `branches/` and then\n+\t'name' can be givent to these commands in place of\n+\t'repository' argument.\n \n hooks::\n \tHooks are customization scripts used by various git\n@@ -173,9 +171,9 @@ info/exclude::\n \tat it. See also: linkgit:gitignore[5].\n \n remotes::\n-\tStores shorthands to be used to give URL and default\n-\trefnames to interact with remote repository to\n-\t'git fetch', 'git pull' and 'git push' commands.\n+\tStores shorthands for URL and default refnames for use\n+\twhen interacting with remote repositories via 'git fetch',\n+\t'git pull' and 'git push' commands.\n \n logs::\n \tRecords of changes made to refs are stored in this\n-- \n1.7.4.1\n"},{"id":"174030","messageId":"7vk4a5wc67.fsf@alter.siamese.dyndns.org","threadId":"28172","inReplyTo":"1313808187-1666-1-git-send-email-bwalton@artsci.utoronto.ca","subject":"Re: [PATCH] Grammar and wording fixes in gitrepository-layout","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-08-22T18:09:36Z","receivedAt":"2011-08-22T18:09:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ben Walton writes:\n\n> This patch corrects a few grammar issues in gitrepository-layout.txt\n> and also rewords a few sections for clarity.\n\nThanks, Ben.\n\nI notice that there are issues, not introduced with your patch, that we\nmay want to address further, though.\n\n> Signed-off-by: Ben Walton \n> ---\n> Documentation/gitrepository-layout.txt | 46 +++++++++++++++----------------\n> 1 files changed, 22 insertions(+), 24 deletions(-)\n>\n> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\n> index eb3d040..02a6167 100644\n> --- a/Documentation/gitrepository-layout.txt\n> +++ b/Documentation/gitrepository-layout.txt\n> @@ -23,32 +23,30 @@ objects::\n> \tObject store associated with this repository. Usually\n> \tan object store is self sufficient (i.e. all the objects\n> \tthat are referred to by an object found in it are also\n> -\tfound in it), but there are couple of ways to violate\n> -\tit.\n> +\tfound in it), but there are a few ways to violate it.\n> +\n> . You could populate the repository by running a commit walker\n> -without `-a` option. Depending on which options are given, you\n> +without `-a` option. Depending on the options given, you\n> could have only commit objects without associated blobs and\n> trees this way, for example. A repository with this kind of\n> incomplete object store is not suitable to be published to the\n> -outside world but sometimes useful for private repository.\n> +outside world but is sometimes useful in a private repository.\n\nHere \"a commit walker\" refers to the \"http-fetch\" dumb http walker, which\nwas unclear and confusing even to me, but more importantly, I wonder if we\neven want to condone the use of it to break the repository integrity in\nsuch a way that other tools in git toolset do not even give support.\n\nOther items in this list, namely shallow-clone and borrowing objects from\nalternates, are supported configurations in which .git/objects do _not_\nhave all the objects, but \"http-fetch without -a\" that pulls in commits\nwithout their associated trees and blobs do not even pass \"fsck\" and worse\nyet cannot be \"fixed\" later by fetching missing objects on top, like\na shallow clone does by allowing deepening it later.\n\nPerhaps we should deprecate http-fetch without -a and drop this item from\nthe list?\n\n> +. You could be using the `objects/info/alternates` or\n> +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'\n> objects from other object stores. A repository with this kind\n> of incomplete object store is not suitable to be published for\n> -use with dumb transports but otherwise is OK as long as\n> -`objects/info/alternates` points at the right object stores\n> -it borrows from.\n> +use with dumb transports but is otherwise OK as long as\n> +`objects/info/alternates` points at the right object stores.\n\nThe last three words in the original are meant to clarify and define what\n\"the right object stores\" are. Was there a compelling reason to drop them?\n\n> objects/[0-9a-f][0-9a-f]::\n> \tTraditionally, each object is stored in its own file.\n\nI would suggest further rewording this to something like:\n\n\tA newly created object is stored in its own file.\n\n> @@ -120,15 +118,15 @@ HEAD::\n> HEAD can also record a specific commit directly, instead of\n> being a symref to point at the current branch. Such a state\n> is often called 'detached HEAD', and almost all commands work\n> -identically as normal. See linkgit:git-checkout[1] for\n> +as they normally would. See linkgit:git-checkout[1] for\n> details.\n\nWe may want to reword the sentence that begins with \"almost all commands\"\nfurther. In the early days after detached HEAD support was introduced, we\nmay have left cases where the result was _undefined_ for commands that\nwould not make sense unless you are on a branch, but by now what we have\nshould behave sensibly by either erroring out when the operation does not\nmake sense unless you are on a real branch, or doing something useful.\n\n> branches::\n> \tA slightly deprecated way to store shorthands to be used\n> -\tto specify URL to 'git fetch', 'git pull' and 'git push'\n> -\tcommands is to store a file in `branches/` and\n> -\tgive 'name' to these commands in place of 'repository'\n> -\targument.\n> +\tto specify a URL to 'git fetch', 'git pull' and 'git push'.\n> +\tA file can be stored as `branches/` and then\n> +\t'name' can be givent to these commands in place of\n\ns/givent to/given to/\n\n> +\t'repository' argument.\n\nWe would at least need \"See linkgit:...\" to say what is expected in this\nfile and how it is used (the information is in urls-remotes.txt but that\nis not a top-level file, so it needs to refer to git-fetch and git-push\ninstead).\n\n> @@ -173,9 +171,9 @@ info/exclude::\n> \tat it. See also: linkgit:gitignore[5].\n> \n> remotes::\n> -\tStores shorthands to be used to give URL and default\n> -\trefnames to interact with remote repository to\n> -\t'git fetch', 'git pull' and 'git push' commands.\n> +\tStores shorthands for URL and default refnames for use\n> +\twhen interacting with remote repositories via 'git fetch',\n> +\t'git pull' and 'git push' commands.\n\nLikewise.\n\nAlso I would personally consider \"branches\" and \"remotes\" both \"slightly\ndeprecated\". \"git init\", \"git clone\", and \"git remote\" stopped populating\nthese long time ago.\n"},{"id":"174059","messageId":"1314057078-sup-8464@pinkfloyd.chass.utoronto.ca","threadId":"28172","inReplyTo":"7vk4a5wc67.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Grammar and wording fixes in gitrepository-layout","fromName":"Ben Walton","fromEmail":"bwalton@artsci.utoronto.ca","sentAt":"2011-08-23T00:43:13Z","receivedAt":"2011-08-23T00:43:13Z","isPatch":true,"sender":{"key":"bdwalton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/396061?v=4"},"body":"Excerpts from Junio C Hamano's message of Mon Aug 22 14:09:36 -0400 2011:\n\nHi Junio,\n\n> Perhaps we should deprecate http-fetch without -a and drop this item\n> from the list?\n\nI don't know much about http-fetch as I've never touched it directly.\nIt doesn't sound like a good idea to allow creating a broken object\nstore though. I'll send a patch shortly that adds the deprecation\nwarning if -a isn't given.\n\n> > +. You could be using the `objects/info/alternates` or\n> > +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'\n> > objects from other object stores. A repository with this kind\n> > of incomplete object store is not suitable to be published for\n> > -use with dumb transports but otherwise is OK as long as\n> > -`objects/info/alternates` points at the right object stores\n> > -it borrows from.\n> > +use with dumb transports but is otherwise OK as long as\n> > +`objects/info/alternates` points at the right object stores.\n> \n> The last three words in the original are meant to clarify and define\n> what \"the right object stores\" are. Was there a compelling reason to\n> drop them?\n\nThe only reason I dropped them is that I didn't feel they were helping\nto clarify the meaning. The wording was a bit awkward and I thought\n'it borrows from' was part the problem. I see what you're saying\nthough and think that the following wording is better:\n\nuse with dumb transports but is otherwise OK as long as\n`objects/info/alternates` points to object stores containing the\nmissing objects.\n\n> > objects/[0-9a-f][0-9a-f]::\n> > Traditionally, each object is stored in its own file.\n> \n> I would suggest further rewording this to something like:\n> \n> A newly created object is stored in its own file.\n\nAgreed. This is much better.\n\n> > @@ -120,15 +118,15 @@ HEAD::\n> > HEAD can also record a specific commit directly, instead of\n> > being a symref to point at the current branch. Such a state\n> > is often called 'detached HEAD', and almost all commands work\n> > -identically as normal. See linkgit:git-checkout[1] for\n> > +as they normally would. See linkgit:git-checkout[1] for\n> > details.\n> \n> We may want to reword the sentence that begins with \"almost all commands\"\n> further. In the early days after detached HEAD support was introduced, we\n> may have left cases where the result was _undefined_ for commands that\n> would not make sense unless you are on a branch, but by now what we have\n> should behave sensibly by either erroring out when the operation does not\n> make sense unless you are on a real branch, or doing something\n> useful.\n\nOk, how about a full stop after 'detached HEAD' and then the link to\ngit-checkout?\n\n> > branches::\n> > A slightly deprecated way to store shorthands to be used\n> > - to specify URL to 'git fetch', 'git pull' and 'git push'\n> > - commands is to store a file in `branches/` and\n> > - give 'name' to these commands in place of 'repository'\n> > - argument.\n> > + to specify a URL to 'git fetch', 'git pull' and 'git push'.\n> > + A file can be stored as `branches/` and then\n> > + 'name' can be givent to these commands in place of\n> \n> s/givent to/given to/\n> \n> > + 'repository' argument.\n> \n> We would at least need \"See linkgit:...\" to say what is expected in this\n> file and how it is used (the information is in urls-remotes.txt but that\n> is not a top-level file, so it needs to refer to git-fetch and git-push\n> instead).\n\nNoted. The updated patch will address this.\n\n> > @@ -173,9 +171,9 @@ info/exclude::\n> > at it. See also: linkgit:gitignore[5].\n> > \n> > remotes::\n> > - Stores shorthands to be used to give URL and default\n> > - refnames to interact with remote repository to\n> > - 'git fetch', 'git pull' and 'git push' commands.\n> > + Stores shorthands for URL and default refnames for use\n> > + when interacting with remote repositories via 'git fetch',\n> > + 'git pull' and 'git push' commands.\n> \n> Likewise.\n> \n> Also I would personally consider \"branches\" and \"remotes\" both \"slightly\n> deprecated\". \"git init\", \"git clone\", and \"git remote\" stopped populating\n> these long time ago.\n\nOk, I've added the note about this being legacy to both of the\nsections in question.\n\nUpdated patch to follow shortly.\n\nThanks\n-Ben\n--\nBen Walton\nSystems Programmer - CHASS\nUniversity of Toronto\nC:416.407.5610 | W:416.978.4302\n"},{"id":"174060","messageId":"1314060519-24035-1-git-send-email-bwalton@artsci.utoronto.ca","threadId":"28172","inReplyTo":"7vk4a5wc67.fsf@alter.siamese.dyndns.org","subject":"[PATCH] Documentation: Grammar correction, wording fixes and cleanup","fromName":"Ben Walton","fromEmail":"bwalton@artsci.utoronto.ca","sentAt":"2011-08-23T00:48:39Z","receivedAt":"2011-08-23T00:48:39Z","isPatch":true,"sender":{"key":"bdwalton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/396061?v=4"},"body":"Correct a few grammar issues in gitrepository-layout.txt and also\nrewords a few sections for clarity.\n\nRemove references to using http-fetch without -a to create a broken\nrepository.\n\nMark a few areas of the repository structure as legacy.\n\nSigned-off-by: Ben Walton \n---\n Documentation/gitrepository-layout.txt | 60 +++++++++++++++-----------------\n 1 files changed, 28 insertions(+), 32 deletions(-)\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex eb3d040..5023ea9 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -23,32 +23,25 @@ objects::\n \tObject store associated with this repository. Usually\n \tan object store is self sufficient (i.e. all the objects\n \tthat are referred to by an object found in it are also\n-\tfound in it), but there are couple of ways to violate\n-\tit.\n+\tfound in it), but there are a few ways to violate it.\n +\n-. You could populate the repository by running a commit walker\n-without `-a` option. Depending on which options are given, you\n-could have only commit objects without associated blobs and\n-trees this way, for example. A repository with this kind of\n-incomplete object store is not suitable to be published to the\n-outside world but sometimes useful for private repository.\n-. You also could have an incomplete but locally usable repository\n-by cloning shallowly. See linkgit:git-clone[1].\n-. You can be using `objects/info/alternates` mechanism, or\n-`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'\n+. You could have an incomplete but locally usable repository\n+by creating a shallow clone. See linkgit:git-clone[1].\n+. You could be using the `objects/info/alternates` or\n+`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'\n objects from other object stores. A repository with this kind\n of incomplete object store is not suitable to be published for\n-use with dumb transports but otherwise is OK as long as\n-`objects/info/alternates` points at the right object stores\n-it borrows from.\n+use with dumb transports but is otherwise OK as long as\n+`objects/info/alternates` points to object stores containing the\n+missing objects.\n \n objects/[0-9a-f][0-9a-f]::\n-\tTraditionally, each object is stored in its own file.\n-\tThey are split into 256 subdirectories using the first\n-\ttwo letters from its object name to keep the number of\n-\tdirectory entries `objects` directory itself needs to\n-\thold. Objects found here are often called 'unpacked'\n-\t(or 'loose') objects.\n+\tA newly created object is stored in its own file.\n+\tThe objects are splayed over 256 subdirectories using\n+\tthe first two characters of the sha1 object name to\n+\tkeep the number of directory entries in `objects`\n+\titself to a manageable number. Objects found\n+\there are often called 'unpacked' (or 'loose') objects.\n \n objects/pack::\n \tPacks (files that store many object in compressed form,\n@@ -85,7 +78,7 @@ objects/info/http-alternates::\n \n refs::\n \tReferences are stored in subdirectories of this\n-\tdirectory. The 'git prune' command knows to keep\n+\tdirectory. The 'git prune' command knows to preserve\n \tobjects reachable from refs found in this directory and\n \tits subdirectories.\n \n@@ -119,16 +112,17 @@ HEAD::\n +\n HEAD can also record a specific commit directly, instead of\n being a symref to point at the current branch. Such a state\n-is often called 'detached HEAD', and almost all commands work\n-identically as normal. See linkgit:git-checkout[1] for\n-details.\n+is often called 'detached HEAD.' See linkgit:git-checkout[1]\n+for details.\n \n branches::\n \tA slightly deprecated way to store shorthands to be used\n-\tto specify URL to 'git fetch', 'git pull' and 'git push'\n-\tcommands is to store a file in `branches/` and\n-\tgive 'name' to these commands in place of 'repository'\n-\targument.\n+\tto specify a URL to 'git fetch', 'git pull' and 'git push'.\n+\tA file can be stored as `branches/` and then\n+\t'name' can be given to these commands in place of\n+\t'repository' argument. See the REMOTES section in\n+\tlinkgit:git-fetch[1] for details. This mechanism is legacy\n+\tand not likely to be found in modern repositories.\n \n hooks::\n \tHooks are customization scripts used by various git\n@@ -173,9 +167,11 @@ info/exclude::\n \tat it. See also: linkgit:gitignore[5].\n \n remotes::\n-\tStores shorthands to be used to give URL and default\n-\trefnames to interact with remote repository to\n-\t'git fetch', 'git pull' and 'git push' commands.\n+\tStores shorthands for URL and default refnames for use\n+\twhen interacting with remote repositories via 'git fetch',\n+\t'git pull' and 'git push' commands. See the REMOTES section\n+\tin linkgit:git-fetch[1] for details. This mechanism is legacy\n+\tand not likely to be found in modern repositories.\n \n logs::\n \tRecords of changes made to refs are stored in this\n-- \n1.7.4.1\n"},{"id":"174123","messageId":"1314134106.5186.64.camel@drew-northup.unet.maine.edu","threadId":"28172","inReplyTo":"1314060519-24035-1-git-send-email-bwalton@artsci.utoronto.ca","subject":"Re: [PATCH] Documentation: Grammar correction, wording fixes and cleanup","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2011-08-23T21:15:06Z","receivedAt":"2011-08-23T21:15:06Z","isPatch":true,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Mon, 2011-08-22 at 20:48 -0400, Ben Walton wrote:\n\n> +. You could be using the `objects/info/alternates` or\n> +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'\n> objects from other object stores. A repository with this kind\n> of incomplete object store is not suitable to be published for\n> -use with dumb transports but otherwise is OK as long as\n> -`objects/info/alternates` points at the right object stores\n> -it borrows from.\n> +use with dumb transports but is otherwise OK as long as\n> +`objects/info/alternates` points to object stores containing the\n> +missing objects.\n\nUmm, I'm not prepared to call this an improvement. The objects aren't\n_missing_, they just aren't present in the most immediate object store.\nI'm a minimalist when it comes to this sort of edit and would have just\nexcised the word \"right\" from the awkward segment.\n\n-- \n-Drew Northup\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"174125","messageId":"7vliujre93.fsf@alter.siamese.dyndns.org","threadId":"28172","inReplyTo":"1314134106.5186.64.camel@drew-northup.unet.maine.edu","subject":"Re: [PATCH] Documentation: Grammar correction, wording fixes and cleanup","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-08-23T21:48:08Z","receivedAt":"2011-08-23T21:48:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Drew Northup writes:\n\n> On Mon, 2011-08-22 at 20:48 -0400, Ben Walton wrote:\n>\n>> +. You could be using the `objects/info/alternates` or\n>> +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'\n>> objects from other object stores. A repository with this kind\n>> of incomplete object store is not suitable to be published for\n>> -use with dumb transports but otherwise is OK as long as\n>> -`objects/info/alternates` points at the right object stores\n>> -it borrows from.\n>> +use with dumb transports but is otherwise OK as long as\n>> +`objects/info/alternates` points to object stores containing the\n>> +missing objects.\n>\n> Umm, I'm not prepared to call this an improvement. The objects aren't\n> _missing_, they just aren't present in the most immediate object store.\n> I'm a minimalist when it comes to this sort of edit and would have just\n> excised the word \"right\" from the awkward segment.\n\nYeah, \"points at the object stores it borrows objects from\" sounds\nreadable and technically correct.\n"},{"id":"174134","messageId":"1314145955-23444-1-git-send-email-bwalton@artsci.utoronto.ca","threadId":"28172","inReplyTo":"7vliujre93.fsf@alter.siamese.dyndns.org","subject":"[PATCH] Documentation: Grammar correction, wording fixes and cleanup","fromName":"Ben Walton","fromEmail":"bwalton@artsci.utoronto.ca","sentAt":"2011-08-24T00:32:35Z","receivedAt":"2011-08-24T00:32:35Z","isPatch":true,"sender":{"key":"bdwalton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/396061?v=4"},"body":"Correct a few grammar issues in gitrepository-layout.txt and also\nrewords a few sections for clarity.\n\nRemove references to using http-fetch without -a to create a broken\nrepository.\n\nMark a few areas of the repository structure as legacy.\n\nSigned-off-by: Ben Walton \n---\n Documentation/gitrepository-layout.txt | 58 +++++++++++++++-----------------\n 1 files changed, 27 insertions(+), 31 deletions(-)\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex eb3d040..5c891f1 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -23,32 +23,25 @@ objects::\n \tObject store associated with this repository. Usually\n \tan object store is self sufficient (i.e. all the objects\n \tthat are referred to by an object found in it are also\n-\tfound in it), but there are couple of ways to violate\n-\tit.\n+\tfound in it), but there are a few ways to violate it.\n +\n-. You could populate the repository by running a commit walker\n-without `-a` option. Depending on which options are given, you\n-could have only commit objects without associated blobs and\n-trees this way, for example. A repository with this kind of\n-incomplete object store is not suitable to be published to the\n-outside world but sometimes useful for private repository.\n-. You also could have an incomplete but locally usable repository\n-by cloning shallowly. See linkgit:git-clone[1].\n-. You can be using `objects/info/alternates` mechanism, or\n-`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'\n+. You could have an incomplete but locally usable repository\n+by creating a shallow clone. See linkgit:git-clone[1].\n+. You could be using the `objects/info/alternates` or\n+`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'\n objects from other object stores. A repository with this kind\n of incomplete object store is not suitable to be published for\n use with dumb transports but otherwise is OK as long as\n-`objects/info/alternates` points at the right object stores\n-it borrows from.\n+`objects/info/alternates` points at the object stores it\n+borrows from.\n \n objects/[0-9a-f][0-9a-f]::\n-\tTraditionally, each object is stored in its own file.\n-\tThey are split into 256 subdirectories using the first\n-\ttwo letters from its object name to keep the number of\n-\tdirectory entries `objects` directory itself needs to\n-\thold. Objects found here are often called 'unpacked'\n-\t(or 'loose') objects.\n+\tA newly created object is stored in its own file.\n+\tThe objects are splayed over 256 subdirectories using\n+\tthe first two characters of the sha1 object name to\n+\tkeep the number of directory entries in `objects`\n+\titself to a manageable number. Objects found\n+\there are often called 'unpacked' (or 'loose') objects.\n \n objects/pack::\n \tPacks (files that store many object in compressed form,\n@@ -85,7 +78,7 @@ objects/info/http-alternates::\n \n refs::\n \tReferences are stored in subdirectories of this\n-\tdirectory. The 'git prune' command knows to keep\n+\tdirectory. The 'git prune' command knows to preserve\n \tobjects reachable from refs found in this directory and\n \tits subdirectories.\n \n@@ -119,16 +112,17 @@ HEAD::\n +\n HEAD can also record a specific commit directly, instead of\n being a symref to point at the current branch. Such a state\n-is often called 'detached HEAD', and almost all commands work\n-identically as normal. See linkgit:git-checkout[1] for\n-details.\n+is often called 'detached HEAD.' See linkgit:git-checkout[1]\n+for details.\n \n branches::\n \tA slightly deprecated way to store shorthands to be used\n-\tto specify URL to 'git fetch', 'git pull' and 'git push'\n-\tcommands is to store a file in `branches/` and\n-\tgive 'name' to these commands in place of 'repository'\n-\targument.\n+\tto specify a URL to 'git fetch', 'git pull' and 'git push'.\n+\tA file can be stored as `branches/` and then\n+\t'name' can be given to these commands in place of\n+\t'repository' argument. See the REMOTES section in\n+\tlinkgit:git-fetch[1] for details. This mechanism is legacy\n+\tand not likely to be found in modern repositories.\n \n hooks::\n \tHooks are customization scripts used by various git\n@@ -173,9 +167,11 @@ info/exclude::\n \tat it. See also: linkgit:gitignore[5].\n \n remotes::\n-\tStores shorthands to be used to give URL and default\n-\trefnames to interact with remote repository to\n-\t'git fetch', 'git pull' and 'git push' commands.\n+\tStores shorthands for URL and default refnames for use\n+\twhen interacting with remote repositories via 'git fetch',\n+\t'git pull' and 'git push' commands. See the REMOTES section\n+\tin linkgit:git-fetch[1] for details. This mechanism is legacy\n+\tand not likely to be found in modern repositories.\n \n logs::\n \tRecords of changes made to refs are stored in this\n-- \n1.7.4.1\n"},{"id":"174146","messageId":"1314185245.13674.7.camel@drew-northup.unet.maine.edu","threadId":"28172","inReplyTo":"1314145955-23444-1-git-send-email-bwalton@artsci.utoronto.ca","subject":"Re: [PATCH] Documentation: Grammar correction, wording fixes and cleanup","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2011-08-24T11:27:25Z","receivedAt":"2011-08-24T11:27:25Z","isPatch":true,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Tue, 2011-08-23 at 20:32 -0400, Ben Walton wrote:\n> Correct a few grammar issues in gitrepository-layout.txt and also\n> rewords a few sections for clarity.\n> \n> Remove references to using http-fetch without -a to create a broken\n> repository.\n> \n> Mark a few areas of the repository structure as legacy.\n> \n> Signed-off-by: Ben Walton \n> ---\n\nThanks Ben.\nLooks good to me. I haven't tried applying it yet (it might not apply to\nmy bowl of breakfast cereal so well, but then again I should not be\nsurprised).\n\n> Documentation/gitrepository-layout.txt | 58 +++++++++++++++-----------------\n> 1 files changed, 27 insertions(+), 31 deletions(-)\n> \n> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\n> index eb3d040..5c891f1 100644\n> --- a/Documentation/gitrepository-layout.txt\n> +++ b/Documentation/gitrepository-layout.txt\n> @@ -23,32 +23,25 @@ objects::\n> \tObject store associated with this repository. Usually\n> \tan object store is self sufficient (i.e. all the objects\n> \tthat are referred to by an object found in it are also\n> -\tfound in it), but there are couple of ways to violate\n> -\tit.\n> +\tfound in it), but there are a few ways to violate it.\n> +\n> -. You could populate the repository by running a commit walker\n> -without `-a` option. Depending on which options are given, you\n> -could have only commit objects without associated blobs and\n> -trees this way, for example. A repository with this kind of\n> -incomplete object store is not suitable to be published to the\n> -outside world but sometimes useful for private repository.\n> -. You also could have an incomplete but locally usable repository\n> -by cloning shallowly. See linkgit:git-clone[1].\n> -. You can be using `objects/info/alternates` mechanism, or\n> -`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'\n> +. You could have an incomplete but locally usable repository\n> +by creating a shallow clone. See linkgit:git-clone[1].\n> +. You could be using the `objects/info/alternates` or\n> +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'\n> objects from other object stores. A repository with this kind\n> of incomplete object store is not suitable to be published for\n> use with dumb transports but otherwise is OK as long as\n> -`objects/info/alternates` points at the right object stores\n> -it borrows from.\n> +`objects/info/alternates` points at the object stores it\n> +borrows from.\n> \n> objects/[0-9a-f][0-9a-f]::\n> -\tTraditionally, each object is stored in its own file.\n> -\tThey are split into 256 subdirectories using the first\n> -\ttwo letters from its object name to keep the number of\n> -\tdirectory entries `objects` directory itself needs to\n> -\thold. Objects found here are often called 'unpacked'\n> -\t(or 'loose') objects.\n> +\tA newly created object is stored in its own file.\n> +\tThe objects are splayed over 256 subdirectories using\n> +\tthe first two characters of the sha1 object name to\n> +\tkeep the number of directory entries in `objects`\n> +\titself to a manageable number. Objects found\n> +\there are often called 'unpacked' (or 'loose') objects.\n> \n> objects/pack::\n> \tPacks (files that store many object in compressed form,\n> @@ -85,7 +78,7 @@ objects/info/http-alternates::\n> \n> refs::\n> \tReferences are stored in subdirectories of this\n> -\tdirectory. The 'git prune' command knows to keep\n> +\tdirectory. The 'git prune' command knows to preserve\n> \tobjects reachable from refs found in this directory and\n> \tits subdirectories.\n> \n> @@ -119,16 +112,17 @@ HEAD::\n> +\n> HEAD can also record a specific commit directly, instead of\n> being a symref to point at the current branch. Such a state\n> -is often called 'detached HEAD', and almost all commands work\n> -identically as normal. See linkgit:git-checkout[1] for\n> -details.\n> +is often called 'detached HEAD.' See linkgit:git-checkout[1]\n> +for details.\n> \n> branches::\n> \tA slightly deprecated way to store shorthands to be used\n> -\tto specify URL to 'git fetch', 'git pull' and 'git push'\n> -\tcommands is to store a file in `branches/` and\n> -\tgive 'name' to these commands in place of 'repository'\n> -\targument.\n> +\tto specify a URL to 'git fetch', 'git pull' and 'git push'.\n> +\tA file can be stored as `branches/` and then\n> +\t'name' can be given to these commands in place of\n> +\t'repository' argument. See the REMOTES section in\n> +\tlinkgit:git-fetch[1] for details. This mechanism is legacy\n> +\tand not likely to be found in modern repositories.\n> \n> hooks::\n> \tHooks are customization scripts used by various git\n> @@ -173,9 +167,11 @@ info/exclude::\n> \tat it. See also: linkgit:gitignore[5].\n> \n> remotes::\n> -\tStores shorthands to be used to give URL and default\n> -\trefnames to interact with remote repository to\n> -\t'git fetch', 'git pull' and 'git push' commands.\n> +\tStores shorthands for URL and default refnames for use\n> +\twhen interacting with remote repositories via 'git fetch',\n> +\t'git pull' and 'git push' commands. See the REMOTES section\n> +\tin linkgit:git-fetch[1] for details. This mechanism is legacy\n> +\tand not likely to be found in modern repositories.\n> \n> logs::\n> \tRecords of changes made to refs are stored in this\n-- \n-Drew Northup\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"},{"id":"293760","messageId":"1314190358-sup-3659@pinkfloyd.chass.utoronto.ca","threadId":"28172","inReplyTo":"1314185245.13674.7.camel@drew-northup.unet.maine.edu","subject":"Re: [PATCH] Documentation: Grammar correction, wording fixes and cleanup","fromName":"Ben Walton","fromEmail":"bwalton@artsci.utoronto.ca","sentAt":"2011-08-24T12:54:10Z","receivedAt":"2011-08-24T12:54:10Z","isPatch":true,"sender":{"key":"bdwalton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/396061?v=4"},"body":"Excerpts from Drew Northup's message of Wed Aug 24 07:27:25 -0400 2011:\n\n> Thanks Ben.\n\nNo problem. Your fix was simpler and better. I missed the forest for\nthe trees on that change.\n\nThanks\n-Ben\n--\nBen Walton\nSystems Programmer - CHASS\nUniversity of Toronto\nC:416.407.5610 | W:416.978.4302\n"}]}