[PATCH 2/2] Documentation/git-gc: improve description of --auto

[PATCH 2/2] Documentation/git-gc: improve description of --auto

[Jeff King]

This patch tries to make the description of --auto a little
more clear for new users, especially those referred by the
"git-gc --auto" notification message.

It also cleans up some grammatical errors and typos in the
original description, as well as rewording for clarity.

Signed-off-by: Jeff King <peff@peff.net>
---
I started by just trying to fix a couple of grammar issues, but it
seemed quite awkward, and somehow this came out. I think it reads better
than the original, but I'm open to comment.

It is a little bit odd that there is so much low-level detail in the
'--auto' description versus the rest of the page. But I think it reads
OK. Also note that the previous incarnation (and my changes) use the
`foo` form to monospace arguments, while the rest of the page uses 'foo'
(which actually means emphasis). I think the former is more correct, but
asciidoc renders the latter much more pleasantly in manpages. I will see
if I can tweak asciidoc to make this look better.

 Documentation/git-gc.txt |   29 +++++++++++++++++------------
 1 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
index 83843a5..872056e 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.txt
@@ -45,18 +45,23 @@ OPTIONS
 	few hundred changesets or so.
 
 --auto::
-	With this option, `git gc` checks if there are too many
-	loose objects in the repository and runs
-	gitlink:git-repack[1] with `-d -l` option to pack them.
-	The threshold for loose objects is set with `gc.auto` configuration
-	variable, and can be disabled by setting it to 0.  Some
-	Porcelain commands use this after they perform operation
-	that could create many loose objects automatically.
-	Additionally, when there are too many packs are present,
-	they are consolidated into one larger pack by running
-	the `git-repack` command with `-A` option.  The
-	threshold for number of packs is set with
-	`gc.autopacklimit` configuration variable.
+	With this option, `git gc` checks whether any housekeeping is
+	required; if not, it exits without performing any work.
+	Some git commands run `git gc --auto` after performing
+	operations that could create many loose objects.
++
+Housekeeping is required if there are too many loose objects or
+too many packs in the repository. If the number of loose objects
+exceeds the value of the `gc.auto` configuration variable, then
+all loose objects are combined into a single pack using
+`git-repack -d -l`.  Setting the value of `gc.auto` to 0
+disables automatic packing of loose objects.
++
+If the number of packs exceeds the value of `gc.autopacklimit`,
+then existing packs (except those marked with a `.keep` file)
+are consolidated into a single pack by using the `-A` option of
+`git-repack`. Setting `gc.autopacklimit` to 0 disables
+automatic consolidation of packs.
 
 Configuration
 -------------
-- 
1.5.3.4.1249.g895be-dirty

Re: [PATCH 2/2] Documentation/git-gc: improve description of --auto

[Shawn O. Pearce]

Jeff King <peff@peff.net> wrote:
> It is a little bit odd that there is so much low-level detail in the
> '--auto' description versus the rest of the page. But I think it reads
> OK. Also note that the previous incarnation (and my changes) use the
> `foo` form to monospace arguments, while the rest of the page uses 'foo'
> (which actually means emphasis). I think the former is more correct, but
> asciidoc renders the latter much more pleasantly in manpages. I will see
> if I can tweak asciidoc to make this look better.

I like this a lot better than what was there before.  Nice work.
I have no real opinion on the asciidoc syntax.

I personally prefer to read commands in the source as `foo` and
feel that asciidoc should just format it correctly for the backend.
If it isn't then we should try to work with the asciidoc folks to
get it right...

>  --auto::
> -	With this option, `git gc` checks if there are too many
> -	loose objects in the repository and runs
> -	gitlink:git-repack[1] with `-d -l` option to pack them.
> -	The threshold for loose objects is set with `gc.auto` configuration
> -	variable, and can be disabled by setting it to 0.  Some
> -	Porcelain commands use this after they perform operation
> -	that could create many loose objects automatically.
> -	Additionally, when there are too many packs are present,
> -	they are consolidated into one larger pack by running
> -	the `git-repack` command with `-A` option.  The
> -	threshold for number of packs is set with
> -	`gc.autopacklimit` configuration variable.
> +	With this option, `git gc` checks whether any housekeeping is
> +	required; if not, it exits without performing any work.
> +	Some git commands run `git gc --auto` after performing
> +	operations that could create many loose objects.
> ++
> +Housekeeping is required if there are too many loose objects or
> +too many packs in the repository. If the number of loose objects
> +exceeds the value of the `gc.auto` configuration variable, then
> +all loose objects are combined into a single pack using
> +`git-repack -d -l`.  Setting the value of `gc.auto` to 0
> +disables automatic packing of loose objects.
> ++
> +If the number of packs exceeds the value of `gc.autopacklimit`,
> +then existing packs (except those marked with a `.keep` file)
> +are consolidated into a single pack by using the `-A` option of
> +`git-repack`. Setting `gc.autopacklimit` to 0 disables
> +automatic consolidation of packs.

-- 
Shawn.

Re: [PATCH 2/2] Documentation/git-gc: improve description of --auto

[Jeff King]

On Thu, Oct 18, 2007 at 10:29:09PM -0400, Shawn O. Pearce wrote:

> I personally prefer to read commands in the source as `foo` and
> feel that asciidoc should just format it correctly for the backend.
> If it isn't then we should try to work with the asciidoc folks to
> get it right...

I am hunting this down right now. asciidoc _does_ generate
XML <literal>foo</literal> for `foo`, but it looks like docbook is
throwing that away when converting to manpages. Hopefully there is an
easy tweak...

-Peff

Re: [PATCH 2/2] Documentation/git-gc: improve description of --auto

[Jeff King]

On Thu, Oct 18, 2007 at 10:38:50PM -0400, Jeff King wrote:

> I am hunting this down right now. asciidoc _does_ generate
> XML <literal>foo</literal> for `foo`, but it looks like docbook is
> throwing that away when converting to manpages. Hopefully there is an
> easy tweak...

Ugh. Looks like Junio came up with a solution to this in 524e5ffc
(although it was for literallayout sections, I think the same technique
could be applied). However, it had problems with docbook 1.69, and was
reverted in 63c21c49.

Julian Phillips added monospacing of listingblocks in 281a53bb, but that
technique is only applicable to asciidoc "blocks", which I think won't
work in this instance.

It really seems silly that docbook doesn't monospace <literal>s when
converting to manpages. Perhaps somebody who knows more about docbook
than I do can say more.

-Peff