[PATCH 0/2] user-manual: reorganize the configuration steps

[PATCH 0/2] user-manual: reorganize the configuration steps

[Felipe Contreras]

This basically introduces the "getting started" section so users get familiar
with the configuration from the get-go, and also, most people prefer to teach
'git config --global' to setup the user name and email. Here are a few
examples:

git tutorial:
http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html

GNOME:
http://live.gnome.org/Git/Developers

SourceForge:
http://sourceforge.net/apps/trac/sourceforge/wiki/Git

github:
http://help.github.com/git-email-settings/

Felipe Contreras (2):
  user-manual: add global config section
  user-manual: simplify the user configuration

 Documentation/user-manual.txt |   35 ++++++++++++++++++++++++++++++-----
 1 files changed, 30 insertions(+), 5 deletions(-)

[PATCH 1/2] user-manual: add global config section

[Felipe Contreras]

So that users get to know how to configure git from the get-to with good
practical example (color.ui = auto) that most people would probably like
anyway.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/user-manual.txt |   27 +++++++++++++++++++++++++++
 1 files changed, 27 insertions(+), 0 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 67ebffa..ff2563a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -40,6 +40,33 @@ without any explanation.
 Finally, see <<todo>> for ways that you can help make this manual more
 complete.
 
+[[getting-started]]
+Getting started
+=============
+
+Git's configuration is distributed among different locations--this manual will
+only to deal with 'global' (for the user) and 'repository' variables, where
+'repository' variables take precedence over 'global' ones.
+
+You would probably want to start setting up something useful:
+------------------------------------------------
+$ git config --global color.ui auto
+------------------------------------------------
+
+This will make prettier the output of certain commands such as `git diff`, but
+that's not important; what is important here is that `color.ui` has been
+stored in the 'global' configuration.
+
+View and manually modify the configuration by opening `~/.gitconfig`:
+------------------------------------------------
+[color]
+        ui = auto
+------------------------------------------------
+
+Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).
+
+More git configurations will be covered in the rest of the manual, if you want
+to learn more look at linkgit:git-config[1] for details.
 
 [[repositories-and-branches]]
 Repositories and Branches
-- 
1.6.5.4.g31fc3

[PATCH 2/2] user-manual: simplify the user configuration

[Felipe Contreras]

This is shorter, avoids the burder to think about the format of the
configuration file, and most guides out there prefer this form.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/user-manual.txt |    8 +++-----
 1 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ff2563a..bab64f8 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1008,13 +1008,11 @@ Telling git your name
 ---------------------
 
 Before creating any commits, you should introduce yourself to git.  The
-easiest way to do so is to make sure the following lines appear in a
-file named .gitconfig in your home directory:
+easiest way is to use the linkgit:git-config[1] command:
 
 ------------------------------------------------
