From: Arsh Srivastava via GitGitGadget <gitgitgadget@gmail.com>
Date: Thu, 12 Mar 2026 20:05:01 GMT
Subject: [PATCH v7] unpack-trees: suggest using 'git stash' when checkout fails
Message-ID: <pull.2233.v7.git.git.1773345901659.gitgitgadget@gmail.com>
In-Reply-To: <pull.2233.v6.git.git.1773288013936.gitgitgadget@gmail.com>

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(-)

diff --git a/t/t6439-merge-co-error-msgs.sh b/t/t6439-merge-co-error-msgs.sh
index 643c9368e0..6ccc1e0416 100755
--- a/t/t6439-merge-co-error-msgs.sh
+++ b/t/t6439-merge-co-error-msgs.sh
@@ -76,7 +76,8 @@ 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.
+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
 
@@ -98,7 +99,8 @@ 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.
+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
 
diff --git a/t/t7406-submodule-update.sh b/t/t7406-submodule-update.sh
index 3adab12091..1ba15918a5 100755
--- a/t/t7406-submodule-update.sh
+++ b/t/t7406-submodule-update.sh
@@ -211,7 +211,8 @@ 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.
+	> 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
diff --git a/unpack-trees.c b/unpack-trees.c
index 998a1e6dc7..e817477926 100644
--- a/unpack-trees.c
+++ b/unpack-trees.c
@@ -128,8 +128,11 @@ void setup_unpack_trees_porcelain(struct unpack_trees_options *opts,
 	if (!strcmp(cmd, "checkout"))
 		msg = advice_enabled(ADVICE_COMMIT_BEFORE_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.")
-		      : _("Your local changes to the following files would be overwritten by checkout:\n%%s");
+			  "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.");
 	else if (!strcmp(cmd, "merge"))
 		msg = advice_enabled(ADVICE_COMMIT_BEFORE_MERGE)
 		      ? _("Your local changes to the following files would be overwritten by merge:\n%%s"

base-commit: d181b9354cf85b44455ce3ca9e6af0b9559e0ae2
-- 
gitgitgadget