Re: [PATCH/RFC] Documentation/checkout: explain behavior wrt local changes

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

Jonathan Nieder <jrnieder@gmail.com> writes:

>  'git checkout' [<branch>]::
>  'git checkout' -b|-B <new_branch> [<start point>]::
>  
> -	This form switches branches by updating the index, working
> -	tree, and HEAD to reflect the specified branch.
> +	This form switches branches by changing `HEAD` and updating the
> +	tracked files to the specified branch.  'git checkout' will
> +	stop without doing anything if local changes overlap with
> +	changes to the tracked files.  (Any local changes that do not
> +	overlap with changes from `HEAD` to the specified branch will
> +	be preserved.)

Even though I am fully aware that "switch" was an attempt to match the
terminology from another SCM (e.g. svn), it may help readers in the longer
term if we stop using "switch" and instead explain this as "checking out a
branch" and what this action is _for_.  I suspect that an explanation of
the purpose would clarify the reason why the command does what it does.

You check out a branch to work on that branch, namely, eventually to
commit changes to that branch (as opposed to committing them to the
current branch).  For that purpose, the local changes obviously need to be
preserved.  And that is why it refuses to act if paths with local changes
need to be updated.

Side note.  When you check out a path (or a set of paths), you don't work
on these files (git does not track individual files), hence there is no
possible interpretation other than "get a fresh unmodified copy out of
something" when the command is used with paths, i.e. "checking out paths
(either out of the index or out of a named commit)".

In any case, your rewrite is certainly an improvement compared to an
unexplained "reflect", so I think this is a step in the right direction.

Thanks.