git-bz(1) ========= NAME ---- git-bz - Command line integration of git with Bugzilla SYNOPSIS -------- [verse] 'git bz add-url' ( | ) 'git bz apply' [-n | --no-add-url] 'git bz apply' (--continue | --skip | --abort) 'git bz attach' [-n | --no-add-url] [-e |--edit] [] ( | ) 'git bz components' [] 'git bz edit' ( | | ) 'git bz edit' (--pushed | --fix | ) 'git bz file' [-n | --no-add-url] [[]/] ( | ) 'git bz push' [--fix ] [ ...] 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 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, Galeon 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 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 <>. -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' ( | ) 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 <> below for how to change this. apply ~~~~~ [verse] 'git bz apply' [-n | --no-add-url] '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] [ | ] 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' [] 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' ( | | ) 'git bz edit' --fix= ( | ) 'git bz edit' --pushed ( | ) 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=;; 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] [[]/] ( | ) 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] [ ...] 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=;; 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. ATTACHMENT FLAGS ---------------- When editing the description of an attachment with 'git-bz attach -e' it is possible to set flag values, depending on the configuration of the bug tracker. However, it is first necessary to configure the flag types available for your bug tracker. Ask the administrator of the tracker or inspect the HTML source code of the attachment.cgi page. For each flag you need to configure its id, and can specify whether it is requesteeable (if you can ask for a specific bugzilla user to update the flag), and multiplicable (if you can request it of several bugzilla users.) Here is a sample configuration: ---------------------------------------- attachment-flag.review.id = 1 attachment-flag.review.requesteeable = true attachment-flag.review.multiplicable = false ---------------------------------------- (requesteeable and multiplicable both default to false.) With the above flag configuration, when editing an attachment description you should see a template allowing setting the flag: ---------------------------------------- # Uncomment to set flags for the attachment; flags can be set to +,- , or ?. # When setting a flag to ? you can optionally specify individuals as, for example: # review: ? joe@example.com #review: ? ---------------------------------------- BUG REFERENCES -------------- On the command line, there are multiple ways to refer to a bug: :: bug # on the default bug tracker ::: bug # on the given host ::: bug # on the given bug tracker alias (see below) :: An URL of the form "http:///show_bug.cgi?id=" git-bz will also look for bug references in the subject and body of commit messages. In commit messages, the following forms are recognized: :: An URL of the form "http:///show_bug.cgi?id=" (Bug|bug) :: bug # on the default bug tracker In commit messages, if a bug reference in either of the above forms is proceeded by "See" or "see" with no more than two words in-between, then it will be ignored. This is to allow referring to other related bugs without confusing git-bz. An example: ------ Fix regression in indentation Changes in the handling of tab characters (see Mozilla bug 2345) caused problems with leading spaces. http://bugzilla.gnome.org/show_bug.cgi?id=12345 ------ [[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 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-+. 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-+ in the per-tracker configuration. See <>. [[per-tracker-configuration]] PER-TRACKER CONFIGURATION ------------------------- In addition to <>, 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. AUTHORS ------- Written by Owen Taylor . REPORTING BUGS -------------- Report bugs in the 'git-bz' product on bugzilla.gnome.org: https://bugzilla.gnome.org/enter_bug.cgi?product=git-bz