{"thread":{"id":"21880","subject":"[PATCH 1/2] Documentation: 'git add --all' can remove files","startedAt":"2009-12-06T18:07:14Z","lastAt":"2009-12-06T21:14:33Z","messageCount":2,"participants":["Björn Gustavsson","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"129348","messageId":"4B1BF2D2.8000506@gmail.com","threadId":"21880","inReplyTo":null,"subject":"[PATCH 1/2] Documentation: 'git add --all' can remove files","fromName":"Björn Gustavsson","fromEmail":"bgustavsson@gmail.com","sentAt":"2009-12-06T18:07:14Z","receivedAt":"2009-12-06T18:07:14Z","isPatch":true,"sender":{"key":"bgustavsson@gmail.com","avatar":"https://avatars.githubusercontent.com/u/74840?v=4"},"body":"Document that 'git add --all' can remove files no longer present\nin the working tree from the index. Also mention why it is useful,\nand insert a cross-reference in the 'git rm' documentation to\n'git add --all'.\n\nSigned-off-by: Björn Gustavsson <bgustavsson@gmail.com>\n---\n Documentation/git-add.txt |   13 +++++++++----\n Documentation/git-rm.txt  |    4 ++++\n 2 files changed, 13 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex e93e606..b7e8aa2 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -16,6 +16,8 @@ DESCRIPTION\n -----------\n This command adds the current content of new or modified files to the\n index, thus staging that content for inclusion in the next commit.\n+(Given the `--all` option, the `git add` command will also remove files\n+from the index that are no longer present in the working tree.)\n \n The \"index\" holds a snapshot of the content of the working tree, and it\n is this snapshot that is taken as the contents of the next commit.  Thus\n@@ -102,10 +104,13 @@ apply.\n \n -A::\n --all::\n-\tUpdate files that git already knows about (same as '\\--update')\n-\tand add all untracked files that are not ignored by '.gitignore'\n-\tmechanism.\n-\n+\tUpdate files that git already knows about (same as '\\--update'),\n+\tadd all untracked files that are not ignored by '.gitignore'\n+\tmechanism and remove files from the index that are no longer\n+\tpresent in the working tree.\n++\n+This option is especially useful after running the `rsync` command with\n+the working tree as the target to sync the index with the working tree.\n \n -N::\n --intent-to-add::\ndiff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt\nindex 5afb1e7..b4dff5b 100644\n--- a/Documentation/git-rm.txt\n+++ b/Documentation/git-rm.txt\n@@ -81,6 +81,10 @@ two directories `d` and `d2`, there is a difference between\n using `git rm \\'d\\*\\'` and `git rm \\'d/\\*\\'`, as the former will\n also remove all of directory `d2`.\n \n+To automatically remove all files from the index that are no longer\n+present in the working tree, see the `--all` option for\n+linkgit:git-add[1].\n+\n EXAMPLES\n --------\n git rm Documentation/\\\\*.txt::\n-- \n1.6.6.rc1.31.g1a56b\n"},{"id":"129355","messageId":"7vmy1vg5za.fsf@alter.siamese.dyndns.org","threadId":"21880","inReplyTo":"4B1BF2D2.8000506@gmail.com","subject":"Re: [PATCH 1/2] Documentation: 'git add --all' can remove files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-12-06T21:14:33Z","receivedAt":"2009-12-06T21:14:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Björn Gustavsson <bgustavsson@gmail.com> writes:\n\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index e93e606..b7e8aa2 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -16,6 +16,8 @@ DESCRIPTION\n>  -----------\n>  This command adds the current content of new or modified files to the\n>  index, thus staging that content for inclusion in the next commit.\n> +(Given the `--all` option, the `git add` command will also remove files\n> +from the index that are no longer present in the working tree.)\n\nThe first paragraph says what \"git add\" does in general (does \"something\"\nto the index) and continues to the second paragraph that describes what an\nindex is.\n\nIt is a good point that you noticed that the existing description of 'does\n\"something\" to the index' covers only the \"add as an entirety\" and not the\nwhole range of what \"git add\" can be used for.  One thing that is missing\nis a removal, and \"-A\" is one of the two options that lets you do so.\n\nBut \"-u\" is to match the index with the work tree contents (it does not\nadd untracked-so-far paths).  At least, \"Given the `--all` option,\" part\nneeds to be rethought.\n\nMore importantly, 'does \"something\" to the index' is not limited to the\n\"add whole\" and \"remove path\".  Perhaps we would want to update the first\nparagraph like this to cover partial add while we are at it.\n\n\tThis command updates the index using the current content found in\n        the work tree, to prepare the content staged for the next commit.\n        It typically adds the current content of existing paths as a whole\n        but with some options, it can also be used to add a content with\n        only part of the changes made to the work tree files applied, or\n        remove paths that do not exist in the work tree anymore.\n\nThat way we also cover what \"add -p\" lets you do.\n\n> ++\n> +This option is especially useful after running the `rsync` command with\n> +the working tree as the target to sync the index with the working tree.\n\nI do not think mentioning `rsync` like this is helpful; I actually think\nthis clutteres the document and nudges people in a wrong direction at the\nsame time.  You usually don't overwrite your source tree you already have\nunder control with rsync.  Use cases that do not use \"git\" as a SCM but as\nsomething else do have a valid reason to use rsync, but \"git add -A\" being\nuseful for that use case is a side effect, and I do not think we should\nhint people who use \"git\" as a SCM into that direction, by casually\nmentioning the use of `rsync` like the above as if it is a common and\nencouraged thing to update your work tree from sideways.\n\n> diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt\n> index 5afb1e7..b4dff5b 100644\n> --- a/Documentation/git-rm.txt\n> +++ b/Documentation/git-rm.txt\n> @@ -81,6 +81,10 @@ two directories `d` and `d2`, there is a difference between\n>  using `git rm \\'d\\*\\'` and `git rm \\'d/\\*\\'`, as the former will\n>  also remove all of directory `d2`.\n>  \n> +To automatically remove all files from the index that are no longer\n> +present in the working tree, see the `--all` option for\n> +linkgit:git-add[1].\n\nI think this change is a lot more harmful than being helpful.  Many lazy\nreaders would _not_ read \"git add --help\" but would think \"git add -A\"\nwould \"automatically remove all files from the index that are no longer\npresent\".  But \"add -A\" does a lot more than:\n\n    git diff --name-only --diff-filter=D -z | xargs -0 rm -f\n\nSo overall I am happy with the issue you identified, but not very happy\nwith the proposed solution.\n"}]}