svn-bisect(1)

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.collab.net/repos/svn/trunk/subversion
157           [snip lots of svn checkout spam]
158           Checked out revision 30958.
159
160           $ cd subversion
161
162           $ ack --nocolor --nogroup 'Last Changed Rev'
163           svn/info-cmd.c:351:    SVN_ERR(svn_cmdline_printf(pool, _("Last Changed Rev: %ld\n"),
164
165           $ date
166           Fri May  2 12:52:20 PDT 2008
167
168           $ svn-bisect start
169           $ svn-bisect before 0
170           $ svn-bisect after
171           There are 13853 revs left in the pool.  Choosing r15480.
172
173           $ ack --nocolor --nogroup 'Last Changed Rev'
174           clients/cmdline/info-cmd.c:137:    SVN_ERR (svn_cmdline_printf (pool, _("Last Changed Rev: %ld\n"),
175
176           $ svn-bisect after
177           There are 6926 revs left in the pool.  Choosing r6010.
178
179           $ ack --nocolor --nogroup 'Last Changed Rev'
180           clients/cmdline/info-cmd.c:158:    printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
181
182           $ svn-bisect after
183           There are 3463 revs left in the pool.  Choosing r2481.
184
185           $ ack --nocolor --nogroup 'Last Changed Rev'
186           clients/cmdline/info-cmd.c:153:    printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
187
188           $ svn-bisect after
189           There are 1731 revs left in the pool.  Choosing r1168.
190
191           $ ack --nocolor --nogroup 'Last Changed Rev'
192
193           $ svn-bisect before
194           There are 865 revs left in the pool.  Choosing r1800.
195
196           $ ack --nocolor --nogroup 'Last Changed Rev'
197
198           $ svn-bisect before
199           There are 432 revs left in the pool.  Choosing r2127.
200
201           $ ack --nocolor --nogroup 'Last Changed Rev'
202           clients/cmdline/info-cmd.c:161:        printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
203
204           $ svn-bisect after
205           There are 216 revs left in the pool.  Choosing r1961.
206
207           $ ack --nocolor --nogroup 'Last Changed Rev'
208           clients/cmdline/info-cmd.c:161:        printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
209
210           $ svn-bisect after
211           There are 108 revs left in the pool.  Choosing r1881.
212
213           $ ack --nocolor --nogroup 'Last Changed Rev'
214           clients/cmdline/info-cmd.c:161:        printf ("Last Changed Rev: %" SVN_REVNUM_T_FMT "\n", entry->cmt_rev);
215
216           $ svn-bisect after
217           There are 54 revs left in the pool.  Choosing r1845.
218
219           $ ack --nocolor --nogroup 'Last Changed Rev'
220           clients/cmdline/info-cmd.c:150:        printf ("Last Changed Rev: %ld\n", entry->cmt_rev);
221
222           $ svn-bisect after
223           There are 27 revs left in the pool.  Choosing r1827.
224
225           $ ack --nocolor --nogroup 'Last Changed Rev'
226           clients/cmdline/info-cmd.c:150:        printf ("Last Changed Rev: %ld\n", entry->cmt_rev);
227
228           $ svn-bisect after
229           There are 13 revs left in the pool.  Choosing r1809.
230
231           $ ack --nocolor --nogroup 'Last Changed Rev'
232           clients/cmdline/info-cmd.c:153:            printf ("Last Changed Rev: %ld\n", entry->cmt_rev);
233
234           $ svn-bisect after
235           There are 6 revs left in the pool.  Choosing r1806.
236
237           $ ack --nocolor --nogroup 'Last Changed Rev'
238
239           $ svn-bisect before
240           There are 2 revs left in the pool.  Choosing r1808.
241
242           $ ack --nocolor --nogroup 'Last Changed Rev'
243
244           $ svn-bisect before
245           This is the end of the road!  The change occurred in r1809.
246
247           $ svn log -r1809
248           ------------------------------------------------------------------------
249           r1809 | rooneg | 2002-04-27 12:23:38 -0700 (Sat, 27 Apr 2002) | 30 lines
250
251           As requested by cmpilato in issue #676, add an 'svn info' command, which
252           prints out the contents of the svn_wc_entry_t for a given versioned resource.
253
254           * CHANGES
255             note the addition of the 'svn info' command.
256
257           * subversion/clients/cmdline/cl.h
258             add declaration for svn_cl__info.
259
260           * subversion/clients/cmdline/info-cmd.c
261             new file implementing the info command.
262
263           * subversion/clients/cmdline/main.c
264             hook up the info command.
265
266           * subversion/clients/cmdline/man/svn.1
267             document the info command.
268
269           * subversion/tests/clients/cmdline/getopt_tests_data/svn--help_stdout
270             update for the addition of info command.
271
272           * subversion/tests/clients/cmdline/getopt_tests_data/svn_help_stdout
273             ditto.
274
275           * subversion/tests/clients/cmdline/getopt_tests_data/svn_stderr
276             ditto.
277
278           * tools/dev/bash_completion
279             add 'info' to the tab completion.
280
281           ------------------------------------------------------------------------
282
283           $ date
284           Fri May  2 12:56:00 PDT 2008
285
286       So, there it is.  In 4 minutes, we've learned that "Last Changed Rev:"
287       has been in there since the inception of the "svn info" command itself,
288       back in 2002.
289

REQUIREMENTS

291       This tool requires:
292
293       * A computer
294
295       * A brain
296
297       * An installation of Perl, version 5.8 or above
298
299       * The IO::All module, installed from CPAN
300
301       * The YAML::Syck module, installed from CPAN
302
303       * The "svn" command somewhere in your PATH, executable by the current
304       user
305
306       * A svn checkout with some history to bisect.
307

AUTHOR

309           Mark Glines <mark-cpan@glines.org>
310

REPOSITORY

312       Browser: http://github.com/Infinoid/svn-bisect/
313       <http://github.com/Infinoid/svn-bisect/> Clone:
314       git://github.com/Infinoid/svn-bisect.git
315       <git://github.com/Infinoid/svn-bisect.git>
316

THANKS

318       * Thanks to the git-bisect author(s), for coming up with a user
319       interface that
320         I actually like.
321
322       * Thanks to Will Coleda for inspiring me to actually write and release
323       this.
324
325       * Thanks to the Parrot project for having so much random stuff going on
326       as to
327         make a tool like this necessary.
328

COPYRIGHT AND LICENSE

335       This software is copyright (c) 2008 Mark Glines.
336
337       It is distributed under the terms of the Artistic License 2.0.  For
338       details, see the "LICENSE" file packaged alongside this tool.
339
340
341
342perl v5.12.1                      2010-06-26                     SVN-BISECT(1)