Add README
[git-bz.git] / git-bz.txt
1 git-bz(1)
2 =========
3
4 NAME
5 ----
6 git-bz - Command line integration of git with Bugzilla
7
8 SYNOPSIS
9 --------
10 [verse]
11 'git bz add-url' <bug reference> (<commit> | <revision range>)
12 'git bz apply' [-n | --no-add-url] <bug reference>
13 'git bz attach' [-n | --no-add-url] [-e |--edit] [<bug reference>] (<commit> | <revision range>)
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
19 DESCRIPTION
20 ------------
21
22 git-bz is a tool for integrating the Git command line with the
23 Bugzilla bug-tracking system. Operations such as attaching patches to bugs,
24 applying patches in bugs to your current tree, and closing bugs once
25 you've pushed the fixes publically can be done completely from the
26 command line without having to go to your web browser.
27
28 Authentication for git-bz can be done by reading the cookies for the
29 Bugzilla host from your web browser. In order to do this, git-bz needs
30 to know how to access the cookies for your web browser; git-bz
31 currently is able to do this for Firefox, Epiphany, and Chromium on
32 Linux.
33
34 Alternatively, you can set the bz-user and bz-password in the
35 git config for each tracker.
36
37 EXAMPLE SESSION
38 ---------------
39
40 Before getting started, you configure the default Bugzilla instance, product and
41 component for your repository:
42
43 ----------------------------------------
44 git config bz.default-tracker bugzilla.example.com
45 git config bz.default-product TiddlyWinks
46 git config bz.default-component AI-Engine
47 ----------------------------------------
48
49 Someone has found a bug in your code, and filed bug 43215 in
50 bugzilla.example.com. You've come up with a fix for that patch
51 locally, but you want the bug reporter to test it, so you attach the change
52 you made locally to the bug report as a patch:
53
54 ----------------------------------------
55 git bz attach 43215 HEAD
56 ----------------------------------------
57
58 This automatically rewrites the commit to add the URL of the bug to
59 the commit message for future reference. The reporter finds some
60 problems in testing, so you come up with a new version of the change
61 and modify your commit using 'git commit --amend'. To attach the new
62 version, you run:
63
64 ----------------------------------------
65 git bz attach -e HEAD
66 ----------------------------------------
67
68 You don't have to specify the bug number this time since git-bz will
69 find it in the commit message. The -e option (short for --edit)
70 allows you to edit the comment for the bug to say what you've changed
71 and pick patches to obsolete. Now everybody's happy with the
72 change. To push your changes and close the bug, you run:
73
74 ----------------------------------------
75 git bz push
76 ----------------------------------------
77
78 This does 'git push', adds a comment that the commits were pushed and
79 marks the patches committed. The changes it is making to the bug will be
80 shown in your editor to give you a chance to confirm them and add
81 extra comments if desired.
82
83 Other useful commands are 'git bz file' to file a new bug rather than
84 attaching patches to an existing one, 'git bz apply' to apply patches from
85 a bug to the current tree, and 'git bz edit' to add comments to or
86 close bug reports.
87
88 COMMON OPTIONS
89 --------------
90
91 -b;;
92 --bugzilla;;
93         Bug tracker to use. Used for 'git bz file' and to resolve bug references.
94         Generally, it's more useful to configure this with 'git config' instead.
95         See the section <<per-repository-configuration, ``Per-Repository Configuration''>>.
96
97 -u;;
98 --add-url;;
99         Rewrite commits to add the bug URL. (This is the default and will not normally
100         need to be specified; you can change the default using the bz.add-url config
101         variable.)
102
103 -n;;
104 --no-add-url;;
105         Don't rewrite commits to add the bug URL
106
107 COMMANDS
108 --------
109
110 add-url
111 ~~~~~~~
112
113 'git bz add-url' <bug reference> (<commit> | <revision range>)
114
115 For each specified commit, rewrite the commit message to add a
116 reference to the given bug. You should only do this if you haven't
117 already pushed the commit publically. You won't need this very often,
118 since 'git bz file' and 'git bz attach' do this automatically. It
119 might be useful if you want to record the bug information but don't
120 want to attach it immediately.
121
122 If the bug number is already found in the commit message, then does nothing.
123
124 Example:
125
126 ----------------------------------------
127 # Add a bug URL to the last commit
128 git bz attach 1234 HEAD
129 ----------------------------------------
130
131 The default behavior is to append the bug URL to the commit body. See the
132 section <<add-url-method, ``Add URL Method''>> below for how to change this.
133
134 apply
135 ~~~~~
136
137 'git bz apply' [-n | --no-add-url] <bug reference>
138
139 For each patch attachment (except for obsolete patches) of the specified
140 bug, prompts whether to apply. If prompt is agreed to runs 'git am' on
141 the patch to apply it to the current branch. Aborts if 'git am' fails to
142 allow cleaning up conflicts.
143
144 Examples:
145
146 ----------------------------------------
147 # Apply patches from the given bug
148 git bz apply bugzillla.gnome.org:1234
149 ----------------------------------------
150
151 The commit messages will automatically be rewritten to include a
152 reference to the bug (see 'git bz add-url'). This can be suppressed
153 with the -n/--no-add-url option.
154
155 attach
156 ~~~~~~
157
158 'git bz attach' [-n | --no-add-url] [-e |--edit] <bug reference> [<commit> | <revision range>]
159
160 For each specified commit, formats as a patch and attaches to the
161 specified bug, with the subject of the commit as the description and
162 the body of the commit as the comment. The patch formatting is as
163 for 'git format-patch'. Unlike 'git format-patch', specifying a single
164 commit means just that commit, not everything after that commit.
165
166 Prompts before actually doing anything to avoid mistakes.
167
168 The commit message will automatically be rewritten to include a reference
169 to the bug (see 'git bz add-url'). This can be suppressed with the
170 -n/--no-add-url option.
171
172 -e;;
173 --edit;;
174         allow the user to edit the description and comment for each patch,
175         and (by uncommenting lines) obsolete old patches.
176
177 Examples:
178 ----------------------------------------
179 # Attach the last commit
180 git bz attach bugzilla.gnome.org:1234 HEAD
181
182 # Attach everything starting at an old commit
183 git bz attach bugzilla.gnome.org:1234 b50ea9bd^..
184 ----------------------------------------
185
186 edit
187 ~~~~
188
189 'git bz edit' (<bug reference> | <commit> | <revision range>)
190 'git bz edit' --pushed (<commit> | <revision range>)
191
192 Allows doing common operations on a Bugzilla bug without going to
193 your web browser. An editable buffer is brought up in a git-like
194 fashion, where you can add comments, resolve a bug, and change
195 the status of patches.
196
197 If the argument identifies a commit or commits rather than a bug
198 then each bug referred to in the commits is edited in turn.
199
200 --fix=<bug reference>;;
201         Treat the specified commits as a fix for the bug. Similar
202         to attaching the commits with 'git bz attach' then using
203         'git bz edit --pushed'.
204
205 --pushed;;
206         Attempt to automatically determine the correct comments, attachment
207         changes, and resolution for the bug from applying the specified commits
208         to the project's official repository. You'll have a chance to edit these
209         changes and add additional comments. See 'git bz push' for a convenient
210         interface to push commits and do this at the same time.
211
212 file
213 ~~~~
214
215 'git bz file' [-n | --no-add-url] [[<product>]/<component>] (<commit> | <revision range>)
216
217 Like 'attach', but files a new bug. Opens an editor for the user to
218 enter the summary and description for the bug. If only a single commit
219 is named, the summary defaults to the subject of the commit. The product and
220 component must be specified unless you have configured defaults.
221
222 The commit message will automatically be rewritten to include a reference to
223 the newly filed bug (see 'git bz add-url') before attaching the patch. This
224 can be suppressed with the -n/--no-add-url option.
225
226 Examples:
227
228 ----------------------------------------
229 # File the last commit as a new bug on the default tracker
230 git bz file my-product/some-component HEAD
231
232 # File a bug with a series of patches starting from an old commit
233 # on a different bug tracker
234 git bz -b bugs.freedesktop.org file my-product/some-component b50ea9bd^..
235 ----------------------------------------
236
237 push
238 ~~~~
239
240 'git bz push' [--fix] [<repository> <refspec>...]
241
242 Exactly like 'git push', but 'git bz edit --pushed' is done for each
243 bug referenced in the newly pushed commits.
244
245 Note that ``newly pushed commit'' are commits that were added to any
246 existing branch by the push. Commits don't have to be pushed to master
247 to be considered newly pushed. However, commits pushed to newly
248 created branches will be ignored.
249
250 --fix=<bug reference>;;
251         Treat the specified commits as a fix for the bug. Similar
252         to attaching the commits with 'git bz attach' before running
253         'git bz push'. This is in an-all-one-solution to use when you
254         have a fix that doesn't need any review or testing.
255
256 AUTHENTICATION
257 --------------
258 In order to use git-bz you need to already be logged into the bug tracker
259 in your web browser, and git-bz reads your browser cookie. Currently only
260 Firefox 3 and Epiphany are supported, and only on Linux. Patches to
261 add more support and to allow configuring username/password directly
262 per bug tracker accepted.
263
264 BUG REFERENCES
265 --------------
266 Ways to refer to a bug:
267
268 <id>:: bug # on the default bug tracker
269
270 <host>:<id>:: bug # on the given host
271
272 <alias>:<id>:: bug # on the given bug tracker alias (see below)
273
274 <url>:: An URL of the form "http://<hostname>/show_bug.cgi?id-<id>"
275
276 [[add-url-method]]
277 ADD URL METHOD
278 --------------
279 You can configure 'git bz add-url', and the --add-url option of 'git
280 bz [apply|attach|file]' to add the URL different ways or to add a
281 non-URL bug reference, using the git config variable
282 +bz.add-url-method+.
283
284 It has the form
285
286  <method>:<format>
287
288 Method is:
289
290 subject-prepend:: prepend to the subject (separated with a space)
291 subject-append::  append to the subject (separated with a space)
292 body-prepend::    prepend to the body (separated with a blank line)
293 body-append::     append to the body (separated with a blank line)
294
295 Format supports the following escapes:
296
297 %u:: the bug URL
298 %d:: the bug #
299 %n:: a newline
300 %%:: a percent
301
302 ----------------------------------------
303 # The default
304 git config bz.add-url-method body-append:%u
305 # 'Bug 34323 - Speed up frobnification'
306 git config bz.add-url-method subject-prepend:Bug %d -
307 ----------------------------------------
308
309 If you want to disable adding URLs by default, you can use the +bz.add-url+
310 config variable, which defaults to false. The -u/--add-url and -n/--no-add-url
311 command line options override the config variable.
312
313 ALIASES
314 -------
315 You can create short aliases for different bug trackers as follows
316
317 ----------------------------------------
318 git config --global bz-tracker.gnome.host bugzilla.gnome.org
319 ----------------------------------------
320
321 And you can set the default bug tracker with:
322
323 ----------------------------------------
324 git config --global bz.default-tracker gnome
325 ----------------------------------------
326
327 [[per-repository-configuration]]
328 PER-REPOSITORY CONFIGURATION
329 ----------------------------
330 Setting the default tracker, product and component in the local
331 config for a repository is useful. Assuming that a global
332 'gnome' alias has been set up as above:
333
334 ----------------------------------------
335 git config bz.default-tracker gnome
336 git config bz.default-product gnome-shell
337 git config bz.default-component general
338 ----------------------------------------
339
340 Note the absence of --global; configuring a default product and component
341 globally is seldom useful.
342
343 PER-TRACKER CONFIGURATION
344 -------------------------
345 git-bz needs some configuration specific to the bugzilla instance (tracker),
346 in particular it needs to know initial field values to use when submitting
347 bugs; legal values for some fields depend on the instance. Initial field
348 values are specified by the config variable +default-<field-name>+.
349
350 In addition to initial field values, some other variables can be configured
351 per tracker:
352
353 auth-user:: the user to use for basic HTTP authentication. Since
354   basic auth sends passwords in clear text, you should not use this unless
355   you are also using https.
356 auth-password:: the password to use for basic HTTP authentication.
357 https:: use https rather than http.
358   For https, *certificates are not checked* so you are completely vulnerable
359   to DNS spoofing and man-in-the-middle attacks. Blame httplib.
360 path:: the root path of the bugzilla installation. If bugs are accessed
361   as http://example.com/bugzilla/show_bug.cgi, this variable would be set
362   to /bugzilla.
363
364 Configuration comes from 4 sources, in descending order of priority
365
366 1. git configuration variables specified for the alias.
367 +
368 ----------------------------------------
369 git config --global bz-tracker.gnome.default-severity trivial
370 ----------------------------------------
371 +
372 2. git configuration variables specified for the host
373 +
374 ----------------------------------------
375 git config --global bz-tracker.bugzilla.gnome.org.default-severity trivial
376 ----------------------------------------
377 +
378 3. Host specific configuration in the git-bz script, see the CONFIG variable.
379 +
380 4. Default configuration in the git-bz script, see the DEFAULT_CONFIG variable.
381
382 In general, settings that are necessary to make a popular bugzilla instance
383 work should be submitted back to me and go in the CONFIG variable.
384
385 Author
386 ------
387 Written by Owen Taylor <otaylor@fishsoup.net>.
388