On Thu, 30 Nov 2006, Junio C Hamano wrote:

Nicolas Pitre [off-list ref] writes:

quoted

...  But let me repeat my last question:

Would it make sense for "git add" to do the same as "git update-index" 
on already tracked files?  Given the explanation above this would make 
100% sense to me.

I think this makes sense and what we did in the original "git
add".

Wonderful! We might be converging to something then.

Because, conceptually, it then becomes much easier to tell newbies about 
the index as follows (this could be pasted in a tutorial somewhere):

  Contrary to other SCMs, with GIT you have to explicitly "add" all
  the changes you want to commit together.  This can be done in a few
  different ways:

  1) By using "git add <file_spec...>"

     This can be performed multiple times before a commit.  Note that 
     this is not only for adding new files.  Even modified files must be
     added to the set of changes about to be committed.  The "git 
     status" command gives you a summary of what is included so far for 
     the commit.  When done you should use the "git commit" command to
     make it real.

     Note: don't forget to "add" a file again if you modified it after 
     the first "add" and before "commit". Otherwise only the previous 
     "added" state of that file will be committed.

  2) By using "git commit -a" directly

     This is a quick way to automatically "add" all modified files to 
     the set of changes and perform the actual commit without having to 
     separately "add" them.  This will not "add" new files -- those 
     files still have to be added explicitly before performing a commit.

  Here's a twist.  If you do "git commit <file1> <file2> ..." then 
  only the  changes belonging to those explicitly specified files will 
  be committed, entirely bypassing the current "added" changes.  Those
  "added" changes will still remain available for a subsequent commit.

  There is a twist about that twist: if you do "git commit -i <file>..." 
  then the commit will consider changes to those specified files 
  _including_ all "added" changes so far.

  But for instance it is best to only remember "git add" + "git 
  commit" and/or "git commit -a".

Doesn't it sounds nice?  The index is being introduced up front without 
even mentioning it, and I think the above should be fairly palatable to 
newbies as well.  Would only lack some enhancements to the commit 
template and the "nothing to commit" message so the user is cued about 
the fact that "current changeset is empty -- don't forget to 'git add' 
modified files, or use 'git commit -a'".

What do you think?