-[user]
-	name = Your Name Comes Here
-	email = you@yourdomain.example.com
+$ git config --global user.name "Your Name Comes Here"
+$ git config --global user.email you@yourdomain.example.com
 ------------------------------------------------
 
 (See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
-- 
1.6.5.4.g31fc3

Re: [PATCH 1/2] user-manual: add global config section

[Jonathan Nieder]

Felipe Contreras wrote:
> So that users get to know how to configure git from the get-to with good
> practical example (color.ui = auto) that most people would probably like
> anyway.
> 
> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>

Good idea.  Some comments:

> +Git's configuration is distributed among different locations--this manual will
> +only to deal with 'global' (for the user) and 'repository' variables, where
> +'repository' variables take precedence over 'global' ones.

What are these different locations you speak of?  If git’s configuration
is complicated to deal with, maybe that is something that could be
improved.

This is very early in the manual, where every word counts.  I am not
very good at wording and do not have any better suggestions, but would
it be possible to more efficiently convey this:

	Git reads its per-user configuration from ~/.gitignore.

	That file can also be manipulated with the "git config"
	command, which can be convenient in scripts or when using
	operating systems like Windows where it is not clear where
	the home directory is.

	For example, if your terminal supports it, you can tell Git
	to use color in the output for commands such as "git diff"
	with "git config --global color.ui auto".

	For more information and a list of possible settings, see
	git-config(1).

By the way, this reminds me that I am not sure git-config(1) conveys the
list of configuration items in an ideal way.  It can be easy to dismiss
that page as plumbing documentation when seeing it for the first time.
Should we ship a sample .gitconfig with all items included and comments
describing them, or a separate gitconfig(5)?  Either would be easy to
generate from config.txt.

Thoughts?
Jonathan

Re: [PATCH 1/2] user-manual: add global config section

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> This is very early in the manual, where every word counts.  I am not
> very good at wording and do not have any better suggestions, but would
> it be possible to more efficiently convey this:
>
> 	Git reads its per-user configuration from ~/.gitignore.
>
> 	That file can also be manipulated with the "git config"
> 	command, which can be convenient in scripts or when using
> 	operating systems like Windows where it is not clear where
> 	the home directory is.
>
> 	For example, if your terminal supports it, you can tell Git
> 	to use color in the output for commands such as "git diff"
> 	with "git config --global color.ui auto".
>
> 	For more information and a list of possible settings, see
> 	git-config(1).

The way how the above introduces the "git config" command to people who
see git for the first time makes sense.  Unfortunately, --global and
per-user do not "click" together when given in isolation, and I think it
would help if it is explained this way, using a setting that can validly
be either per-user or project specific:

    Various configuration variables affect how git operates.  Some are
    specific to the user (e.g. if you prefer to see the output in colour),
    while some are specific to a repository (e.g. what other repositories
    it interacts with).  Git reads from ~/.gitconfig file to learn your
    personal settings and .git/config file of the repository you are
    working in to learn the repository settings.

    These are plain text files that you can view or edit in your text
    editor, but they also can be manipulated with the "git config"
    command, which is convenient in scripts or ...

    For example, if you want to use a particular e-mail address only while
    working in the current repository, you would set "user.email" variable
    to that e-mail address in the repository configuration file (i.e.
    .git/config) with this command:

	git config user.email your@email.address.xz

    If on the other hand you want to use the same address for any project
    you work with, you can instead set this in your personal configuration
    file (i.e.  ~/.gitconfig) with this command:

	git config --global user.email your@email.address.xz

    For more information ...

Since this is an end-user material, I deliberately omitted talking about
the --system (i.e. /etc/gitconfig) in the above.

Re: [PATCH 1/2] user-manual: add global config section

[Michael J Gruber]

Felipe Contreras venit, vidit, dixit 11.10.2009 22:43:
> So that users get to know how to configure git from the get-to with good
> practical example (color.ui = auto) that most people would probably like
> anyway.
> 
> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> ---
>  Documentation/user-manual.txt |   27 +++++++++++++++++++++++++++
>  1 files changed, 27 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 67ebffa..ff2563a 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -40,6 +40,33 @@ without any explanation.
>  Finally, see <<todo>> for ways that you can help make this manual more
>  complete.
>  
> +[[getting-started]]
> +Getting started
> +=============
> +
> +Git's configuration is distributed among different locations--this manual will
> +only to deal with 'global' (for the user) and 'repository' variables, where
> +'repository' variables take precedence over 'global' ones.

Well, you do talk about "system" below, and that's about it. Also, the
configuration is not really distributed among different locations. Most
newbies interested in a *D*VCS will misunderstand this (as git having
distributed configuration).

Alternative:

Git's default configuration can be changed on a system wide, global (per
user) and local (per repository) level, in the order of increasing
precedence.

> +
> +You would probably want to start setting up something useful:
> +------------------------------------------------
> +$ git config --global color.ui auto
> +------------------------------------------------
> +
> +This will make prettier the output of certain commands such as `git diff`, but
> +that's not important; what is important here is that `color.ui` has been
> +stored in the 'global' configuration.

