On Fri, 12 Jan 2007 16:48:09 -0800, Junio C Hamano wrote: > Peter Baumann <waste.manager@xxxxxx> writes: > > > Yes. I fully second Linus opinion. But I think there should be > > a difference in adding completly new content to the index > > (number of entries in the index grows) or replacing content in > > the index. > > Huh? Here's an easy way to see the difference that Peter is trying to point out, (and it really has nothing to do with whether "git add" for a new file should add the content of that file to the index---that's a totally separate issue that Linus was talking about in that other message). Just look at "commit -a" and how its documented right now. Currently it's documented as doing an automatic "add" to all known files. That descriptions is unsatisfactory for two reasons: 1. "commit -a" will also commit the removal of files---which requires an index modification that "git add" cannot do 2. "add" can cause an entirely new path (with content, Vader!) to be added to the index. So the user has to carefully separate out this behavior of "add" to properly understand what "commit -a" is doing. The documentation tries to help here with "known files", but the talk of an "automatic 'add'" that never adds any new paths really goes against the primary functionality of "git add". I say "primary functionality" because the 'commit -a' workflow, (which we've all agreed should be the thing that is taught first), requires users to use 'git add' when adding a new path to the index, but never requires the user to use the 'update the index' sense of 'git add', (instead, the user just needs to _learn_ this sense to understand commit -a). So there's lots of room for potential confusion there, and we've got evidence of that confusion in the messages that started this an other recent threads about how to remove files. I like the idea of adding a porcelain command for update-index, and it's nice to try to describe "commit -a" in terms of the new porcelain command. But, to make that really work, I think that porcelain for update-index should really match the semantics needed by "commit -a". That is, it should never add new paths to the index, but it should update content for existing paths, and it should remove paths from the index when files have been removed from the working tree. Let's call this new command "refresh", just to experiment with another name. If it existed, then "commit -a" could be described as simply doing "refresh" on all files, (with no need to have a notion of "tracked files", nor any extra language about file removal). That is, "commit -a" could be understood as something like: git refresh -a git commit (or maybe "git refresh .; git commit" if one prefers that, but I think it'd be nice to carry the -a option over to the new porcelain). Also, this would even make it possible to provide an accurate index-based description of "commit paths...". Namely, something like: commit paths... This command starts with a new index initialized from the contents of the current commit (HEAD). It then performs the following commands: git refresh paths... git commit [Some extra language needed here about restoring into the index other changes that were "skipped over".] So, someone might like to have that kind of description somewhere in the technical documentation of git. (I'd still prefer to see "commit paths..." documented as simply "commits the working-tree content of all specified paths"). Anyway, did I succeed in pointing out why some of us think that the "add a new path (with content) to the index" and the "update content for existing path" really shouldn't be mixed up in the same "add" command? -Carl
Attachment:
pgpYsUH8rx5Fx.pgp
Description: PGP signature