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

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

[Björn Gustavsson]

Document that 'git add -A/--all' can remove files no longer
present in the working tree from the index, and also document the
behavior with and without path arguments on the command line.

Also update the intro paragraph (as suggested by Junio, with
some minor edits) to make it clear that 'git add' is able to
delete and to also cover the -p option.

Signed-off-by: Björn Gustavsson <bgustavsson@gmail.com>
---
Thanks, Junio, for reviewing my patch, and for suggesting a
much better intro paragraph.

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

I also realized that the documentation was not clear on whether
any path arguments were allowed, so I have clarified that too.

 Documentation/git-add.txt |   20 ++++++++++++++------
 1 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index e93e606..6d3e76f 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -14,8 +14,12 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This command adds the current content of new or modified files to the
-index, thus staging that content for inclusion in the next commit.
+This command updates the index using the current content found in
+the working tree, to prepare the content staged for the next commit.
+It typically adds the current content of existing paths as a whole,
+but with some options it can also be used to add content with
+only part of the changes made to the working tree files applied, or
+remove paths that do not exist in the work tree anymore.
 
 The "index" holds a snapshot of the content of the working tree, and it
 is this snapshot that is taken as the contents of the next commit.  Thus
@@ -102,10 +106,14 @@ apply.
 
 -A::
 --all::
-	Update files that git already knows about (same as '\--update')
-	and add all untracked files that are not ignored by '.gitignore'
-	mechanism.
-
+	Update files that git already knows about (same as '\--update'),
+	add all untracked files that are not ignored by the '.gitignore'
+	mechanism and remove files from the index that are no longer
+	present in the working tree.
++
+If no paths are given on the command line, `git add -A` will operate
+on the current directory and its subdirectories. If paths are given,
+it will operate on those paths and their subdirectories.
 
 -N::
 --intent-to-add::
-- 
1.6.6.rc1.31.g1a56b

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

[Junio C Hamano]

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

> Document that 'git add -A/--all' can remove files no longer
> present in the working tree from the index, and also document the
> behavior with and without path arguments on the command line.

Thanks.

> +This command updates the index using the current content found in
> +the working tree, to prepare the content staged for the next commit.
> +It typically adds the current content of existing paths as a whole,
> +but with some options it can also be used to add content with
> +only part of the changes made to the working tree files applied, or
> +remove paths that do not exist in the work tree anymore.

You probably want to change the last one also to "working tree"?

I often write this as "work tree" without thinking too much about "work"
vs "working", but if anybody asks me, I prefer the former because it is
shorter and because it is more consistent with the way how names of the
environment variable GIT_WORK_TREE and the configuration variable
core.worktree are spelled.  I personally am OK with either word used in
the descriptive text, as there is no room for confusion.

But it would be better to be consistent in a single paragraph.

>  -A::
>  --all::
> -	Update files that git already knows about (same as '\--update')
> -	and add all untracked files that are not ignored by '.gitignore'
> -	mechanism.
> -
> +	Update files that git already knows about (same as '\--update'),
> +	add all untracked files that are not ignored by the '.gitignore'
> +	mechanism and remove files from the index that are no longer
> +	present in the working tree.
> ++
> +If no paths are given on the command line, `git add -A` will operate
> +on the current directory and its subdirectories. If paths are given,
> +it will operate on those paths and their subdirectories.

The first line of the existing description for "--all", by saying "same as
--update", refers to the first sentence of the corresponding entry for
"update", which says:

    -u::
    --update::
            Update only files that git already knows about, staging modified
            content for commit and marking deleted files for removal. This
            is similar
            to what "git commit -a" does in preparation for making a commit,
            except that the update is limited to paths specified on the
            command line. If no paths are specified, all tracked files in the
            current directory and its subdirectories are updated.

In fact, "-A" is "do everything -u does, including removal of lost paths,
honoring the pathspecs exactly the same way (e.g. no pathspec is to work
in the current directory). but unlike -u, also add any new files that are
not excluded by the ignore mechanism."  There is something wrong if we
have to spend more lines to describe "-A" than we describe "-u", if
description of "-A" says "it does the same for -u, and in addition...".

I wonder if we can restructure the description of "-u" to make it easier
to read, to simplify the description of "-A".

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

[Junio C Hamano]

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."

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

[Björn Steinbrink]

On 2009.12.06 15:31:25 -0800, Junio C Hamano wrote:
> I wonder if we can restructure the description of "-u" to make it easier
> to read, to simplify the description of "-A".

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.

So maybe something like this?

-u, --update
    Instead of matching <filepattern> against files in the working tree,
    it is matched against the already tracked files in the index. This
    means that it won't find any new files, but can find files already
    deleted from the working tree and remove them from the index. Also,
    if no <filepattern> is given, this option will make it default to
    ".", updating all tracked files in the current directory and its
    subdirectories.

-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.


Björn

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

[Junio C Hamano]

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?

> 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.

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

[Björn Steinbrink]

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