{"thread":{"id":"21882","subject":"[PATCH 1/2] Documentation: 'git add -A' can remove files","startedAt":"2009-12-06T23:03:38Z","lastAt":"2009-12-07T08:48:11Z","messageCount":6,"participants":["Björn Gustavsson","Junio C Hamano","Björn Steinbrink"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"129357","messageId":"4B1C384A.8000106@gmail.com","threadId":"21882","inReplyTo":null,"subject":"[PATCH 1/2] Documentation: 'git add -A' can remove files","fromName":"Björn Gustavsson","fromEmail":"bgustavsson@gmail.com","sentAt":"2009-12-06T23:03:38Z","receivedAt":"2009-12-06T23:03:38Z","isPatch":true,"sender":{"key":"bgustavsson@gmail.com","avatar":"https://avatars.githubusercontent.com/u/74840?v=4"},"body":"Document that 'git add -A/--all' can remove files no longer\npresent in the working tree from the index, and also document the\nbehavior with and without path arguments on the command line.\n\nAlso update the intro paragraph (as suggested by Junio, with\nsome minor edits) to make it clear that 'git add' is able to\ndelete and to also cover the -p option.\n\nSigned-off-by: Björn Gustavsson \n---\nThanks, Junio, for reviewing my patch, and for suggesting a\nmuch better intro paragraph.\n\nI have cut out the mention of rsync and the reference from\ngit-rm.\n\nI also realized that the documentation was not clear on whether\nany path arguments were allowed, so I have clarified that too.\n\n Documentation/git-add.txt | 20 ++++++++++++++------\n 1 files changed, 14 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex e93e606..6d3e76f 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -14,8 +14,12 @@ SYNOPSIS\n \n 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+This command updates the index using the current content found in\n+the working 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 content with\n+only part of the changes made to the working tree files applied, or\n+remove paths that do not exist in the work tree anymore.\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 +106,14 @@ 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 the '.gitignore'\n+\tmechanism and remove files from the index that are no longer\n+\tpresent in the working tree.\n++\n+If no paths are given on the command line, `git add -A` will operate\n+on the current directory and its subdirectories. If paths are given,\n+it will operate on those paths and their subdirectories.\n \n -N::\n --intent-to-add::\n-- \n1.6.6.rc1.31.g1a56b\n"},{"id":"129359","messageId":"7vr5r7el2q.fsf@alter.siamese.dyndns.org","threadId":"21882","inReplyTo":"4B1C384A.8000106@gmail.com","subject":"Re: [PATCH 1/2] Documentation: 'git add -A' can remove files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-12-06T23:31:25Z","receivedAt":"2009-12-06T23:31:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Björn Gustavsson writes:\n\n> Document that 'git add -A/--all' can remove files no longer\n> present in the working tree from the index, and also document the\n> behavior with and without path arguments on the command line.\n\nThanks.\n\n> +This command updates the index using the current content found in\n> +the working 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 content with\n> +only part of the changes made to the working tree files applied, or\n> +remove paths that do not exist in the work tree anymore.\n\nYou probably want to change the last one also to \"working tree\"?\n\nI often write this as \"work tree\" without thinking too much about \"work\"\nvs \"working\", but if anybody asks me, I prefer the former because it is\nshorter and because it is more consistent with the way how names of the\nenvironment variable GIT_WORK_TREE and the configuration variable\ncore.worktree are spelled. I personally am OK with either word used in\nthe descriptive text, as there is no room for confusion.\n\nBut it would be better to be consistent in a single paragraph.\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 the '.gitignore'\n> +\tmechanism and remove files from the index that are no longer\n> +\tpresent in the working tree.\n> ++\n> +If no paths are given on the command line, `git add -A` will operate\n> +on the current directory and its subdirectories. If paths are given,\n> +it will operate on those paths and their subdirectories.\n\nThe first line of the existing description for \"--all\", by saying \"same as\n--update\", refers to the first sentence of the corresponding entry for\n\"update\", which says:\n\n -u::\n --update::\n Update only files that git already knows about, staging modified\n content for commit and marking deleted files for removal. This\n is similar\n to what \"git commit -a\" does in preparation for making a commit,\n except that the update is limited to paths specified on the\n command line. If no paths are specified, all tracked files in the\n current directory and its subdirectories are updated.\n\nIn fact, \"-A\" is \"do everything -u does, including removal of lost paths,\nhonoring the pathspecs exactly the same way (e.g. no pathspec is to work\nin the current directory). but unlike -u, also add any new files that are\nnot excluded by the ignore mechanism.\" There is something wrong if we\nhave to spend more lines to describe \"-A\" than we describe \"-u\", if\ndescription of \"-A\" says \"it does the same for -u, and in addition...\".\n\nI wonder if we can restructure the description of \"-u\" to make it easier\nto read, to simplify the description of \"-A\".\n"},{"id":"129362","messageId":"7v4oo3ejhy.fsf@alter.siamese.dyndns.org","threadId":"21882","inReplyTo":"4B1C384A.8000106@gmail.com","subject":"Re: [PATCH 1/2] Documentation: 'git add -A' can remove files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-12-07T00:05:29Z","receivedAt":"2009-12-07T00:05:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Björn Gustavsson writes:\n\n> I have cut out the mention of rsync and the reference from\n> git-rm.\n\nI am sorry, but I would like to rescind my earlier comment on the 'rsync'\nissue. When tracking \"vendor code drop\", you often need to:\n\n - untar the version 1 of vendor code drop\n - git init\n - git add -A\n - git commit -m 'vendor #1'\n - git ls-files -z | xargs -0 rm -f ;# remove everything\n - untar the version 1.1\n - git add -A\n - git commit -m 'vendor #1.1'\n ...\n\nand the ability to notice and remove \"gone\" files while adding anything\nnew indeed is a very valid and useful thing to have. The initial \"-A\" can\nalso be spelled as \"git add .\", but not the second and subsequent code\ndrop.\n\nIf your vendor tree is online and rsync'able, \"untar\" in the above\nsequence will naturally be replaced with \"rsync\", and it is entirely\nwithin the scope of SCM.\n\nRegarding \"git rm\", if people very often need to remove paths from the\nindex that are already gone from the filesystem, perhaps we would need an\noption to \"rm\" to let them do that.\n\nHowever, if the reason these people want to do such a removal is almost\nalways because they are accepting a vendor code drop (meaning, they not\nonly want to remove disappeared paths but also want to add new paths at\nthe same time), referring to \"git add -A\" from that manual page would make\na lot of sense. So in that sense, I am not against your original patch\nper-se, but I think the prerequisite context needs to be explained in the\ndocumentation a bit better.\n\nHere is my attempt. I didn't check the existing text of \"git rm\" manual,\nso I do not know if its structure to use displayed examples flows\nnaturally with the existing text; you may need to rewrite to adjust to the\nexisting style.\n\n--\n\nSometimes people ask how paths that disappeared from the filesystem can be\nremoved from the index. A straight answer is\n\n----------------\ngit diff --name-only --diff-filter=D -z | xargs -0 git rm --cached\n----------------\n\nbut it often is not what these people really want to do (XY problem), and\nthere are two alternate answers that may suit their situation better.\n\n1. They may be doing their own development and have removed files from the\nfilesystem using \"rm\" (not \"git rm\"), fully intending that they want to\nrecord the removal of these paths in the next commit. If you make the\nnext commit with \"git commit -a\", it will automatically notice these\nremovals, and there is no need for such a removal they ask in the first\nplace, as long as they intend to make a full commit.\n\nAsking for \"removing all the removed paths from the index\" is a sign of\nwanting to commit the full state of the work tree, as opposed to \"commit\nthis and that change but not others, which you do not use \"commit -a\" for.\n\nSo the second answer may be \"you do not need to in your use case.\"\n\n2. They may be accepting a new vendor code drop, and have just updated\ntheir work tree by untarring (or rsync'ing). They not only want to record\nremoval of disappeared paths, but also want to record addition of new\npaths, but if they know only \"git add\" (but not \"add -A\" or \"add -u\"), it\nmay appear that a separate \"git rm\" to remove disappeared paths is needed.\nIn such a case, instead of doing\n\n----------------\ngit add .\ngit diff --name-only --diff-filter=D -z | xargs -0 git rm --cached\n----------------\n\nthey can simply do so with\n\n----------------\ngit add -A\n----------------\n\nHence the third answer may be \"you do not have to in your use case.\"\n"},{"id":"129370","messageId":"20091207005732.GA20909@atjola.homenet","threadId":"21882","inReplyTo":"7vr5r7el2q.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation: 'git add -A' can remove files","fromName":"Björn Steinbrink","fromEmail":"b.steinbrink@gmx.de","sentAt":"2009-12-07T00:57:32Z","receivedAt":"2009-12-07T00:57:32Z","isPatch":true,"sender":{"key":"b.steinbrink@gmx.de","avatar":"https://avatars.githubusercontent.com/u/230962?v=4"},"body":"On 2009.12.06 15:31:25 -0800, Junio C Hamano wrote:\n> I wonder if we can restructure the description of \"-u\" to make it easier\n> to read, to simplify the description of \"-A\".\n\nWhat I usually say on #git is something like:\n\n\t\"git add \" looks at the working tree to find files\n\tmatching . \"git add -u \" looks at the index, and\n\t\"git add -A \" looks at both. Therefore \"add\" and \"add -A\"\n\tcan add new files to the index, and \"add -u\" and \"add -A\" can\n\tremove files from it.\n\n\tAnd for convenience, -u and -A default to \".\" as the path argument.\n\nSo maybe something like this?\n\n-u, --update\n Instead of matching against files in the working tree,\n it is matched against the already tracked files in the index. This\n means that it won't find any new files, but can find files already\n deleted from the working tree and remove them from the index. Also,\n if no is given, this option will make it default to\n \".\", updating all tracked files in the current directory and its\n subdirectories.\n\n-A, --all\n Like -u, but matches against files in the index in\n addition to the files in working tree. This means that it can find\n new files as well.\n\n\nBjörn\n"},{"id":"129386","messageId":"7vbpib9r10.fsf@alter.siamese.dyndns.org","threadId":"21882","inReplyTo":"20091207005732.GA20909@atjola.homenet","subject":"Re: [PATCH 1/2] Documentation: 'git add -A' can remove files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-12-07T07:34:03Z","receivedAt":"2009-12-07T07:34:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Björn Steinbrink writes:\n\n> What I usually say on #git is something like:\n>\n> \t\"git add \" looks at the working tree to find files\n> \tmatching . \"git add -u \" looks at the index, and\n> \t\"git add -A \" looks at both. Therefore \"add\" and \"add -A\"\n> \tcan add new files to the index, and \"add -u\" and \"add -A\" can\n> \tremove files from it.\n>\n> \tAnd for convenience, -u and -A default to \".\" as the path argument.\n\nHmm, an interesting way of teaching. How effective is it with the real new\nto mid-level users we see on the #git channel?\n\n> So maybe something like this?\n> ...\n> -A, --all\n> Like -u, but matches against files in the index in\n> addition to the files in working tree. This means that it can find\n> new files as well.\n\nSounds easier to read to me but I think this description of \"-A\" seems\nbackwards from your explanation. \"Like -u\" means \"matches the index\" and\nthe difference is it in addition matches with the work tree, so it should\nprobably be the other way around, i.e.\n\n Like -u, but matches against files in the work tree in\n addition to the index. This means that it can find new files as well.\n"},{"id":"129392","messageId":"20091207084811.GA31622@atjola.homenet","threadId":"21882","inReplyTo":"7vbpib9r10.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/2] Documentation: 'git add -A' can remove files","fromName":"Björn Steinbrink","fromEmail":"b.steinbrink@gmx.de","sentAt":"2009-12-07T08:48:11Z","receivedAt":"2009-12-07T08:48:11Z","isPatch":true,"sender":{"key":"b.steinbrink@gmx.de","avatar":"https://avatars.githubusercontent.com/u/230962?v=4"},"body":"On 2009.12.06 23:34:03 -0800, Junio C Hamano wrote:\n> Björn Steinbrink writes:\n> \n> > What I usually say on #git is something like:\n> >\n> > \t\"git add \" looks at the working tree to find files\n> > \tmatching . \"git add -u \" looks at the index, and\n> > \t\"git add -A \" looks at both. Therefore \"add\" and \"add -A\"\n> > \tcan add new files to the index, and \"add -u\" and \"add -A\" can\n> > \tremove files from it.\n> >\n> > \tAnd for convenience, -u and -A default to \".\" as the path argument.\n> \n> Hmm, an interesting way of teaching. How effective is it with the real new\n> to mid-level users we see on the #git channel?\n\nHm, I wanted to check the channel logs for some reactions, but couldn't\nfind much. Apparently, I've not answered many question about add -u/-A\non #git since I switched to the above explanation (instead of saying\n\"git add -A is like git add . && git add -u\" as I did in the past). For\nthe cases I found, the users didn't reply to the explanation. I can't\ntell whether the explanation sucks, or whether the user was happy with\nit or simply didn't care because he got the command he wanted.\n\nI have two more data points for that kind of explanation in my Jabber\nhistory, but those users aren't \"new to mid-level\" anymore.\n\nAnd I recall only one really new user I told this to in face-to-face\n\"teaching\", and that was right after explaining the index, so the\nconcept was present.\n\nI guess the explanation might not be as easy to grok for someone that\ndoesn't have a good understanding of the index. For example, those that\nstill think that the index only stores changes (and is empty when no\n\"changes\" have been staged) probably won't be able to make any sense out\nof it.\n\nGuess I'll have to apply a bunch of context when choosing which\nexplanation to use.\n\n> \n> > So maybe something like this?\n> > ...\n> > -A, --all\n> > Like -u, but matches against files in the index in\n> > addition to the files in working tree. This means that it can find\n> > new files as well.\n> \n> Sounds easier to read to me but I think this description of \"-A\" seems\n> backwards from your explanation. \"Like -u\" means \"matches the index\" and\n> the difference is it in addition matches with the work tree, so it should\n> probably be the other way around, i.e.\n> \n> Like -u, but matches against files in the work tree in\n> addition to the index. This means that it can find new files as well.\n\nHm, I meant that to show that while -u uses the index _instead_ of the\nworking tree, -A uses the index _in_addition_to_ the working tree, i.e.\nI meant to say how -A differs from -u WRT its effect compared to a plain\n\"git add\".\n\nIOW, I treat \"git add\" (working tree only) as the default behaviour. And\n-u changes it to \"index only\", while -A changes it to \"working tree +\nindex\". Your version makes it look more like -A is a modification of -u.\n\nOTOH, I also used to say \"to update all tracked files, use add -u, and\nto also add new files use add -A\", which is better matched by your\nwording. Though I'd go for this then:\n\n Like -u, but also match against files in the working\n tree. This means that it can find new files as well\n\nWhich just says what -A does on top of -u, without repeating what -u\ndoes.\n\nBjörn\n"}]}