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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 7, 2011, 00:16 UTC
Message-ID: <7vtyhl8t5y.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20110106225222.GA15900@burratino>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 11 quoted lines

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