diff options
Diffstat (limited to 'git-bz.txt')
| -rw-r--r-- | git-bz.txt | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/git-bz.txt b/git-bz.txt new file mode 100644 index 0000000..3db24e8 --- /dev/null +++ b/git-bz.txt @@ -0,0 +1,358 @@ +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 (<commit> | <revision range>) +'git bz file' [-n | --no-add-url] [[<product>]/<component>] (<commit> | <revision range>) +'git bz push' [<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. + +-p;; +--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' [<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 on newly +created branches will be ignored. + +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>. + |