Re: should config options be treated as case-sensitive?

[Junio C Hamano]

"Robert P. J. Day"  writes:

>> Unfortunately, that line of thinking leads us to madness, as you are
>> exhibiting the typical symptom of "my today's immediate itch is the
>> most important one in the world"-itis
>
>   fair enough, point taken.

FWIW, everybody suffers from it, including me.

I was trying to come up with an update, and here is an attempted
rewrite of the earlier section.  I am not sure if this is a good
direction to go in, but if so, we'd need to reduce the duplicated
info from the Syntax section that immediately follows.

 Documentation/config.txt | 22 +++---
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git i/Documentation/config.txt w/Documentation/config.txt
index 84e2891aed..5b79411b4b 100644
--- i/Documentation/config.txt
+++ w/Documentation/config.txt
@@ -9,13 +9,21 @@ fallback values for the `.git/config` file. The file 
`/etc/gitconfig`
 can be used to store a system-wide default configuration.
 
 The configuration variables are used by both the Git plumbing
-and the porcelains. The variables are divided into sections, wherein
-the fully qualified variable name of the variable itself is the last
-dot-separated segment and the section name is everything before the last
-dot. The variable names are case-insensitive, allow only alphanumeric
-characters and `-`, and must start with an alphabetic character.  Some
-variables may appear multiple times; we say then that the variable is
-multivalued.
+and the porcelains. The variables are divided into sections, and some
+sections can have subsections.  In a variable name that is fully
+spelled out, the part up to the first dot is the section, the part
+after the last dot is the variable.  If these two dots are not the
+same, what's in the middle is the subsection.
+
+The section and the variable names are case-insensitive, allow only
+alphanumeric characters and `-`, and must start with an alphabetic
+character.  Often multi-word variable names are spelled in CamelCase
+by convention for extra readability.
+
+Some variables may appear multiple times and their effects accumulate;
+we say then that such a variable is multivalued.  For other variables, 
+when they appear more than once, the last one takes effect.
+
 
 Syntax
 ~~

Re: should config options be treated as case-sensitive?

[Robert P. J. Day]

On Wed, 23 May 2018, Junio C Hamano wrote:

> "Robert P. J. Day"  writes:
>
> >> If the documention does not make it clear, then we have
> >> documentation bug ...
> >
> >   personally, i would add a short, really emphatic note at the top of
> > "man git-config" pointing this out -- i wouldn't require people to
> > read all the way down to "Syntax" to learn this. an example just like
> > the one you provide above would be perfect, with an extra line
> > pointing out that the documentation uses "camel case" for nothing more
> > than readability.
>
> Unfortunately, that line of thinking leads us to madness, as you are
> exhibiting the typical symptom of "my today's immediate itch is the
> most important one in the world"-itis.  Tomorrow you would start
> saying that we must have a short, really emphatic note at the top
> that says that the second level name can even have spaces, and on
> the day after that, you would instead have a note that says that you
> cannot use an underscore in the name, and continuing that line of
> thought will lead us to fill the top part of the documentation with
> 47 different short and emphatic sentences.  Let's not go there.

  fair enough, point taken.

rday

-- 


Robert P. J. Day Ottawa, Ontario, CANADA
  http://crashcourse.ca/dokuwiki

Twitter:   http://twitter.com/rpjday
LinkedIn:   http://ca.linkedin.com/in/rpjday

Re: should config options be treated as case-sensitive?

[Junio C Hamano]

"Robert P. J. Day"  writes:

>> If the documention does not make it clear, then we have
>> documentation bug ...
>
>   personally, i would add a short, really emphatic note at the top of
> "man git-config" pointing this out -- i wouldn't require people to
> read all the way down to "Syntax" to learn this. an example just like
> the one you provide above would be perfect, with an extra line
> pointing out that the documentation uses "camel case" for nothing more
> than readability.

Unfortunately, that line of thinking leads us to madness, as you are
exhibiting the typical symptom of "my today's immediate itch is the
most important one in the world"-itis.  Tomorrow you would start
saying that we must have a short, really emphatic note at the top
that says that the second level name can even have spaces, and on
the day after that, you would instead have a note that says that you
cannot use an underscore in the name, and continuing that line of
thought will lead us to fill the top part of the documentation with
47 different short and emphatic sentences.  Let's not go there.

Re: should config options be treated as case-sensitive?

[Robert P. J. Day]

