[PATCH v7] unpack-trees: suggest using 'git stash' when checkout fails

From: Arsh Srivastava <arshsrivastava00@gmail.com>

When a branch switch fails due to local changes and new users who are not familiar with the error message often get confused about how to move ahead and resolve the issue as the previous error message only suggests to commit or stash the changes but doesn't explain how to do that or what the next steps are.

This patch enhances the error message with more specific instructions in a concise manner to help users understand how to resolve the issue and move their local changes safely to the other branch using stash.

Signed-off-by: Arsh Srivastava <arshsrivastava00@gmail.com>
---
    Advice on checkout dirty files
    
    This is my submission for microproject [GSOC]
    
    This patch extends the current message to help users better understand
    risks and alternatives to stashing their changes.
    
    The alternative consists of
    
    > git checkout -m and its repercussions.
    
    This extended message is tied to the existing advice.commitBeforeMerge
    configuration and can be silenced with:
    
    > git config set advice.commitBeforeMerge false
    
    Changes:
    
    > unpack-trees.c: expanded the already existing message.
    > t/t6439-merge-co-error-msgs.sh: update expected output for merge and
    > checkout tests. t/t7406-submodule-update.sh: update expected output
    > for submodule checkout tests.
    
    Signed-off-by: Arsh Srivastava arshsrivastava00@gmail.com

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2233%2FArsh123344423%2Fadvice_on_checkout_dirty_files-v7
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2233/Arsh123344423/advice_on_checkout_dirty_files-v7
Pull-Request: https://github.com/git/git/pull/2233

Range-diff vs v6:

 1:  e0ba5fad82 ! 1:  72cb550621 unpack-trees: suggesting 'git checkout -m' with its repercussions
     @@ Metadata
      Author: Arsh Srivastava <arshsrivastava00@gmail.com>
      
       ## Commit message ##
     -    unpack-trees: suggesting 'git checkout -m' with its repercussions
     +    unpack-trees: suggest using 'git stash' when checkout fails
      
     -    This comment is an extention to the already existing stash comment.
     -    Added updated comment over the already existing function
     -    "setup_unpack_trees_porcelain" with "git checkout -m"
     -    and its repercussions
     -    I have also mentioned the repercussions of using "-m".
     +    When a branch switch fails due to local changes and
     +    new users who are not familiar with the error message often
     +    get confused about how to move ahead and resolve the issue as
     +    the previous error message only suggests to commit or stash the changes
     +    but doesn't explain how to do that or what the next steps are.
      
     -    Signed-off-by: Arsh Srivastava arshsrivastava00@gmail.com
     +    This patch enhances the error message with more specific
     +    instructions in a concise manner to help users understand
     +    how to resolve the issue and move their local changes
     +    safely to the other branch using stash.
     +
     +    Signed-off-by: Arsh Srivastava <arshsrivastava00@gmail.com>
      
       ## t/t6439-merge-co-error-msgs.sh ##
     -@@ t/t6439-merge-co-error-msgs.sh: error: Your local changes to the following files would be overwritten by checkou
     +@@ t/t6439-merge-co-error-msgs.sh: cat >expect <<\EOF
     + error: Your local changes to the following files would be overwritten by checkout:
       	rep/one
       	rep/two
     - Please commit your changes or stash them before you switch branches.
     -+Try using 'git checkout -m <branch>' for a quick fix.
     -+Please Note :- that using -m (merge) will not save your changes, rather would directly merge them.
     -+Meaning if you are not able to resolve conflicts and does --hard reset your local changes would be gone.
     +-Please commit your changes or stash them before you switch branches.
     ++To move you local changes safely to the other branch,
     ++Please try 'git stash' followed by 'git checkout <branch>' followed by 'git stash pop' for safe merge.
       Aborting
       EOF
       
     -@@ t/t6439-merge-co-error-msgs.sh: error: Your local changes to the following files would be overwritten by checkou
     +@@ t/t6439-merge-co-error-msgs.sh: cat >expect <<\EOF
     + error: Your local changes to the following files would be overwritten by checkout:
       	rep/one
       	rep/two
     - Please commit your changes or stash them before you switch branches.
     -+Try using 'git checkout -m <branch>' for a quick fix.
     -+Please Note :- that using -m (merge) will not save your changes, rather would directly merge them.
     -+Meaning if you are not able to resolve conflicts and does --hard reset your local changes would be gone.
     +-Please commit your changes or stash them before you switch branches.
     ++To move you local changes safely to the other branch,
     ++Please try 'git stash' followed by 'git checkout <branch>' followed by 'git stash pop' for safe merge.
       Aborting
       EOF
       
      
       ## t/t7406-submodule-update.sh ##
      @@ t/t7406-submodule-update.sh: test_expect_success 'submodule update should fail due to local changes' '
     + 	sed "s/^> //" >expect <<-\EOF &&
       	> error: Your local changes to the following files would be overwritten by checkout:
       	> 	file
     - 	> Please commit your changes or stash them before you switch branches.
     -+	> Try using '\''git checkout -m <branch>'\'' for a quick fix.
     -+	> Please Note :- that using -m (merge) will not save your changes, rather would directly merge them.
     -+	> Meaning if you are not able to resolve conflicts and does --hard reset your local changes would be gone.
     +-	> Please commit your changes or stash them before you switch branches.
     ++	> To move you local changes safely to the other branch,
     ++	> Please try '\''git stash'\'' followed by '\''git checkout <branch>'\'' followed by '\''git stash pop'\'' for safe merge.
       	> Aborting
       	> fatal: Unable to checkout OID in submodule path '\''submodule'\''
       	EOF
     @@ unpack-trees.c: void setup_unpack_trees_porcelain(struct unpack_trees_options *o
       		      ? _("Your local changes to the following files would be overwritten by checkout:\n%%s"
      -			  "Please commit your changes or stash them before you switch branches.")
      -		      : _("Your local changes to the following files would be overwritten by checkout:\n%%s");
     -+			  "Please commit your changes or stash them before you switch branches.\n"
     -+			  "Try using 'git checkout -m <branch>' for a quick fix.\n"
     -+			  "Please Note :- that using -m (merge) will not save your changes, rather would directly merge them.\n"
     -+			  "Meaning if you are not able to resolve conflicts and does --hard reset your local changes would be gone."
     ++			  "To move you local changes safely to the other branch,\n"
     ++			  "Please try 'git stash' followed by 'git checkout <branch>' followed by 'git stash pop' for safe merge."
      +			  )
      +		      : _("Your local changes to the following files would be overwritten by checkout:\n%%s"
      +				"Please commit your changes or stash them before you switch branches.");

 t/t6439-merge-co-error-msgs.sh | 6 ++++--
 t/t7406-submodule-update.sh    | 3 ++-
 unpack-trees.c                 | 7 +++++--
 3 files changed, 11 insertions(+), 5 deletions(-)