{"thread":{"id":"17216","subject":"[PATCH] git-checkout(1) mention fate of extraneous files","startedAt":"2009-01-17T00:36:17Z","lastAt":"2009-01-20T19:45:15Z","messageCount":13,"participants":["jidanni@jidanni.org","Markus Heidelberg","Boyd Stephen Smith Jr.","Johannes Schindelin","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"100784","messageId":"87k58u4vlq.fsf@jidanni.org","threadId":"17216","inReplyTo":null,"subject":"[PATCH] git-checkout(1) mention fate of extraneous files","fromName":"","fromEmail":"jidanni@jidanni.org","sentAt":"2009-01-17T00:36:17Z","receivedAt":"2009-01-17T00:36:17Z","isPatch":true,"sender":{"key":"jidanni@jidanni.org","avatar":"https://gravatar.com/avatar/36568d4af4c8d3e71627ef3b8c8d00e39065b12f29676cccd38ced75e68fa2a6?d=mp&s=160"},"body":"Signed-off-by: jidanni \n---\n Documentation/git-checkout.txt | 13 +++++++------\n 1 files changed, 7 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 9cd5151..bce31c7 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -14,12 +14,13 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-When are not given, this command switches branches by\n-updating the index and working tree to reflect the specified\n-branch, , and updating HEAD to be or, if\n-specified, . Using -b will cause to\n-be created; in this case you can use the --track or --no-track\n-options, which will be passed to `git branch`.\n+When are not given, this command switches branches by updating\n+the index and working tree to reflect the specified branch, ,\n+and updating HEAD to be or, if specified, . (No\n+extraneous files present are deleted, use linkgit:git-clean[1] for a\n+pristine checkout.) Using -b will cause to be created; in\n+this case you can use the --track or --no-track options, which will be\n+passed to `git branch`.\n \n As a convenience, --track will default to create a branch whose\n name is constructed from the specified branch name by stripping\n-- \n1.6.0.6\n"},{"id":"100825","messageId":"200901171357.18005.markus.heidelberg@web.de","threadId":"17216","inReplyTo":"87k58u4vlq.fsf@jidanni.org","subject":"Re: [PATCH] git-checkout(1) mention fate of extraneous files","fromName":"Markus Heidelberg","fromEmail":"markus.heidelberg@web.de","sentAt":"2009-01-17T12:57:17Z","receivedAt":"2009-01-17T12:57:17Z","isPatch":true,"sender":{"key":"markus.heidelberg@web.de","avatar":"https://avatars.githubusercontent.com/u/6334512?v=4"},"body":"jidanni@jidanni.org, 17.01.2009:\n> Signed-off-by: jidanni \n> ---\n> Documentation/git-checkout.txt | 13 +++++++------\n> 1 files changed, 7 insertions(+), 6 deletions(-)\n\n> -When are not given, this command switches branches by\n> -updating the index and working tree to reflect the specified\n> -branch, , and updating HEAD to be or, if\n> -specified, . Using -b will cause to\n> -be created; in this case you can use the --track or --no-track\n> -options, which will be passed to `git branch`.\n> +When are not given, this command switches branches by updating\n> +the index and working tree to reflect the specified branch, ,\n> +and updating HEAD to be or, if specified, . (No\n> +extraneous files present are deleted, use linkgit:git-clean[1] for a\n> +pristine checkout.) Using -b will cause to be created; in\n> +this case you can use the --track or --no-track options, which will be\n> +passed to `git branch`.\n\nWhy do you reformat the whole paragraph? Just inserting your sentence\nwould give a much nicer diff for easier review, it's no difference for\nasciidoc. Indeed to find the change, I just copied the old and new text\ninto two Vim windows, reformatted and diffed them.\n\nThen you would get this\n\n Documentation/git-checkout.txt | 2 ++\n 1 files changed, 2 insertions(+), 0 deletions(-)\n\nMarkus\n"},{"id":"100868","messageId":"877i4teq78.fsf@jidanni.org","threadId":"17216","inReplyTo":"200901171357.18005.markus.heidelberg@web.de","subject":"Re: [PATCH] git-checkout(1) mention fate of extraneous files","fromName":"","fromEmail":"jidanni@jidanni.org","sentAt":"2009-01-17T18:35:07Z","receivedAt":"2009-01-17T18:35:07Z","isPatch":true,"sender":{"key":"jidanni@jidanni.org","avatar":"https://gravatar.com/avatar/36568d4af4c8d3e71627ef3b8c8d00e39065b12f29676cccd38ced75e68fa2a6?d=mp&s=160"},"body":"MH> Why do you reformat the whole paragraph?\n\nOK, glad to know that I don't need to!!\n"},{"id":"101172","messageId":"87priivrt3.fsf_-_@jidanni.org","threadId":"17216","inReplyTo":"877i4teq78.fsf@jidanni.org","subject":"[PATCH,v2] git-checkout(1): mention fate of extraneous files","fromName":"","fromEmail":"jidanni@jidanni.org","sentAt":"2009-01-19T22:45:12Z","receivedAt":"2009-01-19T22:45:12Z","isPatch":true,"sender":{"key":"jidanni@jidanni.org","avatar":"https://gravatar.com/avatar/36568d4af4c8d3e71627ef3b8c8d00e39065b12f29676cccd38ced75e68fa2a6?d=mp&s=160"},"body":"Signed-off-by: jidanni \n---\n Documentation/git-checkout.txt | 3 ++-\n 1 files changed, 2 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 9cd5151..58abdc6 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -17,7 +17,8 @@ DESCRIPTION\n When are not given, this command switches branches by\n updating the index and working tree to reflect the specified\n branch, , and updating HEAD to be or, if\n-specified, . Using -b will cause to\n+specified, . (No files are deleted, use linkgit:git-clean[1]\n+for a pristine checkout.) Using -b will cause to\n be created; in this case you can use the --track or --no-track\n options, which will be passed to `git branch`.\n \n-- \n1.6.0.6\n"},{"id":"101178","messageId":"200901191716.59373.bss@iguanasuicide.net","threadId":"17216","inReplyTo":"87priivrt3.fsf_-_@jidanni.org","subject":"Re: [PATCH,v2] git-checkout(1): mention fate of extraneous files","fromName":"Boyd Stephen Smith Jr.","fromEmail":"bss@iguanasuicide.net","sentAt":"2009-01-19T23:16:54Z","receivedAt":"2009-01-19T23:16:54Z","isPatch":true,"sender":{"key":"bss@iguanasuicide.net","avatar":"https://gravatar.com/avatar/84b95eeff194b816c1568b1339e63e4b229825298664a9037b9f1ec713ead1e3?d=mp&s=160"},"body":">-specified, . Using -b will cause to\n>+specified, . (No files are deleted, use linkgit:git-clean[1]\n>+for a pristine checkout.) Using -b will cause to\n\nThe parenthetical remark is not true, here:\n$ git status\n# On branch anagrams\nnothing to commit (working directory clean)\n$ ls\nanagram fsdupfind\n$ git checkout master\nSwitched to branch \"master\"\n$ ls\nfsdupfind\n\nI think you mean \"No untracked content is removed,...\".\n-- \nBoyd Stephen Smith Jr. ,= ,-_-. =. \nbss@iguanasuicide.net ((_/)o o(\\_))\nICQ: 514984 YM/AIM: DaTwinkDaddy `-'(. .)`-' \nhttp://iguanasuicide.net/ \\_/ \n"},{"id":"101179","messageId":"87hc3uvpnh.fsf_-_@jidanni.org","threadId":"17216","inReplyTo":"200901191716.59373.bss@iguanasuicide.net","subject":"Re: [PATCH,v3] git-checkout(1): mention fate of extraneous files","fromName":"","fromEmail":"jidanni@jidanni.org","sentAt":"2009-01-19T23:31:46Z","receivedAt":"2009-01-19T23:31:46Z","isPatch":true,"sender":{"key":"jidanni@jidanni.org","avatar":"https://gravatar.com/avatar/36568d4af4c8d3e71627ef3b8c8d00e39065b12f29676cccd38ced75e68fa2a6?d=mp&s=160"},"body":"Signed-off-by: jidanni \n---\nThanks Boyd.\n Documentation/git-checkout.txt | 3 ++-\n 1 files changed, 2 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 9cd5151..56e1ec9 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -17,7 +17,8 @@ DESCRIPTION\n When are not given, this command switches branches by\n updating the index and working tree to reflect the specified\n branch, , and updating HEAD to be or, if\n-specified, . Using -b will cause to\n+specified, . (To also delete untracked content\n+use linkgit:git-clean[1].) Using -b will cause to\n be created; in this case you can use the --track or --no-track\n options, which will be passed to `git branch`.\n \n-- \n1.6.0.6\n"},{"id":"101185","messageId":"alpine.DEB.1.00.0901200040550.3586@pacific.mpi-cbg.de","threadId":"17216","inReplyTo":"200901191716.59373.bss@iguanasuicide.net","subject":"Re: [PATCH,v2] git-checkout(1): mention fate of extraneous files","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2009-01-19T23:42:51Z","receivedAt":"2009-01-19T23:42:51Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Mon, 19 Jan 2009, Boyd Stephen Smith Jr. wrote:\n\n> I think you mean \"No untracked content is removed,...\".\n\nAs \"checkout\" is about switching branches, and as Git is very keen on \navoiding loss of uncommitted changes, I think this comment is utterly \nunnecessary. Indeed, it is rather annoying: when I read a document the \nother day, that I _had_ to read, and which was full of obvious statements, \nsure enough, I missed the single important half-sentence.\n\nIOW do not clutter the man page with distracting stuff, please, please, \nplease.\n\nCiao,\nDscho\n"},{"id":"101191","messageId":"878wp6voar.fsf_-_@jidanni.org","threadId":"17216","inReplyTo":"alpine.DEB.1.00.0901200040550.3586@pacific.mpi-cbg.de","subject":"[PATCH,v4] git-checkout(1): mention fate of extraneous files","fromName":"","fromEmail":"jidanni@jidanni.org","sentAt":"2009-01-20T00:01:00Z","receivedAt":"2009-01-20T00:01:00Z","isPatch":true,"sender":{"key":"jidanni@jidanni.org","avatar":"https://gravatar.com/avatar/36568d4af4c8d3e71627ef3b8c8d00e39065b12f29676cccd38ced75e68fa2a6?d=mp&s=160"},"body":"Signed-off-by: jidanni \n---\nOK thanks Johannes.\nI'm still worried that there is no exact statement on the fate of the\nvarious different classes of files, but OK, moving this to only a SEE ALSO.\n\n Documentation/git-checkout.txt | 3 +++\n 1 files changed, 3 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 9cd5151..6ffb783 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -246,6 +246,9 @@ $ edit frotz\n $ git add frotz\n ------------\n \n+SEE ALSO\n+--------\n+linkgit:git-clean[1]\n \n Author\n ------\n-- \n1.6.0.6\n"},{"id":"101192","messageId":"alpine.DEB.1.00.0901200110410.3586@pacific.mpi-cbg.de","threadId":"17216","inReplyTo":"878wp6voar.fsf_-_@jidanni.org","subject":"Re: [PATCH,v4] git-checkout(1): mention fate of extraneous files","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2009-01-20T00:11:19Z","receivedAt":"2009-01-20T00:11:19Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 20 Jan 2009, jidanni@jidanni.org wrote:\n\n> Signed-off-by: jidanni \n> ---\n> OK thanks Johannes.\n> I'm still worried that there is no exact statement on the fate of the\n> various different classes of files, but OK, moving this to only a SEE ALSO.\n\nYou completely misread me. So I will say it out directly: I think no \npatch is needed.\n\nHth,\nDscho\n"},{"id":"101199","messageId":"200901191854.58029.bss@iguanasuicide.net","threadId":"17216","inReplyTo":"alpine.DEB.1.00.0901200110410.3586@pacific.mpi-cbg.de","subject":"Re: [PATCH,v4] git-checkout(1): mention fate of extraneous files","fromName":"Boyd Stephen Smith Jr.","fromEmail":"bss@iguanasuicide.net","sentAt":"2009-01-20T00:54:53Z","receivedAt":"2009-01-20T00:54:53Z","isPatch":true,"sender":{"key":"bss@iguanasuicide.net","avatar":"https://gravatar.com/avatar/84b95eeff194b816c1568b1339e63e4b229825298664a9037b9f1ec713ead1e3?d=mp&s=160"},"body":"On Monday 19 January 2009, Johannes Schindelin \nwrote about 'Re: [PATCH,v4] git-checkout(1): mention fate of extraneous \nfiles':\n>On Tue, 20 Jan 2009, jidanni@jidanni.org wrote:\n>> Signed-off-by: jidanni \n>> ---\n>> OK thanks Johannes.\n>> I'm still worried that there is no exact statement on the fate of the\n>> various different classes of files, but OK, moving this to only a SEE\n>> ALSO.\n>\n>You completely misread me. So I will say it out directly: I think no\n>patch is needed.\n\nI think some users will expect to get a clean checkout when simply \ndoing \"git checkout \". It would be nice for the documentation \nmention that is not the case, and reference the tool that helps get the \ntree into that state. Just my opinion, though.\n\nIt seems natural to me for this to be mentioned in the 'git checkout' \ndocumentation. Perhaps there's a better place?\n-- \nBoyd Stephen Smith Jr. ,= ,-_-. =. \nbss@iguanasuicide.net ((_/)o o(\\_))\nICQ: 514984 YM/AIM: DaTwinkDaddy `-'(. .)`-' \nhttp://iguanasuicide.net/ \\_/ \n"},{"id":"101206","messageId":"7vy6x6odiw.fsf@gitster.siamese.dyndns.org","threadId":"17216","inReplyTo":"200901191854.58029.bss@iguanasuicide.net","subject":"Re: [PATCH,v4] git-checkout(1): mention fate of extraneous files","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-01-20T03:35:35Z","receivedAt":"2009-01-20T03:35:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Boyd Stephen Smith Jr.\" writes:\n\n> I think some users will expect to get a clean checkout when simply \n> doing \"git checkout \". It would be nice for the documentation \n> mention that is not the case, and reference the tool that helps get the \n> tree into that state. Just my opinion, though.\n>\n> It seems natural to me for this to be mentioned in the 'git checkout' \n> documentation. Perhaps there's a better place?\n\nI think this is probably on the other side of the borderline.\n\nFirst I was about to agree with you, but the more I think about it, I do\nnot think it is natural at all to expect \"checkout\" to behave as if you\ndid \"rm -fr\" everything and then \"tar xf\" over the void. What other SCM\nimplements branch switching that way, and what workflow would such a\nbehaviour help?\n\nWe need to draw a line somewhere to avoid cluttering the documentation too\nmuch, and I do not think this is something even a person with CVS\nbraindamage would get confused about, which is where I think is a\nreasonable place to draw that line.\n\nHaving said all that, I share a desire to help people who do not have any\nprior experience nor knowledge to form a reasonable expectation out of the\nsystem.\n\nFor example, a person who does not have a clue on what version control\nsystem is about may think that the contents recorded in a branch is like a\ntarball, a version control system is not about helping you make changes\nbut its _sole_ purpose is to extract one such tarball after another on\ndemand to let you travel in time. Running an equivalent of \"git clean\"\nautomatically upon checkout may feel as if it is a valid a convenience\nfeature to deal with files that was in one tarball but not in the new one.\nIt is not completely implausible that such a person may be confused upon\nlearning that \"checkout\" leaves untracked paths intact. If you start from\na flawed understanding of what problem the system helps you to solve, you\nend up with flawed expectations.\n\nIt would not help him if you only taught that checkout leaves untracked\npaths intact. You have instead to teach him why you may have, and you\nwould want to keep, untracked paths in the work tree (i.e. they are build\nproducts and notes you take while developing, iow, files that are\nessential during your work, but does not belong to the end product, and\nyou would want to keep them around even while switching branches because\nyou may be growing both branches at the same time), and that it is one of\nthe prime design concern to _any_ command in git not to lose them without\nbeing told. When a user lacks such a basic understanding of the system,\nwhat it was designed for and what it was designed to do, the user's\nexpectation will never match what many parts of the system do. The user\nwill stay confused.\n\nI've always thought such basic concepts should be covered by the tutorial\nand the users are expected to read them before reading about individual\ncommands, but that approach may not work in practice. Perhaps a separate\nsection \"Basic Understanding\" at the end of each manual page of the\ncommand to cover minimum necessary basics to understand the command might\nhelp. The section may quote from the tutorial, or written afresh.\n\nBut I think that such a basic description should be in a separate section\nso that it does not clutter the main text for people who understand the\nbasics. Also I fear there will be quite a lot of repetition (e.g. you may\nhave to repeat that untracked files are unintersting and that is why the\ncommand does not say anything about them in manual pages for \"diff\",\n\"grep\", \"checkout\", etc.). Once it is understood, the user does not need\nit to be repeated, but if we want to let the user freely start reading\nfrom anywhere, the repetition cannot be avoided.\n"},{"id":"101239","messageId":"alpine.DEB.1.00.0901201106030.3586@pacific.mpi-cbg.de","threadId":"17216","inReplyTo":"7vy6x6odiw.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH,v4] git-checkout(1): mention fate of extraneous files","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2009-01-20T10:07:45Z","receivedAt":"2009-01-20T10:07:45Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Mon, 19 Jan 2009, Junio C Hamano wrote:\n\n> [...] the more I think about it, I do not think it is natural at all to \n> expect \"checkout\" to behave as if you did \"rm -fr\" everything and then \n> \"tar xf\" over the void. What other SCM implements branch switching that \n> way, and what workflow would such a behaviour help?\n> \n> We need to draw a line somewhere to avoid cluttering the documentation \n> too much, and I do not think this is something even a person with CVS \n> braindamage would get confused about, which is where I think is a \n> reasonable place to draw that line.\n\nIIRC both CVS and Subversion allow you to say \"$SCM co\" with an existing \nworking directory, which is then updated (and untracked files are left \nalone, as \"$SCM up\" always did and should do).\n\nSo no, not even people with CVS/SVN braindamage would get confused thusly.\n\nCiao,\nDscho\n"},{"id":"101288","messageId":"87zlhl69tg.fsf@jidanni.org","threadId":"17216","inReplyTo":"7vy6x6odiw.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH,v4] git-checkout(1): mention fate of extraneous files","fromName":"","fromEmail":"jidanni@jidanni.org","sentAt":"2009-01-20T19:45:15Z","receivedAt":"2009-01-20T19:45:15Z","isPatch":true,"sender":{"key":"jidanni@jidanni.org","avatar":"https://gravatar.com/avatar/36568d4af4c8d3e71627ef3b8c8d00e39065b12f29676cccd38ced75e68fa2a6?d=mp&s=160"},"body":"Thank you all for your responses. I hope one day the git-checkout man\npage will document what git-checkout does.\n\nI believe that when classified in terms of their differing fates,\nthere are two or three different types of files that might be sitting\naround in one's working tree at the time a \"git checkout comes down on\ntheir heads\".\n\nPerhaps a brief table of their different fates might nice to have on\nthe bottom of the man page.\n\nOK, never mind.\n"}]}