1SVN-BISECT(1)         User Contributed Perl Documentation        SVN-BISECT(1)
2
3
4

NAME

6       svn-bisect
7

SYNOPSIS

9           $ svn-bisect --min 25000 --max 26000 start
10           $ svn-bisect bad
11           $ svn-bisect bad
12           $ svn-bisect good
13           [etc etc]
14           $ svn-bisect reset
15

DESCRIPTION

17       This tool's purpose is to help you determine which revision of a
18       subversion repository contains a change.  It does this by employing a
19       binary search.  It will manage the current revision of your checkout
20       directory, and narrow in on the target revision, as you give it clues
21       about the current revision such as "before" (this revision is before
22       the one you want) or "after" (this revision is after the one you want).
23
24       Start a bisect session with the "start" command.  Then, walk the binary
25       tree by using the "before" and "after" commands.  When you are done,
26       the tool will tell you the target revision.
27
28       The most common usage scenario is finding out which rev a bug was
29       introduced in.  For this purpose, some command aliases have been added:
30       if the current revision contains the bug, you can use the "bad" command
31       (meaning, this revision is "after" the change you want to find),
32       otherwise use the "good" command (meaning, this revision is "before"
33       the change you want to find).
34
35       All commands should be run from within a subversion checkout directory.
36       After a "svn-bisect start", all subsequent svn-bisect commands need to
37       be run from that same directory.
38

OPTIONS

40       Options MUST be specified before subcommands, on the command line.
41       Options specified after the subcommand will be passed to the
42       subcommand; this is currently only useful for the "run" subcommand.
43
44       --help
45           Use anywhere.  Output a command list, or specific help for the
46           given command.
47
48       --version
49           Use anywhere.  Tells you my version number.
50
51       --verbose
52           Use anywhere.  Enable some additional informational output.
53
54       --min
55           Use with "start".  Specify the beginning revision of the range.
56
57       --max
58           Use with "start".  Specify the ending revision of the range.
59
60       --back
61           Use with "reset".  Restores the original repository version.
62

SUBCOMMANDS

64   start
65           svn-bisect [--min M] [--max N] start
66
67       Start a new bisect session.  If --min isn't specified, you can specify
68       it later with the "good" command.  If --max isn't specified, you can
69       specify it later with the "bad" command.
70
71   after
72           svn-bisect after [revision]
73           or: svn-bisect bad [revision]
74
75       Inform svn-bisect that the specified revision is *after* the change
76       we're looking for.  If you don't specify a revision number, the current
77       revision of the working tree is used.  If you are looking for the rev
78       which introduced a bug (which is the common case), the alias "bad"
79       might be easier to remember.
80
81   before
82           svn-bisect before [revision]
83           or: svn-bisect good [revision]
84
85       Inform svn-bisect that the specified revision is *before* the change
86       we're looking for.  If you don't specify a revision number, the current
87       revision of the working tree is used.  If you are looking for the rev
88       which introduced a bug (which is the common case), the alias "good"
89       might be easier to remember.
90
91   skip
92           svn-bisect skip [<rev> [<rev>...]]
93
94       Tell svn-bisect to skip the specified revision.  If no revision is
95       specified, the current version of the working tree is used.  Do this if
96       you can't determine whether the current revision is bad or good, if,
97       for instance, some other issue prevents it from compiling successfully.
98
99       You may specify more than one revision, and they will all be skipped.
100
101   unskip
102           svn-bisect unskip <rev> [<rev>...]
103
104       Tell svn-bisect to no longer skip the specified revision.  You must
105       specify at least one revision to unskip.  If you specify more than one,
106       they will all be unskipped.
107
108   run
109           svn-bisect run <command> [arguments...]
110
111       Runs a command repeatedly to automate the bisection process.
112
113       Examples:
114
115           svn-bisect run ./mytest.sh
116           svn-bisect run test ! -f file
117
118       We run the command and arguments until a conclusion is reached.  The
119       command (usually a shell script) tells us about the current revision by
120       way of its return code.  The following return codes are handled:
121
122           0: This revision is before the change we're looking for
123           1-124, 126-127: This revision includes the change we're looking for
124           125: This revision is untestable and should be skipped
125           any other value: The command failed to run, abort bisection.
126
127       In other words, "run" will automatically find the last revision for
128       which the given command returns success.  (Keep in mind that in the
129       shell, "0" means "success".)
130
131       The normal caveats apply.  In particular, if your script makes any
132       changes, don't forget to clean up afterwards.
133
134   reset
135           svn-bisect reset
136
137       Clean up after a bisect, and return the repository to the revision it
138       was at before you started.
139
140   help
141           svn-bisect help
142           svn-bisect help start
143
144       Gives you some useful descriptions and usage information.
145

