git-bz(1) Manual Page

git-bz is a tool for integrating the Git command line with the Bugzilla bug-tracking system. Operations such as attaching patches to bugs, applying patches in bugs to your current tree, and closing bugs once you’ve pushed the fixes publically can be done completely from the command line without having to go to your web browser.

Authentication for git-bz is done by reading the cookies for the Bugzilla host from your web browser. In order to do this, git-bz needs to know how to access the cookies for your web browser; git-bz currently is able to do this for Firefox, Epiphany, and Chromium on Linux.

Before getting started, you configure the default Bugzilla instance, product and component for your repository:

Someone has found a bug in your code, and filed bug 43215 in bugzilla.example.com. You’ve come up with a fix for that patch locally, but you want the bug reporter to test it, so you attach the change you made locally to the bug report as a patch:

This automatically rewrites the commit to add the URL of the bug to the commit message for future reference. The reporter finds some problems in testing, so you come up with a new version of the change and modify your commit using git command --amend. To attach the new version, you run:

You don’t have to specify the bug number this time since git-bz will find it in the commit message. The -e option (short for --edit) allows you to edit the comment for the bug to say what you’ve changed and pick patches to obsolete. Now everybody’s happy with the change. To push your changes and close the bug, you run:

This does git push, adds a comment that the commits were pushed and marks the patches committed. The changes it is making to the bug will be shown in your editor to give you a chance to confirm them and add extra comments if desired.

Other useful commands are git bz file to file a new bug rather than attaching patches to an existing one, git bz apply to apply patches from a bug to the current tree, and git bz edit to add comments to or close bug reports.

git bz add-url <bug reference> (<commit> | <revision range>)

For each specified commit, rewrite the commit message to add a reference to the given bug. You should only do this if you haven’t already pushed the commit publically. You won’t need this very often, since git bz file and git bz attach do this automatically. It might be useful if you want to record the bug information but don’t want to attach it immediately.

If the bug number is already found in the commit message, then does nothing.

Example:

The default behavior is to append the bug URL to the commit body. See the section “Add URL Method” below for how to change this.

git bz apply [-n | --no-add-url] <bug reference>

For each patch attachment (except for obsolete patches) of the specified bug, prompts whether to apply. If prompt is agreed to runs git am on the patch to apply it to the current branch. Aborts if git am fails to allow cleaning up conflicts.

Examples:

The commit messages will automatically be rewritten to include a reference to the bug (see git bz add-url). This can be suppressed with the -n/--no-add-url option.

git bz attach [-n | --no-add-url] [-e |--edit] <bug reference> [<commit> | <revision range>]

For each specified commit, formats as a patch and attaches to the specified bug, with the subject of the commit as the description and the body of the commit as the comment. The patch formatting is as for git format-patch. Unlike git format-patch, specifying a single commit means just that commit, not everything after that commit.

Prompts before actually doing anything to avoid mistakes.

The commit message will automatically be rewritten to include a reference to the bug (see git bz add-url). This can be suppressed with the -n/--no-add-url option.

Examples:

git bz edit (<bug reference> | <commit> | <revision range>) git bz edit --pushed (<commit> | <revision range>)

Allows doing common operations on a Bugzilla bug without going to your web browser. An editable buffer is brought up in a git-like fashion, where you can add comments, resolve a bug, and change the status of patches.

If the argument identifies a commit or commits rather than a bug then each bug referred to in the commits is edited in turn.

git bz file [-n | --no-add-url] [[<product>]/<component>] (<commit> | <revision range>)

Like attach, but files a new bug. Opens an editor for the user to enter the summary and description for the bug. If only a single commit is named, the summary defaults to the subject of the commit. The product and component must be specified unless you have configured defaults.

The commit message will automatically be rewritten to include a reference to the newly filed bug (see git bz add-url) before attaching the patch. This can be suppressed with the -n/--no-add-url option.

Examples:

git bz push [--fix] [<repository> <refspec>…]

Exactly like git push, but git bz edit --pushed is done for each bug referenced in the newly pushed commits.

Note that “newly pushed commit” are commits that were added to any existing branch by the push. Commits don’t have to be pushed to master to be considered newly pushed. However, commits pushed to newly created branches will be ignored.

In order to use git-bz you need to already be logged into the bug tracker in your web browser, and git-bz reads your browser cookie. Currently only Firefox 3 and Epiphany are supported, and only on Linux. Patches to add more support and to allow configuring username/password directly per bug tracker accepted.

Ways to refer to a bug:

You can configure git bz add-url, and the --add-url option of git bz [apply|attach|file] to add the URL different ways or to add a non-URL bug reference, using the git config variable bz.add-url-method.

It has the form

Method is:

Format supports the following escapes:

You can create short aliases for different bug trackers as follows

And you can set the default bug tracker with:

Setting the default tracker, product and component in the local config for a repository is useful. Assuming that a global gnome alias has been set up as above:

Note the absence of --global; configuring a default product and component globally is seldom useful.

git-bz needs some configuration specific to the bugzilla instance (tracker), in particular it needs to know initial field values to use when submitting bugs; legal values for some fields depend on the instance.

You can also set whether to use http or https by setting the https variabe For https, certificates are not checked so you are completely vulnerable to DNS spoofing and man-in-the-middle attacks. Blame httplib.

Configuration comes from 4 sources, in descending order of priority

In general, settings that are necessary to make a popular bugzilla instance work should be submitted back to me and go in the CONFIG variable.

Written by Owen Taylor <otaylor@fishsoup.net>.