This will make certain commands such as `git diff` use colors in the
output. What is important here is that the value `auto` for the option
`color.ui` has been stored in the 'global' configuration. Use `--system`
for the system wide configuration; specifying neither `--system` nor
`--global` makes `git config` access the local configuration.

> +
> +View and manually modify the configuration by opening `~/.gitconfig`:

View and manually modify the global configuration by opening
`~/.gitconfig` in your editor or using `git config --global --edit`:

> +------------------------------------------------
> +[color]
> +        ui = auto
> +------------------------------------------------
> +
> +Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).

I don't even think we should talk about locations here, "git config -e"
should be the first user's way to do it.

> +
> +More git configurations will be covered in the rest of the manual, if you want
> +to learn more look at linkgit:git-config[1] for details.

"Configurations" is ambiguous, it can be easily (mis)understood as
"types of configuration" (global, local etc.). Also, the above doesn't
really cover even one option. How about:

This manual covers many configuration options (such as `color.ui.`). For
more details on the `git config` command as well as all configuration
options see linkgit:git-config[1].

>  [[repositories-and-branches]]
>  Repositories and Branches

Cheers,
Michael

Re: [PATCH 1/2] user-manual: add global config section

[Felipe Contreras]

On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Felipe Contreras venit, vidit, dixit 11.10.2009 22:43:
>> So that users get to know how to configure git from the get-to with good
>> practical example (color.ui = auto) that most people would probably like
>> anyway.
>>
>> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
>> ---
>>  Documentation/user-manual.txt |   27 +++++++++++++++++++++++++++
>>  1 files changed, 27 insertions(+), 0 deletions(-)
>>
>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
>> index 67ebffa..ff2563a 100644
>> --- a/Documentation/user-manual.txt
>> +++ b/Documentation/user-manual.txt
>> @@ -40,6 +40,33 @@ without any explanation.
>>  Finally, see <<todo>> for ways that you can help make this manual more
>>  complete.
>>
>> +[[getting-started]]
>> +Getting started
>> +=============
>> +
>> +Git's configuration is distributed among different locations--this manual will
>> +only to deal with 'global' (for the user) and 'repository' variables, where
>> +'repository' variables take precedence over 'global' ones.
>
> Well, you do talk about "system" below, and that's about it. Also, the
> configuration is not really distributed among different locations. Most
> newbies interested in a *D*VCS will misunderstand this (as git having
> distributed configuration).
>
> Alternative:
>
> Git's default configuration can be changed on a system wide, global (per
> user) and local (per repository) level, in the order of increasing
> precedence.

When I read that it's not clear if the local level discards the global
level completely or it's aggregated. If we specify that it's only the
variables that take precedence it might be clearer:

Git's configuration is composed of variables that are stored in
multiple locations: 'system' (all users), 'global' (for the user), and
'repository' -- in decreasing order of precedence.

>> +
>> +You would probably want to start setting up something useful:
>> +------------------------------------------------
>> +$ git config --global color.ui auto
>> +------------------------------------------------
>> +
>> +This will make prettier the output of certain commands such as `git diff`, but
>> +that's not important; what is important here is that `color.ui` has been
>> +stored in the 'global' configuration.
>
> This will make certain commands such as `git diff` use colors in the
> output. What is important here is that the value `auto` for the option
> `color.ui` has been stored in the 'global' configuration. Use `--system`
> for the system wide configuration; specifying neither `--system` nor
> `--global` makes `git config` access the local configuration.

I think we should only mention (once) the system wide configuration,
but not cover it. That's for system administrators, not users.

>> +
>> +View and manually modify the configuration by opening `~/.gitconfig`:
>
> View and manually modify the global configuration by opening
> `~/.gitconfig` in your editor or using `git config --global --edit`:

