Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
On 2015-06-12 06.49, Scott Schmit wrote: 'git checkout' with paths or `--patch` is used to restore modified or deleted paths to their original contents from the index or replace paths with the contents from a named tree-ish (most often a commit-ish) instead of switching branches. --- I will probably send a patch, the next days or so. It feels as if we can split the long sentence, and differntiate between the restore and copy content from other tree-sh. How about this: 'git checkout' [--] pathspec...:: 'git checkout' with paths is used to restore modified or deleted paths to their original contents from the index. 'git checkout' [-p|--patch] [tree-ish] [--] pathspec...:: 'git checkout' with [tree-ish] and paths or `--patch` is used to replace paths with the contents from a named tree-ish (most often a commit-ish) instead of switching branches. In this case, the `-b` and `--track` options are meaningless and giving either of them results in an error. The tree-ish argument can be used to specify a specific tree-ish (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree. + -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
Scott Schmit i.g...@comcast.net writes: On Wed, Jun 10, 2015 at 08:05:32AM -0700, Junio C Hamano wrote: How about this? 'git checkout' with paths or `--patch` is used to restore modified or deleted paths to their original contents from the index file or from a named tree-ish (most often a commit) without switching branches. I think these changes would improve the above: s/index file/index/ - index file is implementation; the glossary only defines index Yup, that was sloppy of me. Thanks. s/or from/or replace paths with the contents from/ - the latter case isn't always restoration, if tree-ish doesn't come from an ancestor of HEAD (so I don't like restore in the summary either) Yes, that is why the original said 'checkout' in the first place. s/without switching/instead of switching/ - 'without' implies it makes sense to restore/replace with switching branches, but we've chosen not to. (I then waste time trying to understand that) OK. s/commit/commit-ish/ - tags are also tree-ishes, though you could argue this case is less often Correct. leaving: 'git checkout' with paths or `--patch` is used to restore modified or deleted paths to their original contents from the index or replace paths with the contents from a named tree-ish (most often a commit-ish) instead of switching branches. Yeah, I like that. I'd appreciate if somebody can submit the final version as a patch form after waiting for a few days to hear other's opinions. does a sha1 count as named? Maybe s/named //. The named in the original named tree-ish does not mean the tree-ish has a human readable name (e.g. a tag); it merely means the user tells Git to use one tree-ish to use for this operation; and the tree-ish was specified (by some means) by the user, i.e. the same thing as specified. If you specify the tree-ish with its object name, yes, you are naming that (after all, that is what everything in sha1-name.c does). s/a named tree-ish/the tree-ish/ in the improved text you proposed above would be sufficient, I would think, as it is clear which tree-ish we are talking about in the context. Thanks. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
I guess 'replace' would be a better word than 'restore' for the current behaviour. -- Ed Avis e...@waniasset.com -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
Torsten Bögershausen tbo...@web.de writes: On 2015-06-10 17.05, Junio C Hamano wrote: -git-checkout - Checkout a branch or paths to the working tree +git-checkout - Switch branches or reverts changes in the working tree Two verbs in different moods; either switch branches or restore changes or switches branches or restores changes would fix that, and judging from git help output, I think we want to go with the former, i.e. switch branches or restore changes. Gaah, no we do not restore changes. We restore working tree files to their pristine state. And ... or restore working tree files to their pristine state is way too long. Unfortunately overwrite changes in the working tree is even worse. As it does not say overwrite _with what_, we invite the original confusion that triggered this whole thread if the reader thought an equally useful but different overwrites with result of merging your local changes to the pristine (similar to what checkout -m does) would happen. At least, restore working tree files without saying restoring them to what state? is much less likely to cause such a confusion. So... git-checkout - Switch branches or restore working tree files perhaps? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
On Wed, Jun 10, 2015 at 08:05:32AM -0700, Junio C Hamano wrote: Torsten Bögershausen tbo...@web.de writes: git checkout pathspec can be used to revert changes in the working tree. I somehow thought that concensus in the recent thread was that restore, not revert, is the more appropriate wording? And I think that is indeed sensible because revert (or reset) already means something else in Git (and in other systems), while restore does not have a confusing connotation. It can only mean overwrite with a pristine copy, which is what the command is about. -git-checkout - Checkout a branch or paths to the working tree +git-checkout - Switch branches or reverts changes in the working tree Two verbs in different moods; either switch branches or restore changes or switches branches or restores changes would fix that, and judging from git help output, I think we want to go with the former, i.e. switch branches or restore changes. SYNOPSIS @@ -83,7 +83,8 @@ Omitting branch detaches HEAD at the tip of the current branch. When paths or `--patch` are given, 'git checkout' does *not* switch branches. It updates the named paths in the working tree from the index file or from a named tree-ish (most often a - commit). In this case, the `-b` and `--track` options are + commit). Changes in files are discarded and deleted files are + restored. I see we are suffering from the common disease of giving one explanation and then realizing that first explanation can be misread, clarifying it by more explanation, after reading the updated text three times. Let's instead try to clarify the first explanation to make it harder to misread. In this case, updates X from Y is what causes misunderstanding, as updates does not necessarily mean restores with the original. How about this? 'git checkout' with paths or `--patch` is used to restore modified or deleted paths to their original contents from the index file or from a named tree-ish (most often a commit) without switching branches. I think these changes would improve the above: s/index file/index/ - index file is implementation; the glossary only defines index s/or from/or replace paths with the contents from/ - the latter case isn't always restoration, if tree-ish doesn't come from an ancestor of HEAD (so I don't like restore in the summary either) s/without switching/instead of switching/ - 'without' implies it makes sense to restore/replace with switching branches, but we've chosen not to. (I then waste time trying to understand that) s/commit/commit-ish/ - tags are also tree-ishes, though you could argue this case is less often leaving: 'git checkout' with paths or `--patch` is used to restore modified or deleted paths to their original contents from the index or replace paths with the contents from a named tree-ish (most often a commit-ish) instead of switching branches. does a sha1 count as named? Maybe s/named //. -- Scott Schmit -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
Ed Avis e...@waniasset.com writes: I guess 'replace' would be a better word than 'restore' for the current behaviour. Hmm, but wouldn't replace have the same issue as overwrite, namely, 'replace with what?'. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
Torsten Bögershausen tbo...@web.de writes: git checkout pathspec can be used to revert changes in the working tree. I somehow thought that concensus in the recent thread was that restore, not revert, is the more appropriate wording? And I think that is indeed sensible because revert (or reset) already means something else in Git (and in other systems), while restore does not have a confusing connotation. It can only mean overwrite with a pristine copy, which is what the command is about. -git-checkout - Checkout a branch or paths to the working tree +git-checkout - Switch branches or reverts changes in the working tree Two verbs in different moods; either switch branches or restore changes or switches branches or restores changes would fix that, and judging from git help output, I think we want to go with the former, i.e. switch branches or restore changes. SYNOPSIS @@ -83,7 +83,8 @@ Omitting branch detaches HEAD at the tip of the current branch. When paths or `--patch` are given, 'git checkout' does *not* switch branches. It updates the named paths in the working tree from the index file or from a named tree-ish (most often a - commit). In this case, the `-b` and `--track` options are + commit). Changes in files are discarded and deleted files are + restored. I see we are suffering from the common disease of giving one explanation and then realizing that first explanation can be misread, clarifying it by more explanation, after reading the updated text three times. Let's instead try to clarify the first explanation to make it harder to misread. In this case, updates X from Y is what causes misunderstanding, as updates does not necessarily mean restores with the original. How about this? 'git checkout' with paths or `--patch` is used to restore modified or deleted paths to their original contents from the index file or from a named tree-ish (most often a commit) without switching branches. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
Ed Avis e...@waniasset.com writes: 'restore' may be more consistent with git's internal terminology. But from an outsider's perspective, 'revert' rather than 'restore' is in my view much clearer and more consistent with other version control systems: for example 'svn revert' is what you use to revert files in the working copy. The reason why I said restore is because it does *not* have any internal terminology connotation. On the other hand, revert that means create a counter-effect commit is not internal. git revert is a part of end-user facing command. The only people that will be helped by using revert there will be the ones who haven't learned git revert. And it will make it harder for them to learn git revert. It is unfortunate that other systems use the word revert in a different way, and that is why we should avoid using that word when describing checkout. The original issue was that I naively expected that 'git checkout PATH' would indeed just 'restore' some files, that is, create them when they are missing. ... If 'revert' is not a suitable verb because of the existing git-revert, then I suggest that 'overwrite' or 'replace' might better convey the idea of what the command does. Git is about contents, not files. You modify a file, and restore its contents to its pristine state. It is not restore the file, as Git is not about files. I think overwrite is better is primarily coming from not thinking in terms of Git tracks contents, not files. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
On 2015-06-10 17.05, Junio C Hamano wrote: Torsten Bögershausen tbo...@web.de writes: (Need to drop Eric from CC-list( git checkout pathspec can be used to revert changes in the working tree. I somehow thought that concensus in the recent thread was that restore, not revert, is the more appropriate wording? And I think that is indeed sensible because revert (or reset) already means something else in Git (and in other systems), while restore does not have a confusing connotation. It can only mean overwrite with a pristine copy, which is what the command is about. -git-checkout - Checkout a branch or paths to the working tree +git-checkout - Switch branches or reverts changes in the working tree Two verbs in different moods; either switch branches or restore changes or switches branches or restores changes would fix that, and judging from git help output, I think we want to go with the former, i.e. switch branches or restore changes. OK for me SYNOPSIS @@ -83,7 +83,8 @@ Omitting branch detaches HEAD at the tip of the current branch. When paths or `--patch` are given, 'git checkout' does *not* switch branches. It updates the named paths in the working tree from the index file or from a named tree-ish (most often a -commit). In this case, the `-b` and `--track` options are +commit). Changes in files are discarded and deleted files are +restored. [] How about this? 'git checkout' with paths or `--patch` is used to restore modified or deleted paths to their original contents from the index file or from a named tree-ish (most often a commit) without switching branches. OK for me. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] git-checkout.txt: Document git checkout pathspec better
'restore' may be more consistent with git's internal terminology. But from an outsider's perspective, 'revert' rather than 'restore' is in my view much clearer and more consistent with other version control systems: for example 'svn revert' is what you use to revert files in the working copy. The original issue was that I naively expected that 'git checkout PATH' would indeed just 'restore' some files, that is, create them when they are missing. Its action is rather more drastic than that. If 'revert' is not a suitable verb because of the existing git-revert, then I suggest that 'overwrite' or 'replace' might better convey the idea of what the command does. -- Ed Avis e...@waniasset.com -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
