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

[Junio C Hamano <gitster@pobox.com>]

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.

> +[[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.

> +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.

> +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".

Thanks.