Subject: [PATCH 3/9] BreakingChanges: announce stash {apply,pop} will imply --index

From: "D. Ben Knoble" <[email-masked]>
Date: Sat, 10 May 2025 14:33:38 -0400

Some uses may now require --no-index, but remove a footgun that has bit
users over the years where stash {apply,pop} are not the opposite of
stash push because they drop the (saved) index.

Signed-off-by: D. Ben Knoble <[email-masked]>
---

Notes:
    Dscho/Junio suggested it in the original thread [1], but it wasn't
    considered for the release I believe [2].

    [1]: https://lore.kernel.org/git/[email-masked]/
    [2]: https://lore.kernel.org/git/[email-masked]/

 Documentation/BreakingChanges.adoc | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
index 61bdd586b9..798e742267 100644
--- a/Documentation/BreakingChanges.adoc
+++ b/Documentation/BreakingChanges.adoc
@@ -118,6 +118,17 @@ Cf. <[email-masked]>,
 <[email-masked]>,
 <CA+EOSBncr=[email-masked]>.
 
+* The git-stash(1) command now tries to reinstate the index by default in
+  the "apply" and "pop" modes. Not doing so creates a common trap: "git stash
+  apply" is not the reverse of "git stash push" because carefully staged indices
+  are lost and have to be manually recreated.
++
+Now git-stash(1) will behave like "--index" was given in the "apply" and "pop"
+modes. Use "--no-index" to disable this behavior.
++
+Cf. <[email-masked]>,
+<[email-masked]>.
+
 === Removals
 
 * Support for grafting commits has long been superseded by git-replace(1).
-- 
2.48.1