Re: [PATCH 1/2] Documentation: 'git add -A' can remove files

["Björn Steinbrink" <B.Steinbrink@gmx.de>]

On 2009.12.06 23:34:03 -0800, Junio C Hamano wrote:
> Björn Steinbrink <B.Steinbrink@gmx.de> writes:
> 
> > What I usually say on #git is something like:
> >
> > 	"git add <path>" looks at the working tree to find files
> > 	matching <path>.  "git add -u <path>" looks at the index, and
> > 	"git add -A <path>" looks at both. Therefore "add" and "add -A"
> > 	can add new files to the index, and "add -u" and "add -A" can
> > 	remove files from it.
> >
> > 	And for convenience, -u and -A default to "." as the path argument.
> 
> Hmm, an interesting way of teaching. How effective is it with the real new
> to mid-level users we see on the #git channel?

Hm, I wanted to check the channel logs for some reactions, but couldn't
find much. Apparently, I've not answered many question about add -u/-A
on #git since I switched to the above explanation (instead of saying
"git add -A is like git add . && git add -u" as I did in the past). For
the cases I found, the users didn't reply to the explanation. I can't
tell whether the explanation sucks, or whether the user was happy with
it or simply didn't care because he got the command he wanted.

I have two more data points for that kind of explanation in my Jabber
history, but those users aren't "new to mid-level" anymore.

And I recall only one really new user I told this to in face-to-face
"teaching", and that was right after explaining the index, so the
concept was present.

I guess the explanation might not be as easy to grok for someone that
doesn't have a good understanding of the index. For example, those that
still think that the index only stores changes (and is empty when no
"changes" have been staged) probably won't be able to make any sense out
of it.

Guess I'll have to apply a bunch of context when choosing which
explanation to use.

> 
> > So maybe something like this?
> > ...
> > -A, --all
> >     Like -u, but matches <filepattern> against files in the index in
> >     addition to the files in working tree. This means that it can find
> >     new files as well.
> 
> Sounds easier to read to me but I think this description of "-A" seems
> backwards from your explanation.  "Like -u" means "matches the index" and
> the difference is it in addition matches with the work tree, so it should
> probably be the other way around, i.e.
> 
>      Like -u, but matches <filepattern> against files in the work tree in
>      addition to the index. This means that it can find new files as well.

Hm, I meant that to show that while -u uses the index _instead_ of the
working tree, -A uses the index _in_addition_to_ the working tree, i.e.
I meant to say how -A differs from -u WRT its effect compared to a plain
"git add".

IOW, I treat "git add" (working tree only) as the default behaviour. And
-u changes it to "index only", while -A changes it to "working tree +
index". Your version makes it look more like -A is a modification of -u.

OTOH, I also used to say "to update all tracked files, use add -u, and
to also add new files use add -A", which is better matched by your
wording. Though I'd go for this then:

    Like -u, but also match <filepattern> against files in the working
    tree. This means that it can find new files as well

Which just says what -A does on top of -u, without repeating what -u
does.

Björn