bisect

NAME名

git-bisect - Use binary search to find the commit that introduced a buggit-bisect - バイナリ検索を使ってバグを引き起こしたコミットを見つける

SYNOPSIS概要

git bisect <subcommand> <options>

DESCRIPTION説明

The command takes various subcommands, and different options depending on the subcommand:このコマンドはさまざまなサブコマンドと、サブコマンドに応じて異なるオプションを取ります。

git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>]
	  [--no-checkout] [<bad> [<good>...]] [--] [<paths>...]
git bisect (bad|new|<term-new>) [<rev>]
git bisect (good|old|<term-old>) [<rev>...]
git bisect terms [--term-good | --term-bad]
git bisect skip [(<rev>|<range>)...]
git bisect reset [<commit>]
git bisect (visualize|view)
git bisect replay <logfile>
git bisect log
git bisect run <cmd>...
git bisect help

This command uses a binary search algorithm to find which commit in your project’s history introduced a bug. You use it by first telling it a "bad" commit that is known to contain the bug, and a "good" commit that is known to be before the bug was introduced. Then git bisect picks a commit between those two endpoints and asks you whether the selected commit is "good" or "bad". It continues narrowing down the range until it finds the exact commit that introduced the change.このコマンドはバイナリ検索アルゴリズムを使用して、プロジェクトの履歴のどのコミットがバグを引き起こしたかを見つけます。あなたは最初にそれにバグを含むことが知られている「悪い」コミットと、バグが導入される前に知られている「良い」コミットをそれに伝えることによってそれを使います。次にgit bisect、これら2つのエンドポイント間のコミットを選択し、選択したコミットが「良い」か「悪い」かを尋ねます。変更を導入した正確なコミットが見つかるまで範囲を狭め続けます。

In fact, git bisect can be used to find the commit that changed 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", or you can choose your own terms. See section "Alternate terms" below for more information.実際にgit bisectは、あなたのプロジェクトのあらゆる特性を変更したコミットを見つけるために使用することができます。たとえば、バグを修正したコミット、ベンチマークのパフォーマンスを向上させたコミットなどです。このより一般的な用法をサポートするために、 "良い"と "悪い"の代わりに "古い"と "新しい"という用語を使用することも、独自の用語を選択することもできます。詳細については、下記の「代替用語」のセクションを参照してください。

Basic bisect commands: start, bad, good基本的な二等分コマンド：start、bad、good

As an example, suppose you are trying to find the commit that broke a feature that was known to work in version v2.6.13-rc2 of your project. You start a bisect session as follows:例として、あなたがv2.6.13-rc2自分のプロジェクトのバージョンで機能することが知られている機能を壊したコミットを見つけようとしているとしましょう。次のようにして二等分セッションを開始します。

$ git bisect start
$ git bisect bad                 # Current version is bad
$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good

Once you have specified at least one bad and one good commit, git bisect selects a commit in the middle of that range of history, checks it out, and outputs something similar to the following:少なくとも1つの悪いコミットと1つの良いコミットを指定したらgit bisect、その範囲の履歴の真ん中にあるコミットを選択し、それをチェックアウトして、次のような内容を出力します。

Bisecting: 675 revisions left to test after this (roughly 10 steps)

You should now compile the checked-out version and test it. If that version works correctly, typeチェックアウトしたバージョンをコンパイルしてテストします。そのバージョンが正しく動作するならば、タイプする

$ git bisect good

If that version is broken, typeそのバージョンが壊れているなら、

$ git bisect bad

Then git bisect will respond with something likeその後git bisect、のようなもので応答します

Bisecting: 337 revisions left to test after this (roughly 9 steps)

Keep repeating the process: compile the tree, test it, and depending on whether it is good or bad run git bisect good or git bisect bad to ask for the next commit that needs testing.プロセスを繰り返し続けます。ツリーをコンパイルし、テストします。それが実行の良否に応じて、git bisect goodまたはgit bisect badテストが必要な次のコミットを要求するために行います。

Eventually there will be no more revisions left to inspect, and the command will print out a description of the first bad commit. The reference refs/bisect/bad will be left pointing at that commit.最終的には検査するリビジョンはもうなくなり、コマンドは最初の悪いコミットの説明を表示します。参照refs/bisect/badはそのコミットを指し示したままになります。

