On Sun, Apr 5, 2009 at 12:47 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > Felipe Contreras <felipe.contreras@xxxxxxxxx> writes: > >> Signed-off-by: Felipe Contreras <felipe.contreras@xxxxxxxxx> >> --- >> 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html