how exactly can git config section names contain periods?

how exactly can git config section names contain periods?

[Robert P. J. Day]

  more oddities in my travels, this from Doc.../config.txt:

"The file consists of sections and variables.  A section begins with
the name of the section in square brackets and continues until the
next section begins.  Section names are case-insensitive.  Only
alphanumeric characters, `-` and `.` are allowed in section names.
                                  ^ ?????

  what? how can section names contain periods? reading further,

"Sections can be further divided into subsections.  To begin a
subsection put its name in double quotes, separated by space from the
section name, in the section header, like in the example below:

--------
        [section "subsection"]


  ok, so how on earth would i use "git config" at the command line to
set a config variable with some arbitrary level of subsections? let's
try this:

  $ git config --global a.b.c.d.e rday

huh ... seemed to work fine, and added this to my ~/.gitconfig:

  [a "b.c.d"]
          e = rday

as i see it, the first component is intgerpreted as the section name,
the last component is the variable/key(?) name, and everything in
between is treated as subsection(s), which is not at all obvious from
that Doc file, or from "man git-config".

  and if a section name can contain periods, how would you specify
that at the command line?

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: how exactly can git config section names contain periods?

[Randall S. Becker]

> -----Original Message-----
> From: git-owner@vger.kernel.org <git-owner@vger.kernel.org> On Behalf
> Of Robert P. J. Day
> Sent: June 1, 2018 4:14 PM
> To: Git Mailing list <git@vger.kernel.org>
> Subject: how exactly can git config section names contain periods?
> 
> 
>   more oddities in my travels, this from Doc.../config.txt:
> 
> "The file consists of sections and variables.  A section begins with the
name
> of the section in square brackets and continues until the next section
begins.
> Section names are case-insensitive.  Only alphanumeric characters, `-` and
`.`
> are allowed in section names.
>                                   ^ ?????
> 
>   what? how can section names contain periods? reading further,
> 
> "Sections can be further divided into subsections.  To begin a subsection
put
> its name in double quotes, separated by space from the section name, in
the
> section header, like in the example below:
> 
> --------
>         [section "subsection"]
> 
> 
>   ok, so how on earth would i use "git config" at the command line to set
a
> config variable with some arbitrary level of subsections? let's try this:
> 
>   $ git config --global a.b.c.d.e rday
> 
> huh ... seemed to work fine, and added this to my ~/.gitconfig:
> 
>   [a "b.c.d"]
>           e = rday
> 
> as i see it, the first component is intgerpreted as the section name, the
last
> component is the variable/key(?) name, and everything in between is
> treated as subsection(s), which is not at all obvious from that Doc file,
or from
> "man git-config".
> 
>   and if a section name can contain periods, how would you specify that at
the
> command line?

I'm with Robert on this. I would have thought that the interpretation should
have been:

["a.b.c.d"]
         e = rday

Confused as well,

Randall

-- Brief whoami:
 NonStop developer since approximately 211288444200000000
 UNIX developer since approximately 421664400
-- In my real life, I talk too much.

Re: how exactly can git config section names contain periods?

[Jeff King]

On Fri, Jun 01, 2018 at 04:14:12PM -0400, Robert P. J. Day wrote:

>   more oddities in my travels, this from Doc.../config.txt:
> 
> "The file consists of sections and variables.  A section begins with
> the name of the section in square brackets and continues until the
> next section begins.  Section names are case-insensitive.  Only
> alphanumeric characters, `-` and `.` are allowed in section names.
>                                   ^ ?????
> 
>   what? how can section names contain periods? reading further,

I agree that seems like nonsense. Once we get to the first period, we
consider parts after that to be a subsection name, due to the
"flattened" form we use in various places (i.e., "section.key" or
"section.subsection.key").

Syntactically we do allow:

  [foo.bar]
  key = true

in the config file, which should equivalent to:

  [foo "bar"]
  key = true

This is mentioned later:

  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.

This has been deprecated since 2011. Maybe it's time to finally get rid
of it.

> "Sections can be further divided into subsections.  To begin a
> subsection put its name in double quotes, separated by space from the
> section name, in the section header, like in the example below:
> 
> --------
>         [section "subsection"]
> 
> 
>   ok, so how on earth would i use "git config" at the command line to
> set a config variable with some arbitrary level of subsections? let's
> try this:

You don't. There are only three levels: section, (optional) subsection,
and key. If there is a subsection, it consists of _everything_ between
the two outer periods.

>   $ git config --global a.b.c.d.e rday
> 
> huh ... seemed to work fine, and added this to my ~/.gitconfig:
> 
>   [a "b.c.d"]
>           e = rday
> 
> as i see it, the first component is intgerpreted as the section name,
> the last component is the variable/key(?) name, and everything in
> between is treated as subsection(s), which is not at all obvious from
> that Doc file, or from "man git-config".

Yep, your understanding is correct.

