Re: If you would write git from scratch now, what would you change?

[Junio C Hamano <gitster@pobox.com>]

Steven Walter <stevenrwalter@gmail.com> writes:

> Heartily seconded.  I think checkout is the most egregrious of the
> three.  git-checkout can be used to:
>
>     * Switch branches
>     * Create a branch
>     * Change the state of all files to a particular commit
>     * Change the state of a particular file to that of the index
>     * Change the state of a particular file (and index) to a particular
>       commit

Come on.  The second one is just to give a short-hand side-effet for
commonly used operation and you do not have to use it nor learn it.

Also, you have written the last three in a more confusing way than it is
necessary.  They are all the same thing but with variations --- your way
of writing them is like enumerating "change the state of files whose
name starts with A", "change the state of files whose name starts with
B", etc. as if they are distinctly different and confusing operations.

Let's clear the confusion.  Although it is not bad like the above
"random 5 different operations", checkout does serve 2 quite different
purposes:

 (1) checkout a revision.

     This primarily affects the notion of where your HEAD is.  Is it
     pointing at a branch, or detached at a particular commit?  In
     either case, the objective from the user's point of view here is "I
     want to change on which commit and/or branch I'd build the next
     commit, if I were to issue git-commit command".

     "I started modifying but realized that I wanted to build not on top
     of master but a separate topic", is a typical use case, and this
     form will let you take your local changes with you exactly for this
     reason.

     Obviously when people say "I checkout this commit", they mean the
     state of the work tree and they mean the whole tree.  It is
     hopefully clear that is what you are doing from the fact that you
     do not give any pathspec to the command to trigger this mode of
     operation.

 (2) checkout selected paths out of a commit (or the index).

     "I screwed up.  I want to start over modifications to these files
     from the state of the previous commit (or the last state I
     staged)." is a typical use case for this mode.  For this reason,
     the named paths are updated in the work tree and the work tree and
     the index are made to match.

     Again, it hopefully is clear enough that you need to give some
     pathspec to it for the operation to make sense, if you understand
     the purpose of the command.  Like "." to mean the whole tree, "*.c"
     to mean all C files, or "directory/" to mean everything underneath
     it.

So yes, it does two quite different things, and that's mostly because
the verb "to check out" has overloaded meanings.

Hopefully it is clear which one you are using by thinking about the
reason WHY you are "checking out", and by looking at the way you form
the command line.