[PATCH] config: correct and clarify core.*compression documentation

[PATCH] config: correct and clarify core.*compression documentation

[Brian Downing]

* core.loosecompression stated that the default was "0 (best speed)",
  when in fact 0 is "no compression", and the default is Z_BEST_SPEED,
  which is 1.

* Explain that the default of core.compression is -1, zlib default, and
  add a quote from zlib.h explaining what that actually means.
---
  applies to 'maint'; unfortunately I just noticed 1.5.3.6 went out.

 Documentation/config.txt |    5 ++++-
 1 files changed, 4 insertions(+), 1 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7ee97df..d62a72b 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -226,13 +226,16 @@ core.compression::
 	An integer -1..9, indicating a default compression level.
 	-1 is the zlib default. 0 means no compression,
 	and 1..9 are various speed/size tradeoffs, 9 being slowest.
+	If not set, defaults to -1 (zlib default), which is "a default
+	compromise between speed and compression (currently equivalent
+	to level 6)."
 
 core.loosecompression::
 	An integer -1..9, indicating the compression level for objects that
 	are not in a pack file. -1 is the zlib default. 0 means no
 	compression, and 1..9 are various speed/size tradeoffs, 9 being
 	slowest.  If not set,  defaults to core.compression.  If that is
-	not set,  defaults to 0 (best speed).
+	not set,  defaults to 1 (best speed).
 
 core.packedGitWindowSize::
 	Number of bytes of a pack file to map into memory in a
-- 
1.5.3.5.1824.g5f389

Re: [PATCH] config: correct and clarify core.*compression documentation

[Nicolas Pitre]

On Mon, 19 Nov 2007, Brian Downing wrote:

> * core.loosecompression stated that the default was "0 (best speed)",
>   when in fact 0 is "no compression", and the default is Z_BEST_SPEED,
>   which is 1.

Right.

> * Explain that the default of core.compression is -1, zlib default, and
>   add a quote from zlib.h explaining what that actually means.

No, this is wrong.  core.compression has no default.  It is meaningful 
only when an explicit value is configured.


Nicolas

Re: [PATCH] config: correct and clarify core.*compression documentation

[Brian Downing]

On Mon, Nov 19, 2007 at 10:51:31AM -0500, Nicolas Pitre wrote:
> > * Explain that the default of core.compression is -1, zlib default, and
> >   add a quote from zlib.h explaining what that actually means.
> 
> No, this is wrong.  core.compression has no default.  It is meaningful 
> only when an explicit value is configured.

Would you prefer this?

       If not set, packs will be compressed to the zlib default level,
       which is "a default compromise between speed and compression
       (currently equivalent to level 6)."

I'm trying to make it reassuring as to the fact that, "yes, packs are
compressed plenty, you really don't need to mess with this unless you
want to."  As it stands I could see the potential confusion that no
(or poor) compression will occur in packs unless this is set.

-bcd

Re: [PATCH] config: correct and clarify core.*compression documentation

[Nicolas Pitre]

On Mon, 19 Nov 2007, Brian Downing wrote:

> On Mon, Nov 19, 2007 at 10:51:31AM -0500, Nicolas Pitre wrote:
> > > * Explain that the default of core.compression is -1, zlib default, and
> > >   add a quote from zlib.h explaining what that actually means.
> > 
> > No, this is wrong.  core.compression has no default.  It is meaningful 
> > only when an explicit value is configured.
> 
> Would you prefer this?
> 
>        If not set, packs will be compressed to the zlib default level,
>        which is "a default compromise between speed and compression
>        (currently equivalent to level 6)."

This is still rather incorrect.  If you want to be thorough, you should 
say that this setting provides a global default for pack.compression and 
core.loosecompression when those settings are not set.  Otherwise 
pack.compression and core.loosecompression have a default of their own 
when neither is set.


Nicolas

Re: [PATCH] config: correct and clarify core.*compression documentation

[Brian Downing]

