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

From: Christoph Michelbach <michelbach94@gmail.com>
Date: Apr 16, 2017, 22:06 UTC
Message-ID: <1492380399.19991.13.camel@gmail.com>
In-Reply-To: <DF5E72F5BD2F4BB99D8EC4DF1B4543F7@PhilipOakley>

On Sun, 2017-04-16 at 22:25 +0100, Philip Oakley wrote:

Show 7 quoted lines

> 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.

Show 11 quoted lines

> 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).

-- Christoph