unpack-trees: suggest using 'git stash' when checkout fails

Arsh123344423 · Arsh123344423 · commit f34c20208403 · 2026-03-12T18:49:19.000Z
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 &lt;arshsrivastava00@gmail.com&gt;
diff --git 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
@@ -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
@@ -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'."
+			  )
+		      : _("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"
