Re: [PATCH] Documentation: update [section.subsection] to reflect what git does

[Jeff King <peff@peff.net>]

On Wed, Oct 12, 2011 at 05:52:06PM +0200, Carlos Martín Nieto wrote:

> -There is also a case insensitive alternative `[section.subsection]` syntax.
> -In this syntax, subsection names follow the same restrictions as for section
> -names.
> +There is also a deprecated `[section.subsection]` syntax. With this
> +syntax, the subsection name is converted to lower-case and is also
> +compared case sensitively. These subsection names follow the same
> +restrictions as section names.

Hmm. While technically more correct, I think it is a little more
confusing to read. The lower-case canonicalization thing is actually
used for the other case-insensitive parts, too. So maybe it makes sense
to describe that in detail, and then just note that
"[section.subsection]" uses the same mechanism.

The patch below does this, and then the original text in the section you
tweaked above hopefully makes more sense in the new context.

The explanation matches what we do now, but it did end up a bit longer
than I had hoped. We could make it a lot shorter by:

  1. Canonicalizing the section and key names that the caller gives to
     git-config.

  2. Not mentioning the "section.foo" syntax. We can't canonicalize the
     subsection in (1) because of this syntax. But we can at least gloss
     over the detail, and then maybe just mention it much later in the
     file format. Or even deprecate it.

-- >8 --
Subject: [PATCH] docs/config: explain case-insensitive matching

We generally think of key matching as case-insensitive, but
it's not exactly. It's about canonicalizing one side, and
comparing it byte-wise with the canonical key name given to
git-config.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-config.txt |   50 +++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 49 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index e7ecf5d..e92aee9 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -28,7 +28,7 @@ DESCRIPTION
 -----------
 You can query/set/replace/unset options with this command. The name is
 actually the section and the key separated by a dot, and the value will be
-escaped.
+escaped. See the section on name matching below.
 
 Multiple lines can be added to an option by using the '--add' option.
 If you want to update or unset an option which can occur on multiple
@@ -178,6 +178,54 @@ See also <<FILES>>.
 	Opens an editor to modify the specified config file; either
 	'--system', '--global', or repository (default).
 
+
+NAME MATCHING
+-------------
+
+Configuration key names are matched using an algorithm that allows for
+partial case sensitivity. Section and key names are read from the config
+files, canonicalized according to the rules below, and then compared
+case-sensitively with the input given to git-config. Therefore any
+callers to git-config should request the canonicalized version of the
+name. This typically means lowercasing the section and key names, and
+leaving the subsection (if any) intact. For example, ask for
+`git config core.eol`, not `git config CoRe.EOL`.
+
+The canonicalization rules are:
+
+1. Lowercase the section and key names.
+
+2. If a literal subsection (like `[section "foo"]`) is used, leave it
+   intact.
+
+3. If a non-literal subsection (like `[section.foo]`) is used, lowercase
+   the subsection.
+
+4. Concatenate the resulting section, subsection, and key, separated by
+   a dot ('.').
+
+For example, this configuration file:
+
+-----------------------------------------------
+[CORE]
+eol = true
+
+[branch "Foo"]
+REMOTE = origin
+
+[color.DIFF]
+new = blue
+-----------------------------------------------
+
+would yield the following three canonicalized names:
+
+-----------------------------------------------
+core.eol
+branch.Foo.remote
+color.diff.new
+-----------------------------------------------
+
+
 [[FILES]]
 FILES
 -----
-- 
1.7.7.rc2.21.gb9948