{"thread":{"id":"21196","subject":"[PATCH 0/2] user-manual: reorganize the configuration steps","startedAt":"2009-10-11T20:43:04Z","lastAt":"2009-10-14T19:10:11Z","messageCount":13,"participants":["Felipe Contreras","Jonathan Nieder","Michael J Gruber","Junio C Hamano","J. Bruce Fields"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"124635","messageId":"1255293786-17293-1-git-send-email-felipe.contreras@gmail.com","threadId":"21196","inReplyTo":null,"subject":"[PATCH 0/2] user-manual: reorganize the configuration steps","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-11T20:43:04Z","receivedAt":"2009-10-11T20:43:04Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This basically introduces the \"getting started\" section so users get familiar\nwith the configuration from the get-go, and also, most people prefer to teach\n'git config --global' to setup the user name and email. Here are a few\nexamples:\n\ngit tutorial:\nhttp://www.kernel.org/pub/software/scm/git/docs/gittutorial.html\n\nGNOME:\nhttp://live.gnome.org/Git/Developers\n\nSourceForge:\nhttp://sourceforge.net/apps/trac/sourceforge/wiki/Git\n\ngithub:\nhttp://help.github.com/git-email-settings/\n\nFelipe Contreras (2):\n user-manual: add global config section\n user-manual: simplify the user configuration\n\n Documentation/user-manual.txt | 35 ++++++++++++++++++++++++++++++-----\n 1 files changed, 30 insertions(+), 5 deletions(-)\n"},{"id":"124639","messageId":"1255293786-17293-2-git-send-email-felipe.contreras@gmail.com","threadId":"21196","inReplyTo":"1255293786-17293-1-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH 1/2] user-manual: add global config section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-11T20:43:05Z","receivedAt":"2009-10-11T20:43:05Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"So that users get to know how to configure git from the get-to with good\npractical example (color.ui = auto) that most people would probably like\nanyway.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/user-manual.txt | 27 +++++++++++++++++++++++++++\n 1 files changed, 27 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 67ebffa..ff2563a 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -40,6 +40,33 @@ without any explanation.\n Finally, see <> for ways that you can help make this manual more\n complete.\n \n+[[getting-started]]\n+Getting started\n+=============\n+\n+Git's configuration is distributed among different locations--this manual will\n+only to deal with 'global' (for the user) and 'repository' variables, where\n+'repository' variables take precedence over 'global' ones.\n+\n+You would probably want to start setting up something useful:\n+------------------------------------------------\n+$ git config --global color.ui auto\n+------------------------------------------------\n+\n+This will make prettier the output of certain commands such as `git diff`, but\n+that's not important; what is important here is that `color.ui` has been\n+stored in the 'global' configuration.\n+\n+View and manually modify the configuration by opening `~/.gitconfig`:\n+------------------------------------------------\n+[color]\n+ ui = auto\n+------------------------------------------------\n+\n+Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).\n+\n+More git configurations will be covered in the rest of the manual, if you want\n+to learn more look at linkgit:git-config[1] for details.\n \n [[repositories-and-branches]]\n Repositories and Branches\n-- \n1.6.5.4.g31fc3\n"},{"id":"124641","messageId":"1255293786-17293-3-git-send-email-felipe.contreras@gmail.com","threadId":"21196","inReplyTo":"1255293786-17293-2-git-send-email-felipe.contreras@gmail.com","subject":"[PATCH 2/2] user-manual: simplify the user configuration","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-11T20:43:06Z","receivedAt":"2009-10-11T20:43:06Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This is shorter, avoids the burder to think about the format of the\nconfiguration file, and most guides out there prefer this form.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/user-manual.txt | 8 +++-----\n 1 files changed, 3 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex ff2563a..bab64f8 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1008,13 +1008,11 @@ Telling git your name\n ---------------------\n \n Before creating any commits, you should introduce yourself to git. The\n-easiest way to do so is to make sure the following lines appear in a\n-file named .gitconfig in your home directory:\n+easiest way is to use the linkgit:git-config[1] command:\n \n ------------------------------------------------\n-[user]\n-\tname = Your Name Comes Here\n-\temail = you@yourdomain.example.com\n+$ git config --global user.name \"Your Name Comes Here\"\n+$ git config --global user.email you@yourdomain.example.com\n ------------------------------------------------\n \n (See the \"CONFIGURATION FILE\" section of linkgit:git-config[1] for\n-- \n1.6.5.4.g31fc3\n"},{"id":"124648","messageId":"20091011222729.GA5114@progeny.tock","threadId":"21196","inReplyTo":"1255293786-17293-2-git-send-email-felipe.contreras@gmail.com","subject":"Re: [PATCH 1/2] user-manual: add global config section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2009-10-11T22:27:29Z","receivedAt":"2009-10-11T22:27:29Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Felipe Contreras wrote:\n> So that users get to know how to configure git from the get-to with good\n> practical example (color.ui = auto) that most people would probably like\n> anyway.\n> \n> Signed-off-by: Felipe Contreras \n\nGood idea. Some comments:\n\n> +Git's configuration is distributed among different locations--this manual will\n> +only to deal with 'global' (for the user) and 'repository' variables, where\n> +'repository' variables take precedence over 'global' ones.\n\nWhat are these different locations you speak of? If git’s configuration\nis complicated to deal with, maybe that is something that could be\nimproved.\n\nThis is very early in the manual, where every word counts. I am not\nvery good at wording and do not have any better suggestions, but would\nit be possible to more efficiently convey this:\n\n\tGit reads its per-user configuration from ~/.gitignore.\n\n\tThat file can also be manipulated with the \"git config\"\n\tcommand, which can be convenient in scripts or when using\n\toperating systems like Windows where it is not clear where\n\tthe home directory is.\n\n\tFor example, if your terminal supports it, you can tell Git\n\tto use color in the output for commands such as \"git diff\"\n\twith \"git config --global color.ui auto\".\n\n\tFor more information and a list of possible settings, see\n\tgit-config(1).\n\nBy the way, this reminds me that I am not sure git-config(1) conveys the\nlist of configuration items in an ideal way. It can be easy to dismiss\nthat page as plumbing documentation when seeing it for the first time.\nShould we ship a sample .gitconfig with all items included and comments\ndescribing them, or a separate gitconfig(5)? Either would be easy to\ngenerate from config.txt.\n\nThoughts?\nJonathan\n"},{"id":"124689","messageId":"4AD32024.6020005@drmicha.warpmail.net","threadId":"21196","inReplyTo":"1255293786-17293-2-git-send-email-felipe.contreras@gmail.com","subject":"Re: [PATCH 1/2] user-manual: add global config section","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-10-12T12:25:08Z","receivedAt":"2009-10-12T12:25:08Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Felipe Contreras venit, vidit, dixit 11.10.2009 22:43:\n> So that users get to know how to configure git from the get-to with good\n> practical example (color.ui = auto) that most people would probably like\n> anyway.\n> \n> Signed-off-by: Felipe Contreras \n> ---\n> Documentation/user-manual.txt | 27 +++++++++++++++++++++++++++\n> 1 files changed, 27 insertions(+), 0 deletions(-)\n> \n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index 67ebffa..ff2563a 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -40,6 +40,33 @@ without any explanation.\n> Finally, see <> for ways that you can help make this manual more\n> complete.\n> \n> +[[getting-started]]\n> +Getting started\n> +=============\n> +\n> +Git's configuration is distributed among different locations--this manual will\n> +only to deal with 'global' (for the user) and 'repository' variables, where\n> +'repository' variables take precedence over 'global' ones.\n\nWell, you do talk about \"system\" below, and that's about it. Also, the\nconfiguration is not really distributed among different locations. Most\nnewbies interested in a *D*VCS will misunderstand this (as git having\ndistributed configuration).\n\nAlternative:\n\nGit's default configuration can be changed on a system wide, global (per\nuser) and local (per repository) level, in the order of increasing\nprecedence.\n\n> +\n> +You would probably want to start setting up something useful:\n> +------------------------------------------------\n> +$ git config --global color.ui auto\n> +------------------------------------------------\n> +\n> +This will make prettier the output of certain commands such as `git diff`, but\n> +that's not important; what is important here is that `color.ui` has been\n> +stored in the 'global' configuration.\n\nThis will make certain commands such as `git diff` use colors in the\noutput. What is important here is that the value `auto` for the option\n`color.ui` has been stored in the 'global' configuration. Use `--system`\nfor the system wide configuration; specifying neither `--system` nor\n`--global` makes `git config` access the local configuration.\n\n> +\n> +View and manually modify the configuration by opening `~/.gitconfig`:\n\nView and manually modify the global configuration by opening\n`~/.gitconfig` in your editor or using `git config --global --edit`:\n\n> +------------------------------------------------\n> +[color]\n> + ui = auto\n> +------------------------------------------------\n> +\n> +Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).\n\nI don't even think we should talk about locations here, \"git config -e\"\nshould be the first user's way to do it.\n\n> +\n> +More git configurations will be covered in the rest of the manual, if you want\n> +to learn more look at linkgit:git-config[1] for details.\n\n\"Configurations\" is ambiguous, it can be easily (mis)understood as\n\"types of configuration\" (global, local etc.). Also, the above doesn't\nreally cover even one option. How about:\n\nThis manual covers many configuration options (such as `color.ui.`). For\nmore details on the `git config` command as well as all configuration\noptions see linkgit:git-config[1].\n\n> [[repositories-and-branches]]\n> Repositories and Branches\n\nCheers,\nMichael\n"},{"id":"124717","messageId":"94a0d4530910121009r52d45522jf1c27dd102db4ad9@mail.gmail.com","threadId":"21196","inReplyTo":"4AD32024.6020005@drmicha.warpmail.net","subject":"Re: [PATCH 1/2] user-manual: add global config section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-12T17:09:32Z","receivedAt":"2009-10-12T17:09:32Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber\n wrote:\n> Felipe Contreras venit, vidit, dixit 11.10.2009 22:43:\n>> So that users get to know how to configure git from the get-to with good\n>> practical example (color.ui = auto) that most people would probably like\n>> anyway.\n>>\n>> Signed-off-by: Felipe Contreras \n>> ---\n>>  Documentation/user-manual.txt |   27 +++++++++++++++++++++++++++\n>>  1 files changed, 27 insertions(+), 0 deletions(-)\n>>\n>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n>> index 67ebffa..ff2563a 100644\n>> --- a/Documentation/user-manual.txt\n>> +++ b/Documentation/user-manual.txt\n>> @@ -40,6 +40,33 @@ without any explanation.\n>>  Finally, see <> for ways that you can help make this manual more\n>>  complete.\n>>\n>> +[[getting-started]]\n>> +Getting started\n>> +=============\n>> +\n>> +Git's configuration is distributed among different locations--this manual will\n>> +only to deal with 'global' (for the user) and 'repository' variables, where\n>> +'repository' variables take precedence over 'global' ones.\n>\n> Well, you do talk about \"system\" below, and that's about it. Also, the\n> configuration is not really distributed among different locations. Most\n> newbies interested in a *D*VCS will misunderstand this (as git having\n> distributed configuration).\n>\n> Alternative:\n>\n> Git's default configuration can be changed on a system wide, global (per\n> user) and local (per repository) level, in the order of increasing\n> precedence.\n\nWhen I read that it's not clear if the local level discards the global\nlevel completely or it's aggregated. If we specify that it's only the\nvariables that take precedence it might be clearer:\n\nGit's configuration is composed of variables that are stored in\nmultiple locations: 'system' (all users), 'global' (for the user), and\n'repository' -- in decreasing order of precedence.\n\n>> +\n>> +You would probably want to start setting up something useful:\n>> +------------------------------------------------\n>> +$ git config --global color.ui auto\n>> +------------------------------------------------\n>> +\n>> +This will make prettier the output of certain commands such as `git diff`, but\n>> +that's not important; what is important here is that `color.ui` has been\n>> +stored in the 'global' configuration.\n>\n> This will make certain commands such as `git diff` use colors in the\n> output. What is important here is that the value `auto` for the option\n> `color.ui` has been stored in the 'global' configuration. Use `--system`\n> for the system wide configuration; specifying neither `--system` nor\n> `--global` makes `git config` access the local configuration.\n\nI think we should only mention (once) the system wide configuration,\nbut not cover it. That's for system administrators, not users.\n\n>> +\n>> +View and manually modify the configuration by opening `~/.gitconfig`:\n>\n> View and manually modify the global configuration by opening\n> `~/.gitconfig` in your editor or using `git config --global --edit`:\n\nI have separate patches for 'git config --edit', but Junio suggested\nto hold them back because --edit is a relatively new option.\n\n>> +------------------------------------------------\n>> +[color]\n>> +        ui = auto\n>> +------------------------------------------------\n>> +\n>> +Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).\n>\n> I don't even think we should talk about locations here, \"git config -e\"\n> should be the first user's way to do it.\n\nI disagree. Most useful configurations (color.ui, user.email) should\nbe global. The complete newbie might think: cool, now I have my git\nproperly configured (with 'git config -e'), and then when cloning a\nnew repo (s)he would think: ok, git just forgot what I told him. When\nthat happens (s)he would have to re-learn and re-configure git.\n\nWhen users think about configuration, it's usually a 'global'\nconfiguration, so that's what we should teach from the beginning and\nmake sure they understand the difference between 'global' and\n'repository' configurations.\n\n>> +\n>> +More git configurations will be covered in the rest of the manual, if you want\n>> +to learn more look at linkgit:git-config[1] for details.\n>\n> \"Configurations\" is ambiguous, it can be easily (mis)understood as\n> \"types of configuration\" (global, local etc.). Also, the above doesn't\n> really cover even one option. How about:\n>\n> This manual covers many configuration options (such as `color.ui.`). For\n> more details on the `git config` command as well as all configuration\n> options see linkgit:git-config[1].\n\nLooks better, except s/configuration options/configuration variables/\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"124756","messageId":"7vws30cof4.fsf@alter.siamese.dyndns.org","threadId":"21196","inReplyTo":"20091011222729.GA5114@progeny.tock","subject":"Re: [PATCH 1/2] user-manual: add global config section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-12T21:06:39Z","receivedAt":"2009-10-12T21:06:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> This is very early in the manual, where every word counts. I am not\n> very good at wording and do not have any better suggestions, but would\n> it be possible to more efficiently convey this:\n>\n> \tGit reads its per-user configuration from ~/.gitignore.\n>\n> \tThat file can also be manipulated with the \"git config\"\n> \tcommand, which can be convenient in scripts or when using\n> \toperating systems like Windows where it is not clear where\n> \tthe home directory is.\n>\n> \tFor example, if your terminal supports it, you can tell Git\n> \tto use color in the output for commands such as \"git diff\"\n> \twith \"git config --global color.ui auto\".\n>\n> \tFor more information and a list of possible settings, see\n> \tgit-config(1).\n\nThe way how the above introduces the \"git config\" command to people who\nsee git for the first time makes sense. Unfortunately, --global and\nper-user do not \"click\" together when given in isolation, and I think it\nwould help if it is explained this way, using a setting that can validly\nbe either per-user or project specific:\n\n Various configuration variables affect how git operates. Some are\n specific to the user (e.g. if you prefer to see the output in colour),\n while some are specific to a repository (e.g. what other repositories\n it interacts with). Git reads from ~/.gitconfig file to learn your\n personal settings and .git/config file of the repository you are\n working in to learn the repository settings.\n\n These are plain text files that you can view or edit in your text\n editor, but they also can be manipulated with the \"git config\"\n command, which is convenient in scripts or ...\n\n For example, if you want to use a particular e-mail address only while\n working in the current repository, you would set \"user.email\" variable\n to that e-mail address in the repository configuration file (i.e.\n .git/config) with this command:\n\n\tgit config user.email your@email.address.xz\n\n If on the other hand you want to use the same address for any project\n you work with, you can instead set this in your personal configuration\n file (i.e. ~/.gitconfig) with this command:\n\n\tgit config --global user.email your@email.address.xz\n\n For more information ...\n\nSince this is an end-user material, I deliberately omitted talking about\nthe --system (i.e. /etc/gitconfig) in the above.\n"},{"id":"124824","messageId":"4AD42A1C.1080709@drmicha.warpmail.net","threadId":"21196","inReplyTo":"94a0d4530910121009r52d45522jf1c27dd102db4ad9@mail.gmail.com","subject":"Re: [PATCH 1/2] user-manual: add global config section","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-10-13T07:19:56Z","receivedAt":"2009-10-13T07:19:56Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Felipe Contreras venit, vidit, dixit 12.10.2009 19:09:\n> On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber\n> wrote:\n>> Felipe Contreras venit, vidit, dixit 11.10.2009 22:43:\n>>> So that users get to know how to configure git from the get-to with good\n>>> practical example (color.ui = auto) that most people would probably like\n>>> anyway.\n>>>\n>>> Signed-off-by: Felipe Contreras \n>>> ---\n>>> Documentation/user-manual.txt | 27 +++++++++++++++++++++++++++\n>>> 1 files changed, 27 insertions(+), 0 deletions(-)\n>>>\n>>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n>>> index 67ebffa..ff2563a 100644\n>>> --- a/Documentation/user-manual.txt\n>>> +++ b/Documentation/user-manual.txt\n>>> @@ -40,6 +40,33 @@ without any explanation.\n>>> Finally, see <> for ways that you can help make this manual more\n>>> complete.\n>>>\n>>> +[[getting-started]]\n>>> +Getting started\n>>> +=============\n>>> +\n>>> +Git's configuration is distributed among different locations--this manual will\n>>> +only to deal with 'global' (for the user) and 'repository' variables, where\n>>> +'repository' variables take precedence over 'global' ones.\n>>\n>> Well, you do talk about \"system\" below, and that's about it. Also, the\n>> configuration is not really distributed among different locations. Most\n>> newbies interested in a *D*VCS will misunderstand this (as git having\n>> distributed configuration).\n>>\n>> Alternative:\n>>\n>> Git's default configuration can be changed on a system wide, global (per\n>> user) and local (per repository) level, in the order of increasing\n>> precedence.\n> \n> When I read that it's not clear if the local level discards the global\n> level completely or it's aggregated. If we specify that it's only the\n> variables that take precedence it might be clearer:\n> \n> Git's configuration is composed of variables that are stored in\n> multiple locations: 'system' (all users), 'global' (for the user), and\n> 'repository' -- in decreasing order of precedence.\n\nYep, although established lingo is \"options\" (not \"variables\"), and it's\nreally increasing order, not decreasing.\n\n> \n>>> +\n>>> +You would probably want to start setting up something useful:\n>>> +------------------------------------------------\n>>> +$ git config --global color.ui auto\n>>> +------------------------------------------------\n>>> +\n>>> +This will make prettier the output of certain commands such as `git diff`, but\n>>> +that's not important; what is important here is that `color.ui` has been\n>>> +stored in the 'global' configuration.\n>>\n>> This will make certain commands such as `git diff` use colors in the\n>> output. What is important here is that the value `auto` for the option\n>> `color.ui` has been stored in the 'global' configuration. Use `--system`\n>> for the system wide configuration; specifying neither `--system` nor\n>> `--global` makes `git config` access the local configuration.\n> \n> I think we should only mention (once) the system wide configuration,\n> but not cover it. That's for system administrators, not users.\n> \n>>> +\n>>> +View and manually modify the configuration by opening `~/.gitconfig`:\n>>\n>> View and manually modify the global configuration by opening\n>> `~/.gitconfig` in your editor or using `git config --global --edit`:\n> \n> I have separate patches for 'git config --edit', but Junio suggested\n> to hold them back because --edit is a relatively new option.\n> \n>>> +------------------------------------------------\n>>> +[color]\n>>> + ui = auto\n>>> +------------------------------------------------\n>>> +\n>>> +Other locations are `/etc/gitconfig` (system), and `.git/config` (repository).\n>>\n>> I don't even think we should talk about locations here, \"git config -e\"\n>> should be the first user's way to do it.\n> \n> I disagree. Most useful configurations (color.ui, user.email) should\n> be global. The complete newbie might think: cool, now I have my git\n> properly configured (with 'git config -e'), and then when cloning a\n> new repo (s)he would think: ok, git just forgot what I told him. When\n> that happens (s)he would have to re-learn and re-configure git.\n> \n> When users think about configuration, it's usually a 'global'\n> configuration, so that's what we should teach from the beginning and\n> make sure they understand the difference between 'global' and\n> 'repository' configurations.\n\nSure. What I meant are the file locations, the actual paths. First\ntimers should use \"git config -e\" and \"git config --global -e\" if they\nreally want to edit their local and global config files. Better yet,\nthey should use \"git config\" and \"git config --global\" in their set and\nget modes, because they make sure that there's no total garbage in the\nconfig. The locations of the files are an implementation detail.\n\n> \n>>> +\n>>> +More git configurations will be covered in the rest of the manual, if you want\n>>> +to learn more look at linkgit:git-config[1] for details.\n>>\n>> \"Configurations\" is ambiguous, it can be easily (mis)understood as\n>> \"types of configuration\" (global, local etc.). Also, the above doesn't\n>> really cover even one option. How about:\n>>\n>> This manual covers many configuration options (such as `color.ui.`). For\n>> more details on the `git config` command as well as all configuration\n>> options see linkgit:git-config[1].\n> \n> Looks better, except s/configuration options/configuration variables/\n> \n\nUhm, no, for the reason mentioned above. While the man page of git\nconfig is not completely consistent either, we're really talking about\nconfiguration options. An \"option\" can be set to a \"value\", and the\nthing you pass in order to do that can be called a \"variable\". For the\nmost part this is how git-config[1] uses this terminology.\n\nMichael\n"},{"id":"124919","messageId":"20091014024940.GB9700@fieldses.org","threadId":"21196","inReplyTo":"1255293786-17293-1-git-send-email-felipe.contreras@gmail.com","subject":"Re: [PATCH 0/2] user-manual: reorganize the configuration steps","fromName":"J. Bruce Fields","fromEmail":"bfields@citi.umich.edu","sentAt":"2009-10-14T02:49:40Z","receivedAt":"2009-10-14T02:49:40Z","isPatch":true,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"On Sun, Oct 11, 2009 at 11:43:04PM +0300, Felipe Contreras wrote:\n> This basically introduces the \"getting started\" section so users get familiar\n> with the configuration from the get-go, and also, most people prefer to teach\n> 'git config --global' to setup the user name and email. Here are a few\n> examples:\n\nI'm not personally a big fan of starting out with a \"how to use\ngit-config\" section, because it's not that difficult or important:\nquestions we get on this list suggest confusion about a lot of things,\nbut git configuration is rarely one of them (that I've noticed).\n\nI'd rather just point people to the git-config man page the first time\nwe mention any git configuration. (And improve the man page if\nnecessary to ensure it's up to the job.)\n\nIf we have to do this, just keep it short....\n\n--b.\n\n> \n> git tutorial:\n> http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html\n> \n> GNOME:\n> http://live.gnome.org/Git/Developers\n> \n> SourceForge:\n> http://sourceforge.net/apps/trac/sourceforge/wiki/Git\n> \n> github:\n> http://help.github.com/git-email-settings/\n> \n> Felipe Contreras (2):\n> user-manual: add global config section\n> user-manual: simplify the user configuration\n> \n> Documentation/user-manual.txt | 35 ++++++++++++++++++++++++++++++-----\n> 1 files changed, 30 insertions(+), 5 deletions(-)\n> \n"},{"id":"124974","messageId":"94a0d4530910140714i64c0b5f7gdb8ec4c95e3d2e7f@mail.gmail.com","threadId":"21196","inReplyTo":"20091014024940.GB9700@fieldses.org","subject":"Re: [PATCH 0/2] user-manual: reorganize the configuration steps","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-14T14:14:22Z","receivedAt":"2009-10-14T14:14:22Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Wed, Oct 14, 2009 at 5:49 AM, J. Bruce Fields wrote:\n> On Sun, Oct 11, 2009 at 11:43:04PM +0300, Felipe Contreras wrote:\n>> This basically introduces the \"getting started\" section so users get familiar\n>> with the configuration from the get-go, and also, most people prefer to teach\n>> 'git config --global' to setup the user name and email. Here are a few\n>> examples:\n>\n> I'm not personally a big fan of starting out with a \"how to use\n> git-config\" section, because it's not that difficult or important:\n> questions we get on this list suggest confusion about a lot of things,\n> but git configuration is rarely one of them (that I've noticed).\n\nWhich means either people understand the configuration perfectly, look\nsomewhere else for that, or they don't do it at all.\n\nJudging by the fact that most guides cover it at the beginning, and\npeople still send commits without proper user{.name,.email}, I would\nsay it is needed.\n\n> I'd rather just point people to the git-config man page the first time\n> we mention any git configuration.  (And improve the man page if\n> necessary to ensure it's up to the job.)\n>\n> If we have to do this, just keep it short....\n\nThat's what I tried to do.\n\n-- \nFelipe Contreras\n"},{"id":"124975","messageId":"94a0d4530910140726i4465e919h77045904aa33c61a@mail.gmail.com","threadId":"21196","inReplyTo":"4AD42A1C.1080709@drmicha.warpmail.net","subject":"Re: [PATCH 1/2] user-manual: add global config section","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-10-14T14:26:39Z","receivedAt":"2009-10-14T14:26:39Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Tue, Oct 13, 2009 at 10:19 AM, Michael J Gruber\n wrote:\n> Felipe Contreras venit, vidit, dixit 12.10.2009 19:09:\n>> On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber\n>> wrote:\n>>> Well, you do talk about \"system\" below, and that's about it. Also, the\n>>> configuration is not really distributed among different locations. Most\n>>> newbies interested in a *D*VCS will misunderstand this (as git having\n>>> distributed configuration).\n>>>\n>>> Alternative:\n>>>\n>>> Git's default configuration can be changed on a system wide, global (per\n>>> user) and local (per repository) level, in the order of increasing\n>>> precedence.\n>>\n>> When I read that it's not clear if the local level discards the global\n>> level completely or it's aggregated. If we specify that it's only the\n>> variables that take precedence it might be clearer:\n>>\n>> Git's configuration is composed of variables that are stored in\n>> multiple locations: 'system' (all users), 'global' (for the user), and\n>> 'repository' -- in decreasing order of precedence.\n>\n> Yep, although established lingo is \"options\" (not \"variables\"), and it's\n> really increasing order, not decreasing.\n\nReally? I remember clearly Junio stating otherwise:\nhttp://marc.info/?l=git&m=123460371724873&w=2\n\n----\n> +\tOPT_BOOLEAN(0, \"unset\", &do_unset, \"removes an option: name [value-regex]\"),\n\nPlease don't introduce a new noun \"option\" that has never been used to\nmean a \"configuration variable\" in git documentation. It unnecessarily\nconfuses everybody.\n----\n\n>> I disagree. Most useful configurations (color.ui, user.email) should\n>> be global. The complete newbie might think: cool, now I have my git\n>> properly configured (with 'git config -e'), and then when cloning a\n>> new repo (s)he would think: ok, git just forgot what I told him. When\n>> that happens (s)he would have to re-learn and re-configure git.\n>>\n>> When users think about configuration, it's usually a 'global'\n>> configuration, so that's what we should teach from the beginning and\n>> make sure they understand the difference between 'global' and\n>> 'repository' configurations.\n>\n> Sure. What I meant are the file locations, the actual paths. First\n> timers should use \"git config -e\" and \"git config --global -e\" if they\n> really want to edit their local and global config files. Better yet,\n> they should use \"git config\" and \"git config --global\" in their set and\n> get modes, because they make sure that there's no total garbage in the\n> config. The locations of the files are an implementation detail.\n\nOh, in that case I agree.\n\n>> Looks better, except s/configuration options/configuration variables/\n>>\n>\n> Uhm, no, for the reason mentioned above. While the man page of git\n> config is not completely consistent either, we're really talking about\n> configuration options. An \"option\" can be set to a \"value\", and the\n> thing you pass in order to do that can be called a \"variable\". For the\n> most part this is how git-config[1] uses this terminology.\n\nYeah, but not everything in there is an option. Personally I would\nprefer the \"option\" term, but as I said, Junio disagreed some time\nago.\n\n-- \nFelipe Contreras\n"},{"id":"124988","messageId":"4AD5F7BE.9000704@drmicha.warpmail.net","threadId":"21196","inReplyTo":"94a0d4530910140726i4465e919h77045904aa33c61a@mail.gmail.com","subject":"Re: [PATCH 1/2] user-manual: add global config section","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-10-14T16:09:34Z","receivedAt":"2009-10-14T16:09:34Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Felipe Contreras venit, vidit, dixit 14.10.2009 16:26:\n> On Tue, Oct 13, 2009 at 10:19 AM, Michael J Gruber\n> wrote:\n>> Felipe Contreras venit, vidit, dixit 12.10.2009 19:09:\n>>> On Mon, Oct 12, 2009 at 3:25 PM, Michael J Gruber\n>>> wrote:\n>>>> Well, you do talk about \"system\" below, and that's about it. Also, the\n>>>> configuration is not really distributed among different locations. Most\n>>>> newbies interested in a *D*VCS will misunderstand this (as git having\n>>>> distributed configuration).\n>>>>\n>>>> Alternative:\n>>>>\n>>>> Git's default configuration can be changed on a system wide, global (per\n>>>> user) and local (per repository) level, in the order of increasing\n>>>> precedence.\n>>>\n>>> When I read that it's not clear if the local level discards the global\n>>> level completely or it's aggregated. If we specify that it's only the\n>>> variables that take precedence it might be clearer:\n>>>\n>>> Git's configuration is composed of variables that are stored in\n>>> multiple locations: 'system' (all users), 'global' (for the user), and\n>>> 'repository' -- in decreasing order of precedence.\n>>\n>> Yep, although established lingo is \"options\" (not \"variables\"), and it's\n>> really increasing order, not decreasing.\n> \n> Really? I remember clearly Junio stating otherwise:\n> http://marc.info/?l=git&m=123460371724873&w=2\n> \n> ----\n>> +\tOPT_BOOLEAN(0, \"unset\", &do_unset, \"removes an option: name [value-regex]\"),\n> \n> Please don't introduce a new noun \"option\" that has never been used to\n> mean a \"configuration variable\" in git documentation. It unnecessarily\n> confuses everybody.\n> ----\n\nWell, Junio certainly is authoritative, and I don't want to risk any bad\npatch-acceptance-fu ( :) ), but\n\n2d2465c (Add documentation for git-config-set, 2005-11-17)\n\nis the origin of that doc for git-config. I'm not just claiming it\nmyself. That commit introduced \"option\", uses it in all but one place,\nand this never changed since then! [The ratio went up from 6:1 to 40:5]\nI have no objection to changing this established notion, but established\nit is. I haven't tracked down the use of option vs. variable in other\nplaces than git-config.txt and its predecessors.\n\nMichael\n"},{"id":"125008","messageId":"7vzl7tdc6k.fsf@alter.siamese.dyndns.org","threadId":"21196","inReplyTo":"4AD5F7BE.9000704@drmicha.warpmail.net","subject":"Re: [PATCH 1/2] user-manual: add global config section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-10-14T19:10:11Z","receivedAt":"2009-10-14T19:10:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> Well, Junio certainly is authoritative, and I don't want to risk any bad\n\nEven though I usually call them \"configuration variables\", I do not\nconsider myself authoritative in this particular issue, as I did not care\nabout the wording myself that much. It is not like we have two (or three)\ndistinct concepts that the user need to be aware of among configuration\nvariable/option(/setting). In other words, I never thought consistently\nsticking to one variant matters that much for this particular case, and\nI've used the word very casually and interchangeably, but except in one\nspecific context---see below.\n\nI am open to be corrected by Documentation/glossary.txt and other sources.\n\n> 2d2465c (Add documentation for git-config-set, 2005-11-17)\n>\n> is the origin of that doc for git-config. I'm not just claiming it\n> myself. That commit introduced \"option\", uses it in all but one place,\n> and this never changed since then! [The ratio went up from 6:1 to 40:5]\n> I have no objection to changing this established notion, but established\n> it is. I haven't tracked down the use of option vs. variable in other\n> places than git-config.txt and its predecessors.\n\nI am Ok with calling them \"configuration options\", and I am also Ok with\ncalling them just \"options\" when it is clear from the context that we are\ntalking about configuration file.\n\nThe _only_ thing I deliberately do is to avoid calling them configuration\n\"options\" when discussing \"command line options override what you have in\nthe configuration file\", but even there I would use \"settings\" and\n\"variables\" interchangeably. E.g. both of these are fine with me:\n\n The settings in your .git/config file will give the default when there\n is no command line option given.\n\nvs\n\n The variables in your .git/config file will give the default when\n there is no command line option given.\n\nbut personally I think it would make it less easier to follow if you\nchanged these \"settings/variables\" to \"options\".\n"}]}