The syntax commonly used for alternatives is --opt-(a|b), not
--opt-{a,b}.
List bad/new and good/old consistently in this order, to be
consistent with the description for "git bisect terms". Clarify
<term> to either <term-old> or <term-new> to make them consistent
with the description of "git bisect (good|bad)" subcommands.
Suggested-by: Matthieu Moy <git@matthieu-moy.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation for "git bisect terms", although it did not hide
any information, was a bit incomplete and forced readers to fill in
the blanks to get the complete picture.
Acked-by: Matthieu Moy <git@matthieu-moy.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This is more correct because the <path>... doc syntax already indicates
that the arg is "array-type". It's how other tools do it. Finally, the
later document text mentions 'path' arguments, while it doesn't mention
'paths'.
Signed-off-by: Britton Leo Kerin <britton.kergin@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The description of "git bisect --no-checkout" called BISECT_HEAD a
"special ref", but there is nothing special about it. It merely is
yet another pseudoref.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The description of the `git bisect run` command syntax at the beginning
of the manpage is `git bisect run <cmd>...`, which isn't quite clear
about what `<cmd>` is or what the `...` mean; one could think that it is
the whole (quoted) command line with all arguments in a single string,
or that it supports multiple commands, or that it doesn't accept
commands with arguments at all.
Change to `git bisect run <cmd> [<arg>...]` to clarify the syntax,
in both the manpage and the `git bisect -h` command output.
Additionally, change `--term-{new,bad}` et al to `--term-(new|bad)`
for consistency with the synopsis syntax conventions.
Signed-off-by: Javier Mora <cousteaulecommandant@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This check has involved more environment variables than just `DISPLAY` since
508e84a790 (bisect view: check for MinGW32 and MacOSX in addition to X11,
2008-02-14), so let's update the documentation accordingly.
Signed-off-by: Matthias Aßhauer <mha1993@live.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The positional arguments are specified in this order: "bad" then "good".
To avoid confusion, the options above the positional arguments
are now specified in the same order. They can still be specified in any
order since they're options, not positional arguments.
Signed-off-by: Hugo Locurcio <hugo.locurcio@hugo.pro>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Upon seeing a merge commit when bisecting, this option may be used to
follow only the first parent.
In detecting regressions introduced through the merging of a branch, the
merge commit will be identified as introduction of the bug and its
ancestors will be ignored.
This option is particularly useful in avoiding false positives when a
merged branch contained broken or non-buildable commits, but the merge
itself was OK.
Signed-off-by: Aaron Lipman <alipman88@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The hotfix application example uses `git merge --no-commit` to apply
temporary changes to the working tree during a bisect operation. In some
situations this can be a fast-forward and `merge` will apply the hotfix
branch's commits regardless of `--no-commit` (as documented in the `git
merge` manual).
In the pathological case this will make a `git bisect run` invocation
loop indefinitely between the first bisect step and the fast-forwarded
post-merge HEAD.
Add `--no-ff` to the merge command to avoid this issue.
Signed-off-by: Mihail Atanassov <m.atanassov92@gmail.com>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Tweak a small number of files to mention "view" as an alternative to
"visualize".
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The following part of the description:
git bisect (bad|new) [<rev>]
git bisect (good|old) [<rev>...]
may be a bit confusing, as a reader may wonder if instead it should be:
git bisect (bad|good) [<rev>]
git bisect (old|new) [<rev>...]
Of course the difference between "[<rev>]" and "[<rev>...]" should hint
that there is a good reason for the way it is.
But we can further clarify and complete the description by adding
"<term-new>" and "<term-old>" to the "bad|new" and "good|old"
alternatives.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This is an application of the newly added CodingGuidelines to HEAD and
variants like FETCH_HEAD. It was obtained with:
perl -pi -e "s/'([A-Z_]*HEAD)'/\`\$1\`/g" *.txt
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Wrap with backticks (monospaced font) unwrapped or single-quotes wrapped
(italic type) environment variables which are followed by the word
"environment". It was obtained with:
perl -pi -e "s/\'?(\\\$?[0-9A-Z\_]+)\'?(?= environment ?)/\`\1\`/g" *.txt
One of the main purposes is to stick to the CodingGuidelines as possible so
that people writting new documentation by mimicking the existing are more likely
to have it right (even if they didn't read the CodingGuidelines).
Signed-off-by: Tom Russello <tom.russello@grenoble-inp.org>
Signed-off-by: Erwan Mathoniere <erwan.mathoniere@grenoble-inp.org>
Signed-off-by: Samuel Groot <samuel.groot@grenoble-inp.org>
Signed-off-by: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Reviewed-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
AsciiDoc markup fixes.
* xf/user-manual-markup:
Documentation: match undefline with the text in old release notes
Documentation: match underline with the text
Documentation: fix header markup
Again, we do not usually process release notes with AsciiDoc, but it
is better to be consistent.
This incidentally reveals breakages left by an ancient 5e00439f
(Documentation: build html for all files in technical and howto,
2012-10-23). The index-format documentation was originally written
to be read as straight text without formatting and when the commit
forced everything in Documentation/ to go through AsciiDoc, it did
not do any adjustment--hence the double-dashes will be seen in the
resulting text that is rendered as preformatted fixed-width without
converted into em-dashes.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Even though AsciiDoc is more lenient when deciding if an underline
is for the contents on the previous line to find section headers, we
should match the length of them for other formatters to help them.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This allows a natural user-interface when looking for any change in the
code, not just regression. For example:
git bisect start --term-old fast --term-new slow
git bisect fast
git bisect slow
...
There were several proposed user-interfaces for this feature. This patch
implements it as options to 'git bisect start' for the following reasons:
* By construction, the terms will be valid for one and only one
bisection.
* Unlike positional arguments, using named options avoid having to
remember an order.
* We can combine user-defined terms and passing old/new commits as
argument to "git bisect start".
* The implementation is relatively simple.
See previous discussions:
http://mid.gmane.org/1435337896-20709-3-git-send-email-Matthieu.Moy@imag.fr
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
When not looking for a regression during a bisect but for a fix or a
change in another given property, it can be confusing to use 'good'
and 'bad'.
This patch introduce `git bisect new` and `git bisect old` as an
alternative to 'bad' and good': the commits which have a certain
property must be marked as `new` and the ones which do not as `old`.
The output will be the first commit after the change in the property.
During a new/old bisect session you cannot use bad/good commands and
vice-versa.
Some commands are still not available for old/new:
* git rev-list --bisect does not treat the revs/bisect/new and
revs/bisect/old-SHA1 files.
Old discussions:
- http://thread.gmane.org/gmane.comp.version-control.git/86063
introduced bisect fix unfixed to find fix.
- http://thread.gmane.org/gmane.comp.version-control.git/182398
discussion around bisect yes/no or old/new.
- http://thread.gmane.org/gmane.comp.version-control.git/199758
last discussion and reviews
New discussions:
- http://thread.gmane.org/gmane.comp.version-control.git/271320
( v2 1/7-4/7 )
- http://comments.gmane.org/gmane.comp.version-control.git/271343
( v2 5/7-7/7 )
Signed-off-by: Antoine Delaite <antoine.delaite@ensimag.grenoble-inp.fr>
Signed-off-by: Louis Stuber <stuberl@ensimag.grenoble-inp.fr>
Signed-off-by: Valentin Duperray <Valentin.Duperray@ensimag.imag.fr>
Signed-off-by: Franck Jonas <Franck.Jonas@ensimag.imag.fr>
Signed-off-by: Lucien Kong <Lucien.Kong@ensimag.imag.fr>
Signed-off-by: Thomas Nguy <Thomas.Nguy@ensimag.imag.fr>
Signed-off-by: Huynh Khoi Nguyen Nguyen <Huynh-Khoi-Nguyen.Nguyen@ensimag.imag.fr>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thoroughly revise the "git bisect" manpage, including:
* Beef up the "Description" section.
* Make the first long example less specific to kernel development.
* De-emphasize implementation details in a couple of places.
* Add "(roughly N steps)" in the places where example output is shown.
* Properly markup code within the prose.
* Lots of wordsmithing.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"reset" can be easily misunderstood as resetting a bisect session to its
start without finishing it. Clarify that it actually quits the bisect
session.
Reported-by: Andreas Mohr <andi@lisas.de>
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This enhances the support for bisecting history in bare repositories.
The "git bisect" command no longer needs to be run inside a repository
with a working tree; it defaults to --no-checkout when run in a bare
repository.
Two tests are included to demonstrate this behaviour.
Suggested-by: Junio C Hamano <gitster@pobox.com>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Jon Seymour <jon.seymour@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The SYNOPSIS sections of most commands that span several lines already
use [verse] to retain line breaks. Most commands that don't span
several lines seem not to use [verse]. In the HTML output, [verse]
does not only preserve line breaks, but also makes the section
indented, which causes a slight inconsistency between commands that
use [verse] and those that don't. Use [verse] in all SYNOPSIS sections
for consistency.
Also remove the blank lines from git-fetch.txt and git-rebase.txt to
align with the other man pages. In the case of git-rebase.txt, which
already uses [verse], the blank line makes the [verse] not apply to
the last line, so removing the blank line also makes the formatting
within the document more consistent.
While at it, add single quotes to 'git cvsimport' for consistency with
other commands.
Signed-off-by: Martin von Zweigbergk <martin.von.zweigbergk@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Give an example on how to bisect when older revisions need a hot-fix to
build, run or test. Triggered by the binutils/kernel issue at
http://thread.gmane.org/gmane.comp.gnu.binutils/52601/focus=1112779
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Streamline the presentation of "bisect run" by removing one example
which does not introduce new concepts.
Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The point of these sections is generally to:
1. Give credit where it is due.
2. Give the reader an idea of where to ask questions or
file bug reports.
But they don't do a good job of either case. For (1), they
are out of date and incomplete. A much more accurate answer
can be gotten through shortlog or blame. For (2), the
correct contact point is generally git@vger, and even if you
wanted to cc the contact point, the out-of-date and
incomplete fields mean you're likely sending to somebody
useless.
So let's drop the fields entirely from all manpages except
git(1) itself. We already point people to the mailing list
for bug reports there, and we can update the Authors section
to give credit to the major contributors and point to
shortlog and blame for more information.
Each page has a "This is part of git" footer, so people can
follow that to the main git manpage.
This patch adds an asciidoc version of the "Fighting regressions with
git bisect" article that the author wrote for the Linux-Kongress
2009 (http://www.linux-kongress.org/2009).
This paper might be interesting to people who want to learn as much as
possible about "git bisect" from a single document.
The slides of the related presentation are available at:
http://www.linux-kongress.org/2009/slides/fighting_regressions_with_git_bisect_christian_couder.pdf
But the Linux Kongress people will not publish this paper online because
they print the papers on their UpTimes magazine
(http://www.lob.de/isbn/978-3-86541-358-1). But they don't take away the
rights of the author (which is very nice), so I have the right to publish
it.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
‘git bisect reset’ accepts an optional argument specifying a branch to
check out after cleaning up the bisection state. This lets you
specify an arbitrary commit.
In particular, this provides a way to clean the bisection state
without moving HEAD: ‘git bisect reset HEAD’. This may be useful if
you are not interested in the state before you began a bisect,
especially if checking out the old commit would be expensive and
invalidate most of your compiled tree.
Clarify the ‘git bisect reset’ documentation to explain this optional
argument, which was previously mentioned only in the usage message.
Signed-off-by: Anders Kaseorg <andersk@mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This warning was probably useless anyway, but it is even more so now
that filtering of skipped commits is done in C and that there is a
mechanism to skip away from broken commits.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* dm/maint-docco:
Documentation: Remove spurious uses of "you" in git-bisect.txt.
Documentation: minor grammatical fix in git-check-ref-format.txt
Documentation: minor grammatical fixes in git-check-attr.txt
Documentation: minor grammatical fixes in git-cat-file.txt
Documentation: minor grammatical fixes and rewording in git-bundle.txt
Documentation: remove some uses of the passive voice in git-bisect.txt
These were added by accident in a42dea3.
This patch also rewords the description of how ranges of commits can be
skipped.
Signed-off-by: David J. Mellor <dmellor@whistlingcat.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* dm/maint-docco:
Documentation: reword example text in git-bisect.txt.
Documentation: reworded the "Description" section of git-bisect.txt.
Documentation: minor grammatical fixes in git-branch.txt.
Documentation: minor grammatical fixes in git-blame.txt.
Documentation: reword the "Description" section of git-bisect.txt.
Documentation: minor grammatical fixes in git-archive.txt.
Avoid splitting sentences across examples of command usage.
Signed-off-by: David J. Mellor <dmellor@whistlingcat.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
