Re: [PATCH 6/7] user-manual: add global config section

[Felipe Contreras <felipe.contreras@gmail.com>]

On Sun, Apr 5, 2009 at 12:47 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
>> ---
>>  Documentation/user-manual.txt |   30 ++++++++++++++++++++++++++++++
>>  1 files changed, 30 insertions(+), 0 deletions(-)
>>
>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
>> index 3278aa7..a3032c7 100644
>> --- a/Documentation/user-manual.txt
>> +++ b/Documentation/user-manual.txt
>> @@ -40,6 +40,36 @@ without any explanation.
>>  Finally, see <<todo>> for ways that you can help make this manual more
>>  complete.
>
> I think a "getting started" section near the beginning of the manual is a
> good idea (and ll.40- is a very early part of the manual).
>
> For that "introductory" purpose, however, I'd suggest showing how they
> appear in the actual .git/config file first in the editor and then show a
> way to use the "git config" command as an alternative.

I disagree. Opening ~/.gitconfig will just open an empty file for the
new users, afterwards they'll just scratch their heads wondering, now
what?

If you first teach them to do 'git config --global color.ui auto'
they'll blindly enter the command but then when they open the file
they'll say "ahhh, so that's what happens".

>> +[[getting-started]]
>> +Getting started
>> +=============
>> +
>> +Git's configuration is distributed among different locations--this manual will
>> +only to deal with 'global' 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' (for the user) configuration.
>
> "(for the user)" in parentheses here is better than not saying it
> anywhere, but I think you should have it in the first paragraph where you
> explain there are (at least) two kinds, global vs repository, in order to
> clarify what you mean by 'global' is not "system/site wide" but "in any
> repository I use" upfront.

Ok.

>> +View and manually modify the configuration with the `--edit`
>> +option (which will use '$EDITOR'):
>> +------------------------------------------------
>> +$ git config --global --edit
>> +[color]
>> +        ui = auto
>> +------------------------------------------------
>
> Copies of user manual are found quite easily (and bookmarked by many
> people) on the web, and are looked at by people with not-so-bleeding-edge
> version of git, so I'd rather not to give them "config --edit" this early
> in the documentation.  Perhaps after at least 6 months (preferrably a
> year) after a release that has the new option, we can start encouraging
> it, but not before.  So I'd suggest replacing 'with the --edit ...'  with
> '$HOME/.gitconfig with your favorite editor' or something like that for
> now.

Good point.

>> +Or you can manually edit the file which is located in `~/.gitconfig`. Other
>> +locations are `/etc/gitconfig` (system), and `.git/config` (repository).
>
> IOW, have this (without "Or") at the very beginning, and then as an
> alternative give "git config color.ui auto".

Read my first comment.

I'll send another round of patches.

-- 
Felipe Contreras