On Wed, 23 May 2018, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason  writes:
>
> > The issues you note about the docs using foo.barbaz instead of
> > foo.barBaz should be fixed, but as noted in the "Syntax" section
> > of "git-config" we already document that the config keys are all
> > case-insensitive. We just like talking about them as foo.barBaz
> > because it makes for easier reading.
>
> The first and the last level of configuration variable names are
> case insensitive.
>
> I said "first and last", as there are variables with 2-level and
> 3-level names.  "foo.barBaz" is two-level and it is the same
> variable as "Foo.barbaz".  "remote.origin.url" is three-level, and
> it is the same variable as "Remote.origin.URL", but it is not the
> same variable as "remote.ORIGIN.url".
>
> If the documention does not make it clear, then we have
> documentation bug ...

  personally, i would add a short, really emphatic note at the top of
"man git-config" pointing this out -- i wouldn't require people to
read all the way down to "Syntax" to learn this. an example just like
the one you provide above would be perfect, with an extra line
pointing out that the documentation uses "camel case" for nothing more
than readability.

rday

-- 


Robert P. J. Day Ottawa, Ontario, CANADA
  http://crashcourse.ca/dokuwiki

Twitter:   http://twitter.com/rpjday
LinkedIn:   http://ca.linkedin.com/in/rpjday

Re: should config options be treated as case-sensitive?

[Junio C Hamano]

Ævar Arnfjörð Bjarmason  writes:

> The issues you note about the docs using foo.barbaz instead of
> foo.barBaz should be fixed, but as noted in the "Syntax" section of
> "git-config" we already document that the config keys are all
> case-insensitive. We just like talking about them as foo.barBaz because
> it makes for easier reading.

The first and the last level of configuration variable names are
case insensitive.

I said "first and last", as there are variables with 2-level and
3-level names.  "foo.barBaz" is two-level and it is the same
variable as "Foo.barbaz".  "remote.origin.url" is three-level, and
it is the same variable as "Remote.origin.URL", but it is not the
same variable as "remote.ORIGIN.url".

If the documention does not make it clear, then we have
documentation bug.  As you said, I think we are OK in the sense that
we do say a section or a variable name is icase and a subsection, if
exist, is case sensitive, but there might be a better way to convey
that fact without having the reader read the whole three paragraphs.

Re: should config options be treated as case-sensitive?

[Robert P. J. Day]

On Tue, 22 May 2018, Ævar Arnfjörð Bjarmason wrote:

>
> On Tue, May 22 2018, Robert P. J. Day wrote:
>
> >   in my wanderings, more oddities, such as this:
> >
> > $ grep -ir blankboundary *
> > builtin/blame.c:if (!strcmp(var, "blame.blankboundary")) {
> > Documentation/config.txt:blame.blankBoundary::
> > Documentation/blame-options.txt:be controlled via the 
> > `blame.blankboundary` config option.
> > Documentation/RelNotes/2.15.1.txt: * Description of 
> > blame.{showroot,blankboundary,showemail,date}
> > Documentation/RelNotes/2.16.0.txt: * Description of 
> > blame.{showroot,blankboundary,showemail,date}
> > $
> >
> > where you can see the single instance of "blankBoundary" in
> > Doc/config.txt (with the upper case 'B'), while the rest have no such
> > thing.
> >
> >   for fun, i checked another of blame's config settings, with similar
> > results:
> >
> > builtin/blame.c:if (!strcmp(var, "blame.showemail")) {
> > Documentation/config.txt:blame.showEmail::
> > Documentation/RelNotes/2.15.1.txt: * Description of 
> > blame.{showroot,blankboundary,showemail,date}
> > Documentation/RelNotes/2.5.0.txt: * "git blame" learned blame.showEmail 
> > configuration variable.
> > Documentation/RelNotes/2.16.0.txt: * Description of 
> > blame.{showroot,blankboundary,showemail,date}
> > Documentation/git-blame.txt:This can also be controlled via the 
> > `blame.showEmail` config
> > t/t8002-blame.sh:test_expect_success 'setup showEmail tests' '
> > t/t8002-blame.sh:test_expect_success 'blame with showemail options' '
> > t/t8002-blame.sh:test_expect_success 'blame with showEmail config false' '
> > t/t8002-blame.sh:   git config blame.showEmail false &&
> > t/t8002-blame.sh:test_expect_success 'blame with showEmail config true' '
> > t/t8002-blame.sh:   git config blame.showEmail true &&
> >
> >   thoughts?
>
> The issues you note about the docs using foo.barbaz instead of
> foo.barBaz should be fixed, but as noted in the "Syntax" section of
> "git-config" we already document that the config keys are all
> case-insensitive. We just like talking about them as foo.barBaz
> because it makes for easier reading.

  ah, got it, so really, the only example above that would merit
tweaking would be:

  blame-options.txt:  be controlled via the `blame.blankboundary` config option.

i'll collect those in my travels and submit them all at once.

rday

Re: should config options be treated as case-sensitive?

[Ævar Arnfjörð Bjarmason]

On Tue, May 22 2018, Robert P. J. Day wrote:

>   in my wanderings, more oddities, such as this:
>
> $ grep -ir blankboundary *
> builtin/blame.c:  if (!strcmp(var, "blame.blankboundary")) {
> Documentation/config.txt:blame.blankBoundary::
> Documentation/blame-options.txt:  be controlled via the 
> `blame.blankboundary` config option.
> Documentation/RelNotes/2.15.1.txt: * Description of 
> blame.{showroot,blankboundary,showemail,date}
> Documentation/RelNotes/2.16.0.txt: * Description of 
> blame.{showroot,blankboundary,showemail,date}
> $
>
> where you can see the single instance of "blankBoundary" in
> Doc/config.txt (with the upper case 'B'), while the rest have no such
> thing.
>
>   for fun, i checked another of blame's config settings, with similar
> results:
>
> builtin/blame.c:  if (!strcmp(var, "blame.showemail")) {
> Documentation/config.txt:blame.showEmail::
> Documentation/RelNotes/2.15.1.txt: * Description of 
> blame.{showroot,blankboundary,showemail,date}
> Documentation/RelNotes/2.5.0.txt: * "git blame" learned blame.showEmail 
> configuration variable.
> Documentation/RelNotes/2.16.0.txt: * Description of 
> blame.{showroot,blankboundary,showemail,date}
> Documentation/git-blame.txt:  This can also be controlled via the 
> `blame.showEmail` config
> t/t8002-blame.sh:test_expect_success 'setup showEmail tests' '
> t/t8002-blame.sh:test_expect_success 'blame with showemail options' '
> t/t8002-blame.sh:test_expect_success 'blame with showEmail config false' '
> t/t8002-blame.sh: git config blame.showEmail false &&
> t/t8002-blame.sh:test_expect_success 'blame with showEmail config true' '
> t/t8002-blame.sh: git config blame.showEmail true &&
>
>   thoughts?
>
> rday
>
> p.s. i am not *trying* to be annoyingly pedantic, i am merely
> succeeding.

The issues you note about the docs using foo.barbaz instead of
foo.barBaz should be fixed, but as noted in the "Syntax" section of
"git-config" we already document that the config keys are all
case-insensitive. We just like talking about them as foo.barBaz because
it makes for easier reading.

should config options be treated as case-sensitive?

[Robert P. J. Day]

  in my wanderings, more oddities, such as this:

$ grep -ir blankboundary *
builtin/blame.c:if (!strcmp(var, "blame.blankboundary")) {
Documentation/config.txt:blame.blankBoundary::
Documentation/blame-options.txt:be controlled via the 
`blame.blankboundary` config option.
Documentation/RelNotes/2.15.1.txt: * Description of 
blame.{showroot,blankboundary,showemail,date}
Documentation/RelNotes/2.16.0.txt: * Description of 
blame.{showroot,blankboundary,showemail,date}
$

where you can see the single instance of "blankBoundary" in
Doc/config.txt (with the upper case 'B'), while the rest have no such
thing.

  for fun, i checked another of blame's config settings, with similar
results:

builtin/blame.c:if (!strcmp(var, "blame.showemail")) {
Documentation/config.txt:blame.showEmail::
Documentation/RelNotes/2.15.1.txt: * Description of 
blame.{showroot,blankboundary,showemail,date}
Documentation/RelNotes/2.5.0.txt: * "git blame" learned blame.showEmail 
configuration variable.
Documentation/RelNotes/2.16.0.txt: * Description of 
blame.{showroot,blankboundary,showemail,date}
Documentation/git-blame.txt:This can also be controlled via the 
`blame.showEmail` config
t/t8002-blame.sh:test_expect_success 'setup showEmail tests' '
t/t8002-blame.sh:test_expect_success 'blame with showemail options' '
t/t8002-blame.sh:test_expect_success 'blame with showEmail config false' '
t/t8002-blame.sh:   git config blame.showEmail false &&
t/t8002-blame.sh:test_expect_success 'blame with showEmail config true' '
t/t8002-blame.sh:   git config blame.showEmail true &&

  thoughts?

rday

p.s. i am not *trying* to be annoyingly pedantic, i am merely
succeeding.