[PATCH] git.txt: update description of the configuration mechanism

[PATCH] git.txt: update description of the configuration mechanism

[Matthieu Moy]

The old Git version where it appeared is not useful only to historians,
not to normal users. Also, the text was mentioning only the per-repo
config file, so add a mention of ~/.gitconfig. Describing in details the
system-wide, XDG and all would be counter-productive here, so reword the
description of the link to git-config to make it clear that it is not
only a list of configuration options.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/git.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 0b681d9..e332947 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -535,10 +535,11 @@ include::cmds-purehelpers.txt[]
 Configuration Mechanism
 -----------------------
 
-Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
-is used to hold per-repository configuration options.  It is a
-simple text file modeled after `.ini` format familiar to some
-people.  Here is an example:
+Git uses a simple text file format modeled after `.ini` format
+familiar to some people to store its configuration. The `.git/config`
+file is used to hold per-repository configuration options, and
+per-user configuration can be stored in a `~/.gitconfig` file.
+Here is an example:
 
 ------------
 #
@@ -559,7 +560,7 @@ people.  Here is an example:
 
 Various commands read from the configuration file and adjust
 their operation accordingly.  See linkgit:git-config[1] for a
-list.
+list and more details about the configuration mechanism.
 
 
 Identifier Terminology
-- 
1.8.1.3.572.g35e1b60

Re: [PATCH] git.txt: update description of the configuration mechanism

[Michael J Gruber]

Matthieu Moy venit, vidit, dixit 14.02.2013 16:36:
> The old Git version where it appeared is not useful only to historians,
> not to normal users. Also, the text was mentioning only the per-repo

I do not think you meant to not remove so many nots ;)

Besides, if history is uninteresting, then so is sociology: "familiar to
some people" can go, too.

> config file, so add a mention of ~/.gitconfig. Describing in details the
> system-wide, XDG and all would be counter-productive here, so reword the

Hmpf, I think this gives a way too prominent role to "~/.gitconfig". The
config files most people will have to deal with are:

- the repo config file
- the one set by "config --global"

And really, it would often be best if the latter was the XDG thing.

So, I'm all for improving git.txt, but somewhat differently ;)

> description of the link to git-config to make it clear that it is not
> only a list of configuration options.
> 
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
>  Documentation/git.txt | 11 ++++++-----
>  1 file changed, 6 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 0b681d9..e332947 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -535,10 +535,11 @@ include::cmds-purehelpers.txt[]
>  Configuration Mechanism
>  -----------------------
>  
> -Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
> -is used to hold per-repository configuration options.  It is a
> -simple text file modeled after `.ini` format familiar to some
> -people.  Here is an example:
> +Git uses a simple text file format modeled after `.ini` format
> +familiar to some people to store its configuration. The `.git/config`
> +file is used to hold per-repository configuration options, and
> +per-user configuration can be stored in a `~/.gitconfig` file.
> +Here is an example:
>  
>  ------------
>  #
> @@ -559,7 +560,7 @@ people.  Here is an example:
>  
>  Various commands read from the configuration file and adjust
>  their operation accordingly.  See linkgit:git-config[1] for a
> -list.
> +list and more details about the configuration mechanism.
>  
>  
>  Identifier Terminology
> 

Re: [PATCH] git.txt: update description of the configuration mechanism

[Matthieu Moy]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Matthieu Moy venit, vidit, dixit 14.02.2013 16:36:
>> The old Git version where it appeared is not useful only to historians,
>> not to normal users. Also, the text was mentioning only the per-repo
>
> I do not think you meant to not remove so many nots ;)

The first was meant to be "now", indeed.

> Besides, if history is uninteresting, then so is sociology: "familiar to
> some people" can go, too.

It can, but I'm fine with keeping it too. It may help some users to
realize "ah, OK, the same ini file I'm used to". And it doesn't really
harm.

