{"thread":{"id":"25702","subject":"Re: [PATCH] gitignore(5): explain how to stop tracking a file","startedAt":"2010-11-10T18:55:55Z","lastAt":"2010-11-11T19:05:08Z","messageCount":5,"participants":["Jonathan Nieder","Sitaram Chamarty","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"155609","messageId":"20101110185555.GA12365@burratino","threadId":"25702","inReplyTo":"1289387440-8509-1-git-send-email-sitaram@atc.tcs.com","subject":"Re: [PATCH] gitignore(5): explain how to stop tracking a file","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-11-10T18:55:55Z","receivedAt":"2010-11-10T18:55:55Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Sitaram Chamarty wrote:\n\n> --- a/Documentation/gitignore.txt\n> +++ b/Documentation/gitignore.txt\n> @@ -18,7 +18,8 @@ Note that all the `gitignore` files really concern only files\n> that are not already tracked by git;\n> in order to ignore uncommitted changes in already tracked files,\n> please refer to the 'git update-index --assume-unchanged'\n> -documentation.\n> +documentation. To stop tracking a file that is currently tracked,\n> +use 'git rm --cached'.\n\nAck. But I fear this makes the gitignore page feel even more top-heavy\nthan it already is.\n\nThe current structure is:\n\n\tSYNOPSIS\n\t[list of excludes files]\n\n\tDESCRIPTION\n\tOne-sentence description. Long comment about some totally\n\tdifferent command.\n\n\tDescription of structure. Long comment about precedence rules:\n\n\t. some rules\n\t...\n\n\tParagraph about which excludes file works for which use case.\n\n\tParagraph about which commands pay attention to excludes files.\n\n\tPatterns have the following format:\n\n\t. some rules\n\t...\n\n\tAn example:\n\n\t transcript\n\n\tAnother example:\n\n\t transcript\n\n\tQuick analysis.\n\n\tDOCUMENTATION\n\tVarious people's names.\n\n\tGIT\n\tPart of the git(1) suite.\n\nIt's a wonder people can find anything there. :) So how about this?\n\nPatch 1 splits the description into three sections. Yes, having the\nPATTERN FORMAT section is not part of the conventional list in\nman-pages(7), but I think it's easier to find the interesting part\nthis way.\n\nPatch 2 puts the comments about related commands in a separate NOTES\nsection.\n\nThis way, one could expand on the \"stop tracking file\" procedure\nwithout interrupting the flow of the basic description of what\nexcludes files do, by adding to the NOTES or EXAMPLES section.\n\nThoughts?\n\nJonathan Nieder (2):\n Documentation: split gitignore page into sections\n Documentation: point to related commands from gitignore\n\n Documentation/gitignore.txt | 30 +++++++++++++++++++++++-------\n 1 files changed, 23 insertions(+), 7 deletions(-)\n\n-- \n1.7.2.3.557.gab647.dirty\n"},{"id":"155611","messageId":"20101110185739.GB12365@burratino","threadId":"25702","inReplyTo":"20101110185555.GA12365@burratino","subject":"[PATCH 1/2] Documentation: split gitignore page into sections","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-11-10T18:57:39Z","receivedAt":"2010-11-10T18:57:39Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"A learner-by-example might want to look at the examples section first.\nHelp her out by supplying some section headings: PATTERN FORMAT for\nthe format of lines in an excludes file and EXAMPLES for the two\nexamples.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/gitignore.txt | 6 ++++--\n 1 files changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nindex 7dc2e8b..254bc1a 100644\n--- a/Documentation/gitignore.txt\n+++ b/Documentation/gitignore.txt\n@@ -62,7 +62,8 @@ files specified by command-line options. Higher-level git\n tools, such as 'git status' and 'git add',\n use patterns from the sources specified above.\n \n-Patterns have the following format:\n+PATTERN FORMAT\n+--------------\n \n - A blank line matches no files, so it can serve as a separator\n for readability.\n@@ -98,7 +99,8 @@ Patterns have the following format:\n For example, \"/{asterisk}.c\" matches \"cat-file.c\" but not\n \"mozilla-sha1/sha1.c\".\n \n-An example:\n+EXAMPLES\n+--------\n \n --------------------------------------------------------------\n $ git status\n-- \n1.7.2.3.557.gab647.dirty\n"},{"id":"155612","messageId":"20101110190048.GC12365@burratino","threadId":"25702","inReplyTo":"20101110185555.GA12365@burratino","subject":"[PATCH 2/2] Documentation: point to related commands from gitignore","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-11-10T19:00:48Z","receivedAt":"2010-11-10T19:00:48Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"A frequently asked question on #git is how to stop tracking a file\nthat is mistakenly tracked by git. A frequently attempted strategy is\nto add such files to .gitignore.\n\nThus one might imagine that the gitignore documentation could be a\ngood entry point for 'git rm' documentation. Add some\ncross-references in this vein.\n\nWhile at it, move a reference to update-index --assume-unchanged from\nthe DESCRIPTION to lower down on the page. This way, the methodical\nreader can benefit from first learning what excludes files do, then\nhow they relate to other git facilities.\n\nBased-on-patch-by: Sitaram Chamarty \nSigned-off-by: Jonathan Nieder \n---\n This NOTES section is a bit of a placeholder. I think it is an\n improvement already, but if someone wants to flesh it out I wouldn't\n complain.\n\n Hope that helps.\n\n Documentation/gitignore.txt | 24 +++++++++++++++++++-----\n 1 files changed, 19 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nindex 254bc1a..8416f34 100644\n--- a/Documentation/gitignore.txt\n+++ b/Documentation/gitignore.txt\n@@ -14,11 +14,8 @@ DESCRIPTION\n \n A `gitignore` file specifies intentionally untracked files that\n git should ignore.\n-Note that all the `gitignore` files really concern only files\n-that are not already tracked by git;\n-in order to ignore uncommitted changes in already tracked files,\n-please refer to the 'git update-index --assume-unchanged'\n-documentation.\n+Files already tracked by git are not affected; see the NOTES\n+below for details.\n \n Each line in a `gitignore` file specifies a pattern.\n When deciding whether to ignore a path, git normally checks\n@@ -99,6 +96,18 @@ PATTERN FORMAT\n For example, \"/{asterisk}.c\" matches \"cat-file.c\" but not\n \"mozilla-sha1/sha1.c\".\n \n+NOTES\n+-----\n+\n+The purpose of gitignore files is to ensure that certain files\n+not tracked by git remain untracked.\n+\n+To ignore uncommitted changes in a file that is already tracked,\n+use 'git update-index {litdd}assume-unchanged'.\n+\n+To stop tracking a file that is currently tracked, use\n+'git rm --cached'.\n+\n EXAMPLES\n --------\n \n@@ -142,6 +151,11 @@ Another example:\n The second .gitignore prevents git from ignoring\n `arch/foo/kernel/vmlinux.lds.S`.\n \n+SEE ALSO\n+--------\n+linkgit:git-rm[1], linkgit:git-update-index[1],\n+linkgit:gitrepository-layout[5]\n+\n Documentation\n -------------\n Documentation by David Greaves, Junio C Hamano, Josh Triplett,\n-- \n1.7.2.3.557.gab647.dirty\n"},{"id":"155638","messageId":"AANLkTikpSoMGKDzUWXK-XGNZ8cp9Ltz+n8hNd9Z6FQ2E@mail.gmail.com","threadId":"25702","inReplyTo":"20101110185555.GA12365@burratino","subject":"Re: [PATCH] gitignore(5): explain how to stop tracking a file","fromName":"Sitaram Chamarty","fromEmail":"sitaramc@gmail.com","sentAt":"2010-11-11T01:10:14Z","receivedAt":"2010-11-11T01:10:14Z","isPatch":true,"sender":{"key":"sitaramc@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43316?v=4"},"body":"On Thu, Nov 11, 2010 at 12:25 AM, Jonathan Nieder wrote:\n> Sitaram Chamarty wrote:\n>\n>> --- a/Documentation/gitignore.txt\n>> +++ b/Documentation/gitignore.txt\n>> @@ -18,7 +18,8 @@ Note that all the `gitignore` files really concern only files\n>>  that are not already tracked by git;\n>>  in order to ignore uncommitted changes in already tracked files,\n>>  please refer to the 'git update-index --assume-unchanged'\n>> -documentation.\n>> +documentation.  To stop tracking a file that is currently tracked,\n>> +use 'git rm --cached'.\n>\n> Ack.  But I fear this makes the gitignore page feel even more top-heavy\n> than it already is.\n\nOh... I hadn't thought of that. I was looking at \"what's the minimum\nchange needed to at least mention 'git rm --cached' somewhere\".\nYou're right though, and I think your approach is good.\n\n> The current structure is:\n\n[snip]\n\n> It's a wonder people can find anything there. :)  So how about this?\n>\n> Patch 1 splits the description into three sections.  Yes, having the\n> PATTERN FORMAT section is not part of the conventional list in\n> man-pages(7), but I think it's easier to find the interesting part\n> this way.\n>\n> Patch 2 puts the comments about related commands in a separate NOTES\n> section.\n>\n> This way, one could expand on the \"stop tracking file\" procedure\n> without interrupting the flow of the basic description of what\n> excludes files do, by adding to the NOTES or EXAMPLES section.\n\n++ from me on this approach.\n\nregards\n\nsitaram\n"},{"id":"155731","messageId":"7vwrojfzq3.fsf@alter.siamese.dyndns.org","threadId":"25702","inReplyTo":"20101110190048.GC12365@burratino","subject":"Re: [PATCH 2/2] Documentation: point to related commands from gitignore","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-11-11T19:05:08Z","receivedAt":"2010-11-11T19:05:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> While at it, move a reference to update-index --assume-unchanged from\n> the DESCRIPTION to lower down on the page. This way, the methodical\n> reader can benefit from first learning what excludes files do, then\n> how they relate to other git facilities.\n\nLooks sensible.\n\n> +To ignore uncommitted changes in a file that is already tracked,\n> +use 'git update-index {litdd}assume-unchanged'.\n> +\n> +To stop tracking a file that is currently tracked, use\n> +'git rm --cached'.\n\nI am not very happy with the wording \"to do X, use Y\" above, though. For\nexample, \"rm --cached\" is a good starting point, but that needs to be\nfollowed by a commit some time in the future to take permanent effect.\nThe realization that \"rm --cached\" is a good starting point would come\nonly with an understanding of what \"rm --cached\" does (i.e. it removes the\npath from the index, preparing for its removal from the future history).\n\n\"to do X, see Y\" might be a good compromise, because what I am suggesting\nby the above is that ideally to say \"to do X means doing Z so using Y is a\ngood way to achieve it\", but \"... means doing Z\" part is explained in the\nmanual page of Y.\n\nIn any case, will queue. Thanks.\n"}]}