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

["Shawn O. Pearce" <spearce@spearce.org>]

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.