EXAMPLE

147       ...Because, you know, no software documentation is complete without a
148       flashy screenshot, these days.
149
150       So, lets say you were wondering when the subversion project added the
151       "Last Changed Rev:" line to the output of "svn info".  Determining the
152       existence of this change is a straightforward matter of searching for
153       the text string... if a result was found, the current revision is
154       "after", otherwise it was "before".  So a bisect looks like this:
155
156           $ svn co http://svn.apache.org/repos/asf/subversion/trunk/subversion
157           [snip lots of subversion checkout spam]
158           Checked out revision 980012.
159
160           $ cd subversion
161
162           $ ack --nocolor --nogroup 'Last Changed Rev'
163           svn/info-cmd.c:362:    SVN_ERR(svn_cmdline_printf(pool, _("Last Changed Rev: %ld\n"),
164           tests/cmdline/depth_tests.py:2056:      'Last Changed Rev'   : '^1$',
165           tests/cmdline/upgrade_tests.py:387:      'Last Changed Rev' : '7'
166           tests/cmdline/upgrade_tests.py:396:      'Last Changed Rev' : '10'
167
168           $ date
169           Wed Jul 28 06:40:03 EDT 2010
170
171           $ svn-bisect --min 0 start
172           $ svn-bisect after
173           Fetching history from r0 to r980012; it may take a while.
174           There are 24349 revs left in the pool.  Choosing r862045.
175
176           $ ack --nocolor --nogroup 'Last Changed Rev'
177           svn/info-cmd.c:348:    SVN_ERR(svn_cmdline_printf(pool, _("Last Changed Rev: %ld\n"),
178
179           $ svn-bisect after
180           There are 12174 revs left in the pool.  Choosing r845633.
181
182           $ ack --nocolor --nogroup 'Last Changed Rev'
183           clients/cmdline/info-cmd.c:153:    printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
184
185           $ svn-bisect after
186           There are 6087 revs left in the pool.  Choosing r840416.
187
188           $ ack --nocolor --nogroup 'Last Changed Rev'
189
190           $ svn-bisect before
191           There are 3043 revs left in the pool.  Choosing r842636.
192
193           # ack --nocolor --nogroup 'Last Changed Rev'
194           clients/cmdline/info-cmd.c:153:    printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
195
196           $ svn-bisect after
197           There are 1521 revs left in the pool.  Choosing r841463.
198
199           $ ack --nocolor --nogroup 'Last Changed Rev'
200
201           $ svn-bisect before
202           There are 760 revs left in the pool.  Choosing r841993.
203
204           $ ack --nocolor --nogroup 'Last Changed Rev'
205           clients/cmdline/info-cmd.c:161:        printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
206
207           $ svn-bisect after
208           There are 380 revs left in the pool.  Choosing r841730.
209
210           $ ack --nocolor --nogroup 'Last Changed Rev'
211
212           $ svn-bisect before
213           There are 189 revs left in the pool.  Choosing r841860.
214
215           $ ack --nocolor --nogroup 'Last Changed Rev'
216
217           $ svn-bisect before
218           There are 94 revs left in the pool.  Choosing r841933.
219
220           $ ack --nocolor --nogroup 'Last Changed Rev'
221           clients/cmdline/info-cmd.c:151:        printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
222
223           $ svn-bisect after
224           There are 47 revs left in the pool.  Choosing r841904.
225
226           $ ack --nocolor --nogroup 'Last Changed Rev'
227           clients/cmdline/info-cmd.c:150:        printf ("Last Changed Rev: %ld\n", entry->cmt_rev);
228
229           $ svn-bisect after
230           There are 23 revs left in the pool.  Choosing r841880.
231
232           $ ack --nocolor --nogroup 'Last Changed Rev'
233
234           $ svn-bisect before
235           There are 11 revs left in the pool.  Choosing r841890.
236
237           $ ack --nocolor --nogroup 'Last Changed Rev'
238           clients/cmdline/info-cmd.c:153:            printf ("Last Changed Rev: %ld\n", entry->cmt_rev);
239
240           $ svn-bisect after
241           There are 5 revs left in the pool.  Choosing r841883.
242
243           $ ack --nocolor --nogroup 'Last Changed Rev'
244           clients/cmdline/info-cmd.c:153:            printf ("Last Changed Rev: %ld\n", entry->cmt_rev);
245
246           $ svn-bisect after
247           There are 2 revs left in the pool.  Choosing r841882.
248
249           $ ack --nocolor --nogroup 'Last Changed Rev'
250
251           $ svn-bisect before
252           This is the end of the road!
253           The change occurred in r841883.
254
255           $ svn log -r841883
256           ------------------------------------------------------------------------
257           r841883 | rooneg | 2002-04-27 15:23:38 -0400 (Sat, 27 Apr 2002) | 30 lines
258
259           As requested by cmpilato in issue #676, add an 'svn info' command, which
260           prints out the contents of the svn_wc_entry_t for a given versioned resource.
261
262           * CHANGES
263             note the addition of the 'svn info' command.
264
265           * subversion/clients/cmdline/cl.h
266             add declaration for svn_cl__info.
267
268           * subversion/clients/cmdline/info-cmd.c
269             new file implementing the info command.
270
271           * subversion/clients/cmdline/main.c
272             hook up the info command.
273
274           * subversion/clients/cmdline/man/svn.1
275             document the info command.
276
277           * subversion/tests/clients/cmdline/getopt_tests_data/svn--help_stdout
278             update for the addition of info command.
279
280           * subversion/tests/clients/cmdline/getopt_tests_data/svn_help_stdout
281             ditto.
282
283           * subversion/tests/clients/cmdline/getopt_tests_data/svn_stderr
284             ditto.
285
286           * tools/dev/bash_completion
287             add 'info' to the tab completion.
288
289           ------------------------------------------------------------------------
290
291           $ date
292           Wed Jul 28 06:45:27 EDT 2010
293
294       So, there it is.  In 5 minutes, we've learned that "Last Changed Rev:"
295       has been in there since the inception of the "svn info" command itself,
296       back in 2002.
297
298       You can also provide a script command to do all of the work for you:
299
300           $ svn-bisect --min 0 --max 980012 start
301           $ svn-bisect run '! grep -r "Last Changed Rev" .'
302

REQUIREMENTS

304       This tool requires:
305
306       * A computer
307
308       * A brain
309
310       * An installation of Perl, version 5.8 or above
311
312       * The IO::All module, installed from CPAN
313
314       * The YAML::Syck module, installed from CPAN
315
316       * The "svn" command somewhere in your PATH, executable by the current
317       user
318
319       * A svn checkout with some history to bisect.
320

AUTHOR

322           Mark Glines <mark-cpan@glines.org>
323

REPOSITORY

325       Browser: <http://github.com/Infinoid/svn-bisect/> Clone:
326       <git://github.com/Infinoid/svn-bisect.git>
327

THANKS

329       * Thanks to the git-bisect author(s), for coming up with a user
330       interface that
331         I actually like.
332
333       * Thanks to Will Coleda for inspiring me to actually write and release
334       this.
335
336       * Thanks to the Parrot project for having so much random stuff going on
337       as to
338         make a tool like this necessary.
339

SEE ALSO

341       App::SVNBinarySearch by Will Coleda:
342       <http://search.cpan.org/dist/App-SVNBinarySearch/>
343
345       This software is copyright (c) 2008 Mark Glines.
346
347       It is distributed under the terms of the Artistic License 2.0.  For
348       details, see the "LICENSE" file packaged alongside this tool.
349
350
351
352perl v5.34.0                      2022-01-20                     SVN-BISECT(1)
Impressum