Re: [PATCH] Clarification for the command "git checkout <branch>"

[Avery Pennarun <apenwarr@gmail.com>]

On Wed, Mar 17, 2010 at 12:35 PM, Markus Elfring <Markus.Elfring@web.de> wrote:
> -When <paths> are not given, this command switches branches by
> -updating the index, working tree, and HEAD to reflect the specified
> -branch.
> +When <paths> are not given, this command marks the specified branch
> +as the next commit target. (The reference "HEAD" points to its tip.)
> +Checking out another branch (branch switching) is designed to carry
> +your local modifications across with you. The working tree is not
> +restored to the state of its last commit.
>
>  If `-b` is given, a new branch is created and checked out, as if
>  linkgit:git-branch[1] were called; in this case you can

The new version spends all the time talking about weird exceptions and
none of the time actually saying what the basic functionality is
supposed to be.  How about this:

--
When <paths> are not given, this command switches from your current
branch to the given branch.  This is done by updating HEAD to point at
the given branch, reading the new branch's content into the index, and
checking out the content into your working tree.  Where possible, any
files you have modified in your current working tree or index remain
modified in the newly-checked-out branch.  This cannot be done,
however, when those modified files differ between the old and new
branches, in which case the checkout will abort in order to avoid
losing your changes.  You might want to use 'git stash' in this case.
--

Have fun,

Avery