>   and if a section name can contain periods, how would you specify
> that at the command line?

You can't, because section names cannot contain periods. ;)

I agree that the docs you quoted are somewhere between misleading and
outright wrong. At the very least, we should remove the part about ".
allowed in section names". But I also think we could stand to make the
3-level mental model more explicit.

-Peff

Re: how exactly can git config section names contain periods?

[Robert P. J. Day]

On Fri, 1 Jun 2018, Jeff King wrote:

> This is mentioned later:
>
>   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.

> This has been deprecated since 2011. Maybe it's time to finally get
> rid of it.

  seven years seems sufficient for deprecation.

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: how exactly can git config section names contain periods?

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Syntactically we do allow:
>
>   [foo.bar]
>   key = true
>
> in the config file, which should equivalent to:
>
>   [foo "bar"]
>   key = true
>
> This is mentioned later:
>
>   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.
>
> This has been deprecated since 2011. Maybe it's time to finally get rid
> of it.

Sure, but is it worth the transition noise?

The way we lightly utter the word "deprecated" around here probably
does not align well with the way how end-users perceive the word.
Just marking something deprecated in a corner of the documentation
set, without actively making an effort to wean the existing users
off, while happily accepting the existing "deprecated" practice, is
what we've done.

In those repositories people have with "[foo.bar] key" syntax that
were created before or after 2011, we first should start issuing a
"that syntax will no longer be valid---I'll update it for you if you
want (y/n)?" warning and keep it for a release or three before
finally removing the "feature".

Re: how exactly can git config section names contain periods?

[Jeff King]

On Sat, Jun 02, 2018 at 08:05:22AM +0900, Junio C Hamano wrote:

> > This has been deprecated since 2011. Maybe it's time to finally get rid
> > of it.
> 
> Sure, but is it worth the transition noise?
> 
> The way we lightly utter the word "deprecated" around here probably
> does not align well with the way how end-users perceive the word.
> Just marking something deprecated in a corner of the documentation
> set, without actively making an effort to wean the existing users
> off, while happily accepting the existing "deprecated" practice, is
> what we've done.
> 
> In those repositories people have with "[foo.bar] key" syntax that
> were created before or after 2011, we first should start issuing a
> "that syntax will no longer be valid---I'll update it for you if you
> want (y/n)?" warning and keep it for a release or three before
> finally removing the "feature".

Yeah, sorry to be unclear: I meant that we should actually start moving
forward on the removal, and I agree that the first step is issuing a
warning.

It may not be worth the transition noise. For the most part historical
oddities like these aren't hurting anybody. On the other hand, people
read the documentation and go "huh?". These kinds of vestigial options
and special cases can add up to clutter the explanations. So I dunno.

-Peff

Re: how exactly can git config section names contain periods?

[Robert P. J. Day]

On Fri, 1 Jun 2018, Jeff King wrote:

> On Fri, Jun 01, 2018 at 04:14:12PM -0400, Robert P. J. Day wrote:
>
> >   $ git config --global a.b.c.d.e rday
> >
> > huh ... seemed to work fine, and added this to my ~/.gitconfig:
> >
> >   [a "b.c.d"]
> >           e = rday
> >
> > as i see it, the first component is intgerpreted as the section
> > name, the last component is the variable/key(?) name, and
> > everything in between is treated as subsection(s), which is not at
> > all obvious from that Doc file, or from "man git-config".
>
> Yep, your understanding is correct.

  just to be precise regarding terminology, in my example above, is
"b.c.d" a single subsection, or does it refer to three subsections?
i'm guessing it refers to a single subsection, which is fine with me,
as long as it's very clearly explained that way in the docs.

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: how exactly can git config section names contain periods?

[Jeff King]

On Sat, Jun 02, 2018 at 04:50:57AM -0400, Robert P. J. Day wrote:

> On Fri, 1 Jun 2018, Jeff King wrote:
> 
> > On Fri, Jun 01, 2018 at 04:14:12PM -0400, Robert P. J. Day wrote:
> >
> > >   $ git config --global a.b.c.d.e rday
> > >
> > > huh ... seemed to work fine, and added this to my ~/.gitconfig:
> > >
> > >   [a "b.c.d"]
> > >           e = rday
> > >
> > > as i see it, the first component is intgerpreted as the section
> > > name, the last component is the variable/key(?) name, and
> > > everything in between is treated as subsection(s), which is not at
> > > all obvious from that Doc file, or from "man git-config".
> >
> > Yep, your understanding is correct.
> 
>   just to be precise regarding terminology, in my example above, is
> "b.c.d" a single subsection, or does it refer to three subsections?
> i'm guessing it refers to a single subsection, which is fine with me,
> as long as it's very clearly explained that way in the docs.

It's a single subsection. Each config key at most one subsection.

-Peff

Re: how exactly can git config section names contain periods?

[Robert P. J. Day]

On Fri, 1 Jun 2018, Jeff King wrote:

