Move the example git bisect shell script from perlgit.pod to Porting/

This both avoids cluttering the flow of manpage with auxiliary data, and
saves the user from having to extract the script from within the pod file.

5 files changed, 43 insertions, 30 deletions

diff --git a/MANIFEST b/MANIFEST
index 6aab879ddf..f48957d246 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -4755,6 +4755,7 @@ pod/splitpod			Splits perlfunc into multiple pod pages
 Policy_sh.SH			Hold site-wide preferences between Configure runs.
 Porting/acknowledgements.pl	Generate perldelta acknowledgements text
 Porting/add-package.pl		Add/Update CPAN modules that are part of Core
+Porting/bisect-example.sh	Example script to use with git bisect run
 Porting/bisect.pl		A tool to make bisecting easy
 Porting/bisect-runner.pl	Tool to be called by git bisect run
 Porting/bump-perl-version	bump the perl version in relevant files
diff --git a/Porting/bisect-example.sh b/Porting/bisect-example.sh
new file mode 100755
index 0000000000..d6db406a80
--- /dev/null
+++ b/Porting/bisect-example.sh
@@ -0,0 +1,36 @@
+#!/bin/sh
+echo >&2 You need to edit this to run your test case
+exit 1
+
+git clean -dxf
+
+# If you get './makedepend: 1: Syntax error: Unterminated quoted
+# string' when bisecting versions of perl older than 5.9.5 this hack
+# will work around the bug in makedepend.SH which was fixed in
+# version 96a8704c. Make sure to uncomment 'git checkout makedepend.SH'
+# below too.
+#git show blead:makedepend.SH > makedepend.SH
+
+# If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
+# if Encode is not needed for the test, you can speed up the bisect by
+# excluding it from the runs with -Dnoextensions=Encode
+# ie
+#./Configure -Dusedevel -Doptimize=-g -Dcc=ccache\ gcc -Dld=gcc -Dnoextensions=Encode -des
+./Configure -Dusedevel -Doptimize=-g -des
+test -f config.sh || exit 125
+# Correct makefile for newer GNU gcc
+perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
+# if you just need miniperl, replace test_prep with miniperl
+make test_prep
+[ -x ./perl ] || exit 125
+# This runs the actual testcase. You could use -e instead:
+./perl -Ilib ~/testcase.pl
+ret=$?
+[ $ret -gt 127 ] && ret=127
+git checkout makedepend.SH
+git clean -dxf
+exit $ret
+
+#if you need to invert the exit code, replace the above exit with this:
+#[ $ret -eq 0 ] && exit 1
+#exit 0
diff --git a/Porting/exec-bit.txt b/Porting/exec-bit.txt
index a6044209db..05a896762c 100644
--- a/Porting/exec-bit.txt
+++ b/Porting/exec-bit.txt
@@ -31,6 +31,7 @@ x2p/cflags.SH
 Porting/Maintainers.pl
 Porting/add-package.pl
 Porting/bisect.pl
+Porting/bisect-example.sh
 Porting/bisect-runner.pl
 Porting/check83.pl
 Porting/checkAUTHORS.pl
diff --git a/pod/perlgit.pod b/pod/perlgit.pod
index ee524f991e..e8137191bc 100644
--- a/pod/perlgit.pod
+++ b/pod/perlgit.pod
@@ -391,35 +391,10 @@ the history, which commit should be blamed for introducing a given bug.
 Suppose that we have a script F<~/testcase.pl> that exits with C<0>
 when some behaviour is correct, and with C<1> when it's faulty. You
 need an helper script that automates building C<perl> and running the
-testcase:
-
-  % cat ~/run
-  #!/bin/sh
-  git clean -dxf
-
-  # If you get './makedepend: 1: Syntax error: Unterminated quoted
-  # string' when bisecting versions of perl older than 5.9.5 this hack
-  # will work around the bug in makedepend.SH which was fixed in
-  # version 96a8704c. Make sure to comment out 'git checkout makedepend.SH'
-  # below too.
-  git show blead:makedepend.SH > makedepend.SH
-
-  # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
-  # if Encode is not needed for the test, you can speed up the bisect by
-  # excluding it from the runs with -Dnoextensions=Encode
-  sh Configure -des -Dusedevel -Doptimize="-g"
-  test -f config.sh || exit 125
-  # Correct makefile for newer GNU gcc
-  perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
-  # if you just need miniperl, replace test_prep with miniperl
-  make test_prep
-  [ -x ./perl ] || exit 125
-  ./perl -Ilib ~/testcase.pl
-  ret=$?
-  [ $ret -gt 127 ] && ret=127
-  # git checkout makedepend.SH
-  git clean -dxf
-  exit $ret
+testcase. For an example script, see F<Porting/bisect-example.sh>, which
+you should copy B<outside> of the repository as the bisect process will
+reset the state to a clean checkout as it runs. The instructions below assume
+that you copied it as F<~/run> and then edited as appropriate.
 
 This script may return C<125> to indicate that the corresponding commit
 should be skipped. Otherwise, it returns the status of
diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index 9ee04351cd..ed338027d8 100644
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -225,7 +225,7 @@ pod/perlebcdic.pod	Verbatim line length including indents exceeds 79 by	273
 pod/perlembed.pod	Verbatim line length including indents exceeds 79 by	27
 pod/perlfunc.pod	There is more than one target	1
 pod/perlfunc.pod	Verbatim line length including indents exceeds 79 by	167
-pod/perlgit.pod	Verbatim line length including indents exceeds 79 by	14
+pod/perlgit.pod	Verbatim line length including indents exceeds 79 by	11
 pod/perlgpl.pod	Verbatim line length including indents exceeds 79 by	50
 pod/perlguts.pod	? Should you be using F<...> or maybe L<...> instead of	2
 pod/perlguts.pod	? Should you be using L<...> instead of	1