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 attach' [-n | --no-add-url] [-e |--edit] [] ( | ) '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 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 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: ---------------------------------------- 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.) -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 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 <> below for how to change this. apply ~~~~~ 'git bz apply' [-n | --no-add-url] 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] [ | ] 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' ( | | ) '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 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: :: 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- [[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 - ---------------------------------------- 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 .