1GIT-BZ(1) Git Bz Manual GIT-BZ(1)
2
6 git-bz - Command line integration of git with Bugzilla
7
9 git bz add-url <bug reference> (<commit> | <revision range>)
10 git bz apply [-n | --no-add-url] <bug reference>
11 git bz apply (--continue | --skip | --abort)
12 git bz attach [-n | --no-add-url] [-e |--edit] [<bug reference>] (<commit> | <revision range>)
13 git bz components [<product>]
14 git bz edit (<bug reference> | <commit> | <revision range>)
15 git bz edit (--pushed | --fix <bug reference) (<commit> | <revision range>)
16 git bz file [-n | --no-add-url] [[<product>]/<component>] (<commit> | <revision range>)
17 git bz push [--fix <bug reference>] [<repository> <refspec>...]
18
20 git-bz is a tool for integrating the Git command line with the Bugzilla
21 bug-tracking system. Operations such as attaching patches to bugs,
22 applying patches in bugs to your current tree, and closing bugs once
23 you’ve pushed the fixes publicly can be done completely from the
24 command line without having to go to your web browser.
25 Authentication for git-bz is done by reading the cookies for the
27 Bugzilla host from your web browser. In order to do this, git-bz needs
28 to know how to access the cookies for your web browser; git-bz
29 currently is able to do this for Firefox, Epiphany, Galeon and Chromium
30 on Linux.
31
33 Before getting started, you configure the default Bugzilla instance,
34 product and component for your repository:
35 git config bz.default-tracker bugzilla.example.com
37 git config bz.default-product TiddlyWinks
38 git config bz.default-component AI-Engine
39 Someone has found a bug in your code, and filed bug 43215 in
41 bugzilla.example.com. You’ve come up with a fix for that patch locally,
42 but you want the bug reporter to test it, so you attach the change you
43 made locally to the bug report as a patch:
44 git bz attach 43215 HEAD
46 This automatically rewrites the commit to add the URL of the bug to the
48 commit message for future reference. The reporter finds some problems
49 in testing, so you come up with a new version of the change and modify
50 your commit using git commit --amend. To attach the new version, you
51 run:
52 git bz attach -e HEAD
54 You don’t have to specify the bug number this time since git-bz will
56 find it in the commit message. The -e option (short for --edit) allows
57 you to edit the comment for the bug to say what you’ve changed and pick
58 patches to obsolete. Now everybody’s happy with the change. To push
59 your changes and close the bug, you run:
60 git bz push
62 This does git push, adds a comment that the commits were pushed and
64 marks the patches committed. The changes it is making to the bug will
65 be shown in your editor to give you a chance to confirm them and add
66 extra comments if desired.
67 Other useful commands are git bz file to file a new bug rather than
69 attaching patches to an existing one, git bz apply to apply patches
70 from a bug to the current tree, and git bz edit to add comments to or
71 close bug reports.
72
74 -b, --bugzilla
75 Bug tracker to use. Used for git bz file and to resolve bug
76 references. Generally, it’s more useful to configure this with git
77 config instead. See the section “Per-Repository Configuration”.
78 -u, --add-url
80 Rewrite commits to add the bug URL. (This is the default and will
81 not normally need to be specified; you can change the default using
82 the bz.add-url config variable.)
83 -n, --no-add-url
85 Don’t rewrite commits to add the bug URL
86
88 add-url
89 git bz add-url <bug reference> (<commit> | <revision range>)
90 For each specified commit, rewrite the commit message to add a
92 reference to the given bug. You should only do this if you haven’t
93 already pushed the commit publicly. You won’t need this very often,
94 since git bz file and git bz attach do this automatically. It might be
95 useful if you want to record the bug information but don’t want to
96 attach it immediately.
97 If the bug number is already found in the commit message, then does
99 nothing.
100 Example:
102 # Add a bug URL to the last commit
104 git bz attach 1234 HEAD
105 The default behavior is to append the bug URL to the commit body. See
107 the section “Add URL Method” below for how to change this.
108 apply
110 git bz apply [-n | --no-add-url] <bug reference>
111 git bz apply (--continue | --skip | --abort)
112 Lists all "pending" patches on the specified bug (ie, the patches that
114 are not obsolete, committed, or rejected), and then prompts whether to
115 apply them. In addition to simply accepting or rejecting the list of
116 patches, you can also type "i" to interactively choose which patches to
117 apply, and in what order, as with git rebase -i. If any patches are
118 selected, it runs git am on each one to apply it to the current branch.
119 (If the bug contains patches in the form of plain diffs, git bz apply
120 will create a commit based on the other patch metadata, and prompt you
121 for a commit message.)
122 If a git am operation fails, git bz apply will save its state and then
124 exit, at which point you can attempt to apply the patch by hand and
125 then resume with git bz apply --continue; skip this patch but continue
126 applying the remaining patches with git bz apply --skip; or abort the
127 operation and return to the original tree state with git bz apply
128 --abort.
129 Examples:
131 # Apply patches from the given bug
133 git bz apply bugzillla.gnome.org:1234
134 The commit messages will automatically be rewritten to include a
136 reference to the bug (see git bz add-url). This can be suppressed with
137 the -n/--no-add-url option.
138 attach
140 git bz attach [-n | --no-add-url] [-e |--edit] <bug reference>
141 [<commit> | <revision range>]
142 For each specified commit, formats as a patch and attaches to the
144 specified bug, with the subject of the commit as the description and
145 the body of the commit as the comment. The patch formatting is as for
146 git format-patch. Unlike git format-patch, specifying a single commit
147 means just that commit, not everything after that commit.
148 Prompts before actually doing anything to avoid mistakes.
150 The commit message will automatically be rewritten to include a
152 reference to the bug (see git bz add-url). This can be suppressed with
153 the -n/--no-add-url option.
154 -e, --edit
156 allow the user to edit the description and comment for each patch,
157 and (by uncommenting lines) obsolete old patches.
158 When a commit with the same subject as an existing patch is attached,
160 this is interpreted as a new version of the existing patch and the old
161 patch is obsoleted. (With -e, the obsoletes line can be commented to
162 suppress this.)
163 Examples:
165 # Attach the last commit
167 git bz attach bugzilla.gnome.org:1234 HEAD
168 # Attach everything starting at an old commit
170 git bz attach bugzilla.gnome.org:1234 b50ea9bd^..
171 components
173 git bz components [<product>]
174 Prints out the list of components for the given product (or the default
176 product if none is given on the command line).
177 edit
179 git bz edit (<bug reference> | <commit> | <revision range>)
180 git bz edit --fix=<bug reference> (<commit> | <revision range>)
181 git bz edit --pushed (<commit> | <revision range>)
182 Allows doing common operations on a Bugzilla bug without going to your
184 web browser. An editable buffer is brought up in a git-like fashion,
185 where you can add comments, resolve a bug, and change the status of
186 patches.
187 If the argument identifies a commit or commits rather than a bug then
189 each bug referred to in the commits is edited in turn.
190 --fix=<bug reference>
192 Treat the specified commits as a fix for the bug. Similar to
193 attaching the commits with git bz attach then using git bz edit
194 --pushed.
195 --pushed
197 Attempt to automatically determine the correct comments, attachment
198 changes, and resolution for the bug from applying the specified
199 commits to the project’s official repository. You’ll have a chance
200 to edit these changes and add additional comments. See git bz push
201 for a convenient interface to push commits and do this at the same
202 time.
203 file
205 git bz file [-n | --no-add-url] [[<product>]/<component>] (<commit> |
206 <revision range>)
207 Like attach, but files a new bug. Opens an editor for the user to enter
209 the summary and description for the bug. If only a single commit is
210 named, the summary defaults to the subject of the commit. The product
211 and component must be specified unless you have configured defaults.
212 The commit message will automatically be rewritten to include a
214 reference to the newly filed bug (see git bz add-url) before attaching
215 the patch. This can be suppressed with the -n/--no-add-url option.
216 Examples:
218 # File the last commit as a new bug on the default tracker
220 git bz file my-product/some-component HEAD
221 # File a bug with a series of patches starting from an old commit
223 # on a different bug tracker
224 git bz -b bugs.freedesktop.org file my-product/some-component b50ea9bd^..
225 push
227 git bz push [--fix] [<repository> <refspec>...]
228 Exactly like git push, but git bz edit --pushed is done for each bug
230 referenced in the newly pushed commits.
231 Note that “newly pushed commit” are commits that were added to any
233 existing branch by the push. Commits don’t have to be pushed to master
234 to be considered newly pushed. However, commits pushed to newly created
235 branches will be ignored.
236 --fix=<bug reference>
238 Treat the specified commits as a fix for the bug. Similar to
239 attaching the commits with git bz attach before running git bz
240 push. This is in an-all-one-solution to use when you have a fix
241 that doesn’t need any review or testing.
242
244 In order to use git-bz you need to already be logged into the bug
245 tracker in your web browser, and git-bz reads your browser cookie.
246 Currently only Firefox 3, Epiphany and Galeon are supported, and only
247 on Linux. Patches to add more support and to allow configuring
248 username/password directly per bug tracker accepted.
249
251 When editing the description of an attachment with git-bz attach -e it
252 is possible to set flag values, depending on the configuration of the
253 bug tracker. However, it is first necessary to configure the flag types
254 available for your bug tracker. Ask the administrator of the tracker or
255 inspect the HTML source code of the attachment.cgi page. For each flag
256 you need to configure its id, and can specify whether it is
257 requesteeable (if you can ask for a specific bugzilla user to update
258 the flag), and multiplicable (if you can request it of several bugzilla
259 users.) Here is a sample configuration:
260 attachment-flag.review.id = 1
262 attachment-flag.review.requesteeable = true
263 attachment-flag.review.multiplicable = false
264 (requesteeable and multiplicable both default to false.) With the above
266 flag configuration, when editing an attachment description you should
267 see a template allowing setting the flag:
268 # Uncomment to set flags for the attachment; flags can be set to +,- , or ?.
270 # When setting a flag to ? you can optionally specify individuals as, for example:
271 # review: ? joe@example.com
272 #review: ?
273
275 On the command line, there are multiple ways to refer to a bug:
276 <id>
278 bug # on the default bug tracker
279 <host>:<id>
281 bug # on the given host
282 <alias>:<id>
284 bug # on the given bug tracker alias (see below)
285 <url>
287 An URL of the form "http://<hostname>/show_bug.cgi?id=<id>"
288 git-bz will also look for bug references in the subject and body of
290 commit messages. In commit messages, the following forms are
291 recognized:
292 <url>
294 An URL of the form "http://<hostname>/show_bug.cgi?id=<id>"
295 (Bug|bug) <id>
297 bug # on the default bug tracker
298 In commit messages, if a bug reference in either of the above forms is
300 proceeded by "See" or "see" with no more than two words in-between,
301 then it will be ignored. This is to allow referring to other related
302 bugs without confusing git-bz. An example:
303 Fix regression in indentation
305 Changes in the handling of tab characters (see Mozilla bug 2345) caused
307 problems with leading spaces.
308 http://bugzilla.gnome.org/show_bug.cgi?id=12345
310
312 You can configure git bz add-url, and the --add-url option of git bz
313 [apply|attach|file] to add the URL different ways or to add a non-URL
314 bug reference, using the git config variable bz.add-url-method.
315 It has the form
317 <method>:<format>
319 Method is:
321 subject-prepend
323 prepend to the subject (separated with a space)
324 subject-append
326 append to the subject (separated with a space)
327 body-prepend
329 prepend to the body (separated with a blank line)
330 body-append
332 append to the body (separated with a blank line)
333 Format supports the following escapes:
335 %u
337 the bug URL
338 %d
340 the bug #
341 %n
343 a newline
344 %%
346 a percent
347 # The default
349 git config bz.add-url-method body-append:%u
350 # 'Bug 34323 - Speed up frobnification'
351 git config bz.add-url-method subject-prepend:Bug %d -
352 If you want to disable adding URLs by default, you can use the
354 bz.add-url config variable, which defaults to false. The -u/--add-url
355 and -n/--no-add-url command line options override the config variable.
356
358 You can create short aliases for different bug trackers as follows
359 git config --global bz-tracker.gnome.host bugzilla.gnome.org
361 And you can set the default bug tracker with:
363 git config --global bz.default-tracker gnome
365
367 Setting the default tracker, product and component in the local config
368 for a repository is useful. Assuming that a global gnome alias has been
369 set up as above:
370 git config bz.default-tracker gnome
372 git config bz.default-product gnome-shell
373 git config bz.default-component general
374 Note the absence of --global; configuring a default product and
376 component globally is seldom useful.
377
379 When filing a bug, git-bz needs to know the default values to use for
380 the fields version, op-sys, platform, assigned-to and priority. git-bz
381 has built-in global defaults and specific defaults for particular
382 common bug trackers, but if you are using a bug tracker that it doesn’t
383 know about, you may need to configure appropriate field values. Valid
384 values for priority are especially likely to vary between different
385 Bugzilla instances.
386 Also, for version, each product has it’s own list of versions, and if
388 the product owner has deleted the unspecified version that git-bz uses
389 as a default, you’ll have to set that.
390 The first place that git-bz checks for default field values is in the
392 bugzilla config variable bz.default-<field-name>. So, to change the
393 default value of version for the current repository, do:
394 git config bz.default-version 1.0
396 If no value is set there, then it looks for default-<field-name> in the
398 per-tracker configuration. See below.
399
401 In addition to default field values, some other variables can be
402 configured per tracker:
403 auth-user
405 the user to use for basic HTTP authentication. Since basic auth
406 sends passwords in clear text, you should not use this unless you
407 are also using https.
408 auth-password
410 the password to use for basic HTTP authentication.
411 https
413 use https rather than http. For https, certificates are not checked
414 so you are completely vulnerable to DNS spoofing and
415 man-in-the-middle attacks. Blame httplib.
416 path
418 the root path of the bugzilla installation. If bugs are accessed as
419 http://example.com/bugzilla/show_bug.cgi, this variable would be
420 set to /bugzilla.
421 Configuration comes from 4 sources, in descending order of priority
423 1. git configuration variables specified for the alias.
425 git config --global bz-tracker.gnome.default-severity trivial
427 2. git configuration variables specified for the host
429 git config --global bz-tracker.bugzilla.gnome.org.default-severity trivial
431 3. Host specific configuration in the git-bz script, see the CONFIG
433 variable.
434 4. Default configuration in the git-bz script, see the DEFAULT_CONFIG
436 variable.
437 In general, settings that are necessary to make a popular bugzilla
439 instance work should be submitted back to me and go in the CONFIG
440 variable.
441
443 Written by Owen Taylor <otaylor@fishsoup.net[1]>.
444
446 Report bugs in the git-bz product on bugzilla.gnome.org:
447 https://bugzilla.gnome.org/enter_bug.cgi?product=git-bz
448
450 1. otaylor@fishsoup.net
451 mailto:otaylor@fishsoup.net
452Git Bz 01/31/2019 GIT-BZ(1)