{"thread":{"id":"39565","subject":"[PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","startedAt":"2015-06-08T20:21:28Z","lastAt":"2015-06-12T20:41:26Z","messageCount":12,"participants":["Torsten Bögershausen","Junio C Hamano","Ed Avis","Scott Schmit"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"263301","messageId":"5575F948.4060400@web.de","threadId":"39565","inReplyTo":null,"subject":"[PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2015-06-08T20:21:28Z","receivedAt":"2015-06-08T20:21:28Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"git checkout <pathspec> can be used to revert changes in the working tree.\n\nSigned-off-by: Torsten Bögershausen <tboegi@web.de>\n---\nMy first attempt to improve the documentation\n\n Documentation/git-checkout.txt | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d263a56..8cd018a 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -3,7 +3,7 @@ git-checkout(1)\n \n NAME\n ----\n-git-checkout - Checkout a branch or paths to the working tree\n+git-checkout - Switch branches or reverts changes in the working tree\n \n SYNOPSIS\n --------\n@@ -83,7 +83,8 @@ Omitting <branch> detaches HEAD at the tip of the current branch.\n \tWhen <paths> or `--patch` are given, 'git checkout' does *not*\n \tswitch branches.  It updates the named paths in the working tree\n \tfrom the index file or from a named <tree-ish> (most often a\n-\tcommit).  In this case, the `-b` and `--track` options are\n+\tcommit).  Changes in files are discarded and deleted files are\n+\trestored. In this case, the `-b` and `--track` options are\n \tmeaningless and giving either of them results in an error.  The\n \t<tree-ish> argument can be used to specify a specific tree-ish\n \t(i.e.  commit, tag or tree) to update the index for the given\n-- \n2.2.0.rc1.790.ge19fcd2\n"},{"id":"263472","messageId":"xmqqioavob7n.fsf@gitster.dls.corp.google.com","threadId":"39565","inReplyTo":"5575F948.4060400@web.de","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-10T15:05:32Z","receivedAt":"2015-06-10T15:05:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Torsten Bögershausen <tboegi@web.de> writes:\n\n> git checkout <pathspec> can be used to revert changes in the working tree.\n\nI somehow thought that concensus in the recent thread was that\n\"restore\", not \"revert\", is the more appropriate wording?\n\nAnd I think that is indeed sensible because \"revert\" (or \"reset\")\nalready means something else in Git (and in other systems), while\n\"restore\" does not have a confusing connotation.  It can only mean\n\"overwrite with a pristine copy\", which is what the command is\nabout.\n\n> -git-checkout - Checkout a branch or paths to the working tree\n> +git-checkout - Switch branches or reverts changes in the working tree\n\nTwo verbs in different moods; either \"switch branches or restore\nchanges\" or \"switches branches or restores changes\" would fix that,\nand judging from \"git help\" output, I think we want to go with the\nformer, i.e. \"switch branches or restore changes\".\n\n>  \n>  SYNOPSIS\n>  --------\n> @@ -83,7 +83,8 @@ Omitting <branch> detaches HEAD at the tip of the current branch.\n>  \tWhen <paths> or `--patch` are given, 'git checkout' does *not*\n>  \tswitch branches.  It updates the named paths in the working tree\n>  \tfrom the index file or from a named <tree-ish> (most often a\n> -\tcommit).  In this case, the `-b` and `--track` options are\n> +\tcommit).  Changes in files are discarded and deleted files are\n> +\trestored.\n\nI see we are suffering from the common disease of giving one\nexplanation and then realizing that first explanation can be\nmisread, clarifying it by more explanation, after reading the\nupdated text three times.  Let's instead try to clarify the first\nexplanation to make it harder to misread.\n\nIn this case, \"updates X from Y\" is what causes misunderstanding, as\n\"updates\" does not necessarily mean \"restores with the original\".\n\nHow about this?\n\n  \t'git checkout' with <paths> or `--patch` is used to restore\n        modified or deleted paths to their original contents from\n        the index file or from a named <tree-ish> (most often a\n        commit) without switching branches.\n"},{"id":"263475","messageId":"loom.20150610T170737-586@post.gmane.org","threadId":"39565","inReplyTo":"xmqqioavob7n.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Ed Avis","fromEmail":"eda@waniasset.com","sentAt":"2015-06-10T15:11:57Z","receivedAt":"2015-06-10T15:11:57Z","isPatch":true,"sender":{"key":"eda@waniasset.com","avatar":null},"body":"'restore' may be more consistent with git's internal terminology.\nBut from an outsider's perspective, 'revert' rather than 'restore' is in my\nview much clearer and more consistent with other version control systems:\nfor example 'svn revert' is what you use to revert files in the working copy.\n\nThe original issue was that I naively expected that 'git checkout PATH' would\nindeed just 'restore' some files, that is, create them when they are missing.\nIts action is rather more drastic than that.\n\nIf 'revert' is not a suitable verb because of the existing git-revert, then\nI suggest that 'overwrite' or 'replace' might better convey the idea of what\nthe command does.\n\n-- \nEd Avis <eda@waniasset.com>\n"},{"id":"263504","messageId":"xmqq7frbmsce.fsf@gitster.dls.corp.google.com","threadId":"39565","inReplyTo":"loom.20150610T170737-586@post.gmane.org","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-10T16:38:25Z","receivedAt":"2015-06-10T16:38:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ed Avis <eda@waniasset.com> writes:\n\n> 'restore' may be more consistent with git's internal terminology.\n> But from an outsider's perspective, 'revert' rather than 'restore' is in my\n> view much clearer and more consistent with other version control systems:\n> for example 'svn revert' is what you use to revert files in the working copy.\n\nThe reason why I said \"restore\" is because it does *not* have any\n\"internal terminology\" connotation.\n\nOn the other hand, \"revert\" that means \"create a counter-effect\ncommit\" is not \"internal\".  \"git revert\" is a part of end-user\nfacing command.\n\nThe only people that will be helped by using \"revert\" there will be\nthe ones who haven't learned \"git revert\".  And it will make it\nharder for them to learn \"git revert\".  It is unfortunate that other\nsystems use the word \"revert\" in a different way, and that is why we\nshould avoid using that word when describing \"checkout\".\n\n> The original issue was that I naively expected that 'git checkout PATH' would\n> indeed just 'restore' some files, that is, create them when they are missing.\n> ...\n> If 'revert' is not a suitable verb because of the existing git-revert, then\n> I suggest that 'overwrite' or 'replace' might better convey the idea of what\n> the command does.\n\nGit is about \"contents\", not \"files\".  You modify a file, and\nrestore its contents to its pristine state.  It is not \"restore the\nfile\", as Git is not about \"files\".\n\nI think \"overwrite is better\" is primarily coming from not thinking\nin terms of \"Git tracks contents, not files\".\n"},{"id":"263515","messageId":"55788190.80106@web.de","threadId":"39565","inReplyTo":"xmqqioavob7n.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2015-06-10T18:27:28Z","receivedAt":"2015-06-10T18:27:28Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On 2015-06-10 17.05, Junio C Hamano wrote:\n> Torsten Bögershausen <tboegi@web.de> writes:\n> \n(Need to drop Eric from CC-list( \n>> git checkout <pathspec> can be used to revert changes in the working tree.\n> \n> I somehow thought that concensus in the recent thread was that\n> \"restore\", not \"revert\", is the more appropriate wording?\n> \n> And I think that is indeed sensible because \"revert\" (or \"reset\")\n> already means something else in Git (and in other systems), while\n> \"restore\" does not have a confusing connotation.  It can only mean\n> \"overwrite with a pristine copy\", which is what the command is\n> about.\n> \n>> -git-checkout - Checkout a branch or paths to the working tree\n>> +git-checkout - Switch branches or reverts changes in the working tree\n> \n> Two verbs in different moods; either \"switch branches or restore\n> changes\" or \"switches branches or restores changes\" would fix that,\n> and judging from \"git help\" output, I think we want to go with the\n> former, i.e. \"switch branches or restore changes\".\nOK for me\n> \n>>  \n>>  SYNOPSIS\n>>  --------\n>> @@ -83,7 +83,8 @@ Omitting <branch> detaches HEAD at the tip of the current branch.\n>>  \tWhen <paths> or `--patch` are given, 'git checkout' does *not*\n>>  \tswitch branches.  It updates the named paths in the working tree\n>>  \tfrom the index file or from a named <tree-ish> (most often a\n>> -\tcommit).  In this case, the `-b` and `--track` options are\n>> +\tcommit).  Changes in files are discarded and deleted files are\n>> +\trestored.\n> \n[]\n> How about this?\n> \n>   \t'git checkout' with <paths> or `--patch` is used to restore\n>         modified or deleted paths to their original contents from\n>         the index file or from a named <tree-ish> (most often a\n>         commit) without switching branches.\nOK for me.\n"},{"id":"263578","messageId":"loom.20150611T121345-144@post.gmane.org","threadId":"39565","inReplyTo":"xmqq7frbmsce.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] git-checkout.txt: Document","fromName":"Ed Avis","fromEmail":"eda@waniasset.com","sentAt":"2015-06-11T10:24:50Z","receivedAt":"2015-06-11T10:24:50Z","isPatch":true,"sender":{"key":"eda@waniasset.com","avatar":null},"body":">\nI agree, the word 'revert' is already taken for the operation of creating\na new commit which undoes some earlier commit.  So 'revert' cannot be used\nfor the operation of overwriting a working tree file with its contents from\nthe repository.\n\nBut just because 'revert' is not a good choice, doesn't mean that 'restore'\nis either.\n\n>Git is about \"contents\", not \"files\".  You modify a file, and\n>restore its contents to its pristine state.  It is not \"restore the\n>file\", as Git is not about \"files\".\n\n'Restore to its pristine state' does convey the flavour of what happens.\nPlain 'restore' by itself doesn't, really.\n\n>I think \"overwrite is better\" is primarily coming from not thinking\n>in terms of \"Git tracks contents, not files\".\n\nBut 'git checkout .' is primarily an operation on the local filesystem.  As\nfar as I know, it does not change the git repository, nor the index, stashes\nand so on.  Its only effect is to create and overwrite local files, much the\nsame as 'tar x'.  So the appropriate language to describe it should be based\nmore in common usage rather than git-specific terms - if indeed 'restore' is\nthe git-specific term for replacing a file in the working tree.  (In which\ncase why not call the command 'git restore'?)\n\nIf indeed it did work by tracking contents, there wouldn't be a problem.\nThe old contents of the file could be saved as a stash and then the file's\ncontents replaced with the version from the current commit.\n\n% git checkout .\nThe following files have been restored to their pristine state:\n   foo\nThe previous contents have been saved and can be got back with:\n   git stash apply checkout_backup_abcde\n\nThen there would be no need for agonizing over the documentation to make it\nclear that 'git checkout PATH' can be a dangerous operation, because it\nwould no longer be dangerous.\n\n-- \nEd Avis <eda@waniasset.com>\n"},{"id":"263588","messageId":"xmqqegligv45.fsf@gitster.dls.corp.google.com","threadId":"39565","inReplyTo":"55788190.80106@web.de","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-11T14:47:22Z","receivedAt":"2015-06-11T14:47:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Torsten Bögershausen <tboegi@web.de> writes:\n\n> On 2015-06-10 17.05, Junio C Hamano wrote:\n>\n>>> -git-checkout - Checkout a branch or paths to the working tree\n>>> +git-checkout - Switch branches or reverts changes in the working tree\n>> \n>> Two verbs in different moods; either \"switch branches or restore\n>> changes\" or \"switches branches or restores changes\" would fix that,\n>> and judging from \"git help\" output, I think we want to go with the\n>> former, i.e. \"switch branches or restore changes\".\n\nGaah, no we do not \"restore\" changes.  We \"restore\" working tree files\nto their pristine state.\n\nAnd \"... or restore working tree files to their pristine state\" is\nway too long.\n\nUnfortunately \"overwrite changes in the working tree\" is even worse.\nAs it does not say overwrite _with what_, we invite the original\nconfusion that triggered this whole thread if the reader thought an\nequally useful but different \"overwrites with result of merging your\nlocal changes to the pristine\" (similar to what \"checkout -m\" does)\nwould happen.\n\nAt least, \"restore working tree files\" without saying \"restoring\nthem to what state?\" is much less likely to cause such a confusion.\n\nSo...\n\n    git-checkout - Switch branches or restore working tree files\n\nperhaps?\n"},{"id":"263589","messageId":"loom.20150611T164935-263@post.gmane.org","threadId":"39565","inReplyTo":"xmqqegligv45.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Ed Avis","fromEmail":"eda@waniasset.com","sentAt":"2015-06-11T14:52:21Z","receivedAt":"2015-06-11T14:52:21Z","isPatch":true,"sender":{"key":"eda@waniasset.com","avatar":null},"body":"I guess 'replace' would be a better word than 'restore' for the current\nbehaviour.\n\n-- \nEd Avis <eda@waniasset.com>\n"},{"id":"263626","messageId":"xmqqoakmf6k7.fsf@gitster.dls.corp.google.com","threadId":"39565","inReplyTo":"loom.20150611T164935-263@post.gmane.org","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-11T18:23:04Z","receivedAt":"2015-06-11T18:23:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ed Avis <eda@waniasset.com> writes:\n\n> I guess 'replace' would be a better word than 'restore' for the current\n> behaviour.\n\nHmm, but wouldn't replace have the same issue as overwrite, namely,\n'replace with what?'.\n"},{"id":"263646","messageId":"20150612044906.GA17424@odin.ulthar.us","threadId":"39565","inReplyTo":"xmqqioavob7n.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Scott Schmit","fromEmail":"i.grok@comcast.net","sentAt":"2015-06-12T04:49:06Z","receivedAt":"2015-06-12T04:49:06Z","isPatch":true,"sender":{"key":"i.grok@comcast.net","avatar":null},"body":"On Wed, Jun 10, 2015 at 08:05:32AM -0700, Junio C Hamano wrote:\n> Torsten Bögershausen <tboegi@web.de> writes:\n> \n> > git checkout <pathspec> can be used to revert changes in the working tree.\n> \n> I somehow thought that concensus in the recent thread was that\n> \"restore\", not \"revert\", is the more appropriate wording?\n> \n> And I think that is indeed sensible because \"revert\" (or \"reset\")\n> already means something else in Git (and in other systems), while\n> \"restore\" does not have a confusing connotation.  It can only mean\n> \"overwrite with a pristine copy\", which is what the command is\n> about.\n> \n> > -git-checkout - Checkout a branch or paths to the working tree\n> > +git-checkout - Switch branches or reverts changes in the working tree\n> \n> Two verbs in different moods; either \"switch branches or restore\n> changes\" or \"switches branches or restores changes\" would fix that,\n> and judging from \"git help\" output, I think we want to go with the\n> former, i.e. \"switch branches or restore changes\".\n> \n> >  \n> >  SYNOPSIS\n> >  --------\n> > @@ -83,7 +83,8 @@ Omitting <branch> detaches HEAD at the tip of the current branch.\n> >  \tWhen <paths> or `--patch` are given, 'git checkout' does *not*\n> >  \tswitch branches.  It updates the named paths in the working tree\n> >  \tfrom the index file or from a named <tree-ish> (most often a\n> > -\tcommit).  In this case, the `-b` and `--track` options are\n> > +\tcommit).  Changes in files are discarded and deleted files are\n> > +\trestored.\n> \n> I see we are suffering from the common disease of giving one\n> explanation and then realizing that first explanation can be\n> misread, clarifying it by more explanation, after reading the\n> updated text three times.  Let's instead try to clarify the first\n> explanation to make it harder to misread.\n> \n> In this case, \"updates X from Y\" is what causes misunderstanding, as\n> \"updates\" does not necessarily mean \"restores with the original\".\n> \n> How about this?\n> \n>   \t'git checkout' with <paths> or `--patch` is used to restore\n>         modified or deleted paths to their original contents from\n>         the index file or from a named <tree-ish> (most often a\n>         commit) without switching branches.\n\nI think these changes would improve the above:\n\ns/index file/index/\n- index file is implementation; the glossary only defines \"index\"\n\ns/or from/or replace paths with the contents from/\n- the latter case isn't always restoration, if <tree-ish> doesn't come\n  from an ancestor of HEAD (so I don't like \"restore\" in the summary\n  either)\n\ns/without switching/instead of switching/\n- 'without' implies it makes sense to restore/replace with switching\n  branches, but we've chosen not to.  (I then waste time trying to\n  understand that)\n\ns/commit/commit-ish/\n- tags are also tree-ishes, though you could argue this case is less\n  \"often\"\n\nleaving:\n\n'git checkout' with <paths> or `--patch` is used to restore modified or\ndeleted paths to their original contents from the index or replace paths\nwith the contents from a named <tree-ish> (most often a commit-ish)\ninstead of switching branches.\n\ndoes a sha1 count as \"named\"? Maybe s/named //.\n\n-- \nScott Schmit\n"},{"id":"263672","messageId":"xmqqa8w4evyx.fsf@gitster.dls.corp.google.com","threadId":"39565","inReplyTo":"20150612044906.GA17424@odin.ulthar.us","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-12T16:24:06Z","receivedAt":"2015-06-12T16:24:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Scott Schmit <i.grok@comcast.net> writes:\n\n> On Wed, Jun 10, 2015 at 08:05:32AM -0700, Junio C Hamano wrote:\n>\n>> How about this?\n>> \n>>         'git checkout' with <paths> or `--patch` is used to restore\n>>         modified or deleted paths to their original contents from\n>>         the index file or from a named <tree-ish> (most often a\n>>         commit) without switching branches.\n>\n> I think these changes would improve the above:\n>\n> s/index file/index/\n> - index file is implementation; the glossary only defines \"index\"\n\nYup, that was sloppy of me.  Thanks.\n\n> s/or from/or replace paths with the contents from/\n> - the latter case isn't always restoration, if <tree-ish> doesn't come\n>   from an ancestor of HEAD (so I don't like \"restore\" in the summary\n>   either)\n\nYes, that is why the original said 'checkout' in the first place.\n\n> s/without switching/instead of switching/\n> - 'without' implies it makes sense to restore/replace with switching\n>   branches, but we've chosen not to.  (I then waste time trying to\n>   understand that)\n\nOK.\n\n> s/commit/commit-ish/\n> - tags are also tree-ishes, though you could argue this case is less\n>   \"often\"\n\nCorrect.\n\n> leaving:\n>\n> 'git checkout' with <paths> or `--patch` is used to restore modified or\n> deleted paths to their original contents from the index or replace paths\n> with the contents from a named <tree-ish> (most often a commit-ish)\n> instead of switching branches.\n\nYeah, I like that.  I'd appreciate if somebody can submit the final\nversion as a patch form after waiting for a few days to hear other's\nopinions.\n\n> does a sha1 count as \"named\"? Maybe s/named //.\n\nThe \"named\" in the original \"named tree-ish\" does not mean \"the\ntree-ish has a human readable name (e.g. a tag)\"; it merely means\n\"the user tells Git to use one tree-ish to use for this operation;\nand the tree-ish was specified (by some means) by the user\", i.e.\nthe same thing as \"specified\".  If you specify the tree-ish with its\nobject name, yes, you are naming that (after all, that is what\neverything in sha1-name.c does).\n\ns/a named <tree-ish>/the <tree-ish>/ in the improved text you\nproposed above would be sufficient, I would think, as it is clear\nwhich <tree-ish> we are talking about in the context.\n\nThanks.\n"},{"id":"263696","messageId":"557B43F6.9070502@web.de","threadId":"39565","inReplyTo":"20150612044906.GA17424@odin.ulthar.us","subject":"Re: [PATCH] git-checkout.txt: Document \"git checkout <pathspec>\" better","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2015-06-12T20:41:26Z","receivedAt":"2015-06-12T20:41:26Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On 2015-06-12 06.49, Scott Schmit wrote:\n> 'git checkout' with <paths> or `--patch` is used to restore modified or\n> deleted paths to their original contents from the index or replace paths\n> with the contents from a named <tree-ish> (most often a commit-ish)\n> instead of switching branches.\n-------------------\nI will probably send a patch, the next days or so.\nIt feels as if we can split the long sentence, and differntiate\nbetween the \"restore\" and \"copy content from other tree-sh\".\nHow about this:\n\n\n'git checkout' [--] <pathspec>...::\n\t'git checkout' with <paths> is used to restore modified or\n\tdeleted paths to their original contents from the index.\n\n'git checkout' [-p|--patch] [<tree-ish>] [--] <pathspec>...::\n\t'git checkout' with [<tree-ish>] and <paths> or `--patch` is used\n\tto replace <paths> with the contents from a named <tree-ish>\n\t(most often a commit-ish) instead of switching branches.\n\tIn this case, the `-b` and `--track` options are\n\tmeaningless and giving either of them results in an error.  The\n\t<tree-ish> argument can be used to specify a specific tree-ish\n\t(i.e.  commit, tag or tree) to update the index for the given\n\tpaths before updating the working tree.\n+\n"}]}