Re: Documentation/git-commit.txt

From: Junio C Hamano <junkio@cox.net>
Date: Dec 8, 2006, 19:31 UTC
Message-ID: <7vfybqi3r1.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <4579529F.9030401@Intel.com>

Salikh Zakirov <Salikh.Zakirov@Intel.com> writes:

Show 10 quoted lines

> Junio Hamano wrote:
>> +Instead of staging files after each individual change, you can
>> +tell `git commit` to notice the changes to the tracked files in
>> +your working tree and do corresponding `git add` and `git rm`
>> +for you.  
>
> This part is confusing as hell to anyone having any experience
> with either CVS, SVN, Hg or Monotone, as doing "corresponding `git add`
> and `git rm`" commands automatically will be interpreted as adding
> untracked files automatically, which is not the case here.

Well, that's why the description says 'the changes to the tracked files' above to make it clear. An obvious alternative is not to talk about staging in terms of `git add` and `git rm` but instead mention `git update-index` in that part of the documentation, but I think that is going backwards. I think the conclusion of recent discussions is not to paper over the differences from new people (nor making git closer to other systems by castrating git), but make things easier to learn for them. My attempt to update git-commit documentation is a part of this effort.

Better rewording is very much appreciated.

But you are right. Prior experiences with other systems would make it harder to learn git here, because 'git add', especially with Nico's enhancement in 'next', is different from 'cvs add'.

The problem is that these systems do not have the concept of tracking 'contents' (they instead track paths), and 'add' to them mean 'add the named paths to the set of tracked paths'.

On the other hand, git fundamentally tracks contents. We do have the concept of 'the set of tracked paths', but that is a side effect of tracking contents. In other words, you do not 'add' a path without 'add'ing its contents.

By the way, I have been wondering if the --only variant of the command should also add untracked files to the index. That is:

	$ git commit foo.c '*.h'

currently barfs if foo.c is not tracked, and/or there is no tracked header files. We could instead run git-update-index --add on them.

Incidentally, this would make this sequence possible:

	$ tar xf /var/tmp/foo.tar ;# extract tarball here.
        $ git init-db
        $ git commit -m 'initial import' .