Skip to content

Commit 178fb6f

Browse files
crobinsocrazyscientist
crobinso
authored and
crazyscientist
committed
man: Regenerate bugzilla.1
Signed-off-by: Cole Robinson <crobinso@redhat.com>
1 parent efd2c17 commit 178fb6f

1 file changed

Lines changed: 76 additions & 40 deletions

File tree

‎man/bugzilla.1‎

Lines changed: 76 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
11
.\" Man page generated from reStructuredText.
22
.
3-
.TH BUGZILLA 1 "" "" "User Commands"
4-
.SH NAME
5-
bugzilla \- command line tool for interacting with Bugzilla
63
.
74
.nr rst2man-indent-level 0
85
.
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
3027
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
3128
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
3229
..
30+
.TH "BUGZILLA" 1 "" "" "User Commands"
31+
.SH NAME
32+
bugzilla \- command line tool for interacting with Bugzilla
3333
.SH SYNOPSIS
3434
.sp
3535
\fBbugzilla\fP [\fIoptions\fP] [\fIcommand\fP] [\fIcommand\-options\fP]
@@ -86,7 +86,7 @@ client side certificate file needed by the webserver.
8686
.sp
8787
\fBSyntax:\fP \fB\-\-login\fP
8888
.sp
89-
Run interactive "login" before performing the specified command.
89+
Run interactive \(dqlogin\(dq before performing the specified command.
9090
.SS \fB\-\-username\fP
9191
.sp
9292
\fBSyntax:\fP \fB\-\-username\fP USERNAME
@@ -114,13 +114,8 @@ they expire the tool errors, rather than subtly change output.
114114
.sp
115115
\fBSyntax:\fP \fB\-\-no\-cache\-credentials\fP
116116
.sp
117-
Don\(aqt save any bugzilla cookies or tokens to disk, and don\(aqt use any
117+
Don\(aqt save any bugzilla tokens to disk, and don\(aqt use any
118118
pre\-existing credentials.
119-
.SS \fB\-\-cookiefile\fP
120-
.sp
121-
\fBSyntax:\fP \fB\-\-cookiefile\fP COOKIEFILE
122-
.sp
123-
cookie file to use for bugzilla authentication
124119
.SS \fB\-\-tokenfile\fP
125120
.sp
126121
\fBSyntax:\fP \fB\-\-tokenfile\fP TOKENFILE
@@ -260,7 +255,7 @@ Bug assignee
260255
\fBSyntax:\fP \fB\-\-qa_contact\fP QA_CONTACT
261256
.sp
262257
QA contact
263-
.SS \fB\-\-flag\fP
258+
.SS \fB\-f, \-\-flag\fP
264259
.sp
265260
\fBSyntax:\fP \fB\-\-flag\fP FLAG
266261
.sp
@@ -299,16 +294,22 @@ RHBZ QA whiteboard field
299294
RHBZ \(aqFixed in version\(aq field
300295
.SS \fB\-\-field\fP
301296
.sp
302-
\fBSyntax:\fP \fB\-\-field\fP FIELD\(ga\(ga VALUE
297+
\fBSyntax:\fP \fB\-\-field\fP FIELD=VALUE
303298
.sp
304299
Manually specify a bugzilla API field. FIELD is the raw name used
305300
by the bugzilla instance. For example if your bugzilla instance has a
306301
custom field cf_my_field, do: \-\-field cf_my_field=VALUE
302+
.SS \fB\-\-field\-json\fP
303+
.sp
304+
\fBSyntax:\fP \fB\-\-field\-json\fP JSONSTRING
305+
.sp
306+
Specify \-\-field data as a JSON string. Example:
307+
\-\-field\-json \(aq{\(dqcf_my_field\(dq: \(dqVALUE\(dq, \(dqcf_array_field\(dq: [1, 2]}\(aq
307308
.SH OUTPUT OPTIONS
308309
.sp
309310
These options are shared by several commands, for tweaking the text
310311
output of the command results.
311-
.SS \fB\-f, \-\-full\fP
312+
.SS \fB\-\-full\fP
312313
.sp
313314
\fBSyntax:\fP \fB\-\-full\fP
314315
.sp
@@ -379,7 +380,7 @@ the formats are not stable and are subject to change.
379380
format. For example, to print a returned bug ID, component, and product,
380381
separated with ::, do:
381382
.sp
382-
\-\-outputformat "%{id}::%{component}::%{product}"
383+
\-\-outputformat \(dq%{id}::%{component}::%{product}\(dq
383384
.sp
384385
The fields (like \(aqid\(aq, \(aqcomponent\(aq, etc.) are the names of the values
385386
returned by bugzilla\(aqs API. To see a list of all fields,
@@ -542,44 +543,78 @@ List the versions for the given product
542543
\fBSyntax:\fP \fB\-\-active\-components\fP
543544
.sp
544545
Only show active components. Combine with \-\-components*
545-
.SH AUTHENTICATION CACHE AND API KEYS
546+
.SH BUGZILLARC CONFIG FILE
546547
.sp
547-
Some command usage will require an active login to the bugzilla
548-
instance. For example, if the bugzilla instance has some private bugs,
549-
those bugs will be missing from \(aqquery\(aq output if you do not have an
550-
active login.
548+
Both \fBbugzilla\fP and the python\-bugzilla library will read
549+
a \fBbugzillarc\fP config file if it is present in the following
550+
locations:
551+
.INDENT 0.0
552+
.IP \(bu 2
553+
/etc/bugzillarc
554+
.IP \(bu 2
555+
~/.bugzillarc
556+
.IP \(bu 2
557+
~/.config/python\-bugzilla/bugzillarc
558+
.UNINDENT
551559
.sp
552-
If you are connecting to a bugzilla 5.0 or later instance, the best
553-
option is to use bugzilla API keys. From the bugzilla web UI, log in,
554-
navigate to Preferences\->API Keys, and generate a key (it will be a long
555-
string of characters and numbers). Then create a
556-
~/.config/python\-bugzilla/bugzillarc like this:
560+
The contents of the files are processed and merged together
561+
in the order they are listed above.
562+
.sp
563+
The main usage for \fBbugzillarc\fP is to store API keys for your
564+
bugzilla URLs:
557565
.INDENT 0.0
558566
.INDENT 3.5
559567
.sp
560568
.nf
561569
.ft C
562-
$ cat ~/.config/python\-bugzilla/bugzillarc
563-
564570
[bugzilla.example.com]
565-
api_key=YOUR_API_KEY
571+
api_key=INSERT\-YOUR\-API\-KEY\-HERE
572+
573+
[bugzilla.redhat.com]
574+
api_key=MY\-REDHAT\-API\-KEY\-BLAH
566575
.ft P
567576
.fi
568577
.UNINDENT
569578
.UNINDENT
570579
.sp
571-
Replace \(aqbugzilla.example.com\(aq with your bugzilla host name, and
572-
YOUR_API_KEY with the generated API Key from the Web UI.
580+
The sections must be hostnames. Other values that can be
581+
set per hostname section are
582+
.INDENT 0.0
583+
.IP \(bu 2
584+
\fBuser\fP: default auth username
585+
.IP \(bu 2
586+
\fBpassword\fP: default auth password
587+
.IP \(bu 2
588+
\fBcert\fP: default client side certificate
589+
.UNINDENT
590+
.sp
591+
A \fB[DEFAULTS]\fP section is also accepted, which takes the following
592+
values:
593+
.INDENT 0.0
594+
.IP \(bu 2
595+
\fBurl\fP: default bugzilla URL
596+
.UNINDENT
597+
.SH AUTHENTICATION CACHE AND API KEYS
598+
.sp
599+
Some command usage will require an active login to the bugzilla
600+
instance. For example, if the bugzilla instance has some private bugs,
601+
those bugs will be missing from \(aqquery\(aq output if you do not have an
602+
active login.
573603
.sp
574-
Alternatively, you can use \(aqbugzilla login \-\-api\-key\(aq, which will ask
575-
for the API key, and save it to bugzillarc for you.
604+
If you are connecting to a bugzilla 5.0 or later instance, the best
605+
option is to use bugzilla API keys. From the bugzilla web UI, log in,
606+
navigate to Preferences\->API Keys, and generate a key (it will be a long
607+
string of characters and numbers).
576608
.sp
577-
For older bugzilla instances, you will need to cache a login cookie or
578-
token with the "login" subcommand or the "\-\-login" argument.
609+
Then use \(aqbugzilla \-\-bugzilla URL login \-\-api\-key\(aq, which will ask
610+
for the API key, and save it to \fBbugzillarc\fP for you.
611+
.sp
612+
For older bugzilla instances, you will need to cache a login token
613+
with the \(dqlogin\(dq subcommand or the \(dq\-\-login\(dq argument.
579614
.sp
580615
Additionally, the \-\-no\-cache\-credentials option will tell the bugzilla
581616
tool to \fInot\fP save or use any authentication cache, including the
582-
bugzillarc file.
617+
\fBbugzillarc\fP file.
583618
.SH EXAMPLES
584619
.nf
585620
bugzilla query \-\-bug_id 62037
@@ -590,17 +625,17 @@ bugzilla login
590625

591626
bugzilla new \-p Fedora \-v rawhide \-c python\-bugzilla \e
592627
.in +2
593-
\-\-summary "python\-bugzilla causes headaches" \e
594-
\-\-comment "python\-bugzilla made my brain hurt when I used it."
628+
\-\-summary \(dqpython\-bugzilla causes headaches\(dq \e
629+
\-\-comment \(dqpython\-bugzilla made my brain hurt when I used it.\(dq
595630

596631
.in -2
597-
bugzilla attach \-\-file ~/Pictures/cam1.jpg \-\-desc "me, in pain"
632+
bugzilla attach \-\-file ~/Pictures/cam1.jpg \-\-desc \(dqme, in pain\(dq
598633
$BUGID
599634

600635
bugzilla attach \-\-getall $BUGID
601636

602-
bugzilla modify \-\-close NOTABUG \-\-comment "Actually, you\(aqre
603-
hungover." $BUGID
637+
bugzilla modify \-\-close NOTABUG \-\-comment \(dqActually, you\(aqre
638+
hungover.\(dq $BUGID
604639
.fi
605640
.sp
606641
.SH EXIT STATUS
@@ -616,6 +651,7 @@ Please report any bugs as github issues at
616651
.SH SEE ALSO
617652
.sp
618653
\fI\%https://bugzilla.readthedocs.io/en/latest/api/index.html\fP
619-
\fI\%https://bugzilla.redhat.com/docs/en/html/api/Bugzilla/WebService/Bug.html\fP
654+
.sp
655+
\fI\%https://bugzilla.redhat.com/docs/en/html/api/core/v1/bug.html\fP
620656
.\" Generated by docutils manpage writer.
621657
.

0 commit comments

Comments
 (0)