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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 5, 2009, 09:47 UTC
Message-ID: <7v7i1zv3cg.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1238837909-3060-7-git-send-email-felipe.contreras@gmail.com>

Felipe Contreras <felipe.contreras@gmail.com> writes:

Show 12 quoted lines

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

Show 16 quoted lines

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

Show 7 quoted lines

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