On Saturday 02 December 2006 06:54, Carl Worth wrote: ... > The proposal in the current thread of using "add" is an improvement on > the shortness side, and I am _delighted_ to see documentation > appearing that is focused on what the user wants to achieve and what > the user should expect to happen. So, Junio, please go ahead with > Nico's stuff here. It is an improvement over the current > situation. (And thanks, Nico, for fighting against having technical > details getting added to user-oriented documentation). > > But I do still think it's a mistake to muddle the concepts of "adding" > a file and "staging edited content" for a file. In index terms, the > distinction is between adding a new path (and contents, of course) to > the index vs. just updating the contents for an existing path. > > But it's not the index distinction that's interesting. It's that users > think of those operations differently. An "add" operation takes a > files out of the "untracked file" state as reported by git > status. That's a very different thing conceptually than updating the > contents of a file that is already being tracked by git. And if the > user thinks of an operation as being different, the command should > reflect that. There is a sense in which the user is always right here, > (since if the tool doesn't do what the user wants, the user just goes > somewhere else). > ... > > Except it does still leave open the user confusion of: > > git add file1 > git commit > "cool, that works" > > edit file1 > git add file2 > git commit > "hmm, why didn't file1 get commited that time?!" > > And the only answer we can give to the poor user is: > > Oh, "git add", (and "git commit" for that matter) don't do > what you think they do. Go read the documentation and try > again. > ... > If add really were uniquely about _adding_ files to be tracked, > (rather than just a short synonym for update-index), and if we tweaked > the default behavior of git-commit, we could fix these things. And > all the model and power of git would still exist and be ready to be > learned by anyone that wants it, (rather than only by those who manage > to get past snags like these). There is a conceptual difference between thinking that git-add is about adding a file and git-add adding the current state of a files content. If your conceptual model is the first of these - then I can see why you see a problem with git-add being used to say a files contents have changed. However, if you regard the git-add command is "adding the current content of the file to a staging area" , and you say this is an SCM which by definition keeps the history of things once its been told about them I don't see why there is a need for a different name for the operation the first time and for the operation later. Trying to put myself in the shoes of a newbie - if taught to use add in both ways up front - is to ask why git isn't clever enough to notice that I have changed the content of something it already knows about rather than having it to manually add it again. So I am with you that we need to effective teach git add <filename> #add content of filename to the SCM #edit <filename> git commit -a #commit current state of all tracked content first, and then move on to teach selective commiting The benefit of one name rather than two is that its less to remember -- Alan Chandler http://www.chandlerfamily.org.uk - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html