[PATCH 1/1] stash: document stash.useBuiltin

From: Johannes Schindelin via GitGitGadget <gitgitgadget@gmail.com>
Date: May 14, 2019, 09:19 UTC
Message-ID: <6c250451658f34c1415bfcba35ee6303cecac0dc.1557825553.git.gitgitgadget@gmail.com>
In-Reply-To: <pull.193.git.gitgitgadget@gmail.com>

From: Johannes Schindelin <johannes.schindelin@gmx.de>

The stash.useBuiltin variable introduced in 90a462725e ("stash: optionally use the scripted version again", 2019-02-25) was turned on by default, but had no documentation.

Let's document it so that users who run into any stability issues with the C rewrite know there's an escape hatch, and spell out that the user should please report the bug when they have to turn off the built-in stash.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
 Documentation/config/stash.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt
index c583d46d6b..d7bf6ec61f 100644
--- a/Documentation/config/stash.txt
+++ b/Documentation/config/stash.txt
@@ -1,3 +1,18 @@
+stash.useBuiltin::
+       Set to `false` to use the legacy shell script implementation of
+       linkgit:git-stash[1]. Is `true` by default, which means use
+       the built-in rewrite of it in C.
++
+The C rewrite is first included with Git version 2.22 (and Git for Windows
+version 2.19). This option serves an an escape hatch to re-enable the
+legacy version in case any bugs are found in the rewrite. This option and
+the shell script version of linkgit:git-stash[1] will be removed in some
+future release.
++
+If you find some reason to set this option to `false` other than
+one-off testing you should report the behavior difference as a bug in
+git (see https://git-scm.com/community for details).
+
 stash.showPatch::
 	If this is set to true, the `git stash show` command without an
 	option will show the stash entry in patch form.  Defaults to false.

-- 
gitgitgadget