Re: [PATCH] make 'git add' a first class user friendly interface to the index

From: Alan Chandler <alan@chandlerfamily.org.uk>
Date: Dec 2, 2006, 08:28 UTC
Message-ID: <200612020828.57989.alan@chandlerfamily.org.uk>
In-Reply-To: <87veku3i0j.wl%cworth@cworth.org>

On Saturday 02 December 2006 06:54, Carl Worth wrote: ...

Show 23 quoted lines

> 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).
>

...

Show 18 quoted lines

> 
> 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.
>

...

Show 6 quoted lines

> 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