Felipe Contreras venit, vidit, dixit 12.10.2009 19:09: > On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber > <git@xxxxxxxxxxxxxxxxxxxx> 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@xxxxxxxxx> >>> --- >>> 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 -- 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