I have separate patches for 'git config --edit', but Junio suggested
to hold them back because --edit is a relatively new option.

>> +------------------------------------------------
>> +[color]
>> +        ui = auto
>> +------------------------------------------------
>> +
>> +Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).
>
> I don't even think we should talk about locations here, "git config -e"
> should be the first user's way to do it.

I disagree. Most useful configurations (color.ui, user.email) should
be global. The complete newbie might think: cool, now I have my git
properly configured (with 'git config -e'), and then when cloning a
new repo (s)he would think: ok, git just forgot what I told him. When
that happens (s)he would have to re-learn and re-configure git.

When users think about configuration, it's usually a 'global'
configuration, so that's what we should teach from the beginning and
make sure they understand the difference between 'global' and
'repository' configurations.

>> +
>> +More git configurations will be covered in the rest of the manual, if you want
>> +to learn more look at linkgit:git-config[1] for details.
>
> "Configurations" is ambiguous, it can be easily (mis)understood as
> "types of configuration" (global, local etc.). Also, the above doesn't
> really cover even one option. How about:
>
> This manual covers many configuration options (such as `color.ui.`). For
> more details on the `git config` command as well as all configuration
> options see linkgit:git-config[1].

Looks better, except s/configuration options/configuration variables/

Cheers.

-- 
Felipe Contreras

Re: [PATCH 1/2] user-manual: add global config section

[Michael J Gruber]

Felipe Contreras venit, vidit, dixit 12.10.2009 19:09:
> On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber
> <git@drmicha.warpmail.net> wrote:
>> Felipe Contreras venit, vidit, dixit 11.10.2009 22:43:
>>> So that users get to know how to configure git from the get-to with good
>>> practical example (color.ui = auto) that most people would probably like
>>> anyway.
>>>
>>> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
>>> ---
>>>  Documentation/user-manual.txt |   27 +++++++++++++++++++++++++++
>>>  1 files changed, 27 insertions(+), 0 deletions(-)
>>>
>>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
>>> index 67ebffa..ff2563a 100644
>>> --- a/Documentation/user-manual.txt
>>> +++ b/Documentation/user-manual.txt
>>> @@ -40,6 +40,33 @@ without any explanation.
>>>  Finally, see <<todo>> for ways that you can help make this manual more
>>>  complete.
>>>
>>> +[[getting-started]]
>>> +Getting started
>>> +=============
>>> +
>>> +Git's configuration is distributed among different locations--this manual will
>>> +only to deal with 'global' (for the user) and 'repository' variables, where
>>> +'repository' variables take precedence over 'global' ones.
>>
>> Well, you do talk about "system" below, and that's about it. Also, the
>> configuration is not really distributed among different locations. Most
>> newbies interested in a *D*VCS will misunderstand this (as git having
>> distributed configuration).
>>
>> Alternative:
>>
>> Git's default configuration can be changed on a system wide, global (per
>> user) and local (per repository) level, in the order of increasing
>> precedence.
> 
> When I read that it's not clear if the local level discards the global
> level completely or it's aggregated. If we specify that it's only the
> variables that take precedence it might be clearer:
> 
> Git's configuration is composed of variables that are stored in
> multiple locations: 'system' (all users), 'global' (for the user), and
> 'repository' -- in decreasing order of precedence.

Yep, although established lingo is "options" (not "variables"), and it's
really increasing order, not decreasing.