On Mon, Nov 19, 2007 at 11:43:56AM -0500, Nicolas Pitre wrote:
> On Mon, 19 Nov 2007, Brian Downing wrote:
> > On Mon, Nov 19, 2007 at 10:51:31AM -0500, Nicolas Pitre wrote:
> > > > * Explain that the default of core.compression is -1, zlib default, and
> > > >   add a quote from zlib.h explaining what that actually means.
> > > 
> > > No, this is wrong.  core.compression has no default.  It is meaningful 
> > > only when an explicit value is configured.
> > 
> > Would you prefer this?
> > 
> >        If not set, packs will be compressed to the zlib default level,
> >        which is "a default compromise between speed and compression
> >        (currently equivalent to level 6)."
> 
> This is still rather incorrect.  If you want to be thorough, you should 
> say that this setting provides a global default for pack.compression and 
> core.loosecompression when those settings are not set.  Otherwise 
> pack.compression and core.loosecompression have a default of their own 
> when neither is set.

Okay, thanks.  (See, I didn't know this either!  :)  I'll try to work
with that...

-bcd

[PATCH 1/2] config: correct core.loosecompression documentation

[Brian Downing]

* core.loosecompression stated that the default was "0 (best speed)",
  when in fact 0 is "no compression", and the default is Z_BEST_SPEED,
  which is 1.

Signed-off-by: Brian Downing <bdowning@lavos.net>
---
 Documentation/config.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7ee97df..9565652 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -232,7 +232,7 @@ core.loosecompression::
 	are not in a pack file. -1 is the zlib default. 0 means no
 	compression, and 1..9 are various speed/size tradeoffs, 9 being
 	slowest.  If not set,  defaults to core.compression.  If that is
-	not set,  defaults to 0 (best speed).
+	not set,  defaults to 1 (best speed).
 
 core.packedGitWindowSize::
 	Number of bytes of a pack file to map into memory in a
-- 
1.5.3.5.1824.g5f389

[PATCH 2/2] config: clarify compression defaults

[Brian Downing]

* Clarify that core.compression provides a system-wide default to
  other compression parameters.

* Explain that the default for pack.compression, -1, is "a default
  compromise between speed and compression (currently equivalent
  to level 6)" according to zlib.h.

Signed-off-by: Brian Downing <bdowning@lavos.net>
---
 Documentation/config.txt |    6 +++++-
 1 files changed, 5 insertions(+), 1 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 9565652..5d1eb5d 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -226,6 +226,8 @@ core.compression::
 	An integer -1..9, indicating a default compression level.
 	-1 is the zlib default. 0 means no compression,
 	and 1..9 are various speed/size tradeoffs, 9 being slowest.
+	If set, this provides a default to other compression variables, 
+	such as 'core.loosecompression' and 'pack.compression'.
 
 core.loosecompression::
 	An integer -1..9, indicating the compression level for objects that
@@ -622,7 +624,9 @@ pack.compression::
 	in a pack file. -1 is the zlib default. 0 means no
 	compression, and 1..9 are various speed/size tradeoffs, 9 being
 	slowest.  If not set,  defaults to core.compression.  If that is
-	not set,  defaults to -1.
+	not set,  defaults to -1, the zlib default, which is "a default
+	compromise between speed and compression (currently equivalent 
+	to level 6)."
 
 pack.deltaCacheSize::
 	The maximum memory in bytes used for caching deltas in
-- 
1.5.3.5.1824.g5f389

Re: [PATCH 2/2] config: clarify compression defaults

[Nicolas Pitre]

On Mon, 19 Nov 2007, Brian Downing wrote:

> * Clarify that core.compression provides a system-wide default to
>   other compression parameters.
> 
> * Explain that the default for pack.compression, -1, is "a default
>   compromise between speed and compression (currently equivalent
>   to level 6)" according to zlib.h.
> 
> Signed-off-by: Brian Downing <bdowning@lavos.net>

Looks fine to me.


Nicolas