> On Fri, Jun 01, 2018 at 04:14:12PM -0400, Robert P. J. Day wrote:

... snip ...

> >   ok, so how on earth would i use "git config" at the command line
> > to set a config variable with some arbitrary level of subsections?
> > let's try this:
>
> You don't. There are only three levels: section, (optional)
> subsection, and key. If there is a subsection, it consists of
> _everything_ between the two outer periods.
>
> >   $ git config --global a.b.c.d.e rday
> >
> > huh ... seemed to work fine, and added this to my ~/.gitconfig:
> >
> >   [a "b.c.d"]
> >           e = rday
> >
> > as i see it, the first component is intgerpreted as the section name,
> > the last component is the variable/key(?) name, and everything in
> > between is treated as subsection(s), which is not at all obvious from
> > that Doc file, or from "man git-config".
>
> Yep, your understanding is correct.
>
> >   and if a section name can contain periods, how would you specify
> > that at the command line?
>
> You can't, because section names cannot contain periods. ;)

  if (for some weird reason) i wanted to define a multi-level
subsection, is there any benefit to using periods as i did above, as
opposed to any other delimiting character? apparently, running this:

  $ git config --global a.b_c_d.e rday

dumps this into my ~/.gitconfig:

  [a "b_c_d"]
	e = rday

if i wanted to do something this admittedly awkward, would using
periods give me some benefit related to, i don't know, regex matching,
as compared to using a different character? or am i just way
overthinking this? is anyone out there actually taking advantage of
multi-level subsections?

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: how exactly can git config section names contain periods?

[SZEDER Gábor]

> On Fri, 1 Jun 2018, Jeff King wrote:
> 
> > On Fri, Jun 01, 2018 at 04:14:12PM -0400, Robert P. J. Day wrote:
> > >   ok, so how on earth would i use "git config" at the command line
> > > to set a config variable with some arbitrary level of subsections?
> > > let's try this:
> >
> > You don't. There are only three levels: section, (optional)
> > subsection, and key. If there is a subsection, it consists of
> > _everything_ between the two outer periods.

<snip>

>   if (for some weird reason) i wanted to define a multi-level
> subsection,

You can't, there are no multi-level subsections, see above.

Re: how exactly can git config section names contain periods?

[Robert P. J. Day]

[-- Attachment #1: Type: text/plain, Size: 1346 bytes --]

On Sun, 3 Jun 2018, SZEDER Gábor wrote:

>
>
> > On Fri, 1 Jun 2018, Jeff King wrote:
> >
> > > On Fri, Jun 01, 2018 at 04:14:12PM -0400, Robert P. J. Day wrote:
> > > >   ok, so how on earth would i use "git config" at the command line
> > > > to set a config variable with some arbitrary level of subsections?
> > > > let's try this:
> > >
> > > You don't. There are only three levels: section, (optional)
> > > subsection, and key. If there is a subsection, it consists of
> > > _everything_ between the two outer periods.
>
> <snip>
>
> >   if (for some weird reason) i wanted to define a multi-level
> > subsection,
>
> You can't, there are no multi-level subsections, see above.

  no, i *get* that, what i was asking was if i wanted to simulate or
emulate such a thing ... or is that just getting too weird and there
is no compelling reason to want to go down that road? (which i am
totally prepared to accept.)

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: how exactly can git config section names contain periods?

[Jeff King]

On Sun, Jun 03, 2018 at 06:35:44AM -0400, Robert P. J. Day wrote:

> > >   if (for some weird reason) i wanted to define a multi-level
> > > subsection,
> >
> > You can't, there are no multi-level subsections, see above.
> 
>   no, i *get* that, what i was asking was if i wanted to simulate or
> emulate such a thing ... or is that just getting too weird and there
> is no compelling reason to want to go down that road? (which i am
> totally prepared to accept.)

You can do whatever you like with the subsection; its contents are
generally dependent on the semantics of the key. E.g.,
remote.<remotename>.*, branch.<branchname>.*. That's why Git tries to be
permissive with the syntax.

So you are free to consider "foo.a.b.c.key" as some kind of multi-level
hierarchy if that's useful to you. But you won't get any tool support
from Git, and I don't think there is any compelling reason to use "."
versus some other syntax (except that it perhaps looks better to the
user).

-Peff

Re: how exactly can git config section names contain periods?

[Johannes Sixt]

Am 03.06.2018 um 11:53 schrieb Robert P. J. Day:
> if i wanted to do something this admittedly awkward, would using
> periods give me some benefit related to, i don't know, regex matching,
> as compared to using a different character? or am i just way
> overthinking this? is anyone out there actually taking advantage of
> multi-level subsections?

There is nothing wrong with having all of these

     git config foo.a.b.c.key value
     git config foo.a.b.c value
     git config foo.a.b.key value

in a single configuration file, I think. There is nothing special there. 
They're three different settings in two different (sub-)sections.

-- Hannes