From: Junio C Hamano Date: Wed, 25 Apr 2018 04:28:56 +0000 (+0900) Subject: Merge branch 'ak/bisect-doc-typofix' X-Git-Tag: v2.18.0-rc0~122 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/f2d5e076674cccbe83d7f069201ec23608726650?hp=-c Merge branch 'ak/bisect-doc-typofix' Docfix. * ak/bisect-doc-typofix: Documentation/git-bisect.txt: git bisect term → git bisect terms --- f2d5e076674cccbe83d7f069201ec23608726650 diff --combined Documentation/git-bisect.txt index 4a1417bdcd,0b305a6c21..4b45d837a7 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@@ -16,14 -16,13 +16,14 @@@ DESCRIPTIO The command takes various subcommands, and different options depending on the subcommand: - git bisect start [--no-checkout] [ [...]] [--] [...] - git bisect (bad|new) [] - git bisect (good|old) [...] + git bisect start [--term-{old,good}= --term-{new,bad}=] + [--no-checkout] [ [...]] [--] [...] + git bisect (bad|new|) [] + git bisect (good|old|) [...] git bisect terms [--term-good | --term-bad] git bisect skip [(|)...] git bisect reset [] - git bisect visualize + git bisect (visualize|view) git bisect replay git bisect log git bisect run ... @@@ -42,7 -41,7 +42,7 @@@ In fact, `git bisect` can be used to fi *any* property of your project; e.g., the commit that fixed a bug, or the commit that caused a benchmark's performance to improve. To support this more general usage, the terms "old" and "new" can be used -in place of "good" and "bad". See +in place of "good" and "bad", or you can choose your own terms. See section "Alternate terms" below for more information. Basic bisect commands: start, bad, good @@@ -137,7 -136,7 +137,7 @@@ respectively, in place of "good" and "b mix "good" and "bad" with "old" and "new" in a single session.) In this more general usage, you provide `git bisect` with a "new" -commit has some property and an "old" commit that doesn't have that +commit that has some property and an "old" commit that doesn't have that property. Each time `git bisect` checks out a commit, you test if that commit has the property. If it does, mark the commit as "new"; otherwise, mark it as "old". When the bisection is done, `git bisect` @@@ -165,51 -164,27 +165,51 @@@ To get a reminder of the currently use git bisect terms ------------------------------------------------ - You can get just the old (respectively new) term with `git bisect term - --term-old` or `git bisect term --term-good`. + You can get just the old (respectively new) term with `git bisect terms + --term-old` or `git bisect terms --term-good`. -Bisect visualize -~~~~~~~~~~~~~~~~ +If you would like to use your own terms instead of "bad"/"good" or +"new"/"old", you can choose any names you like (except existing bisect +subcommands like `reset`, `start`, ...) by starting the +bisection using + +------------------------------------------------ +git bisect start --term-old --term-new +------------------------------------------------ + +For example, if you are looking for a commit that introduced a +performance regression, you might use + +------------------------------------------------ +git bisect start --term-old fast --term-new slow +------------------------------------------------ + +Or if you are looking for the commit that fixed a bug, you might use + +------------------------------------------------ +git bisect start --term-new fixed --term-old broken +------------------------------------------------ + +Then, use `git bisect ` and `git bisect ` instead +of `git bisect good` and `git bisect bad` to mark commits. + +Bisect visualize/view +~~~~~~~~~~~~~~~~~~~~~ To see the currently remaining suspects in 'gitk', issue the following -command during the bisection process: +command during the bisection process (the subcommand `view` can be used +as an alternative to `visualize`): ------------ $ git bisect visualize ------------ -`view` may also be used as a synonym for `visualize`. - -If the 'DISPLAY' environment variable is not set, 'git log' is used +If the `DISPLAY` environment variable is not set, 'git log' is used instead. You can also give command-line options such as `-p` and `--stat`. ------------ -$ git bisect view --stat +$ git bisect visualize --stat ------------ Bisect log and bisect replay @@@ -255,7 -230,7 +255,7 @@@ Then compile and test the chosen revisi the revision as good or bad in the usual manner. Bisect skip -~~~~~~~~~~~~ +~~~~~~~~~~~ Instead of choosing a nearby commit by yourself, you can ask Git to do it for you by issuing the command: @@@ -334,7 -309,7 +334,7 @@@ cannot be tested. If the script exits w revision will be skipped (see `git bisect skip` above). 125 was chosen as the highest sensible value to use for this purpose, because 126 and 127 are used by POSIX shells to signal specific error status (127 is for -command not found, 126 is for command found but not executable---these +command not found, 126 is for command found but not executable--these details do not matter, as they are normal errors in the script, as far as `bisect run` is concerned). @@@ -357,7 -332,7 +357,7 @@@ OPTION --no-checkout:: + Do not checkout the new working tree at each iteration of the bisection -process. Instead just update a special reference named 'BISECT_HEAD' to make +process. Instead just update a special reference named `BISECT_HEAD` to make it point to the commit that should be tested. + This option may be useful when the test you would perform in each step @@@ -475,13 -450,6 +475,13 @@@ $ git bisect star $ git bisect new HEAD # current commit is marked as new $ git bisect old HEAD~10 # the tenth commit from now is marked as old ------------ ++ +or: +------------ +$ git bisect start --term-old broken --term-new fixed +$ git bisect fixed +$ git bisect broken HEAD~10 +------------ Getting help ~~~~~~~~~~~~