emacs-31 c565251dd6a: ; * admin/notes/repo (Bisecting): Provide a 'git bisect run' recipe.

branch: emacs-31
commit c565251dd6a82c99b60a2b2b8bb985ec1ec3c5eb
Author: Sean Whitton <[email protected]>
Commit: Sean Whitton <[email protected]>

    ; * admin/notes/repo (Bisecting): Provide a 'git bisect run' recipe.
---
 admin/notes/repo | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/admin/notes/repo b/admin/notes/repo
index 2ed51c5cfc7..1384c4eb3ba 100644
--- a/admin/notes/repo
+++ b/admin/notes/repo
@@ -118,6 +118,8 @@ again.
 This is a semi-automated way to find the revision that introduced a bug.
 Browse 'git help bisect' for technical instructions.
 
+** Starting a bisection
+
 It is recommended to start a bisection with the admin/git-bisect-start
 script.  Using that script ensures that commits in branches that are
 the result of merging external trees into the Emacs repository, as
@@ -126,6 +128,34 @@ during the bisection process.  That script can also be executed
 automatically when 'git bisect start' is called, with the help of a
 wrapper script that is included in its commentary section.
 
+** Automated bisection
+
+In the case that you have a command which exits non-zero if and only if
+the bug is present, then after starting the bisection, you can have Git
+automatically recompile Emacs at the relevant revisions and run that
+command for you, recording a result based on the exit code.
+
+Suppose 'emacs -batch -eval "(foo)"' exits non-zero if and only if the
+bug is present.  Then you may be able to use something like this:
+
+    git bisect run sh -ec '{ test -e configure && { make || make	\
+    bootstrap; }; } || { git clean -xdff && ./autogen.sh autoconf &&	\
+    ./configure && make; } || exit 125; src/emacs -batch -eval "(foo)"'
+
+This tries to recompile Emacs, tries a bootstrap build if that fails,
+and completely empties out your working tree of build products with 'git
+clean -xdff' if even that fails.  If that isn't enough for a successful
+build, returning code 125 tells Git to skip evaluating that commit.
+
+You can substitute in any options to './configure' you need on your
+machine, and the test command at the end.  It is usually best to
+configure with '--without-native-compilation' for rebuild speed, unless
+the bug only occurs with native compilation enabled.
+
+Note that this runs 'git clean -xdff', which deletes **any and all
+untracked files**, so it is best to run it in a throwaway Git worktree.
+You can create these using 'C-x v w c' from inside Emacs.
+
 * Maintaining ChangeLog history
 
 Older ChangeLog entries are kept in history files named ChangeLog.1,