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

["r.ductor@gmail.com" <r.ductor@gmail.com>]

Dear all

I'm a beginner git user trying to defend the beginners' party. Using Jonathan's explanations (and some educated guess on git behavior) I tried to concoct the man git-checkout documentation I would have liked to read, which is somewhat more explicit than Jonathan's patch. If you want to implement/improve it please double check it (and maybe warn me about my own errors). If you are happy about that I will try to send more suggestions. Thanks for your time and your work.

riccardo   

git checkout [<branch>]
git checkout -b|-B <new_branch> [<start point>]

     Tries to change the current HEAD to <branch> (or <start point>) and to safely update the working tree and the index.
     If there exist files having three distinct contents in the current commit, in the new branch and in the working tree, then the operation is canceled and all state is preserved.
     (This behavior may be changed with the option --merge.) If this is not the case, for all other files it acts as follows.  
       - Files not differing between the current commit and the new branch: their contents in the working tree (and eventually in the index) are left unchanged. 
       - Files in the current commit, unchanged or absent in the working tree, but not present in the new branch are removed from the working tree and from the index.
       - Files in the new branch but not in the current commit are added to the working tree and to the index (if they were already there they must have had the same contents by hypothesis).
       - Files in the working tree or in the index that are absent in the current commit and in the new branch are left unchanged.
    
    If -b is given, ...



On Friday 07 January 2011 01:16:25 Junio C Hamano wrote:
> 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.)
>