Bisect reset二分リセット

After a bisect session, to clean up the bisection state and return to the original HEAD, issue the following command:二分セッションの後、二分状態をクリーンアップして元のHEADに戻るには、次のコマンドを発行します。

$ git bisect reset

By default, this will return your tree to the commit that was checked out before git bisect start. (A new git bisect start will also do that, as it cleans up the old bisection state.)デフォルトでは、これはあなたのツリーを以前にチェックアウトされたコミットに戻しますgit bisect start。（git bisect startそれは古い二分状態をきれいにするので、新しいこともそうするでしょう。）

With an optional argument, you can return to a different commit instead:オプションの引数を使用すると、代わりに別のコミットに戻ることができます。

$ git bisect reset <commit>

For example, git bisect reset bisect/bad will check out the first bad revision, while git bisect reset HEAD will leave you on the current bisection commit and avoid switching commits at all.たとえばgit bisect reset bisect/bad、最初の悪いリビジョンをチェックアウトしgit bisect reset HEADますが、現在の二分コミットをそのままにしてコミットの切り替えをまったく避けます。

Alternate terms代替用語

Sometimes you are not looking for the commit that introduced a breakage, but rather for a commit that caused a change between some other "old" state and "new" state. For example, you might be looking for the commit that introduced a particular fix. Or you might be looking for the first commit in which the source-code filenames were finally all converted to your company’s naming standard. Or whatever.時には、破損を引き起こしたコミットを探しているのではなく、他の「古い」状態と「新しい」状態の間の変更を引き起こしたコミットを探しているのです。たとえば、特定の修正を導入したコミットを探しているかもしれません。あるいは、ソースコードのファイル名がついにあなたの会社の命名基準に変換された最初のコミットを探しているかもしれません。それとも何でも。

In such cases it can be very confusing to use the terms "good" and "bad" to refer to "the state before the change" and "the state after the change". So instead, you can use the terms "old" and "new", respectively, in place of "good" and "bad". (But note that you cannot mix "good" and "bad" with "old" and "new" in a single session.)そのような場合、「変更前の状態」と「変更後の状態」を指すために「良い」と「悪い」という用語を使用することは非常に混乱を招く可能性があります。その代わりに、「良い」と「悪い」の代わりに、それぞれ「古い」と「新しい」という用語を使用できます。（ただし、1回のセッションで、「良い」と「悪い」を「古い」と「新しい」と混同することはできません。）

In this more general usage, you provide git bisect with a "new" 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 will report which commit introduced the property.このより一般的な使用法でgit bisectは、何らかのプロパティを持つ「新しい」コミットと、そのプロパティを持たない「古い」コミットを用意します。git bisectコミットをチェックアウトするたびに、そのコミットにプロパティがあるかどうかをテストします。もしそうなら、コミットを "new"としてマークします。それ以外の場合は、「old」としてマークします。二分されたとき、git bisectどのコミットが財産を導入したかを報告するでしょう。

To use "old" and "new" instead of "good" and bad, you must run git bisect start without commits as argument and then run the following commands to add the commits:"good"と "bad"の代わりに "old"と "new"を使用するgit bisect startには、引数としてコミットなしで実行してから、次のコマンドを実行してコミットを追加する必要があります。

git bisect old [<rev>]

to indicate that a commit was before the sought change, orコミットが求められている変更の前であったことを示すため

git bisect new [<rev>...]

to indicate that it was after.それが後であったことを示すために。

To get a reminder of the currently used terms, use現在使用されている用語を思い出すには、

git bisect terms

You can get just the old (respectively new) term with git bisect terms --term-old or git bisect terms --term-good.git bisect terms --term-oldまたはを使って、古い（それぞれ新しい）用語を取得できますgit bisect terms --term-good。

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あなたの代わりに「悪い」/「良い」または「新しい」/「古い」の独自の用語を使用したい場合は、（のような既存の二等分サブコマンドを除いて、好きな名前を選択することができreset、start使用して二等分を開始することにより、...）

