path: root/git-bz.txt

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 apply' (--continue | --skip | --abort)
'git bz attach' [-n | --no-add-url] [-e |--edit] [<bug reference>] (<commit> | <revision range>)
'git bz components' [<product>]
'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 publicly can be done completely from the
command line without having to go to your web browser.

Authentication for git-bz can be 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, Galeon and Chromium on
Linux.

Alternatively, you can set the bz-user and bz-password in the
git config for each tracker.

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 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 commit --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 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:

----------------------------------------
git bz push
----------------------------------------

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.

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; you can change the default using the bz.add-url config
	variable.)

-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 publicly. 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
~~~~~

[verse]
'git bz apply' [-n | --no-add-url] <bug reference>
'git bz apply' (--continue | --skip | --abort)

Lists all "pending" patches on the specified bug (ie, the patches that
are not obsolete, committed, or rejected), and then prompts whether to
apply them. In addition to simply accepting or rejecting the list of
patches, you can also type "i" to interactively choose which patches
to apply, and in what order, as with 'git rebase -i'. If any patches
are selected, it runs 'git am' on each one to apply it to the current
branch. (If the bug contains patches in the form of plain diffs, 'git
bz apply' will create a commit based on the other patch metadata, and
prompt you for a commit message.)

If a 'git am' operation fails, 'git bz apply' will save its state and
then exit, at which point you can attempt to apply the patch by hand
and then resume with 'git bz apply --continue'; skip this patch but
continue applying the remaining patches with 'git bz apply --skip'; or
abort the operation and return to the original tree state with 'git bz
apply --abort'.

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.

When a commit with the same subject as an existing patch is attached,
this is interpreted as a new version of the existing patch and the old
patch is obsoleted. (With '-e', the obsoletes line can be commented
to suppress this.)

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^..
----------------------------------------

components
~~~~~~~~~~

'git bz components' [<product>]

Prints out the list of components for the given product (or the
default product if none is given on the command line).

edit
~~~~

[verse]
'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, Epiphany and Galeon 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 -
----------------------------------------

If you want to disable adding URLs by default, you can use the +bz.add-url+
config variable, which defaults to false. The -u/--add-url and -n/--no-add-url
command line options override the config variable.

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.

[[default-field-values]]
DEFAULT FIELD VALUES
--------------------
When filing a bug, git-bz needs to know the default values to use for
the fields +version+, +op-sys+, +platform+, +assigned-to+ and
+priority+.  git-bz has built-in global defaults and specific defaults
for particular common bug trackers, but if you are using a bug tracker
that it doesn't know about, you may need to configure appropriate
field values. Valid values for +priority+ are especially likely to vary
between different Bugzilla instances.

Also, for +version+, each product has it's own list of versions, and if
the product owner has deleted the +unspecified+ version that git-bz
uses as a default, you'll have to set that.

The first place that git-bz checks for default field values is in the
bugzilla config variable +bz.default-<field-name>+. So, to change the
default value of version for the current repository, do:

----------------------------------------
git config bz.default-version 1.0
----------------------------------------

If no value is set there, then it looks for +default-<field-name>+ in
the per-tracker configuration. See <<per-tracker-configuration, below>>.

[[per-tracker-configuration]]
PER-TRACKER CONFIGURATION
-------------------------
In addition to <<default-field-values, default field values>>, some
other variables can be configured per tracker:

auth-user:: the user to use for basic HTTP authentication. Since
  basic auth sends passwords in clear text, you should not use this unless
  you are also using https.
auth-password:: the password to use for basic HTTP authentication.
https:: use https rather than http.
  For https, *certificates are not checked* so you are completely vulnerable
  to DNS spoofing and man-in-the-middle attacks. Blame httplib.
path:: the root path of the bugzilla installation. If bugs are accessed
  as http://example.com/bugzilla/show_bug.cgi, this variable would be set
  to /bugzilla.

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>.