threads / patch / 32905

patchgit.txt: update description of the configuration mechanism

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

## tl;dr

8 messages between Feb 14, 2013 and Feb 15, 2013. Diffs are folded; open one to read it.

replies: 7people: 4as markdown or json

Matthieu Moy· Feb 14, 2013, 15:36 UTC · lore

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(-)
Show changes to Documentation/git.txt +6 −5
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
Michael J Gruber· Feb 14, 2013, 16:15 UTC · re: Matthieu Moy · lore

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

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 ;)
Show 38 quoted lines
> 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
>
Matthieu Moy· Feb 14, 2013, 16:23 UTC · re: Michael J Gruber · lore

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

Michael J Gruber <git@drmicha.warpmail.net> writes:
Show 5 quoted lines
> 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.

Show 10 quoted lines
>> 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/
Junio C Hamano· Feb 14, 2013, 17:10 UTC · re: Matthieu Moy · lore

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

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(-)
Show changes to Documentation/git.txt +5 −6
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
Matthieu Moy· Feb 14, 2013, 17:36 UTC · re: Junio C Hamano · lore

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

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/
Junio C Hamano· Feb 14, 2013, 18:03 UTC · re: Matthieu Moy · lore

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

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:
Show 7 quoted lines
> 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.

Michael J Gruber· Feb 15, 2013, 08:18 UTC · re: Junio C Hamano · lore

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

Junio C Hamano venit, vidit, dixit 14.02.2013 19:03:
Show 12 quoted lines
> 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
Junio C Hamano· Feb 14, 2013, 16:52 UTC · re: Matthieu Moy · lore

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

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.

Show 14 quoted lines
> +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.

← back to recent threads