Re: Better cooperation between checkouts and stashing

To Junio in particular: See the very bottom of this email.

On Mon, Mar 1, 2010 at 04:50, Markus Elfring <Markus.Elfring@web.de> wrote:

Junio pointed out that the documentation is currently lacking:

  [Unfortunately,] I don't see anything that states
  clearly that "checkout" is designed to carry your
  local changes across in any documentation (I gave
  a cursory look to the user manual, tutorial and
  checkout manual page). Probably "git checkout --help"
  needs a "Switching branches" section, just like the
  planned enhancement for "Detached HEAD" section.

In other words, the documentation NEEDS to be updated to include the explanation and rationale that Junio also supplied:

  Checking out another branch (branch switching) is
  designed to carry your local modification across
  with you. This is to allow you to start working on
  something, realize that your changes are better suited
  for another branch, and at that point after the fact
  "git checkout" that other branch, while keeping what
  you have done so far.

  If the original branch you started your work from and
  the branch you are checking out have different contents
  in files you have changed (aka "your changes conflict
  at the paths level"), without -m option, "git checkout"
  refuses to check out the other branch, because it will
  need a three-way merge to carry your changes forward,
  and you might not be prepared to resolve conflicts
  resulting from such a merge.

  In practice, however, your changes often don't conflict
  with the changes between the branches at the paths
  level, and "git checkout" lets you carry your local
  changes across just fine. I'd say this is the majority
  of the case especially for experienced git users, as
  they tend to commit in smaller and more logical units
  than those from other SCM background.

and Junio expanded on this later:

  It is important to understand that a local change does
  not belong to your current branch (it does not belong to
  _any_ branch). It belongs to you, and you can take it
  around while switching between branches. And that is a
  big time-saving feature.
  
  This lets you work like this:
  
   - You are reading a mailing list message that
   asks for help, and you know the solution---you
   can give the help real quick.
  
   - You hack in whatever branch that happen to be
   checked out. The change is perfect, it works.
  
   - The branch you happen to have checked out
   was 'next', but the solution is a bugfix, and
   should go to 'maint'.
  
  Now, at this point, you want to checkout 'maint' without
  losing your local change. The paths you touched with
  your quick fix are often not different between the two
  branches, and "checkout maint" will checkout the branch
  while keeping your local changes intact. All that is
  left for you to do is to run another round of test to
  make sure that your fix didn't depend on anything not
  in 'maint' and commit the change with appropriate log
  message, and then you can go back to whatever you were
  doing with "checkout next".
  
  When the change involves paths that were touched
  between 'maint' and 'next', of course you won't be
  able to switch without merging the local change to the
  difference between 'next' and 'maint'. There are a few
  workflows to deal with such a case, and the easiest is
  "checkout -m", if you are confident that you can resolve
  it.

  In a case where "checkout -m" would result in a conflict
  too big to resolve, the original fix you made would not
  be applicable to 'maint' (iow, you should have solved it
  differently starting from 'maint'), and you may end up
  doing "reset --hard" and start from scratch, but that is
  a rare worst case.

  I said it is rare, because you would notice, while doing
  the "quick fix" based on 'next' codebase, that the code
  you are touching have changed since 'maint' and won't be
  applicable to its final destination (by that time you
  know you are "fixing"), and you won't waste too much
  time continuing to work in a checkout of 'next'.

I think it would be a great contribution if you could clean up Junio's explanation and submit a patch that includes it in the documentation for "git checkout".

"git checkout" with something like the following (this hack is **not** meant as a solution; it is only meant to illustrate what I think is Markus Elfring's desire):

  # Utility:

    get_stash_id()
    {
      local branch=$(git rev-parse --symbolic-full-name HEAD)
      [ $branch = HEAD ] && return 1 # don't stash for detached HEAD
      echo -n "$branch" | md5sum | awk -F" " '{print $1}'
    }

  # New implementation:

    checkout()
    {
      # Stash local modifications (including index modifications) if
      # necessary, using an easily identifiable message known as the
      # 'stash id':

	local stash_id
        stash_id=$(get_stash_id) &&
          git stash save -q "$stash_id" ||    # Save local modifications
            git reset --hard HEAD             # Throw away changes on detached HEAD

      # Do the checkout that was requested:

        git checkout "$@"

      # Unstash previously stashed local modifications (including
      # index modifications) if they were automatically stashed
      # before (the lookup is done with the relevant 'stash id'):

        stash_id=$(get_stash_id)                                            &&
          stash_id=$(git stash list | awk -F': ' "/$stash_id/ {print \$1}") &&
            [ -n "$stash_id" ]                                              &&
              git stash pop --index "$stash_id"
    }

Sincerely, Michael Witten