git bisect start --term-old <term-old> --term-new <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 <term-old> and git bisect <term-new> instead of git bisect good and git bisect bad to mark commits.次に、git bisect <term-old>とのgit bisect <term-new>代わりにgit bisect goodand git bisect badを使用してコミットをマークします。

Bisect visualize/view二分して可視化/表示

To see the currently remaining suspects in gitk, issue the following command during the bisection process (the subcommand view can be used as an alternative to visualize):gitkで現在残っている容疑者を見るには、二等分プロセス中に次のコマンドを発行します（サブコマンドviewはその代わりに使用することができますvisualize）。

$ git bisect visualize

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.DISPLAY環境変数が設定されていない場合は、代わりにgit logが使用されます。-pやなどのコマンドラインオプションを指定することもできます--stat。

$ git bisect visualize --stat

Bisect log and bisect replayログを二分して再生する

After having marked revisions as good or bad, issue the following command to show what has been done so far:リビジョンをgoodまたはbadとしてマークした後、以下のコマンドを発行してこれまでに行われたことを表示します。

$ git bisect log

If you discover that you made a mistake in specifying the status of a revision, you can save the output of this command to a file, edit it to remove the incorrect entries, and then issue the following commands to return to a corrected state:リビジョンのステータスを誤って指定したことがわかった場合は、このコマンドの出力をファイルに保存し、それを編集して誤ったエントリを削除してから、次のコマンドを発行して修正済みの状態に戻すことができます。

$ git bisect reset
$ git bisect replay that-file

Avoiding testing a commitコミットをテストしない

If, in the middle of a bisect session, you know that the suggested revision is not a good one to test (e.g. it fails to build and you know that the failure does not have anything to do with the bug you are chasing), you can manually select a nearby commit and test that one instead.二分されたセッションの最中に、提案されたリビジョンがテストに適したものではないことを知っているなら（例えばそれはビルドに失敗し、失敗はあなたが追いかけているバグとは関係ない）。手動で近くのコミットを選択し、代わりにそれをテストすることができます。

For example:例えば：

$ git bisect good/bad			# previous round was good or bad.
Bisecting: 337 revisions left to test after this (roughly 9 steps)
$ git bisect visualize			# oops, that is uninteresting.
$ git reset --hard HEAD~3		# try 3 revisions before what
					# was suggested

Then compile and test the chosen revision, and afterwards mark the revision as good or bad in the usual manner.その後、選択したリビジョンをコンパイルしてテストし、その後は通常の方法でそのリビジョンをgoodまたはbadとしてマークします。

Bisect skip二分スキップ

Instead of choosing a nearby commit by yourself, you can ask Git to do it for you by issuing the command:自分で近くのコミットを選択する代わりに、次のコマンドを発行してGitにあなたに代わってコミットするように依頼できます。

$ git bisect skip                 # Current version cannot be tested

However, if you skip a commit adjacent to the one you are looking for, Git will be unable to tell exactly which of those commits was the first bad one.しかし、探しているコミットに隣接するコミットをスキップすると、Gitはそれらのコミットのどれが最初の悪いコミットであるかを正確に見分けることができません。

You can also skip a range of commits, instead of just one commit, using range notation. For example:範囲表記を使用して、1回のコミットではなく、一定範囲のコミットをスキップすることもできます。例えば：

$ git bisect skip v2.5..v2.6

This tells the bisect process that no commit after v2.5, up to and including v2.6, should be tested.これは、バイセクトプロセスに、それ以降v2.5も含めてコミットをv2.6テストしないように指示します。

Note that if you also want to skip the first commit of the range you would issue the command:範囲の最初のコミットもスキップしたい場合は、次のコマンドを発行します。

$ git bisect skip v2.5 v2.5..v2.6

This tells the bisect process that the commits between v2.5 and v2.6 (inclusive) should be skipped.これは、コミット間で二分プロセス告げるv2.5とv2.6（包括的）をスキップする必要があります。

Cutting down bisection by giving more parameters to bisect start2分割開始にさらにパラメータを指定して2分割を削減