> 
>>> +
>>> +You would probably want to start setting up something useful:
>>> +------------------------------------------------
>>> +$ git config --global color.ui auto
>>> +------------------------------------------------
>>> +
>>> +This will make prettier the output of certain commands such as `git diff`, but
>>> +that's not important; what is important here is that `color.ui` has been
>>> +stored in the 'global' configuration.
>>
>> This will make certain commands such as `git diff` use colors in the
>> output. What is important here is that the value `auto` for the option
>> `color.ui` has been stored in the 'global' configuration. Use `--system`
>> for the system wide configuration; specifying neither `--system` nor
>> `--global` makes `git config` access the local configuration.
> 
> I think we should only mention (once) the system wide configuration,
> but not cover it. That's for system administrators, not users.
> 
>>> +
>>> +View and manually modify the configuration by opening `~/.gitconfig`:
>>
>> View and manually modify the global configuration by opening
>> `~/.gitconfig` in your editor or using `git config --global --edit`:
> 
> I have separate patches for 'git config --edit', but Junio suggested
> to hold them back because --edit is a relatively new option.
> 
>>> +------------------------------------------------
>>> +[color]
>>> +        ui = auto
>>> +------------------------------------------------
>>> +
>>> +Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).
>>
>> I don't even think we should talk about locations here, "git config -e"
>> should be the first user's way to do it.
> 
> I disagree. Most useful configurations (color.ui, user.email) should
> be global. The complete newbie might think: cool, now I have my git
> properly configured (with 'git config -e'), and then when cloning a
> new repo (s)he would think: ok, git just forgot what I told him. When
> that happens (s)he would have to re-learn and re-configure git.
> 
> When users think about configuration, it's usually a 'global'
> configuration, so that's what we should teach from the beginning and
> make sure they understand the difference between 'global' and
> 'repository' configurations.

Sure. What I meant are the file locations, the actual paths. First
timers should use "git config -e" and "git config --global -e" if they
really want to edit their local and global config files. Better yet,
they should use "git config" and "git config --global" in their set and
get modes, because they make sure that there's no total garbage in the
config. The locations of the files are an implementation detail.

> 
>>> +
>>> +More git configurations will be covered in the rest of the manual, if you want
>>> +to learn more look at linkgit:git-config[1] for details.
>>
>> "Configurations" is ambiguous, it can be easily (mis)understood as
>> "types of configuration" (global, local etc.). Also, the above doesn't
>> really cover even one option. How about:
>>
>> This manual covers many configuration options (such as `color.ui.`). For
>> more details on the `git config` command as well as all configuration
>> options see linkgit:git-config[1].
> 
> Looks better, except s/configuration options/configuration variables/
> 

Uhm, no, for the reason mentioned above. While the man page of git
config is not completely consistent either, we're really talking about
configuration options. An "option" can be set to a "value", and the
thing you pass in order to do that can be called a "variable". For the
most part this is how git-config[1] uses this terminology.

Michael

Re: [PATCH 1/2] user-manual: add global config section

[Felipe Contreras]

On Tue, Oct 13, 2009 at 10:19 AM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Felipe Contreras venit, vidit, dixit 12.10.2009 19:09:
>> On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber
>> <git@drmicha.warpmail.net> wrote:
>>> Well, you do talk about "system" below, and that's about it. Also, the
>>> configuration is not really distributed among different locations. Most
>>> newbies interested in a *D*VCS will misunderstand this (as git having
>>> distributed configuration).
>>>
>>> Alternative:
>>>
>>> Git's default configuration can be changed on a system wide, global (per
>>> user) and local (per repository) level, in the order of increasing
>>> precedence.
>>
>> When I read that it's not clear if the local level discards the global
>> level completely or it's aggregated. If we specify that it's only the
>> variables that take precedence it might be clearer:
>>
>> Git's configuration is composed of variables that are stored in
>> multiple locations: 'system' (all users), 'global' (for the user), and
>> 'repository' -- in decreasing order of precedence.
>
> Yep, although established lingo is "options" (not "variables"), and it's
> really increasing order, not decreasing.

Really? I remember clearly Junio stating otherwise:
http://marc.info/?l=git&m=123460371724873&w=2

----
> +	OPT_BOOLEAN(0, "unset", &do_unset, "removes an option: name [value-regex]"),

Please don't introduce a new noun "option" that has never been used to
mean a "configuration variable" in git documentation.  It unnecessarily
confuses everybody.
----

