git: 4a04ef6034 - main - git: recommend git bisect start --first-parent

The branch main has been updated by imp:

URL: https://cgit.FreeBSD.org/doc/commit/?id=4a04ef603433e5dadeb78ee5d7f6aa1c07e4ae2f

commit 4a04ef603433e5dadeb78ee5d7f6aa1c07e4ae2f
Author:     Warner Losh <imp@FreeBSD.org>
AuthorDate: 2021-10-11 16:49:35 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2021-10-11 17:07:29 +0000

    git: recommend git bisect start --first-parent
    
    Due to how we do merge commits from the vendor branches, we don't want
    git bisect selecting those revisions as a bisection point. Recommend
    using 'git bisect start --first-parent' as a workaround.
    
    Sponsored by:           Netflix
---
 documentation/content/en/articles/committers-guide/_index.adoc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 231dfebaf7..d29fbf8c36 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -569,11 +569,12 @@ Here's a brief outline of how to use it.
 For more information, you can view https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination or https://git-scm.com/docs/git-bisect for more details.
 The man git-bisect page is good at describing what can go wrong, what to do when versions won't build, when you want to use terms other than 'good' and 'bad', etc, none of which will be covered here.
 
-`git bisect start` will start the bisection process.
+`git bisect start --first-parent` will start the bisection process.
 Next, you need to tell a range to go through.
 'git bisect good XXXXXX' will tell it the working version and 'git bisect bad XXXXX' will tell it the bad version.
 The bad version will almost always be HEAD (a special tag for what you have checked out).
 The good version will be the last one you checked out.
+The `--first-parent` argument is necessary so that subsequent `git bisect` commands do not try to check out a vendor branch which lacks the full FreeBSD source tree.
 
 [TIP]
 ====
@@ -593,7 +594,7 @@ Set the 'good' version first, then set the bad (though the order doesn't matter)
 When you set the bad version, it will give you some statistics on the process:
 [source,shell]
 ....
-% git bisect start
+% git bisect start --first-parent
 % git bisect good a8163e165c5b
 % git bisect bad HEAD
 Bisecting: 1722 revisions left to test after this (roughly 11 steps)