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

[Junio C Hamano <gitster@pobox.com>]

Björn Gustavsson <bgustavsson@gmail.com> writes:

> I have cut out the mention of rsync and the reference from
> git-rm.

I am sorry, but I would like to rescind my earlier comment on the 'rsync'
issue.  When tracking "vendor code drop", you often need to:

    - untar the version 1 of vendor code drop
    - git init
    - git add -A
    - git commit -m 'vendor #1'
    - git ls-files -z | xargs -0 rm -f ;# remove everything
    - untar the version 1.1
    - git add -A
    - git commit -m 'vendor #1.1'
    ...

and the ability to notice and remove "gone" files while adding anything
new indeed is a very valid and useful thing to have.  The initial "-A" can
also be spelled as "git add .", but not the second and subsequent code
drop.

If your vendor tree is online and rsync'able, "untar" in the above
sequence will naturally be replaced with "rsync", and it is entirely
within the scope of SCM.

Regarding "git rm", if people very often need to remove paths from the
index that are already gone from the filesystem, perhaps we would need an
option to "rm" to let them do that.

However, if the reason these people want to do such a removal is almost
always because they are accepting a vendor code drop (meaning, they not
only want to remove disappeared paths but also want to add new paths at
the same time), referring to "git add -A" from that manual page would make
a lot of sense.  So in that sense, I am not against your original patch
per-se, but I think the prerequisite context needs to be explained in the
documentation a bit better.

Here is my attempt.  I didn't check the existing text of "git rm" manual,
so I do not know if its structure to use displayed examples flows
naturally with the existing text; you may need to rewrite to adjust to the
existing style.

--

Sometimes people ask how paths that disappeared from the filesystem can be
removed from the index.  A straight answer is

----------------
git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached
----------------

but it often is not what these people really want to do (XY problem), and
there are two alternate answers that may suit their situation better.

1. They may be doing their own development and have removed files from the
filesystem using "rm" (not "git rm"), fully intending that they want to
record the removal of these paths in the next commit.  If you make the
next commit with "git commit -a", it will automatically notice these
removals, and there is no need for such a removal they ask in the first
place, as long as they intend to make a full commit.

Asking for "removing all the removed paths from the index" is a sign of
wanting to commit the full state of the work tree, as opposed to "commit
this and that change but not others, which you do not use "commit -a" for.

So the second answer may be "you do not need to in your use case."

2. They may be accepting a new vendor code drop, and have just updated
their work tree by untarring (or rsync'ing).  They not only want to record
removal of disappeared paths, but also want to record addition of new
paths, but if they know only "git add" (but not "add -A" or "add -u"), it
may appear that a separate "git rm" to remove disappeared paths is needed.
In such a case, instead of doing

----------------
git add .
git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached
----------------

they can simply do so with

----------------
git add -A
----------------

Hence the third answer may be "you do not have to in your use case."