>> I disagree. Most useful configurations (color.ui, user.email) should
>> be global. The complete newbie might think: cool, now I have my git
>> properly configured (with 'git config -e'), and then when cloning a
>> new repo (s)he would think: ok, git just forgot what I told him. When
>> that happens (s)he would have to re-learn and re-configure git.
>>
>> When users think about configuration, it's usually a 'global'
>> configuration, so that's what we should teach from the beginning and
>> make sure they understand the difference between 'global' and
>> 'repository' configurations.
>
> Sure. What I meant are the file locations, the actual paths. First
> timers should use "git config -e" and "git config --global -e" if they
> really want to edit their local and global config files. Better yet,
> they should use "git config" and "git config --global" in their set and
> get modes, because they make sure that there's no total garbage in the
> config. The locations of the files are an implementation detail.

Oh, in that case I agree.

>> Looks better, except s/configuration options/configuration variables/
>>
>
> Uhm, no, for the reason mentioned above. While the man page of git
> config is not completely consistent either, we're really talking about
> configuration options. An "option" can be set to a "value", and the
> thing you pass in order to do that can be called a "variable". For the
> most part this is how git-config[1] uses this terminology.

Yeah, but not everything in there is an option. Personally I would
prefer the "option" term, but as I said, Junio disagreed some time
ago.

-- 
Felipe Contreras

Re: [PATCH 1/2] user-manual: add global config section

[Michael J Gruber]

Felipe Contreras venit, vidit, dixit 14.10.2009 16:26:
> On Tue, Oct 13, 2009 at 10:19 AM, Michael J Gruber
> <git@drmicha.warpmail.net> wrote:
>> Felipe Contreras venit, vidit, dixit 12.10.2009 19:09:
>>> On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber
>>> <git@drmicha.warpmail.net> wrote:
>>>> Well, you do talk about "system" below, and that's about it. Also, the
>>>> configuration is not really distributed among different locations. Most
>>>> newbies interested in a *D*VCS will misunderstand this (as git having
>>>> distributed configuration).
>>>>
>>>> Alternative:
>>>>
>>>> Git's default configuration can be changed on a system wide, global (per
>>>> user) and local (per repository) level, in the order of increasing
>>>> precedence.
>>>
>>> When I read that it's not clear if the local level discards the global
>>> level completely or it's aggregated. If we specify that it's only the
>>> variables that take precedence it might be clearer:
>>>
>>> Git's configuration is composed of variables that are stored in
>>> multiple locations: 'system' (all users), 'global' (for the user), and
>>> 'repository' -- in decreasing order of precedence.
>>
>> Yep, although established lingo is "options" (not "variables"), and it's
>> really increasing order, not decreasing.
> 
> Really? I remember clearly Junio stating otherwise:
> http://marc.info/?l=git&m=123460371724873&w=2
> 
> ----
>> +	OPT_BOOLEAN(0, "unset", &do_unset, "removes an option: name [value-regex]"),
> 
> Please don't introduce a new noun "option" that has never been used to
> mean a "configuration variable" in git documentation.  It unnecessarily
> confuses everybody.
> ----

Well, Junio certainly is authoritative, and I don't want to risk any bad
patch-acceptance-fu ( :) ), but

2d2465c (Add documentation for git-config-set, 2005-11-17)

is the origin of that doc for git-config. I'm not just claiming it
myself. That commit introduced "option", uses it in all but one place,
and this never changed since then! [The ratio went up from 6:1 to 40:5]
I have no objection to changing this established notion, but established
it is. I haven't tracked down the use of option vs. variable in other
places than git-config.txt and its predecessors.

Michael

Re: [PATCH 1/2] user-manual: add global config section

[Junio C Hamano]

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

> Well, Junio certainly is authoritative, and I don't want to risk any bad

