threads / patch / 10932

patchconfig: correct and clarify core.*compression documentation

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

## tl;dr

8 messages between Nov 19, 2007 and Nov 19, 2007. Diffs are folded; open one to read it.

replies: 7people: 2as markdown or json

Brian Downing· Nov 19, 2007, 15:28 UTC · lore
* 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(-)
Show changes to Documentation/config.txt +4 −1
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
Nicolas Pitre· Nov 19, 2007, 15:51 UTC · re: Brian Downing · lore

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

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
Brian Downing· Nov 19, 2007, 16:23 UTC · re: Nicolas Pitre · lore

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

On Mon, Nov 19, 2007 at 10:51:31AM -0500, Nicolas Pitre wrote:
Show 5 quoted lines
> > * 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
Nicolas Pitre· Nov 19, 2007, 16:43 UTC · re: Brian Downing · lore

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

On Mon, 19 Nov 2007, Brian Downing wrote:
Show 12 quoted lines
> 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
Brian Downing· Nov 19, 2007, 16:46 UTC · re: Nicolas Pitre · lore

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

On Mon, Nov 19, 2007 at 11:43:56AM -0500, Nicolas Pitre wrote:
Show 19 quoted lines
> 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
Brian Downing· Nov 19, 2007, 16:58 UTC · re: Nicolas Pitre · lore

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

* 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(-)
Show changes to Documentation/config.txt +1 −1
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
Brian Downing· Nov 19, 2007, 16:58 UTC · re: Brian Downing · lore

[PATCH 2/2] config: clarify compression defaults

* 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(-)
Show changes to Documentation/config.txt +5 −1
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
Nicolas Pitre· Nov 19, 2007, 17:30 UTC · re: Brian Downing · lore

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

On Mon, 19 Nov 2007, Brian Downing wrote:
Show 8 quoted lines
> * 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

← back to recent threads