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

Björn Gustavsson [off-list ref] 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".

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