Even though I usually call them "configuration variables", I do not
consider myself authoritative in this particular issue, as I did not care
about the wording myself that much.  It is not like we have two (or three)
distinct concepts that the user need to be aware of among configuration
variable/option(/setting).  In other words, I never thought consistently
sticking to one variant matters that much for this particular case, and
I've used the word very casually and interchangeably, but except in one
specific context---see below.

I am open to be corrected by Documentation/glossary.txt and other sources.

> 2d2465c (Add documentation for git-config-set, 2005-11-17)
>
> is the origin of that doc for git-config. I'm not just claiming it
> myself. That commit introduced "option", uses it in all but one place,
> and this never changed since then! [The ratio went up from 6:1 to 40:5]
> I have no objection to changing this established notion, but established
> it is. I haven't tracked down the use of option vs. variable in other
> places than git-config.txt and its predecessors.

I am Ok with calling them "configuration options", and I am also Ok with
calling them just "options" when it is clear from the context that we are
talking about configuration file.

The _only_ thing I deliberately do is to avoid calling them configuration
"options" when discussing "command line options override what you have in
the configuration file", but even there I would use "settings" and
"variables" interchangeably.  E.g. both of these are fine with me:

    The settings in your .git/config file will give the default when there
    is no command line option given.

vs

    The variables in your .git/config file will give the default when
    there is no command line option given.

but personally I think it would make it less easier to follow if you
changed these "settings/variables" to "options".

Re: [PATCH 0/2] user-manual: reorganize the configuration steps

[J. Bruce Fields]

On Sun, Oct 11, 2009 at 11:43:04PM +0300, Felipe Contreras wrote:
> This basically introduces the "getting started" section so users get familiar
> with the configuration from the get-go, and also, most people prefer to teach
> 'git config --global' to setup the user name and email. Here are a few
> examples:

I'm not personally a big fan of starting out with a "how to use
git-config" section, because it's not that difficult or important:
questions we get on this list suggest confusion about a lot of things,
but git configuration is rarely one of them (that I've noticed).

I'd rather just point people to the git-config man page the first time
we mention any git configuration.  (And improve the man page if
necessary to ensure it's up to the job.)

If we have to do this, just keep it short....

--b.

> 
> git tutorial:
> http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
> 
> GNOME:
> http://live.gnome.org/Git/Developers
> 
> SourceForge:
> http://sourceforge.net/apps/trac/sourceforge/wiki/Git
> 
> github:
> http://help.github.com/git-email-settings/
> 
> Felipe Contreras (2):
>   user-manual: add global config section
>   user-manual: simplify the user configuration
> 
>  Documentation/user-manual.txt |   35 ++++++++++++++++++++++++++++++-----
>  1 files changed, 30 insertions(+), 5 deletions(-)
> 

Re: [PATCH 0/2] user-manual: reorganize the configuration steps

[Felipe Contreras]

On Wed, Oct 14, 2009 at 5:49 AM, J. Bruce Fields <bfields@citi.umich.edu> wrote:
> On Sun, Oct 11, 2009 at 11:43:04PM +0300, Felipe Contreras wrote:
>> This basically introduces the "getting started" section so users get familiar
>> with the configuration from the get-go, and also, most people prefer to teach
>> 'git config --global' to setup the user name and email. Here are a few
>> examples:
>
> I'm not personally a big fan of starting out with a "how to use
> git-config" section, because it's not that difficult or important:
> questions we get on this list suggest confusion about a lot of things,
> but git configuration is rarely one of them (that I've noticed).

Which means either people understand the configuration perfectly, look
somewhere else for that, or they don't do it at all.

Judging by the fact that most guides cover it at the beginning, and
people still send commits without proper user{.name,.email}, I would
say it is needed.

> I'd rather just point people to the git-config man page the first time
> we mention any git configuration.  (And improve the man page if
> necessary to ensure it's up to the job.)
>
> If we have to do this, just keep it short....

That's what I tried to do.

-- 
Felipe Contreras