git-bz(1)
=========
NAME
----
git-bz - Command line integration of git with Bugzilla
SYNOPSIS
--------
[verse]
'git bz add-url' <bug reference> (<commit> | <revision range>)
'git bz apply' [-n | --no-add-url] <bug reference>
'git bz attach' [-n | --no-add-url] [-e |--edit] [<bug reference>] (<commit> | <revision range>)
'git bz edit' (<bug reference> | <commit> | <revision range>)
'git bz edit' (--pushed | --fix <bug reference) (<commit> | <revision range>)
'git bz file' [-n | --no-add-url] [[<product>]/<component>] (<commit> | <revision range>)
'git bz push' [--fix <bug reference>] [<repository> <refspec>...]
DESCRIPTION
------------
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.
EXAMPLE SESSION
---------------
Before getting started, you configure the default Bugzilla instance, product and
component for your repository:
----------------------------------------
git config bz.default-tracker bugzilla.example.com
git config bz.default-product TiddlyWinks
git config bz.default-component AI-Engine
----------------------------------------
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:
----------------------------------------
git bz attach 43215 HEAD
----------------------------------------
This automatically rewrites the commit to add the URL of the bug to the commit for
future reference. The reporter finds some problems in testing, so you come up
with a new up with a new version of the change and modify your commit using
'git command --amend'. To attach the new version, you run:
----------------------------------------
git bz attach -e HEAD
----------------------------------------
You don't have to specify the bug number this time since git-bz will
find it it in the bug. 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:
----------------------------------------
git bz push
----------------------------------------
This does 'git bz 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.
COMMON OPTIONS
--------------
-b;;
--bugzilla;;
Bug tracker to use. Used for 'git bz file' and to resolve bug references.
Generally, it's more useful to configure this with 'git config' instead.
See the section <<per-repository-configuration, ``Per-Repository Configuration''>>.
-u;;
--add-url;;
Rewrite commits to add the bug URL. (This is the default and will not normally
need to be specified.)
-n;;
--no-add-url;;
Don't rewrite commits to add the bug URL
COMMANDS
--------
add-url
~~~~~~~
'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:
----------------------------------------
# Add a bug URL to the last commit
git bz attach 1234 HEAD
----------------------------------------
The default behavior is to append the bug URL to the commit body. See the
section <<add-url-method, ``Add URL Method''>> below for how to change this.
apply
~~~~~
'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:
----------------------------------------
# Apply patches from the given bug
git bz apply bugzillla.gnome.org:1234
----------------------------------------
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.
attach
~~~~~~
'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.
-e;;
--edit;;
allow the user to edit the description and comment for each patch,
and (by uncommenting lines) obsolete old patches.
Examples:
----------------------------------------
# Attach the last commit
git bz attach bugzilla.gnome.org:1234 HEAD
# Attach everything starting at an old commit
git bz attach bugzilla.gnome.org:1234 b50ea9bd^..
----------------------------------------
edit
~~~~
'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.
--fix=<bug reference>;;
Treat the specified commits as a fix for the bug. Similar
to attaching the commits with 'git bz attach' then using
'git bz edit --pushed'.
--pushed;;
Attempt to automatically determine the correct comments, attachment
changes, and resolution for the bug from applying the specified commits
to the project's official repository. You'll have a chance to edit these
changes and add additional comments. See 'git bz push' for a convenient
interface to push commits and do this at the same time.
file
~~~~
'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:
----------------------------------------
# File the last commit as a new bug on the default tracker
git bz file my-product/some-component HEAD
# File a bug with a series of patches starting from an old commit
# on a different bug tracker
git bz -b bugs.freedesktop.org file my-product/some-component b50ea9bd^..
----------------------------------------
push
~~~~
'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.
--fix=<bug reference>;;
Treat the specified commits as a fix for the bug. Similar
to attaching the commits with 'git bz attach' before running
'git bz push'. This is in an-all-one-solution to use when you
have a fix that doesn't need any review or testing.
AUTHENTICATION
--------------
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.
BUG REFERENCES
--------------
Ways to refer to a bug:
<id>:: bug # on the default bug tracker
<host>:<id>:: bug # on the given host
<alias>:<id>:: bug # on the given bug tracker alias (see below)
<url>:: An URL of the form http://<hostname>/show_bug.cgi?id-<id>
[[add-url-method]]
ADD URL METHOD
--------------
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>:<format>
Method is:
subject-prepend:: prepend to the subject (separated with a space)
subject-append:: append to the subject (separated with a space)
body-prepend:: prepend to the body (separated with a blank line)
body-append:: append to the body (separated with a blank line)
Format supports the following escapes:
%u:: the bug URL
%d:: the bug #
%n:: a newline
%%:: a percent
----------------------------------------
# The default
git config bz.add-url-method body-append:%u
# 'Bug 34323 - Speed up frobnification'
git config bz.add-url-method subject-prepend:Bug %d -
----------------------------------------
ALIASES
-------
You can create short aliases for different bug trackers as follows
----------------------------------------
git config --global bz-tracker.gnome.host bugzilla.gnome.org
----------------------------------------
And you can set the default bug tracker with:
----------------------------------------
git config --global bz.default-tracker gnome
----------------------------------------
[[per-repository-configuration]]
PER-REPOSITORY CONFIGURATION
----------------------------
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:
----------------------------------------
git config bz.default-tracker gnome
git config bz.default-product gnome-shell
git config bz.default-component general
----------------------------------------
Note the absence of --global; configuring a default product and component
globally is seldom useful.
PER-TRACKER CONFIGURATION
-------------------------
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
1. git configuration variables specified for the alias.
+
----------------------------------------
git config --global bz-tracker.gnome.default-severity trivial
----------------------------------------
+
2. git configuration variables specified for the host
+
----------------------------------------
git config --global bz-tracker.bugzilla.gnome.org.default-severity trivial
----------------------------------------
+
3. Host specific configuration in the git-bz script, see the CONFIG variable.
+
4. Default configuration in the git-bz script, see the DEFAULT_CONFIG variable.
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.
Author
------
Written by Owen Taylor <otaylor@fishsoup.net>.
