Re: [PATCH] Documentation/git-checkout: make doc. of checkout <tree-ish> clearer

> On Sun, 2017-04-16 at 22:25 +0100, Philip Oakley wrote:
>> From: "Christoph Michelbach" <michelbach94@gmail.com>
>> > It's: git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>...
>> The one I quoted is direct from the Synopsis, which does indicate
>> there are
>> potentially more aspects to resolve, such as the influence of using
>> the
>> [-p|--patch] options.
>
> Oh, you are right. I didn't even notice the one in the synopsis doesn't
> match the one further down. The one in the synopsis is wrong because
> after removing the optional parameters, it's the same as the first one
> in the synopsis, yet we expect very different behavior from them.
>
>
>> It maybe that the paragraph / sentence that needs adjusting is;
>>
>> '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).
>>
>> and split it at the "or replace paths" option to pick out your
>> specific
>> case.
>
> This one is confusing, too: Paths can lead to folders, yet folders whose
> contents have been modified are not restored to their original contents
> when executing that command. Only files are.
>
> After reading the documentation and having never used the command
> before, one would expect
>
>    #!/bin/bash
>    rm -Rf repo
>    mkdir repo
>    cd repo
>    git init &> /dev/null
>    mkdir folder
>    echo a > folder/a
>    git add -A
>    git commit -m "Commit 1." &> /dev/null
>    echo b > folder/b
>    git add -A
>    git commit -m "Commit 2." &> /dev/null
>    echo c > folder/c
>    git add -A
>    git commit -m "Commit 3." &> /dev/null
>    git checkout `git log --pretty=format:%H | tail -1` folder
>    ls folder
>
> to print `a`. However, it prints `a b c` because all of the files inside
> `folder` which have been modified or deleted since (here: none) are
> reset to their original state after the first commit, but `folder`
> itself isn't. Yet, the only path which was passed to the command in
> question is `folder`.
>
> In my opinion, this command needs improved documentation (and the
> synopsis needs to be fixed).
>