Re: [PATCH] Documentation/git-checkout: make doc. of checkout <tree-ish> clearer
- From
- Christoph Michelbach <michelbach94@gmail.com>
- Date
- Apr 18, 2017, 11:50 UTC
- Message-ID
- <1492516221.5720.22.camel@gmail.com>
- In-Reply-To
- <5FD0803E166B4D2F9F64D8D21AC23EB3@PhilipOakley>
On Mon, 2017-04-17 at 21:59 +0100, Philip Oakley wrote:
> I've added back the list, as it was accidentally dropped.
Thanks. I'm sorry. I apparently pressed the wrong button in my emails client. What I wrote is visible in your quote.
Show 23 quoted lines
> From: "Christoph Michelbach" <michelbach94@gmail.com> > > I understand what the command does. It behaves perfectly as I > > expected > > it to. I did not find this script but wrote it to demonstrate that > > what > > the documentation says is different from how it behaves after having > > read what the documentation says it should do and noticing that > > that's > > not how I expected it to work from experience. > > > > What it really does is to copy all files described by the given > > paths > > from the given tree-ish to the working directory. Or at least that's > > my > > expectation of what it does. > > > > The documentation, however, says that the given paths are > > *restored*. > > This is different. > I don't see that difference in the phrase *restored*, compared to your > 'copy > all files described by the given paths'. Could you explain a little > more?
Suppose you have X. If you say X is restored to what it was half an hour ago, I expect everything about X to be exactly as it was half an hour ago. So if X is a file containing the text "Hello, world!", I expect there to be a file (with the exact same file name) which contains the text "Hello, world!", even if I changed that text in the mean time or deleted the file entirely. If X is a folder which contains files, I expect it to have the exact same contents as before. If there were 5 files in the folder half an hour ago, I expect there to be 5 files with the same file names and the same content in each file, again, even if I deleted, renamed, changed the contents of, or added files in the mean time. This is, however, not the case. Suppose I renamed a file from "foo" to "bar". Then there are 6 files, not 5. This is not how X was half an hour ago.
If you, however, say that all files in the path X are copied back from what they were half an hour ago, if X is a file, I expect the exact same thing as before for it. And that's actually what happens in reality. But if X is a folder, there's a difference: Because only the *files X contains* are copied back – *not X itself* –, all the files in X which do not occur in the state from half an hour ago, are unaffected. So now I expect there to be a 6th file because there is no file "bar" in the state from half an hour ago which could overwrite the file "bar" in the working tree.
Show 19 quoted lines
> > Yeah, definitely. There should be 2 separate entries for this. > > > > I think someone thought it was a good idea to make `<pathspec>...` > > optional in the synopsis because `git checkout` behaves in that > > special > > way if a patch *or* paths are given. But then, of course, with both > > `- > > p|--patch` and `<pathspec>...` optional, the command is the same as > > the > > first variation, just with optional parameters -- but the > > documentation > > (correctly) says those variations should behave very differently > > from > > each other. > > > > I don't see how this can be avoided without having 2 separate > > entries > > for those cases. > true.
So now we have to find someone who used that command with both a patch and a tree-ish present a lot because I have no idea how that would behave and don't even know why you would use it.
-- Christoph