>> config file, so add a mention of ~/.gitconfig. Describing in details the
>> system-wide, XDG and all would be counter-productive here, so reword the
>
> Hmpf, I think this gives a way too prominent role to "~/.gitconfig". The
> config files most people will have to deal with are:
>
> - the repo config file
> - the one set by "config --global"
>
> And really, it would often be best if the latter was the XDG thing.

That's a different question. For now, ~/.gitconfig is the default
destination of "config --global" and we should wait for XDG-aware Gits
to be widely deployed before reconsidering that.

If the XDG config file ever become the default, then sure, it will have
to be promoted instead of ~/.gitconfig in git.txt (and I'll be all for
it when it's time, even though I can foresee a few flamewars ;-) ), but
I don't think we should do that now.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH] git.txt: update description of the configuration mechanism

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> If the XDG config file ever become the default, then sure, it will have
> to be promoted instead of ~/.gitconfig in git.txt (and I'll be all for
> it when it's time, even though I can foresee a few flamewars ;-) ), but
> I don't think we should do that now.

We are giving an overview to list what things are possible and what
words the reader should be familiar with in this part of the manual.
The fact that configuration can be done per user and per repository
is a relevant thing to know at the conceptual level.

But the exact location of per-user and per-repository configuration
files does not matter in this context and is best left to the
git-config documentation.


 Documentation/git.txt | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 0b681d9..2d975e3 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -535,10 +535,9 @@ include::cmds-purehelpers.txt[]
 Configuration Mechanism
 -----------------------
 
-Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
-is used to hold per-repository configuration options.  It is a
-simple text file modeled after `.ini` format familiar to some
-people.  Here is an example:
+Git uses a simple text format to store customizations that are per
+repository and are per user.  Such a configuration file may look
+like this:
 
 ------------
 #
@@ -553,13 +552,13 @@ people.  Here is an example:
 ; user identity
 [user]
 	name = "Junio C Hamano"
-	email = "junkio@twinsun.com"
+	email = "gitster@pobox.com"
 
 ------------
 
 Various commands read from the configuration file and adjust
 their operation accordingly.  See linkgit:git-config[1] for a
-list.
+list and more details about the configuration mechanism.
 
 
 Identifier Terminology

Re: [PATCH] git.txt: update description of the configuration mechanism

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

> But the exact location of per-user and per-repository configuration
> files does not matter in this context and is best left to the
> git-config documentation.

I'm OK with your version.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH] git.txt: update description of the configuration mechanism

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> But the exact location of per-user and per-repository configuration
>> files does not matter in this context and is best left to the
>> git-config documentation.
>
> I'm OK with your version.

I already queued your original with one s/not/now/; perhaps I will
redo it then.

Re: [PATCH] git.txt: update description of the configuration mechanism

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 14.02.2013 19:03:
> Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
> 
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>>> But the exact location of per-user and per-repository configuration
>>> files does not matter in this context and is best left to the
>>> git-config documentation.
>>
>> I'm OK with your version.
> 
> I already queued your original with one s/not/now/; perhaps I will
> redo it then.

Yes, I think the new version improves upon Matthieu's which was a good
start to begin with :)

Michael

Re: [PATCH] git.txt: update description of the configuration mechanism

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> The old Git version where it appeared is not useful only to historians,
> not to normal users.

That statement cannot be generally true, unless the "old" is really
old and no longer relevant but 0.99.9 is sufficiently old so the
value of the part of the message you removed that warns users with
ancient versions that they may not be able to use the feature
without upgrading has diminished.

> +Git uses a simple text file format modeled after `.ini` format
> +familiar to some people to store its configuration. The `.git/config`
> +file is used to hold per-repository configuration options, and
> +per-user configuration can be stored in a `~/.gitconfig` file.
> +Here is an example:
>  
>  ------------
>  #
> @@ -559,7 +560,7 @@ people.  Here is an example:
>  
>  Various commands read from the configuration file and adjust
>  their operation accordingly.  See linkgit:git-config[1] for a
> -list.
> +list and more details about the configuration mechanism.

Both look sensible.