piknik.1 (8721B)
1 .TH piknik 1 2 3 4 .SH NAME 5 piknik \- Issue tracking using CLI 6 7 8 .SH SYNOPSIS 9 10 .SY piknik 11 add [ -d store_dir ] [ --alias issue_alias ] caption 12 .YS 13 14 .SY piknik 15 show [ -i issue_id ] [ -d store_dir ] [ -r renderer ] [ --state state ] 16 .YS 17 18 .SY piknik 19 show [ -d store_dir ] -r html [ -o output_dir ] 20 .YS 21 22 .SY piknik 23 mod < -i issue_id > [ -d store_dir ] [ --state state ] [ -t tag ] [ -u tag ] [ --dep issue_id ] [ --undep issue_id ] [ --assign id ] [ --unassign id ] 24 .YS 25 26 .SY piknik 27 mod < -i issue_id > [ -d store_dir ] [ --block ] 28 .YS 29 30 .SY piknik 31 mod < -i issue_id > [ -d store_dir ] [ --unblock ] 32 .YS 33 34 .SY piknik 35 comment < -i issue_id > [ -d store_dir ] [ [ -x "text content" ... ] [ -y file ... ] ... ] 36 .YS 37 38 39 .SH DESCRIPTION 40 .P 41 This tool enables issue tracking by command line interface. 42 .P 43 After an issue has been created it can move through different pre-defined, kanban-like states. They can also be tagged, assigned and commented on. 44 45 46 .SH COMMANDS 47 48 The following commands are available: 49 50 .IP 51 \fBshow\fP \- Output all issues for all or selected issue states. 52 .IP 53 \fBadd\fP \- Propose a new issue. 54 .IP 55 \fBmod\fP \- Tag, assign, set dependencies and modify state of an existing issue. 56 .IP 57 \fBcomment\fP \- Add comment to an existing issue. 58 59 60 .SS Common options 61 62 .TP 63 \fB-d\fP 64 Issue state store directory. 65 66 .TP 67 .TQ 68 .B -h 69 .TQ 70 .B --help 71 Command help summary. 72 73 .TP 74 .TQ 75 .BI -i issue_id 76 .TQ 77 .BI --issue-id issue_id 78 Issue to operate on. Argument can be issue alias or full issue uuid. Only available with \fBmod\fP and \fBcomment\fP. 79 80 .TP 81 .TQ 82 .BI -s state 83 .TQ 84 .BI --state state 85 Limit output to issue having the given \fIstate\fP. (Only valid with \fBshow\fP or \fBmod\fP). 86 87 .TP 88 -v 89 Write debugging log to standard error. 90 91 .SS Options for add 92 93 .TP 94 \fB--alias\fP 95 Specify alias used to refer to issue when using \fB-i\fP. If not specified, an alias will be auto-generated. See \fBALIAS\fP. Only available with \fBadd\fP. 96 97 98 .SS Options for show 99 100 .TP 101 .TQ 102 .B -f 103 .TQ 104 .B --files 105 Save attachments to filesystem. Can be used in the context of viewing details of a single issue, or in conjunction with \fB-r html -o\fP. Only available with \fBshow\fP. 106 107 .TP 108 .TQ 109 .BI -o dir 110 .TQ 111 .BI --files-dir dir 112 Output issue details to individual files in \fIdir\fP. Only available with \fBshow -r html ...\fP. 113 114 .TP 115 .TQ 116 .BI -r format 117 .TQ 118 .BI --renderer format 119 Output format. Valid values are \fIplain\fP and \fIhtml\fP. 120 121 .TP 122 .B -reverse 123 Sort comments with oldest first. Only available with \fBshow\fP. 124 125 .TP 126 .B --show-finished 127 Include issues with state \fBFINISHED\fP in output. Only available with \fBshow\fP. 128 129 130 .SS Options for mod 131 132 .TP 133 .BI --assign key_id 134 Assign the issue to entity defined by \fIkey_id\fP. If it is the first assignment for an issue, the assigned will become the issue \fIowner\fP (see \fB--owner\fP and \fBACTIONS/Assignment\fP below. Only available with \fBmod\fP. 135 136 .TP 137 .BI --block 138 Set the \fBBLOCKED\fP state on the issue. Preserves the previous state; a following \fB--unblock\fP instruction will return the issue to the pre-blocked state. Only available with \fBmod\fP. 139 140 .TP 141 .BI --dep issue_id 142 Make the current issue (identified by \fB-i\fP dependent on \fIissue_id\fP. Only available with \fBmod\fP. 143 144 .TP 145 .BI --owner key_id 146 Set the entity represented by \fIkey_id\fP as issue owner. 147 148 149 .TP 150 .TQ 151 .BI -t tag 152 .TQ 153 .BI --tag tag 154 Add the given tag to the issue. Only available with \fBmod\fP. 155 156 .TP 157 .BI --unassign key_id 158 Remove the assignment of the issue to entity defined by \fIkey_id\fP. Only available with \fBmod\fP. 159 160 .TP 161 .BI --unblock 162 Remove block on issue. Will return the issue to its previous state (before the block). Only available with \fBmod\fP. 163 164 165 .TP 166 .BI --undep issue_id 167 Remove dependency on \fIissue_id\fP. Only available with \fBmod\fP. 168 169 .TP 170 .TQ 171 .BI -u tag 172 .TQ 173 .BI --untag tag 174 Remove the given tag from the issue. Only available with \fBmod\fP. 175 176 177 .SS Options for comment 178 179 .TP 180 .TQ 181 .BI -s pgp_key_fingerprint 182 .TQ 183 .BI --sign-as pgp_key_fingerprint 184 Use the private key matching the fingerprint to sign (instead of the default key). Only available with \fBcomment\fP. 185 186 .TP 187 .TQ 188 .BI -x "text" 189 .TQ 190 .BI --text "text" 191 Add a text content part to the comment. Must be enclosed by double quotes. Only available with \fBcomment\fP. 192 193 .TP 194 .TQ 195 .BI -y file 196 .TQ 197 .BI --file file 198 Add file as content part to the comment. Can be any type of file. Only available with \fBcomment\fP. See the \fBCOMMENT\fP section for more information. 199 200 201 202 .SH STATES 203 204 The tracking of the issue lifetime is organized using a pre-defined set of kanban-like states. 205 206 .TP 207 .B PROPOSED 208 The initial state of an issue after being created by \fBpiknik add\fP. Is intended for review by issue board moderator. 209 210 .TP 211 .B BACKLOG 212 The initial state of an issue after being "accepted" by a moderator. 213 214 .TP 215 .B PENDING 216 An issue has been queued for imminent processing. 217 218 .TP 219 .B DOING 220 An issue is currently being worked on. 221 222 .TP 223 .B REVIEW 224 Work that was done on an issue is currently in review. 225 226 .TP 227 .B BLOCKED 228 Progress on a \fBPENDING\fP issue is currently not possible. 229 230 .TP 231 .B FINISHED 232 Processing of an issue has been completed. 233 234 235 .SH ACTIONS 236 .P 237 238 .SS Assignment 239 .P 240 Indicates an individual or entity that is responsible for processing the issue. 241 .P 242 Currently assigments are defined as hexadecimal values. By convention, the value should correspond to e.g. a public key or a key fingerprint (e.g. PGP). \fBpiknik\fP will check that the value is hexadecimal, but will not do additional verification. 243 .P 244 The first assigned entity to an issue automatically becomes the issue owner. The issue ownership may be changed using \fB--owner\fP, but ownership cannot be removed entirely after the initial assignment. 245 246 .SS Tagging 247 .P 248 Any issue may be assigned any number of tags. Tags may be added and removed individually. 249 250 251 .SS Dependencies 252 .P 253 Any issue may be set as dependent on another issue. Dependencies may be set or unset. Dependencies must be manually managed, and will not be magically removed as a side-effect of state transitions. 254 255 256 .SH COMMENTING 257 .P 258 Comments are stored as email-like Multipart MIME message logs. They may include any number of plaintext and file attachment parts intermingled. 259 260 All comments must be \fBsigned\fP using a PGP key. Unless the \fB-s\fP flag is used, the default signing key will be used. It is currently not possible to comment without a PGP key. 261 262 263 .SH RENDERING 264 .P 265 There are currently two rendering options for displaying issue indices and individual issue details, \fIplain\fP (plain text) and \fIhtml\fP. 266 Ideosyncracies for each are described below. 267 268 .SS PLAIN 269 .P 270 When listing the issue index, output will be in the form: 271 272 .EX 273 [STATE] 274 <caption> <tags> <uuid> [(alias)] 275 .EE 276 277 Per-issue render should be self-explanatory. 278 279 .SS HTML 280 .P 281 If rendered with \fB-o\fP \fIoutdir\fP it creates a browseable version of individual issues from the issue index in the specified directory. 282 .P 283 Some image types will by default be displayed inline. There is currently no way to toggle this behavior. 284 285 286 .SH EXAMPLE 287 .P 288 This example illustrates a possible lifetime of an issue. 289 290 .EX 291 # propose new issue 292 piknik add Title describing the issue --alias myissue 293 294 # accept proposed issue (move to backlog state) 295 piknik mod -i myissue --accept 296 297 # move the issue to state "DOING" 298 piknik mod -i myissue --state doing 299 300 # tag the issue as a "BUG" 301 piknik mod -i myissue --tag bug 302 303 # Add a signed text comment to the issue 304 piknik comment -i myissue -x "This is a text comment" 305 306 # Add a comment with intermixed text and attachment contents to the issue 307 piknik comment -i myissue -x "This is a text comment with two attachments " -y attachment.png -y another.pdf -x "This text follows the attachments" 308 309 # Write index of all issues as plain text to standard output 310 piknik show 311 312 # Write issue details as plain text to standard output 313 piknik show -i myissue 314 315 # Write index of all issues as html to standard output 316 piknik show --render html 317 318 # Write index and individual issue as browseable html to directory "outdir" 319 piknik show --render html -o outdir 320 321 # Mark issue as finished 322 piknik mod -i myissue --finish 323 .EE 324 325 326 .SH KNOWN ISSUES 327 Currently issues are tracked using - in fact - \fBpiknik\fP. An HTML (read-only) render can be found at 328 .UR https://holbrook.no/issues/piknik 329 .UE https://holbrook.no/issues/piknik 330 .IP 331 332 333 .SH LICENSE 334 335 This documentation and its source is licensed under the Creative Commons Attribution-Sharealike 4.0 International license. 336 337 The source code of the tool this documentation describes is licensed under the GNU General Public License 3.0. 338 339 340 .SH COPYRIGHT AND CONTACT 341 342 .MT dev@holbrook.no 343 Louis Holbrook 344 .ME 345 346 .UR https://holbrook.no 347 .UE https://holbrook.no 348 349 .P 350 PGP: 59A844A484AC11253D3A3E9DCDCBD24DD1D0E001 351 352 353 .SH SOURCE CODE 354 355 https://git.defalsify.org/piknik