* [PATCH v2 0/2] user-manual: new "getting started" section @ 2009-10-24 9:44 Felipe Contreras 2009-10-24 9:44 ` [PATCH v2 1/2] user-manual: add global config section Felipe Contreras ` (3 more replies) 0 siblings, 4 replies; 28+ messages in thread From: Felipe Contreras @ 2009-10-24 9:44 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Michael J Gruber, Jonathan Nieder, Felipe Contreras This basically introduces the "getting started" section so users get familiar with the configuration from the get-go, and also, most people prefer to teach 'git config --global' to setup the user name and email. Here are a few examples: git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html GNOME: http://live.gnome.org/Git/Developers SourceForge: http://sourceforge.net/apps/trac/sourceforge/wiki/Git github: http://help.github.com/git-email-settings/ v2: Reworded the getting started section based on comments from Michael J Gruber, Jonathan Nieder and Junio C Hamano. Felipe Contreras (2): user-manual: add global config section user-manual: simplify the user configuration Documentation/user-manual.txt | 37 ++++++++++++++++++++++++++++++++----- 1 files changed, 32 insertions(+), 5 deletions(-) ^ permalink raw reply [flat|nested] 28+ messages in thread
* [PATCH v2 1/2] user-manual: add global config section 2009-10-24 9:44 [PATCH v2 0/2] user-manual: new "getting started" section Felipe Contreras @ 2009-10-24 9:44 ` Felipe Contreras 2009-10-24 9:44 ` [PATCH v2 2/2] user-manual: simplify the user configuration Felipe Contreras ` (2 subsequent siblings) 3 siblings, 0 replies; 28+ messages in thread From: Felipe Contreras @ 2009-10-24 9:44 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Michael J Gruber, Jonathan Nieder, Felipe Contreras Comments from Michael J Gruber, Jonathan Nieder and Junio C Hamano. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/user-manual.txt | 29 +++++++++++++++++++++++++++++ 1 files changed, 29 insertions(+), 0 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 67ebffa..3fcbc36 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -40,6 +40,35 @@ without any explanation. Finally, see <<todo>> for ways that you can help make this manual more complete. +[[getting-started]] +Getting started +============= + +Various configuration options affect how git operates. Some are specific to +the user (e.g. if you prefer to see the output in colour), while some are +specific to a repository (e.g. what other repositories it interacts with). + +For example, you can tell git to use color in the output of commands such as +`git diff` by setting the `color.ui` option: +------------------------------------------------ +$ git config --global color.ui auto +------------------------------------------------ + +Note that in this case the option is stored in the 'global' configuration. If +you don't specify `--global`, then the option will be stored on the local +(repository) configuration, which is probably not what you want. + +The options are stored in plain text files that you can view, or edit manually +using the `--edit` option, and the format is very simple: +------------------------------------------------ +$ git config --global --edit +[color] + ui = auto +------------------------------------------------ + +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]. [[repositories-and-branches]] Repositories and Branches -- 1.6.5.1 ^ permalink raw reply related [flat|nested] 28+ messages in thread
* [PATCH v2 2/2] user-manual: simplify the user configuration 2009-10-24 9:44 [PATCH v2 0/2] user-manual: new "getting started" section Felipe Contreras 2009-10-24 9:44 ` [PATCH v2 1/2] user-manual: add global config section Felipe Contreras @ 2009-10-24 9:44 ` Felipe Contreras 2009-10-24 13:06 ` [PATCH v2 0/2] user-manual: new "getting started" section Nanako Shiraishi 2009-10-24 17:51 ` Junio C Hamano 3 siblings, 0 replies; 28+ messages in thread From: Felipe Contreras @ 2009-10-24 9:44 UTC (permalink / raw) To: git; +Cc: Junio C Hamano, Michael J Gruber, Jonathan Nieder, Felipe Contreras This is shorter, avoids the burder to think about the format of the configuration file, and git config is already used in other places in the manual. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/user-manual.txt | 8 +++----- 1 files changed, 3 insertions(+), 5 deletions(-) diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 3fcbc36..a0a75af 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1010,13 +1010,11 @@ Telling git your name --------------------- Before creating any commits, you should introduce yourself to git. The -easiest way to do so is to make sure the following lines appear in a -file named .gitconfig in your home directory: +easiest way is to use the linkgit:git-config[1] command: ------------------------------------------------ -[user] - name = Your Name Comes Here - email = you@yourdomain.example.com +$ git config --global user.name "Your Name Comes Here" +$ git config --global user.email you@yourdomain.example.com ------------------------------------------------ (See the "CONFIGURATION FILE" section of linkgit:git-config[1] for -- 1.6.5.1 ^ permalink raw reply related [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 9:44 [PATCH v2 0/2] user-manual: new "getting started" section Felipe Contreras 2009-10-24 9:44 ` [PATCH v2 1/2] user-manual: add global config section Felipe Contreras 2009-10-24 9:44 ` [PATCH v2 2/2] user-manual: simplify the user configuration Felipe Contreras @ 2009-10-24 13:06 ` Nanako Shiraishi 2009-10-24 14:08 ` Felipe Contreras 2009-10-24 17:51 ` Junio C Hamano 3 siblings, 1 reply; 28+ messages in thread From: Nanako Shiraishi @ 2009-10-24 13:06 UTC (permalink / raw) To: Felipe Contreras; +Cc: git, Junio C Hamano, Michael J Gruber, Jonathan Nieder Quoting Felipe Contreras <felipe.contreras@gmail.com> writes: > ... > Reworded the getting started section based on comments from Michael J Gruber, > Jonathan Nieder and Junio C Hamano. I'm surprised that you ignored comments from the original author of the document you are updating. Date: Tue, 13 Oct 2009 22:49:40 -0400 Message-ID: <20091014024940.GB9700@fieldses.org> -- Nanako Shiraishi http://ivory.ap.teacup.com/nanako3/ ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 13:06 ` [PATCH v2 0/2] user-manual: new "getting started" section Nanako Shiraishi @ 2009-10-24 14:08 ` Felipe Contreras 2009-10-24 14:14 ` Björn Steinbrink 0 siblings, 1 reply; 28+ messages in thread From: Felipe Contreras @ 2009-10-24 14:08 UTC (permalink / raw) To: Nanako Shiraishi; +Cc: git, Junio C Hamano, Michael J Gruber, Jonathan Nieder On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote: > Quoting Felipe Contreras <felipe.contreras@gmail.com> writes: > >> ... >> Reworded the getting started section based on comments from Michael J Gruber, >> Jonathan Nieder and Junio C Hamano. > > I'm surprised that you ignored comments from the original > author of the document you are updating. I did not. His comment was that if we do this, it must be short, and it is. If it's not, then it would be more productive to suggest ways to trim it down. > Date: Tue, 13 Oct 2009 22:49:40 -0400 > Message-ID: <20091014024940.GB9700@fieldses.org> I've no way of figuring out what is that. Most people use a direct link to a mail archive. -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 14:08 ` Felipe Contreras @ 2009-10-24 14:14 ` Björn Steinbrink 2009-10-24 14:22 ` Felipe Contreras 0 siblings, 1 reply; 28+ messages in thread From: Björn Steinbrink @ 2009-10-24 14:14 UTC (permalink / raw) To: Felipe Contreras Cc: Nanako Shiraishi, git, Junio C Hamano, Michael J Gruber, Jonathan Nieder On 2009.10.24 17:08:06 +0300, Felipe Contreras wrote: > On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote: > > Date: Tue, 13 Oct 2009 22:49:40 -0400 > > Message-ID: <20091014024940.GB9700@fieldses.org> > > I've no way of figuring out what is that. Most people use a direct > link to a mail archive. Having the Message-ID is quite useful, so you can search your local mbox to find the right message. You can also use gmane's Message-ID search: http://mid.gmane.org/message_id_here So: http://mid.gmane.org/20091014024940.GB9700@fieldses.org Björn ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 14:14 ` Björn Steinbrink @ 2009-10-24 14:22 ` Felipe Contreras 0 siblings, 0 replies; 28+ messages in thread From: Felipe Contreras @ 2009-10-24 14:22 UTC (permalink / raw) To: Björn Steinbrink Cc: Nanako Shiraishi, git, Junio C Hamano, Michael J Gruber, Jonathan Nieder 2009/10/24 Björn Steinbrink <B.Steinbrink@gmx.de>: > On 2009.10.24 17:08:06 +0300, Felipe Contreras wrote: >> On Sat, Oct 24, 2009 at 4:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote: >> > Date: Tue, 13 Oct 2009 22:49:40 -0400 >> > Message-ID: <20091014024940.GB9700@fieldses.org> >> >> I've no way of figuring out what is that. Most people use a direct >> link to a mail archive. > > Having the Message-ID is quite useful, so you can search your local mbox > to find the right message. I don't have a local mbox, and I suspect I'm not the only one. > You can also use gmane's Message-ID search: > http://mid.gmane.org/message_id_here That's a nice trick, but then using the following link would serve exactly the same purpose, wouldn't it? > So: http://mid.gmane.org/20091014024940.GB9700@fieldses.org -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 9:44 [PATCH v2 0/2] user-manual: new "getting started" section Felipe Contreras ` (2 preceding siblings ...) 2009-10-24 13:06 ` [PATCH v2 0/2] user-manual: new "getting started" section Nanako Shiraishi @ 2009-10-24 17:51 ` Junio C Hamano 2009-10-24 18:19 ` Junio C Hamano 3 siblings, 1 reply; 28+ messages in thread From: Junio C Hamano @ 2009-10-24 17:51 UTC (permalink / raw) To: Felipe Contreras; +Cc: git, Junio C Hamano, Michael J Gruber, Jonathan Nieder Felipe Contreras <felipe.contreras@gmail.com> writes: > Reworded the getting started section based on comments from Michael J Gruber, > Jonathan Nieder and Junio C Hamano. Hmm, I thought JBF also had some input... ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 17:51 ` Junio C Hamano @ 2009-10-24 18:19 ` Junio C Hamano 2009-10-24 20:16 ` Felipe Contreras 0 siblings, 1 reply; 28+ messages in thread From: Junio C Hamano @ 2009-10-24 18:19 UTC (permalink / raw) To: Felipe Contreras; +Cc: Junio C Hamano, git, Michael J Gruber, Jonathan Nieder Junio C Hamano <gitster@pobox.com> writes: > Felipe Contreras <felipe.contreras@gmail.com> writes: > >> Reworded the getting started section based on comments from Michael J Gruber, >> Jonathan Nieder and Junio C Hamano. > > Hmm, I thought JBF also had some input... Ah, nevermind. Yes, he did have input, and I tend to agree with him, and more importantly trust his judgement on the manual. I think a "Getting started" section that only covers "git config" looks way out of place in the beginning of this document. Manuals by other people that teach "here is how you would do a hello-world repository" would want to teach user.name before reaching that point, but because the user-manual is written in such a way that it first introduces concepts to understand what is going on without changing anything, we do not have much need user.name until it gets to "Developing with git" section. "Many people prefer to teach it this way" does not justify "everybody must teach it this way" an iota, when teaching "config user.name" upfront will fit the flow of how they teach but does not fit the flow of how this manual teaches [*1*]. I'm inclined to to discard the first patch. The point of the original text the second patch touches was to show how simple the contents of the configuration file is and give the users that there is nothing magic there. While I do not like the second patch as-is, because it destroys that nice property and treats the end users mindless "cut-and-paste without thinking" sheeples, I think that it is rather vague and unhelpful to the current target audience to say: ... The easiest way to do so is to make sure the following lines appear in a file named .gitconfig in your home directory: and the parts can use some improvement. For example, "home directory" does not hold true for people on platforms that lack the concept. Keeping the current "the following lines appear", rewording "in a file named .gitconfig in your home directory" with "in your per-user configuration file", keeping the display that shows how the config snippet should look like, and using "config --global -e" might be a better approach. [Footnote] *1* Unless you are changing the flow of how this manual teaches at the same time, that is. And no, I am not suggesting that we should start from "let's do a hello-world repository from scratch". I think the current "start from read-only and then learn how to grow history later" is one valid way to teach. ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 18:19 ` Junio C Hamano @ 2009-10-24 20:16 ` Felipe Contreras 2009-10-25 0:26 ` J. Bruce Fields 2009-10-25 3:08 ` Junio C Hamano 0 siblings, 2 replies; 28+ messages in thread From: Felipe Contreras @ 2009-10-24 20:16 UTC (permalink / raw) To: Junio C Hamano Cc: git, Michael J Gruber, Jonathan Nieder, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Sat, Oct 24, 2009 at 9:19 PM, Junio C Hamano <gitster@pobox.com> wrote: > Junio C Hamano <gitster@pobox.com> writes: > >> Felipe Contreras <felipe.contreras@gmail.com> writes: >> >>> Reworded the getting started section based on comments from Michael J Gruber, >>> Jonathan Nieder and Junio C Hamano. >> >> Hmm, I thought JBF also had some input... > > Ah, nevermind. Yes, he did have input, and I tend to agree with him, and > more importantly trust his judgement on the manual. JBF said this[1]: If we have to do this, just keep it short.... And I am trying to keep it short. > I think a "Getting started" section that only covers "git config" looks > way out of place in the beginning of this document. Now you are saying that the fact that it's short is a bad thing? That goes against to what JBF said. And let's not forget your previous comments [2]: 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). [3]: I actually wish this section appeared a lot earlier in the document, but that is a separate issue. > Manuals by other people that teach "here is how you would do a hello-world > repository" would want to teach user.name before reaching that point, but > because the user-manual is written in such a way that it first introduces > concepts to understand what is going on without changing anything, we do > not have much need user.name until it gets to "Developing with git" > section. > > "Many people prefer to teach it this way" does not justify "everybody must > teach it this way" an iota, when teaching "config user.name" upfront will > fit the flow of how they teach but does not fit the flow of how this > manual teaches [*1*]. Nobody argued that "everybody must teach it this way", the argument was that most people find it easier, and considering the section is about "developing with git" it is sensible to avoid burdening the reader with concepts that don't pertain to the objective at hand, which is getting them to configure their user. And let's not forget that the current text is broken for Windows users. > I'm inclined to to discard the first patch. And you decided to mention that after many people including you, have agreed that it's a good idea? > The point of the original text the second patch touches was to show how > simple the contents of the configuration file is and give the users that > there is nothing magic there. While I do not like the second patch as-is, > because it destroys that nice property and treats the end users mindless > "cut-and-paste without thinking" sheeples, What's wrong with teaching one thing at a time? Configuring the user is something so essential, I don't think it makes sense to make the task difficult on purpose. Some people might avoid doing it precisely because of that. > I think that it is rather vague > and unhelpful to the current target audience to say: > > ... The easiest way to do so is to make sure the following lines > appear in a file named .gitconfig in your home directory: > > and the parts can use some improvement. For example, "home directory" > does not hold true for people on platforms that lack the concept. Keeping > the current "the following lines appear", rewording "in a file named > .gitconfig in your home directory" with "in your per-user configuration > file", keeping the display that shows how the config snippet should look > like, and using "config --global -e" might be a better approach. If you read the results of the last git survey you'll see that the area that needs most improvement is the documentation. Also I still see many people doing commits without configuring the user name and email properly and so I've tried very hard to improve the user manual to make it easier for them to understand they must do that. In the process I've added the --edit option to 'git config' and the new "getting started" section, in order to address all the issues mentioned in previous threads and gone through several iterations of these patches already. I'm starting to think that all the previous "constructive" feedback was actually targeted to deter people from making any changes. I'm CC'ing people that have been involved in previous threads. > [Footnote] > > *1* Unless you are changing the flow of how this manual teaches at the > same time, that is. And no, I am not suggesting that we should start from > "let's do a hello-world repository from scratch". I think the current > "start from read-only and then learn how to grow history later" is one > valid way to teach. I also don't think the flow should be changed, that's why I didn't put the user configuration on the "getting started" section. It goes into the "developing with git" section. [1] http://article.gmane.org/gmane.comp.version-control.git/130236 [2] http://article.gmane.org/gmane.comp.version-control.git/115649 [3] http://article.gmane.org/gmane.comp.version-control.git/106667 -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 20:16 ` Felipe Contreras @ 2009-10-25 0:26 ` J. Bruce Fields 2009-10-25 3:08 ` Junio C Hamano 1 sibling, 0 replies; 28+ messages in thread From: J. Bruce Fields @ 2009-10-25 0:26 UTC (permalink / raw) To: Felipe Contreras Cc: Junio C Hamano, git, Michael J Gruber, Jonathan Nieder, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Sat, Oct 24, 2009 at 11:16:51PM +0300, Felipe Contreras wrote: > And let's not forget that the current text is broken for Windows users. Just out of curiosity: do you have a list of what would need to be done to make the manual work for windows users? I haven't used any Windows/DOS commandline since, um, 1980-something, so I'm a little clueless here. --b. ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-24 20:16 ` Felipe Contreras 2009-10-25 0:26 ` J. Bruce Fields @ 2009-10-25 3:08 ` Junio C Hamano 2009-10-25 9:43 ` Felipe Contreras 1 sibling, 1 reply; 28+ messages in thread From: Junio C Hamano @ 2009-10-25 3:08 UTC (permalink / raw) To: Felipe Contreras Cc: git, Michael J Gruber, Jonathan Nieder, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer Felipe Contreras <felipe.contreras@gmail.com> writes: >> I'm inclined to to discard the first patch. > > And you decided to mention that after many people including you, have > agreed that it's a good idea? This line of argument is wrong and counterproductive. Of course, after reading what others said and thinking about it more myself, I can change my mind based on their opinions. Otherwise there is no point in having any mailing list discussion. People propose changes, and two things can happen: (1) I and others may think it is not a good idea, clarifying argument may come from the original author and/or additional arguments defending the change may come from others. People who thought it was not a good idea may change their mind, and the patch gets accepted. git becomes better. If people cannot change their mind, it is useless to make supporting arguments to nudge them to reconsider. (2) I and others may think it is a good idea, a counterargument comes, and people who originally thought it was a good idea may change their mind, and the patch does not go in. git is saved from becoming worse. If people cannot change their mind, it is useless to make counter- arguments to nudge them to reconsider. Yes, I originally thought a "getting started" section may be a good idea. There is no need to point it out to me. But after I saw that the original author said "_if_ we have to do this, keep it short", the comment made me question my previous assumption one more time: is it really a good idea to add "getting started", and is it a good idea to cover the config command in that section? After re-reading the first thousand lines of the user manual, I realized that the explanation was carefully laid out so that you do not have to be taught "git config" in the beginning to be able to follow it. Now, after applying your latest patch, if we do not have to teach "config" there, what else is left in the section? --- Nothing. What conclusion do you expect me to reach after such a consideration, other than "then let's not have it"? > If you read the results of the last git survey you'll see that the > area that needs most improvement is the documentation. Yes, I did read it, but what about it? You already know we both want to have a good set of documentation. Remember that "changing" and "improving" is different; some changes may not necessarily be improvements. "It needs improving, so let's change it" is not an argument. This isn't obviously limited to the documentation but also applies to UI changes. > Also I still > see many people doing commits without configuring the user name and > email properly and so I've tried very hard to improve the user manual > to make it easier for them to understand they must do that. The "unconfigured user.name is wrong" is the least of the problems for people who start commiting without understanding the basic principles. People may ask "how do I publish my changes", "how do I discard the commit" and "how do I modify the commit two days ago", and teaching them things like "reset HEAD^" and "rebase -i", without making them aware of the implications will do disservice to them in the long run. That kind of self-teaching is already done by people (and for doing so sometimes they hurt themselves) by diving into man pages of individual commands before understanding the distributedness and its implications, and my hope has always been to keep the user-manual a document that teaches things in one coherent and hopefully the most useful order. The early part of the manual (the first thousand lines) does not talk about making commits but lays out the groundwork for a good reason. And in order to follow the current structure of the manual, you do not need to be taught "config" as the first thing. It is a totally different story if we are going to rewrite the manual in such a way that we start from "hello world". I am not necessarily saying it is a bad way to teach [*1*]. But the current "starting from a sightseer, while learning the basic concepts like reachability and stuff, and then learn to build on top of others' work" structure would also be a valid way to teach, and in that presentation order, I do not think teaching "config" sits well at the beginning. [Footnote] *1* Indeed, the book I did recently does just that, starting from a solo user who develops on his own from scratch, and then uses another repository as a back up repository, and then works on two different machines with a repository each, still working solo no the same project. After that working with other users collaboratively comes. If you teach in that order, you have to cover config before you cover commit, which pretty much means config is mentioned at the very beginning. ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-25 3:08 ` Junio C Hamano @ 2009-10-25 9:43 ` Felipe Contreras 2009-10-25 11:14 ` Jonathan Nieder 0 siblings, 1 reply; 28+ messages in thread From: Felipe Contreras @ 2009-10-25 9:43 UTC (permalink / raw) To: Junio C Hamano Cc: git, Michael J Gruber, Jonathan Nieder, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Sun, Oct 25, 2009 at 6:08 AM, Junio C Hamano <gitster@pobox.com> wrote: > Felipe Contreras <felipe.contreras@gmail.com> writes: > >>> I'm inclined to to discard the first patch. >> >> And you decided to mention that after many people including you, have >> agreed that it's a good idea? > > This line of argument is wrong and counterproductive. Of course, after > reading what others said and thinking about it more myself, I can change > my mind based on their opinions. Otherwise there is no point in having > any mailing list discussion. > > People propose changes, and two things can happen: > > (1) I and others may think it is not a good idea, clarifying argument may > come from the original author and/or additional arguments defending > the change may come from others. People who thought it was not a > good idea may change their mind, and the patch gets accepted. git > becomes better. > > If people cannot change their mind, it is useless to make supporting > arguments to nudge them to reconsider. > > (2) I and others may think it is a good idea, a counterargument comes, > and people who originally thought it was a good idea may change their > mind, and the patch does not go in. git is saved from becoming > worse. > > If people cannot change their mind, it is useless to make counter- > arguments to nudge them to reconsider. Yes, people can change their mind, but if they do so, they must tell it as it is, and you didn't: I think a "Getting started" section that only covers "git config" looks way out of place in the beginning of this document. If you would have said it properly "I've changed my mind" there's an obvious question that arises: Why? What made you change your mind. You didn't say that either. > Yes, I originally thought a "getting started" section may be a good idea. > There is no need to point it out to me. One never knows =/ > But after I saw that the original author said "_if_ we have to do this, > keep it short", the comment made me question my previous assumption one > more time: is it really a good idea to add "getting started", and is it a > good idea to cover the config command in that section? > > After re-reading the first thousand lines of the user manual, I realized > that the explanation was carefully laid out so that you do not have to be > taught "git config" in the beginning to be able to follow it. Now, after > applying your latest patch, if we do not have to teach "config" there, > what else is left in the section? --- Nothing. > > What conclusion do you expect me to reach after such a consideration, > other than "then let's not have it"? Aha! That's the explanation I was looking for, and what I think you should have said in the first place. Now we can do some productive discussion. I disagree. I think it's awfully useful to have color.ui = auto configured before reading the multitude of 'git branch', 'git show', and 'git diff' commands that are presented on first two sections. So useful, in fact, that I think it should be enabled by default. Supposing that color.ui is 'auto' by default, then yeah, I don't see the point of such a "git config" section so early in the document, but it must be explained somewhere. >> If you read the results of the last git survey you'll see that the >> area that needs most improvement is the documentation. > > Yes, I did read it, but what about it? You already know we both want to > have a good set of documentation. > > Remember that "changing" and "improving" is different; some changes may > not necessarily be improvements. "It needs improving, so let's change it" > is not an argument. This isn't obviously limited to the documentation but > also applies to UI changes. No, but "improving" needs "changing", and the discussion I see is biased towards "not changing". >> Also I still >> see many people doing commits without configuring the user name and >> email properly and so I've tried very hard to improve the user manual >> to make it easier for them to understand they must do that. > > The "unconfigured user.name is wrong" is the least of the problems for > people who start commiting without understanding the basic principles. > People may ask "how do I publish my changes", "how do I discard the > commit" and "how do I modify the commit two days ago", and teaching them > things like "reset HEAD^" and "rebase -i", without making them aware of > the implications will do disservice to them in the long run. That kind of > self-teaching is already done by people (and for doing so sometimes they > hurt themselves) by diving into man pages of individual commands before > understanding the distributedness and its implications, and my hope has > always been to keep the user-manual a document that teaches things in one > coherent and hopefully the most useful order. I don't think the user manual is achieving that purpose. I don't know if it's the user manual's fault, or git's UI. Both areas need a lot of improvement (as the git user survey suggests), and I've tried to improve both with a lot resistance in both. So I'm not very hopeful anymore. > The early part of the manual (the first thousand lines) does not talk > about making commits but lays out the groundwork for a good reason. And > in order to follow the current structure of the manual, you do not need to > be taught "config" as the first thing. > > It is a totally different story if we are going to rewrite the manual in > such a way that we start from "hello world". I am not necessarily saying > it is a bad way to teach [*1*]. > > But the current "starting from a sightseer, while learning the basic > concepts like reachability and stuff, and then learn to build on top of > others' work" structure would also be a valid way to teach, and in that > presentation order, I do not think teaching "config" sits well at the > beginning. IMO the vast majority of git users will use it to just fetch a repository, and browse through it, and that's because most people are not developers. Even developers most probably will start that way, and only start committing after a while. However, I haven't met any proficient git user that got to that point by reading the user manual, so I think it must be completely re-thought. Judging from the luck I've had pushing even the simplest changes I don't think it will improve much more, unfortunately. Cheers. -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-25 9:43 ` Felipe Contreras @ 2009-10-25 11:14 ` Jonathan Nieder 2009-11-11 23:15 ` Felipe Contreras 0 siblings, 1 reply; 28+ messages in thread From: Jonathan Nieder @ 2009-10-25 11:14 UTC (permalink / raw) To: Felipe Contreras Cc: Junio C Hamano, git, Michael J Gruber, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer Hi Felipe, Felipe Contreras wrote: > I disagree. I think it's awfully useful to have color.ui = auto > configured before reading the multitude of 'git branch', 'git show', > and 'git diff' commands that are presented on first two sections. So > useful, in fact, that I think it should be enabled by default. This is why I think you had a good idea here. When a program doesn’t behave as I would like, it can be very comforting to know where its dotfile is and be able to edit it (I’m not sure how I learn this for most programs). And it is much easier to parse git output without reading it all when color is turned on, so that is a setting I imagine could be useful to people. On the other hand, it is far more pleasant to use a program that doesn’t need configuration at all. And as I mentioned before, it is best to avoid wasted time at the beginning of the manual. > Supposing that color.ui is 'auto' by default, Should it be? I think it would not be too hard to detect a color terminal by checking $TERM. Are many people bothered by color? Do we need some way to make it more obvious how to turn color _off_? > No, but "improving" needs "changing", and the discussion I see is > biased towards "not changing". [...] > I don't think the user manual is achieving that purpose. I don't know > if it's the user manual's fault, or git's UI. Both areas need a lot of > improvement (as the git user survey suggests), and I've tried to > improve both with a lot resistance in both. So I'm not very hopeful > anymore. I hope you have not misunderstood. I cannot speak for everyone else here, but I know I am happier when (1) fixes match problems to be solved in a documented way and (2) fixes do not unnecessarily break unrelated habits. One way to bring this about is to justify each change by explaining what real problem it will solve and how it avoids collateral damage. Without that justification, a change is indeed dangerous and might be worth resisting until it gets clarified. But this is not meant to prevent fixes from occuring at all. Could you list some UI patches that were overlooked or not properly addressed? Maybe people just forgot about them or were waiting for an updated version, or maybe the problems some solve weren’t articulated clearly yet. I would be glad to help out in any way I can. > However, I haven't met any proficient git user that got to that point > by reading the user manual, so I think it must be completely > re-thought. I have met one. (Well, he read the git tutorial and learned by using git, too.) I think the user manual’s pretty well written, though it certainly has its gaps and rough spots. > Judging from the luck I've had pushing even the simplest > changes I don't think it will improve much more, unfortunately. Even the simplest changes can be hard. But I hope they do not amount to nothing. I hope at the very least the git-config manual page will improve... Thank you for working on this. I hope you succeed in improving git’s usability, one way or another. Regards, Jonathan ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-10-25 11:14 ` Jonathan Nieder @ 2009-11-11 23:15 ` Felipe Contreras 2009-11-12 11:29 ` Michael J Gruber 0 siblings, 1 reply; 28+ messages in thread From: Felipe Contreras @ 2009-11-11 23:15 UTC (permalink / raw) To: Jonathan Nieder Cc: Junio C Hamano, git, Michael J Gruber, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Sun, Oct 25, 2009 at 1:14 PM, Jonathan Nieder <jrnieder@gmail.com> wrote: > Felipe Contreras wrote: >> Supposing that color.ui is 'auto' by default, > > Should it be? I think it would not be too hard to detect a color > terminal by checking $TERM. Are many people bothered by color? Do we > need some way to make it more obvious how to turn color _off_? I think it should be. >> No, but "improving" needs "changing", and the discussion I see is >> biased towards "not changing". > [...] >> I don't think the user manual is achieving that purpose. I don't know >> if it's the user manual's fault, or git's UI. Both areas need a lot of >> improvement (as the git user survey suggests), and I've tried to >> improve both with a lot resistance in both. So I'm not very hopeful >> anymore. > > I hope you have not misunderstood. I cannot speak for everyone else > here, but I know I am happier when (1) fixes match problems to be > solved in a documented way and (2) fixes do not unnecessarily break > unrelated habits. One way to bring this about is to justify each > change by explaining what real problem it will solve and how it avoids > collateral damage. Without that justification, a change is indeed > dangerous and might be worth resisting until it gets clarified. But > this is not meant to prevent fixes from occuring at all. Well. I've sent many patches, and gone through several iterations. After fixing all outstanding issues, addressing all the comments, and getting several "I like this" votes, Junio suddenly decides he doesn't like the initial changes at all and doesn't provide any way forward. I don't see how that's an environment that fosters changes. > Could you list some UI patches that were overlooked or not properly > addressed? Maybe people just forgot about them or were waiting for an > updated version, or maybe the problems some solve weren’t articulated > clearly yet. I would be glad to help out in any way I can. For example there have been many attempts to bring the 'git stage' to foreground of the UI; right now it's kind of hidden and many people don't even realize it's there. Even simplistic attempts as standardizing --index, --cache and so on into --stage have failed miserably. Again, there doesn't seem to be a path forward. Perhaps the git's stage will remain an obscure feature of git forever. (all the input from git user's survey points out that people are not really using it) >> Judging from the luck I've had pushing even the simplest >> changes I don't think it will improve much more, unfortunately. > > Even the simplest changes can be hard. But I hope they do not amount > to nothing. I hope at the very least the git-config manual page will > improve... What I mean is: if the simplest changes are *impossible*, then there's barely any hope of progress. Cheers. -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-11 23:15 ` Felipe Contreras @ 2009-11-12 11:29 ` Michael J Gruber 2009-11-12 20:04 ` Felipe Contreras 2009-11-13 21:06 ` Nanako Shiraishi 0 siblings, 2 replies; 28+ messages in thread From: Michael J Gruber @ 2009-11-12 11:29 UTC (permalink / raw) To: Felipe Contreras Cc: Jonathan Nieder, Junio C Hamano, git, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer Felipe Contreras venit, vidit, dixit 12.11.2009 00:15: > On Sun, Oct 25, 2009 at 1:14 PM, Jonathan Nieder <jrnieder@gmail.com> wrote: >> Felipe Contreras wrote: >>> Supposing that color.ui is 'auto' by default, >> >> Should it be? I think it would not be too hard to detect a color >> terminal by checking $TERM. Are many people bothered by color? Do we >> need some way to make it more obvious how to turn color _off_? > > I think it should be. Back then (before my involvement with git) the result of the discussion was something like: "Since some of us are way more opposed to the use of colors than others are in favor..." This does not sound overly democratic. Feel free to bring this issue on for a change in Git 1.7.0. It would be good to research any possible incompatibilities this would imply (other than the looks of the output), >>> No, but "improving" needs "changing", and the discussion I see is >>> biased towards "not changing". >> [...] >>> I don't think the user manual is achieving that purpose. I don't know >>> if it's the user manual's fault, or git's UI. Both areas need a lot of >>> improvement (as the git user survey suggests), and I've tried to >>> improve both with a lot resistance in both. So I'm not very hopeful >>> anymore. >> >> I hope you have not misunderstood. I cannot speak for everyone else >> here, but I know I am happier when (1) fixes match problems to be >> solved in a documented way and (2) fixes do not unnecessarily break >> unrelated habits. One way to bring this about is to justify each >> change by explaining what real problem it will solve and how it avoids >> collateral damage. Without that justification, a change is indeed >> dangerous and might be worth resisting until it gets clarified. But >> this is not meant to prevent fixes from occuring at all. > > Well. I've sent many patches, and gone through several iterations. > After fixing all outstanding issues, addressing all the comments, and > getting several "I like this" votes, Junio suddenly decides he doesn't > like the initial changes at all and doesn't provide any way forward. > > I don't see how that's an environment that fosters changes. The process can be frustrating at times. Many patches go through many rounds. I've had occasions where I got frustrated and gave up, as well as those where I learned a lot and the actual result was much better than it would have been without thorough discussions. It's this process which tries to ensure that the project is moving forward most of the time, rather than sporadically back and forth; moving forward maybe a bit slower, but still at an impressive overall rate. Regarding this specific patch series: I took part in the initial discussion, and got frustrated by the original poster's seemingly unwillingness to accept advice, so I left. I'm not drawing any general conclusions, and please don't take this as an ad hominem argument. Sometimes it's simply a matter of mismatching participants. It's just my impression that many people retreat from a discussion because they feel it's getting unproductive (from their particular point of view), maybe hoping the thread will die out sooner or later. Once it looks as if something they object to could be included they come back with counter arguments. This makes the discussion seemingly go back and forth, but is a natural sociological effect. >> Could you list some UI patches that were overlooked or not properly >> addressed? Maybe people just forgot about them or were waiting for an >> updated version, or maybe the problems some solve weren’t articulated >> clearly yet. I would be glad to help out in any way I can. > > For example there have been many attempts to bring the 'git stage' to > foreground of the UI; right now it's kind of hidden and many people > don't even realize it's there. Even simplistic attempts as > standardizing --index, --cache and so on into --stage have failed > miserably. > > Again, there doesn't seem to be a path forward. Perhaps the git's > stage will remain an obscure feature of git forever. (all the input > from git user's survey points out that people are not really using it) I didn't read that out of the survey. On the other hand, the last survey pretty impressively showed where it had been publicized most prominently. One should keep that in mind when interpreting the results. If you care to go back to that discussion you see that there is good reason for having both --cached and --index. They are different. "git help cli" explains this nicely. "To stage" has been introduced to describe what "git add" does to people who hard wire "add" to the meaning it has in other VCSes. In fact, this would be unnecessary if the concept of Git as a *content* tracker could be transmitted more successfully. Git cares about content only, so what could "git add" possibly mean? "git stage" is a failed follow up ui experiment. In this regard, I think the problem is that there are really two kinds of people in terms of learning style: - Some prefer recipes, similarities with previously known recipes. "How do I...?" And then try do understand "How does (G)it...?" from that. - Some want to understand concepts first: "How does (G)it...?" And then figure out how to use (G)it to do what they want. I'd guess most developers and a large fraction of the "technical crowd" belong in the second camp. I still think we should both - try and teach concepts early, emphasize that Git is different (content, index, branch - that's it) - make Git behave in "expected ways", making it easy for the (willing) beginner) without compromising its usefulness as a power tool. I better stop before I digress even more from the original topic :) Michael ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-12 11:29 ` Michael J Gruber @ 2009-11-12 20:04 ` Felipe Contreras 2009-11-13 21:06 ` Nanako Shiraishi 1 sibling, 0 replies; 28+ messages in thread From: Felipe Contreras @ 2009-11-12 20:04 UTC (permalink / raw) To: Michael J Gruber Cc: Jonathan Nieder, Junio C Hamano, git, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Thu, Nov 12, 2009 at 1:29 PM, Michael J Gruber <git@drmicha.warpmail.net> wrote: > Feel free to bring this issue on for a change in Git 1.7.0. It would be > good to research any possible incompatibilities this would imply (other > than the looks of the output), Isn't that what we are doing just now? > The process can be frustrating at times. Many patches go through many > rounds. I've had occasions where I got frustrated and gave up, as well > as those where I learned a lot and the actual result was much better > than it would have been without thorough discussions. It's this process > which tries to ensure that the project is moving forward most of the > time, rather than sporadically back and forth; moving forward maybe a > bit slower, but still at an impressive overall rate. Except in this case there is no path forward. If there is, I would like to hear it. > Regarding this specific patch series: I took part in the initial > discussion, and got frustrated by the original poster's seemingly > unwillingness to accept advice, so I left. I'm not drawing any general > conclusions, and please don't take this as an ad hominem argument. > Sometimes it's simply a matter of mismatching participants. What are you talking about? All your comments were addressed in subsequent patches, as the commit message of the patch in this thread points out. Moreover, in the paragraph before you argued that these thorough discussions are actually a good thing. Or are patch committers not allowed to discuss? > I didn't read that out of the survey. On the other hand, the last survey > pretty impressively showed where it had been publicized most > prominently. One should keep that in mind when interpreting the results. So? What are the surveys supposed to be for, if not to use the results? > If you care to go back to that discussion you see that there is good > reason for having both --cached and --index. They are different. "git > help cli" explains this nicely. "good" is a very subjective term; I don't think "they are different" is a good reason. By that logic --only-index and --index-and-working-dir serve the same purpose, just like --gogo and --dance. But there's no point in discussing this until people accept there is a problem, and there seems to be unwillingness to accept that very few people use the stage properly. > "To stage" has been introduced to describe what "git add" does to people > who hard wire "add" to the meaning it has in other VCSes. In fact, this > would be unnecessary if the concept of Git as a *content* tracker could > be transmitted more successfully. Git cares about content only, so what > could "git add" possibly mean? usage: git add [options] [--] <filepattern>... I don't see any mention of this "blob" mythical creature. In the vast majority of the minds of git users, 'git add' adds files to the repository, just like any other VCS. Proof of that is that only 23% of the people use "git add -i / -p" and 15% "git add -u / -A" often. > "git stage" is a failed follow up ui experiment. I agree with that. But assuming because one UI experiment failed, all other "stage" proposals are doomed. > In this regard, I think the problem is that there are really two kinds > of people in terms of learning style: > > - Some prefer recipes, similarities with previously known recipes. "How > do I...?" And then try do understand "How does (G)it...?" from that. > > - Some want to understand concepts first: "How does (G)it...?" And then > figure out how to use (G)it to do what they want. > > I'd guess most developers and a large fraction of the "technical crowd" > belong in the second camp. I actually belong to the two groups. When I started to use git I learned it through recipes and grew fond of it, but didn't really know what was really happening even thought I used it for years. It wasn't until a colleague recommended me to read "Git from the bottom up", then I really started to understand git and realized I didn't know squat. Sure, I heard concepts such as "feature branches", "rebase" and "stage interactive", and I had in my to-do list to learn them, but that was it. I'm pretty sure the vast majority of users are in the darkness just as I was. > I still think we should both What? > - try and teach concepts early, emphasize that Git is different > (content, index, branch - that's it) Well, that's the first failure right there. If your objective is to confuse people, then sure, call it "index", otherwise choose a name that corresponds with it's purpose: stage. > - make Git behave in "expected ways", making it easy for the (willing) > beginner) without compromising its usefulness as a power tool. Sure, but if the UI was more friendly people would learn to use the advanced features through it's use. Currently there are no ropes to do that. You have to read a book or something. -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-12 11:29 ` Michael J Gruber 2009-11-12 20:04 ` Felipe Contreras @ 2009-11-13 21:06 ` Nanako Shiraishi 2009-11-16 22:52 ` Felipe Contreras 1 sibling, 1 reply; 28+ messages in thread From: Nanako Shiraishi @ 2009-11-13 21:06 UTC (permalink / raw) To: Michael J Gruber Cc: Felipe Contreras, Jonathan Nieder, Junio C Hamano, git, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer Quoting Michael J Gruber <git@drmicha.warpmail.net> > Regarding this specific patch series: I took part in the initial > discussion, and got frustrated by the original poster's seemingly > unwillingness to accept advice, so I left. I'm not drawing any general > conclusions, and please don't take this as an ad hominem argument. > Sometimes it's simply a matter of mismatching participants. I didn't get myself involved in the follow-up discussion exactly for the same reason. > If you care to go back to that discussion you see that there is good > reason for having both --cached and --index. They are different. "git > help cli" explains this nicely. The need to support both options in the same command (eg. apply) means that anybody who says "I don't like 'index' nor 'cache'; why don't we change them all to 'stage'" doesn't understand the issue. But that doesn't mean "apply --cached" vs "apply --index" is the best way to let the users specify which operation is requested. I don't think Felipe seriously wants to change them to --gogo vs --dance, but if he made a more constructive proposal, instead of making such a comment whose intended effect is only to annoy people, we may see an improved UI at the end. Proposing "--index-only" vs "--index-too" or even "--stage-only" vs "--stage-too" would have helped him appear to be more serious and constructive and I think your expression "mismatching participants" was a great way to say this. There was a similar discussion about "diff --cached". The command compares two things and the current syntax relies on counting the number of treeish on the command line to specify what these two things are, and sometimes people are confused which way the comparison occurs. * If you have two treeish, it compares the two treeish. Specifically, it shows the change to make one treeish into the other treeish. * If you have one treeish, it compares the treeish with working tree or the index (it shows the change to make the treeish into working tree or the index). You need --cached to choose the "index", and this can safely be aliased to --staged. * If you have zero treeish, it compares the index with working tree (it shows the change to make the index into working tree). But it is also possible to have an alternate syntax to explicitly say what you are comparing with what. Perhaps these may make it unnecessary to remember which way the comparison occurs: git diff --tree-vs-staged HEAD same as "git diff --cached HEAD" git diff --staged-vs-tree HEAD same as "git diff -R --cached HEAD" git diff --staged-vs-working same as "git diff" git diff --working-vs-staged same as "git diff -R" git diff --tree-vs-working HEAD same as "git diff HEAD" git diff --working-vs-tree HEAD same as "git diff -R HEAD" If people like this as a concept we can introduce shorter way to spell them, eg. "git diff --ts HEAD", etc. -- Nanako Shiraishi http://ivory.ap.teacup.com/nanako3/ ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-13 21:06 ` Nanako Shiraishi @ 2009-11-16 22:52 ` Felipe Contreras 2009-11-17 12:06 ` Nanako Shiraishi 0 siblings, 1 reply; 28+ messages in thread From: Felipe Contreras @ 2009-11-16 22:52 UTC (permalink / raw) To: Nanako Shiraishi Cc: Michael J Gruber, Jonathan Nieder, Junio C Hamano, git, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Fri, Nov 13, 2009 at 11:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote: > Quoting Michael J Gruber <git@drmicha.warpmail.net> >> If you care to go back to that discussion you see that there is good >> reason for having both --cached and --index. They are different. "git >> help cli" explains this nicely. > > The need to support both options in the same command (eg. apply) means > that anybody who says "I don't like 'index' nor 'cache'; why don't we > change them all to 'stage'" doesn't understand the issue. > > But that doesn't mean "apply --cached" vs "apply --index" is the best > way to let the users specify which operation is requested. I don't > think Felipe seriously wants to change them to --gogo vs --dance, but > if he made a more constructive proposal, instead of making such a > comment whose intended effect is only to annoy people, we may see > an improved UI at the end. Proposing "--index-only" vs "--index-too" > or even "--stage-only" vs "--stage-too" would have helped him appear > to be more serious and constructive and I think your expression > "mismatching participants" was a great way to say this. Right, your explanation is more clear: the fact that we need both doesn't mean we cannot use the term "stage". As to "constructive proposal" I deliberately tried to avoid them in case somebody tried to disregard it as bike-shedding, and move on. What I'm trying to do is bring up the issue that the stage is not user friendly. > There was a similar discussion about "diff --cached". The command > compares two things and the current syntax relies on counting the > number of treeish on the command line to specify what these two things > are, and sometimes people are confused which way the comparison occurs. > > * If you have two treeish, it compares the two treeish. Specifically, > it shows the change to make one treeish into the other treeish. > > * If you have one treeish, it compares the treeish with working tree > or the index (it shows the change to make the treeish into working > tree or the index). You need --cached to choose the "index", and > this can safely be aliased to --staged. > > * If you have zero treeish, it compares the index with working tree > (it shows the change to make the index into working tree). > > But it is also possible to have an alternate syntax to explicitly say > what you are comparing with what. Perhaps these may make it unnecessary > to remember which way the comparison occurs: > > git diff --tree-vs-staged HEAD > same as "git diff --cached HEAD" > git diff --staged-vs-tree HEAD > same as "git diff -R --cached HEAD" > > git diff --staged-vs-working > same as "git diff" > git diff --working-vs-staged > same as "git diff -R" > > git diff --tree-vs-working HEAD > same as "git diff HEAD" > git diff --working-vs-tree HEAD > same as "git diff -R HEAD" I like David Kågedal's suggestion more: http://kerneltrap.org/mailarchive/git/2008/10/29/3857134 Cheers. -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-16 22:52 ` Felipe Contreras @ 2009-11-17 12:06 ` Nanako Shiraishi 2009-11-17 17:28 ` J. Bruce Fields 2009-11-17 17:53 ` Matthieu Moy 0 siblings, 2 replies; 28+ messages in thread From: Nanako Shiraishi @ 2009-11-17 12:06 UTC (permalink / raw) To: Felipe Contreras Cc: Michael J Gruber, Jonathan Nieder, Junio C Hamano, git, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer Quoting Felipe Contreras <felipe.contreras@gmail.com> > On Fri, Nov 13, 2009 at 11:06 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote: >> ... I don't >> think Felipe seriously wants to change them to --gogo vs --dance, but >> if he made a more constructive proposal, instead of making such a >> comment whose intended effect is only to annoy people, we may see >> an improved UI at the end. Proposing "--index-only" vs "--index-too" >> or even "--stage-only" vs "--stage-too" would have helped him appear >> to be more serious and constructive and I think your expression >> "mismatching participants" was a great way to say this. > > Right, your explanation is more clear: You have a funny way of saying "I'm sorry, I wasn't constructive, and my attitude repelled many participants from the discussion". > the fact that we need both > doesn't mean we cannot use the term "stage". As to "constructive > proposal" I deliberately tried to avoid them in case somebody tried to > disregard it as bike-shedding, and move on. If the only constructive proposal you could make is to replace words used in two operations without clarifying concepts any better to newbies, then what you are doing is bike-shedding. I don't think trying to hide that by not making any proposal changes that. > What I'm trying to do is > bring up the issue that the stage is not user friendly. I thought you were the one who wanted to use "stage" everywhere? For what it's worth, "stage" isn't very user friendly to me; maybe it is because I'm not a native English speaker. I'm not saying that when I hear "index" or "cached" I'll understand what they mean even if I didn't have any prior knowledge of git, but I am saying "stage" isn't any better than these two words in that respect. Of course the user needs to understand what it is and how it is used, no matter what word you use. I think a proposal to replace the word "index" with "stage" will sound nothing but bike-shedding to anybody, especially after getting familiar with "index" and seeing it taught on many web pages and books. > I like David Kågedal's suggestion more: > http://kerneltrap.org/mailarchive/git/2008/10/29/3857134 For people who like a usable threaded interface to read the message in context here is its URL. http://thread.gmane.org/gmane.comp.version-control.git/99332/focus=99401 Yes, I had David's proposal in mind when I wrote my response. Even though the fundamental idea is the same, I used --X-vs-Y option to avoid the problems David's proposal has in a slightly nicer way. David's proposal introduced two magic tokens STAGE and WORKTREE. git diff STAGE WORKTREE (like "git diff" today) git diff HEAD WORKTREE (like "git diff HEAD" today) git diff WORKTREE HEAD (like "git diff -R HEAD" today) git diff HEAD STAGE (like "git diff --cached" today) git diff commit STAGE (like "git diff --cached commit" today) This looks nice on surface, but I think the apparent niceness is shallow. If of course has a small problem of introducing an obvious backward incompatibility. You can't use a branch whose name is STAGE anymore, but a deeper problem is that these two magic tokens pretend to be refs. But they do so only to the diff command. I don't see how you can make them sanely be usable to other commands like "git log v1.0.0..WORKTREE". -- Nanako Shiraishi http://ivory.ap.teacup.com/nanako3/ ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-17 12:06 ` Nanako Shiraishi @ 2009-11-17 17:28 ` J. Bruce Fields 2009-11-17 18:25 ` Junio C Hamano 2009-11-17 17:53 ` Matthieu Moy 1 sibling, 1 reply; 28+ messages in thread From: J. Bruce Fields @ 2009-11-17 17:28 UTC (permalink / raw) To: Nanako Shiraishi Cc: Felipe Contreras, Michael J Gruber, Jonathan Nieder, Junio C Hamano, git, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Tue, Nov 17, 2009 at 09:06:25PM +0900, Nanako Shiraishi wrote: > David's proposal introduced two magic tokens STAGE and WORKTREE. > > git diff STAGE WORKTREE (like "git diff" today) > git diff HEAD WORKTREE (like "git diff HEAD" today) > git diff WORKTREE HEAD (like "git diff -R HEAD" today) > git diff HEAD STAGE (like "git diff --cached" today) > git diff commit STAGE (like "git diff --cached commit" today) > > This looks nice on surface, but I think the apparent niceness > is shallow. If of course has a small problem of introducing an > obvious backward incompatibility. You can't use a branch whose > name is STAGE anymore, but a deeper problem is that these two > magic tokens pretend to be refs. But they do so only to the diff > command. I don't see how you can make them sanely be usable to > other commands like "git log v1.0.0..WORKTREE". Doesn't appear that refs have to point to commits; e.g., on the linux project: git log v2.6.11-tree..v2.6.32-rc7 error: Object 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c is a tree, not a commit fatal: Invalid revision range v2.6.11-tree..v2.6.32-rc7 You might be able to add some extra syntax to prevent conflicts with branch names. Uh, :STAGE, :WORKTREE ?? But I think that conflicts with something else. And the "magic tokens" get a little uglier and harder to remember. Bah. --b. ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-17 17:28 ` J. Bruce Fields @ 2009-11-17 18:25 ` Junio C Hamano 2009-11-17 22:00 ` Felipe Contreras 0 siblings, 1 reply; 28+ messages in thread From: Junio C Hamano @ 2009-11-17 18:25 UTC (permalink / raw) To: J. Bruce Fields Cc: Nanako Shiraishi, Felipe Contreras, Michael J Gruber, Jonathan Nieder, Junio C Hamano, git, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer "J. Bruce Fields" <bfields@fieldses.org> writes: > On Tue, Nov 17, 2009 at 09:06:25PM +0900, Nanako Shiraishi wrote: >> David's proposal introduced two magic tokens STAGE and WORKTREE. >> >> git diff STAGE WORKTREE (like "git diff" today) >> git diff HEAD WORKTREE (like "git diff HEAD" today) >> git diff WORKTREE HEAD (like "git diff -R HEAD" today) >> git diff HEAD STAGE (like "git diff --cached" today) >> git diff commit STAGE (like "git diff --cached commit" today) >> >> This looks nice on surface, but I think the apparent niceness >> is shallow. If of course has a small problem of introducing an >> obvious backward incompatibility. You can't use a branch whose >> name is STAGE anymore, but a deeper problem is that these two >> magic tokens pretend to be refs. But they do so only to the diff >> command. I don't see how you can make them sanely be usable to >> other commands like "git log v1.0.0..WORKTREE". > > Doesn't appear that refs have to point to commits; e.g., on the linux > project: > > git log v2.6.11-tree..v2.6.32-rc7 > error: Object 5dc01c595e6c6ec9ccda4f6f69c131c0dd945f8c is a tree, not a > commit > fatal: Invalid revision range v2.6.11-tree..v2.6.32-rc7 True. A ref can even point to a blob. I think "diff" always takes two (pseudo-)tree-ish in David's world, and you should be able to use these magic topens anywhere that expects a tree-ish. For example: $ git checkout STAGE Makefile would be a way to say "please check out the version of Makefile in the staging area". And $ git archive WORKTREE $ git archive STAGE would be a version of tar that is index-aware. But we do not have to support commit-ish operations, such as "git log". It is a different story if these pseudo-refs that denote tree-ish are useful outside the context of "diff". I do not think of many commands that take arbitrary tree-ish other than the ones I mentioned above. Even though they take arbitrary tree-ish, people almost always use commit-ish with them. Which points to another issue with the approach. The original intention of these magic tokens are to make things easier, but they actually may make things _harder_ to teach, because you have to explain why "git log WORKTREE" does not work but "git archive WORKTREE" does. Admittedly, you already have to explain your example to people saying "it does not work because v2.6.11 is a tree and a tree by itself does not have a point in history", but the thing is, v2.6.11-tree and v2.6.11 are oddballs, and you do not have to give that explanation very often, simply because the users are not exposed to a raw tree. But WORKTREE and STAGE tokens are _meant_ to be exposed to them much more prominently. That's the whole point of the "git diff STAGE WORKTREE" proposal. People would become aware that they are very different from ordinary commits, and then eventually they will realize that they are not even trees [*1*]. At that point, I suspect that these magic tokens become larger UI warts themselves; they behave differently from everything else that is spelled in all caps (e.g. HEAD, ORIG_HEAD, MERGE_HEAD). As to --tree-vs-index counterproposal (was it a counterproposal?), except for that I think they are too long to type in practice and need to be shortened to be useful, I do not have a fundamental objection against it. [Footnote] *1* For example, I would not expect that we will make "git show WORKTREE" to build a tree on the fly by running "git add -A && git write-tree" with a temporary index and then running "git show" on the resulting tree object, because there would be a better response than that if a user asks "please show my worktree". ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-17 18:25 ` Junio C Hamano @ 2009-11-17 22:00 ` Felipe Contreras 2009-11-17 22:19 ` Junio C Hamano 0 siblings, 1 reply; 28+ messages in thread From: Felipe Contreras @ 2009-11-17 22:00 UTC (permalink / raw) To: Junio C Hamano Cc: J. Bruce Fields, Nanako Shiraishi, Michael J Gruber, Jonathan Nieder, git, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Tue, Nov 17, 2009 at 8:25 PM, Junio C Hamano <gitster@pobox.com> wrote: > But we do not have to support commit-ish operations, such as "git log". Right, and actuallly don't have to support WORKTREE/STAGE on all the commands that work with the stage. For example I think 'git apply' behaves completely different than 'git diff', since you cannot apply a patch on top of a commit, therefore it doesn't make sense to stage stuff as pseudo-refs; it makes sense to keep the --foo options (although I would prefer something like --stage and --stage-only). > It is a different story if these pseudo-refs that denote tree-ish are > useful outside the context of "diff". I do not think of many commands > that take arbitrary tree-ish other than the ones I mentioned above. Even > though they take arbitrary tree-ish, people almost always use commit-ish > with them. > > Which points to another issue with the approach. > > The original intention of these magic tokens are to make things easier, > but they actually may make things _harder_ to teach, because you have to > explain why "git log WORKTREE" does not work but "git archive WORKTREE" > does. Admittedly, you already have to explain your example to people > saying "it does not work because v2.6.11 is a tree and a tree by itself > does not have a point in history", but the thing is, v2.6.11-tree and > v2.6.11 are oddballs, and you do not have to give that explanation very > often, simply because the users are not exposed to a raw tree. > > But WORKTREE and STAGE tokens are _meant_ to be exposed to them much more > prominently. That's the whole point of the "git diff STAGE WORKTREE" > proposal. > > People would become aware that they are very different from ordinary > commits, and then eventually they will realize that they are not even > trees [*1*]. > > At that point, I suspect that these magic tokens become larger UI warts > themselves; they behave differently from everything else that is spelled > in all caps (e.g. HEAD, ORIG_HEAD, MERGE_HEAD). That could be easily fixed by making explicit in the syntax that these are not typical refs: i.e. @stage and @work. -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-17 22:00 ` Felipe Contreras @ 2009-11-17 22:19 ` Junio C Hamano 2009-11-17 23:06 ` Felipe Contreras 0 siblings, 1 reply; 28+ messages in thread From: Junio C Hamano @ 2009-11-17 22:19 UTC (permalink / raw) To: Felipe Contreras Cc: Junio C Hamano, J. Bruce Fields, Nanako Shiraishi, Michael J Gruber, Jonathan Nieder, git, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer Felipe Contreras <felipe.contreras@gmail.com> writes: > That could be easily fixed by making explicit in the syntax that these > are not typical refs: i.e. @stage and @work. The message I get from that suggestion is that the most sensible approach, if we are going to add something from this discussion to "git diff", is to do what you did _not_ quote from my message, which is: As to --tree-vs-index counterproposal (was it a counterproposal?), except for that I think they are too long to type in practice and need to be shortened to be useful, I do not have a fundamental objection against it. IOW, this is about options, and should not be done as syntax sugar that does a half-baked job of pretending to be refs. ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-17 22:19 ` Junio C Hamano @ 2009-11-17 23:06 ` Felipe Contreras 2009-11-17 23:13 ` Junio C Hamano 0 siblings, 1 reply; 28+ messages in thread From: Felipe Contreras @ 2009-11-17 23:06 UTC (permalink / raw) To: Junio C Hamano Cc: J. Bruce Fields, Nanako Shiraishi, Michael J Gruber, Jonathan Nieder, git, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Wed, Nov 18, 2009 at 12:19 AM, Junio C Hamano <gitster@pobox.com> wrote: > Felipe Contreras <felipe.contreras@gmail.com> writes: > >> That could be easily fixed by making explicit in the syntax that these >> are not typical refs: i.e. @stage and @work. > > The message I get from that suggestion is that the most sensible approach, > if we are going to add something from this discussion to "git diff", is to > do what you did _not_ quote from my message, which is: > > As to --tree-vs-index counterproposal (was it a counterproposal?), > except for that I think they are too long to type in practice and need > to be shortened to be useful, I do not have a fundamental objection > against it. > > IOW, this is about options, and should not be done as syntax sugar that > does a half-baked job of pretending to be refs. Sorry, I thought your only objection to STAGE and WORKTREE was that they were not clearly differentiated, and my proposal gets rid of that issue. Now I fail to see what's the problem since you didn't explain what's wrong with adding syntactic sugar. If the goal of the change is to make things more user-friendly, then I'd say "git diff HEAD @stage" is better than "git diff --tree-vs-staged HEAD". -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-17 23:06 ` Felipe Contreras @ 2009-11-17 23:13 ` Junio C Hamano 2009-11-18 0:05 ` Felipe Contreras 0 siblings, 1 reply; 28+ messages in thread From: Junio C Hamano @ 2009-11-17 23:13 UTC (permalink / raw) To: Felipe Contreras Cc: Junio C Hamano, J. Bruce Fields, Nanako Shiraishi, Michael J Gruber, Jonathan Nieder, git, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer Felipe Contreras <felipe.contreras@gmail.com> writes: > If the goal of the change is to make things more user-friendly, then > I'd say "git diff HEAD @stage" is better than "git diff > --tree-vs-staged HEAD". Exactly. That is where we disagree. The funny "@stage" does not convey the fact that it is affecting how "git diff" operates, like any other option like "-R" does in "git diff -R" command line does. Now the user needs to know git commands take -option like other normal tools do, but in addition they need to remember that an oddball "diff" subcommand takes "@funny" in addition to the usual "-option". How would that be an improvement? ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-17 23:13 ` Junio C Hamano @ 2009-11-18 0:05 ` Felipe Contreras 0 siblings, 0 replies; 28+ messages in thread From: Felipe Contreras @ 2009-11-18 0:05 UTC (permalink / raw) To: Junio C Hamano Cc: J. Bruce Fields, Nanako Shiraishi, Michael J Gruber, Jonathan Nieder, git, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer On Wed, Nov 18, 2009 at 1:13 AM, Junio C Hamano <gitster@pobox.com> wrote: > Exactly. That is where we disagree. The funny "@stage" does not convey > the fact that it is affecting how "git diff" operates, like any other > option like "-R" does in "git diff -R" command line does. Now the user > needs to know git commands take -option like other normal tools do, but in > addition they need to remember that an oddball "diff" subcommand takes > "@funny" in addition to the usual "-option". Right now there are 4 modes of operations, the user would need to remember all of them... instead, the @stage pointer would reduce the modes to 1, so the user would have to look on the man-page only once, quickly. Also, to me it feels more natural to do "git diff b a" rather than "git diff -R a b", therefore "git diff @stage HEAD" beats "git diff -R --cached HEAD". Moreover, I wonder if these modes are really properly implemented. For example, what's with these funky commands: git diff HEAD master next <- shouldn't only 2 be allowed? git diff HEAD..master HEAD..next Anyway, you are making the assumption that users actually use, and understand the different modes of operation, but I'm claiming most of them don't, and one of the reasons could be that they are not intuitive. > How would that be an improvement? It might make people actually start using the stage, which again, it seems apparent to me they don't. This can be easily interpreted from reading the git user survey (only 23% of the people use "git add -i / -p", and 15% "git add -u / -A" often), but if you don't believe so, we can wait for the next one and ask the question explicitly. -- Felipe Contreras ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: [PATCH v2 0/2] user-manual: new "getting started" section 2009-11-17 12:06 ` Nanako Shiraishi 2009-11-17 17:28 ` J. Bruce Fields @ 2009-11-17 17:53 ` Matthieu Moy 1 sibling, 0 replies; 28+ messages in thread From: Matthieu Moy @ 2009-11-17 17:53 UTC (permalink / raw) To: Nanako Shiraishi Cc: Felipe Contreras, Michael J Gruber, Jonathan Nieder, Junio C Hamano, git, J. Bruce Fields, Hannu Koivisto, Jeff King, Wincent Colaiuta, Matthias Lederhofer Nanako Shiraishi <nanako3@lavabit.com> writes: > I don't see how you can make them sanely be usable to > other commands like "git log v1.0.0..WORKTREE". See what gitk is showing you when you have uncommited changes. You have some kind of "pseudo-commits" on top of your history for the index and the worktree. "git log v1.0.0..WORKTREE" could very well be a text-mode version of what's already in gitk. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply [flat|nested] 28+ messages in thread
end of thread, other threads:[~2009-11-18 0:05 UTC | newest] Thread overview: 28+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2009-10-24 9:44 [PATCH v2 0/2] user-manual: new "getting started" section Felipe Contreras 2009-10-24 9:44 ` [PATCH v2 1/2] user-manual: add global config section Felipe Contreras 2009-10-24 9:44 ` [PATCH v2 2/2] user-manual: simplify the user configuration Felipe Contreras 2009-10-24 13:06 ` [PATCH v2 0/2] user-manual: new "getting started" section Nanako Shiraishi 2009-10-24 14:08 ` Felipe Contreras 2009-10-24 14:14 ` Björn Steinbrink 2009-10-24 14:22 ` Felipe Contreras 2009-10-24 17:51 ` Junio C Hamano 2009-10-24 18:19 ` Junio C Hamano 2009-10-24 20:16 ` Felipe Contreras 2009-10-25 0:26 ` J. Bruce Fields 2009-10-25 3:08 ` Junio C Hamano 2009-10-25 9:43 ` Felipe Contreras 2009-10-25 11:14 ` Jonathan Nieder 2009-11-11 23:15 ` Felipe Contreras 2009-11-12 11:29 ` Michael J Gruber 2009-11-12 20:04 ` Felipe Contreras 2009-11-13 21:06 ` Nanako Shiraishi 2009-11-16 22:52 ` Felipe Contreras 2009-11-17 12:06 ` Nanako Shiraishi 2009-11-17 17:28 ` J. Bruce Fields 2009-11-17 18:25 ` Junio C Hamano 2009-11-17 22:00 ` Felipe Contreras 2009-11-17 22:19 ` Junio C Hamano 2009-11-17 23:06 ` Felipe Contreras 2009-11-17 23:13 ` Junio C Hamano 2009-11-18 0:05 ` Felipe Contreras 2009-11-17 17:53 ` Matthieu Moy
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).