You can further cut down the number of trials, if you know what part of the tree is involved in the problem you are tracking down, by specifying path parameters when issuing the bisect start command:bisect startコマンドの発行時にパスパラメータを指定することで、追跡している問題にツリーのどの部分が関係しているかがわかっていれば、試行回数をさらに減らすことができます。

$ git bisect start -- arch/i386 include/asm-i386

If you know beforehand more than one good commit, you can narrow the bisect space down by specifying all of the good commits immediately after the bad commit when issuing the bisect start command:複数の適切なコミットを事前に知っている場合は、bisect start次のコマンドを発行するときに、不適切なコミットの直後にすべての適切なコミットを指定することによって、2分の1スペースを狭めることができます。

$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
                   # v2.6.20-rc6 is bad
                   # v2.6.20-rc4 and v2.6.20-rc1 are good

Bisect runバイセクトラン

If you have a script that can tell if the current source code is good or bad, you can bisect by issuing the command:現在のソースコードが正しいか悪いかを判断できるスクリプトがある場合は、次のコマンドを発行して二等分することができます。

$ git bisect run my_script arguments

Note that the script (my_script in the above example) should exit with code 0 if the current source code is good/old, and exit with a code between 1 and 127 (inclusive), except 125, if the current source code is bad/new.（my_script上記の例の）スクリプトは、現在のソースコードが古くなっている場合はコード0で終了し、現在のソースコードが正しくない場合は125を除き、1から127までのコードで終了します。。

Any other exit code will abort the bisect process. It should be noted that a program that terminates via exit(-1) leaves $? = 255, (see the exit(3) manual page), as the value is chopped with & 0377.他の終了コードは二等分処理を中止します。注意しなければならないのは、経由で終了するプログラムexit(-1)は$ を離れるということですか？= 255、（exit（3）のマニュアルページを参照）、値は切り落とされ& 0377ます。

The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current 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 details do not matter, as they are normal errors in the script, as far as bisect run is concerned).現在のソースコードをテストできない場合は、特別な終了コード125を使用してください。スクリプトがこのコードで終了すると、現在のリビジョンはスキップされます（git bisect skip上記参照）。126と127はPOSIXシェルで特定のエラーステータスを通知するために使用されるため（127はコマンドが見つかりませんが、126はコマンドが見つかりましたが実行可能ではありません。）問題は、スクリプト内の通常のエラーなので、bisect run関係している限り）。

You may often find that during a bisect session you want to have temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a header file, or "revision that does not have this commit needs this patch applied to work around another problem this bisection is not interested in") applied to the revision being tested.2分の1セッション中に一時的な変更（ヘッダファイルのs /＃define DEBUG 0 /＃define DEBUG 1 /など）が必要になることがよくあります。このコミットがないリビジョンにはこのパッチを適用する必要があります。この二分法が興味を持っていない別の問題は "）テストされているリビジョンに適用されます。

To cope with such a situation, after the inner git bisect finds the next revision to test, the script can apply the patch before compiling, run the real test, and afterwards decide if the revision (possibly with the needed patch) passed the test and then rewind the tree to the pristine state. Finally the script should exit with the status of the real test to let the git bisect run command loop determine the eventual outcome of the bisect session.このような状況に対処するために、内側のgit bisectがテストする次のリビジョンを見つけた後、スクリプトはコンパイル前にパッチを適用し、実際のテストを実行し、その後リビジョン（おそらく必要なパッチを含む）がテストにパスしたかどうかを判断できます。その後、ツリーを元の状態に巻き戻します。最後に、スクリプトは実際のテストのステータスで終了し、git bisect runコマンドループがバイセクトセッションの最終的な結果を判断できるようにします。

OPTIONSオプション

--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 it point to the commit that should be tested.二分法の各反復で新しい作業ツリーをチェックアウトしないでください。代わりBISECT_HEADに、テストされるべきコミットを指すようにという名前の特別な参照を更新するだけです。

This option may be useful when the test you would perform in each step does not require a checked out tree.このオプションは、各ステップで実行するテストにチェックアウト済みのツリーが不要な場合に便利です。

If the repository is bare, --no-checkout is assumed.リポジトリが裸であれば、とします--no-checkout。

EXAMPLES例

Automatically bisect a broken build between v1.2 and HEAD:壊れたビルドをv1.2とHEADの間で自動的に二分する：

$ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
$ git bisect run make                # "make" builds the app
$ git bisect reset                   # quit the bisect session

Automatically bisect a test failure between origin and HEAD:原点とHEADの間のテスト失敗を自動的に二分する：

$ git bisect start HEAD origin --    # HEAD is bad, origin is good
$ git bisect run make test           # "make test" builds and tests
$ git bisect reset                   # quit the bisect session

Automatically bisect a broken test case:壊れたテストケースを自動的に二分する：
```
$ cat ~/test.sh
#!/bin/sh
make || exit 125                     # this skips broken builds
~/check_test_case.sh                 # does the test case pass?
$ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
$ git bisect run ~/test.sh
$ git bisect reset                   # quit the bisect session
```
Here we use a test.sh custom script. In this script, if make fails, we skip the current commit. check_test_case.sh should exit 0 if the test case passes, and exit 1 otherwise.ここではtest.shカスタムスクリプトを使います。このスクリプトでは、make失敗した場合、現在のコミットをスキップします。check_test_case.shべきexit 0テストケースに合格した場合、およびexit 1そうでありません。

It is safer if both test.sh and check_test_case.sh are outside the repository to prevent interactions between the bisect, make and test processes and the scripts.両方の場合、それはより安全であるtest.shとcheck_test_case.shリポジトリの外にあるが、二分間の相互作用を防止するためのプロセスやスクリプトを作成し、テストします。
Automatically bisect with temporary modifications (hot-fix):一時的な変更で自動的に二分する（ホットフィックス）：
```
$ cat ~/test.sh
#!/bin/sh
# tweak the working tree by merging the hot-fix branch
# and then attempt a build
if	git merge --no-commit hot-fix &&
	make
then
	# run project specific test and report its status
	~/check_test_case.sh
	status=$?
else
	# tell the caller this is untestable
	status=125
fi
# undo the tweak to allow clean flipping to the next commit
git reset --hard
# return control
exit $status
```
This applies modifications from a hot-fix branch before each test run, e.g. in case your build or test environment changed so that older revisions may need a fix which newer ones have already. (Make sure the hot-fix branch is based off a commit which is contained in all revisions which you are bisecting, so that the merge does not pull in too much, or use git cherry-pick instead of git merge.)これは、各テスト実行の前にホットフィックスブランチからの修正を適用します。例えば、あなたのビルドやテスト環境が変更されたため、古いリビジョンには、新しいリビジョンの修正が必要になるかもしれません。（マージがあまり引き込まれないように、またはgit cherry-pick代わりに使用するように、ホットフィックスブランチが、二分しているすべてのリビジョンに含まれるコミットに基づいていることを確認してくださいgit merge。）
Automatically bisect a broken test case:壊れたテストケースを自動的に二分する：
```
$ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
$ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
$ git bisect reset                   # quit the bisect session
```
This shows that you can do without a run script if you write the test on a single line.これは、テストを単一行で記述すれば実行スクリプトがなくても実行できることを示しています。
Locate a good region of the object graph in a damaged repository破損したリポジトリでオブジェクトグラフの適切な領域を探します
```
$ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
$ git bisect run sh -c '
	GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
	git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
	git pack-objects --stdout >/dev/null <tmp.$$
	rc=$?
	rm -f tmp.$$
	test $rc = 0'
$ git bisect reset                   # quit the bisect session
```
In this case, when git bisect run finishes, bisect/bad will refer to a commit that has at least one parent whose reachable graph is fully traversable in the sense required by git pack objects.この場合、git bisectの実行が終了すると、bisect / badは、git packオブジェクトが要求する意味で到達可能グラフが完全にトラバース可能な少なくとも1つの親を持つコミットを参照します。

Look for a fix instead of a regression in the codeコードで回帰の代わりに修正を探す

$ git bisect start
$ 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助けを得る

Use git bisect to get a short usage description, and git bisect help or git bisect -h to get a long usage description.使用git bisect短い使用方法の説明を取得するために、およびgit bisect helpまたはgit bisect -h長い使用法の説明を取得します。

GIT

Part of the git[1] suite一部のgit [1]スイート