{"thread":{"id":"19061","subject":"[PATCH 0/2] Documentation: git-clean: description updates","startedAt":"2009-04-25T15:13:39Z","lastAt":"2009-04-26T08:04:16Z","messageCount":8,"participants":["Wesley J. Landaker","Stephen Boyd","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"112302","messageId":"1240672421-10309-1-git-send-email-wjl@icecavern.net","threadId":"19061","inReplyTo":null,"subject":"[PATCH 0/2] Documentation: git-clean: description updates","fromName":"Wesley J. Landaker","fromEmail":"wjl@icecavern.net","sentAt":"2009-04-25T15:13:39Z","receivedAt":"2009-04-25T15:13:39Z","isPatch":true,"sender":{"key":"wjl@icecavern.net","avatar":"https://avatars.githubusercontent.com/u/67229?v=4"},"body":"I stumbled over the git-clean documentation when I was first learning\ngit, and ran into this again when a colleage was asking for help. So\nhere are two fixes.\n\nThe first patch fixes some minor grammatical errors in very\nnon-intrusive manner. This should be completely uncontroversial.\n\nThe second patch rewrites the first paragraph in the description\nsection to make it more readable and friendly. I think this change\nis a very good one, but I split it into a separate patch since it is\na more intrusive change.\n\nWesley J. Landaker (2):\n Documentation: git-clean: fix minor grammatical errors\n Documentation: git-clean: make description more readable\n\n Documentation/git-clean.txt | 13 ++++++++-----\n 1 files changed, 8 insertions(+), 5 deletions(-)\n"},{"id":"112303","messageId":"1240672421-10309-2-git-send-email-wjl@icecavern.net","threadId":"19061","inReplyTo":"1240672421-10309-1-git-send-email-wjl@icecavern.net","subject":"[PATCH 1/2] Documentation: git-clean: fix minor grammatical errors","fromName":"Wesley J. Landaker","fromEmail":"wjl@icecavern.net","sentAt":"2009-04-25T15:13:40Z","receivedAt":"2009-04-25T15:13:40Z","isPatch":true,"sender":{"key":"wjl@icecavern.net","avatar":"https://avatars.githubusercontent.com/u/67229?v=4"},"body":"There were a few minor grammatical errors that made this paragraph hard\nto read. This patch fixes the errors in a very minimal manner.\n\nSigned-off-by: Wesley J. Landaker \n---\n\nThis could still be made much more readable, but this patch tries to be\nvery non-invasive.\n\n Documentation/git-clean.txt | 6 +++---\n 1 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 8a11450..932d44d 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -12,9 +12,9 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Removes files unknown to git. This allows to clean the working tree\n-from files that are not under version control. If the '-x' option is\n-specified, ignored files are also removed, allowing to remove all\n+Removes files unknown to git. This allows cleaning the working tree\n+of files that are not under version control. If the '-x' option is\n+specified, ignored files are also removed, allowing the removal of all\n build products.\n If any optional `...` arguments are given, only those paths\n are affected.\n-- \n1.6.2.4\n"},{"id":"112304","messageId":"1240672421-10309-3-git-send-email-wjl@icecavern.net","threadId":"19061","inReplyTo":"1240672421-10309-1-git-send-email-wjl@icecavern.net","subject":"[PATCH 2/2] Documentation: git-clean: make description more readable","fromName":"Wesley J. Landaker","fromEmail":"wjl@icecavern.net","sentAt":"2009-04-25T15:13:41Z","receivedAt":"2009-04-25T15:13:41Z","isPatch":true,"sender":{"key":"wjl@icecavern.net","avatar":"https://avatars.githubusercontent.com/u/67229?v=4"},"body":"The existing text is a little bit awkward. This rewrites the description\nsection to be more readable and friendly.\n\nSigned-off-by: Wesley J. Landaker \n---\n\nThis is a more major change, but since at least I and one other person I\nknow have both stumbled on this section, I think making it more readable\nand friendly is a good change.\n\n Documentation/git-clean.txt | 13 ++++++++-----\n 1 files changed, 8 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex 932d44d..43b2de7 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -12,14 +12,17 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Removes files unknown to git. This allows cleaning the working tree\n-of files that are not under version control. If the '-x' option is\n-specified, ignored files are also removed, allowing the removal of all\n-build products.\n+\n+This allows cleaning the working tree by removing files that are not\n+under version control.\n+\n+Normally, only files unknown to git are removed, but if the '-x'\n+option is specified, ignored files are also removed. This can, for\n+example, be useful to remove all build products.\n+\n If any optional `...` arguments are given, only those paths\n are affected.\n \n-\n OPTIONS\n -------\n -d::\n-- \n1.6.2.4\n"},{"id":"112313","messageId":"49F35833.5070005@gmail.com","threadId":"19061","inReplyTo":"1240672421-10309-3-git-send-email-wjl@icecavern.net","subject":"Re: [PATCH 2/2] Documentation: git-clean: make description more readable","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2009-04-25T18:36:35Z","receivedAt":"2009-04-25T18:36:35Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"Wesley J. Landaker wrote:\n> DESCRIPTION\n> -----------\n> -Removes files unknown to git. This allows cleaning the working tree\n> -of files that are not under version control. If the '-x' option is\n> -specified, ignored files are also removed, allowing the removal of all\n> -build products.\n> +\n> +This allows cleaning the working tree by removing files that are not\n> +under version control.\n> +\n\nWhy is the \"Removes files unknown to git\" part lost? Maybe it should be\nreplaced with a copy of the Name section, similar to log and diff. For\nexample:\n\nDESCRIPTION\n-----------\nRemoves untracked files from the working tree. This allows cleaning the\nworking tree by removing files that are not under version control.\n\nBut then the second sentence becomes redundant.\n\n> +Normally, only files unknown to git are removed, but if the '-x'\n> +option is specified, ignored files are also removed. This can, for\n> +example, be useful to remove all build products.\n\nThis seems overly wordy. Maybe:\n\nSpecifying the '-x' option will also remove ignored files. This is\nuseful to remove generated files.\n\nBetter?\n\nOn a side note, why is -x getting special treatment here but not -X or\n-d? You might want to just describe the general usefulness of the\ncommand and let the reader move onto the options to learn more.\n"},{"id":"112323","messageId":"7vhc0cxok0.fsf@gitster.siamese.dyndns.org","threadId":"19061","inReplyTo":"1240672421-10309-1-git-send-email-wjl@icecavern.net","subject":"Re: [PATCH 0/2] Documentation: git-clean: description updates","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-04-26T00:10:23Z","receivedAt":"2009-04-26T00:10:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Wesley J. Landaker\" writes:\n\n> I stumbled over the git-clean documentation when I was first learning\n> git, and ran into this again when a colleage was asking for help. So\n> here are two fixes.\n>\n> The first patch fixes some minor grammatical errors in very\n> non-intrusive manner. This should be completely uncontroversial.\n>\n> The second patch rewrites the first paragraph in the description\n> section to make it more readable and friendly. I think this change\n> is a very good one, but I split it into a separate patch since it is\n> a more intrusive change.\n\nThanks, will queue for 1.6.3, as I think both are clearly improvements.\n\nOne could argue that the second one could be further improved, but I do\nnot see anything controversial in it.\n\n This allows cleaning the working tree by removing files that are not\n under version control.\n\n Normally, only files unknown to git are removed, but if the '-x'\n option is specified, ignored files are also removed. This can, for\n example, be useful to remove all build products.\n\nThe only iffy point I can see is that \"unknown\" is a bit fuzzy phrase in\nthis context. I know what you mean, but you are not writing for people\nwho know what \"git clean\" does ;-)\n\nIn the above, \"unknown\" refers to a set of files that is a strict subset\nof \"untracked\" files, excluding the \"ignored\" set. But that is not\ndefined anywhere in the glossary.\n\nSometimes we colloquially say \"files _known_ to git\" to refer to \"tracked\"\nfiles (paths that appear in the index). But your \"files _unknown_ to git\"\nis different from the complement of it.\n\nThe saddest part is that \"untracked files\" is not defined in the glossary\neither.\n\n Normally, the command removes files that are not in the index, but\n ignored (see linkgit:gitignore[5]) files are kept. With the '-x'\n option, the command removes the ignored files as well.\n"},{"id":"112325","messageId":"200904251923.46448.wjl@icecavern.net","threadId":"19061","inReplyTo":"49F35833.5070005@gmail.com","subject":"Re: [PATCH 2/2] Documentation: git-clean: make description more readable","fromName":"Wesley J. Landaker","fromEmail":"wjl@icecavern.net","sentAt":"2009-04-26T01:23:43Z","receivedAt":"2009-04-26T01:23:43Z","isPatch":true,"sender":{"key":"wjl@icecavern.net","avatar":"https://avatars.githubusercontent.com/u/67229?v=4"},"body":"On Saturday 25 April 2009 12:36:35 Stephen Boyd wrote:\n> Wesley J. Landaker wrote:\n> > DESCRIPTION\n> > -----------\n> > -Removes files unknown to git. This allows cleaning the working tree\n> > -of files that are not under version control. If the '-x' option is\n> > -specified, ignored files are also removed, allowing the removal of all\n> > -build products.\n> > +\n> > +This allows cleaning the working tree by removing files that are not\n> > +under version control.\n> > +\n>\n> Why is the \"Removes files unknown to git\" part lost? Maybe it should be\n> replaced with a copy of the Name section, similar to log and diff. For\n> example:\n\nThe main reason I took that out in my patch was because I think the second \nsentence more says the same thing, except more clearly, and the exact \nsemantics of \"files unknown to git\" versus \"ignored files\", etc seem to not have \ngood definitions anyway, so I left that for the second paragraph that talks \nabout how '-x' changes things.\n\nAlso, the NAME section already says \"Remove untracked files from the working \ntree\", and most other git command documentation pages do not repeat the \nsummary in the description, but start right in to the behavioral details.\n\n> > +Normally, only files unknown to git are removed, but if the '-x'\n> > +option is specified, ignored files are also removed. This can, for\n> > +example, be useful to remove all build products.\n>\n> This seems overly wordy. Maybe:\n>\n> Specifying the '-x' option will also remove ignored files. This is\n> useful to remove generated files.\n>\n> Better?\n\nI agree more concise is usually better. But I do think keeping the \"for \nexample\" is important so that the user doesn't think that \"generated files\" is \nsomething special (ignore rules are used for lots of different things).\n\nSo I might edit yours to say:\n\nSpecifying the '-x' option will also remove ignored files. This is useful to \nremove, for example, generated files that are normally ignored.\n\n> On a side note, why is -x getting special treatment here but not -X or\n> -d? You might want to just describe the general usefulness of the\n> command and let the reader move onto the options to learn more.\n\nI left the part about '-x' there mostly because it was already in there, so I \nfigured someone at some point thought it was special enough. I didn't want to \nundo any good decisions that had already been made. =) That said, both -x and \n-X are somewhat special because they change the behavior a LOT compared to, \nsay, -d.\n"},{"id":"112326","messageId":"200904251933.56710.wjl@icecavern.net","threadId":"19061","inReplyTo":"7vhc0cxok0.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH 0/2] Documentation: git-clean: description updates","fromName":"Wesley J. Landaker","fromEmail":"wjl@icecavern.net","sentAt":"2009-04-26T01:33:55Z","receivedAt":"2009-04-26T01:33:55Z","isPatch":true,"sender":{"key":"wjl@icecavern.net","avatar":"https://avatars.githubusercontent.com/u/67229?v=4"},"body":"On Saturday 25 April 2009 18:10:23 Junio C Hamano wrote:\n> Thanks, will queue for 1.6.3, as I think both are clearly improvements.\n>\n> One could argue that the second one could be further improved, but I do\n> not see anything controversial in it.\n\nOkay, great! I'm all for incremental improvements, so please do hack my patch \nup if it helps!\n\n> This allows cleaning the working tree by removing files that are not\n> under version control.\n>\n> Normally, only files unknown to git are removed, but if the '-x'\n> option is specified, ignored files are also removed. This can, for\n> example, be useful to remove all build products.\n>\n> The only iffy point I can see is that \"unknown\" is a bit fuzzy phrase in\n> this context. I know what you mean, but you are not writing for people\n> who know what \"git clean\" does ;-)\n>\n> In the above, \"unknown\" refers to a set of files that is a strict subset\n> of \"untracked\" files, excluding the \"ignored\" set. But that is not\n> defined anywhere in the glossary.\n>\n> Sometimes we colloquially say \"files _known_ to git\" to refer to \"tracked\"\n> files (paths that appear in the index). But your \"files _unknown_ to git\"\n> is different from the complement of it.\n>\n> The saddest part is that \"untracked files\" is not defined in the glossary\n> either.\n\nWell, I wasn't sure how to canonically refer to \"git that git does not track \nbut also does not have ignore rules for\" and \"files that git ignores\", so I \ntried to mostly just use the same terminology I saw kicking around in other \ndocumentation. I think \"unknown files\" and \"ignored files\" are fairly clear and \nseem like the terms I usually hear people using. If we add them to the \nglossary then we could use them in a standard way in the documentation.\n\n> Normally, the command removes files that are not in the index, but\n> ignored (see linkgit:gitignore[5]) files are kept. With the '-x'\n> option, the command removes the ignored files as well.\n\nAre you already queuing this or any of these other things? If not, I would be \nhappy to work on another patchset that attacks both this and the glossary \nissue.\n"},{"id":"112339","messageId":"49F41580.3080004@gmail.com","threadId":"19061","inReplyTo":"200904251923.46448.wjl@icecavern.net","subject":"Re: [PATCH 2/2] Documentation: git-clean: make description more readable","fromName":"Stephen Boyd","fromEmail":"bebarino@gmail.com","sentAt":"2009-04-26T08:04:16Z","receivedAt":"2009-04-26T08:04:16Z","isPatch":true,"sender":{"key":"bebarino@gmail.com","avatar":"https://avatars.githubusercontent.com/u/38832?v=4"},"body":"Wesley J. Landaker wrote:\n> The main reason I took that out in my patch was because I think the second \n> sentence more says the same thing, except more clearly, and the exact \n> semantics of \"files unknown to git\" versus \"ignored files\", etc seem to not have \n> good definitions anyway, so I left that for the second paragraph that talks \n> about how '-x' changes things.\nIf you want to keep it, maybe change it to be more active. Something like:\n\n Cleans the working tree by removing files that are not under version\ncontrol.\n\n> So I might edit yours to say:\n>\n> Specifying the '-x' option will also remove ignored files. This is useful to \n> remove, for example, generated files that are normally ignored.\n\nThe \"for example\" just comes sticking out again. Could you put it at the\nbeginning of the sentence?\n\n> I left the part about '-x' there mostly because it was already in there, so I \n> figured someone at some point thought it was special enough. I didn't want to \n> undo any good decisions that had already been made. =) That said, both -x and \n> -X are somewhat special because they change the behavior a LOT compared to, \n> say, -d.\n\nSo maybe -X should be described as well?\n"}]}