# NAME
piknik - Issue tracking using CLI
# SYNOPSIS
**piknik** add \[ -d store_dir \] \[ \--alias issue_alias \] caption
**piknik** show \[ -i issue_id \] \[ -d store_dir \] \[ -r renderer \]
\[ \--state state \]
**piknik** show \[ -d store_dir \] -r html \[ -o output_dir \]
**piknik** mod \< -i issue_id \> \[ -d store_dir \] \[ \--state state
\] \[ -t tag \] \[ -u tag \] \[ \--dep issue_id \] \[ \--undep issue_id
\] \[ \--assign id \] \[ \--unassign id \]
**piknik** mod \< -i issue_id \> \[ -d store_dir \] \[ \--block \]
**piknik** mod \< -i issue_id \> \[ -d store_dir \] \[ \--unblock \]
**piknik** comment \< -i issue_id \> \[ -d store_dir \] \[ \[ -x \"text
content\" \... \] \[ -y file \... \] \... \]
# DESCRIPTION
This tool enables issue tracking by command line interface.
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.
# COMMANDS
The following commands are available:
> **show** - Output all issues for all or selected issue states.
>
> **add** - Propose a new issue.
>
> **mod** - Tag, assign, set dependencies and modify state of an
> existing issue.
>
> **comment** - Add comment to an existing issue.
## Common options
**-d**
: Issue state store directory.
**-h**
**\--help** Command help summary.
**-i***issue_id*
**\--issue-id***issue_id* Issue to operate on. Argument can be issue
alias or full issue uuid. Only available with **mod** and **comment**.
**-s***state*
**\--state***state* Limit output to issue having the given *state*.
(Only valid with **show** or **mod**).
-v
: Write debugging log to standard error.
## Options for add
**\--alias**
: Specify alias used to refer to issue when using **-i**. If not
specified, an alias will be auto-generated. See **ALIAS**. Only
available with **add**.
## Options for show
**-f**
**\--files** Save attachments to filesystem. Can be used in the context
of viewing details of a single issue, or in conjunction with **-r html
-o**. Only available with **show**.
**-o***dir*
**\--files-dir***dir* Output issue details to individual files in *dir*.
Only available with **show -r html \...**.
**-r***format*
**\--renderer***format* Output format. Valid values are *plain* and
*html*.
**-reverse**
: Sort comments with oldest first. Only available with **show**.
**\--show-finished**
: Include issues with state **FINISHED** in output. Only available
with **show**.
## Options for mod
**\--assign***key_id*
: Assign the issue to entity defined by *key_id*. If it is the first
assignment for an issue, the assigned will become the issue *owner*
(see **\--owner** and **ACTIONS/Assignment** below. Only available
with **mod**.
**\--block**
: Set the **BLOCKED** state on the issue. Preserves the previous
state; a following **\--unblock** instruction will return the issue
to the pre-blocked state. Only available with **mod**.
**\--dep***issue_id*
: Make the current issue (identified by **-i** dependent on
*issue_id*. Only available with **mod**.
**\--owner***key_id*
: Set the entity represented by *key_id* as issue owner.
**-t***tag*
**\--tag***tag* Add the given tag to the issue. Only available with
**mod**.
**\--unassign***key_id*
: Remove the assignment of the issue to entity defined by *key_id*.
Only available with **mod**.
**\--unblock**
: Remove block on issue. Will return the issue to its previous state
(before the block). Only available with **mod**.
**\--undep***issue_id*
: Remove dependency on *issue_id*. Only available with **mod**.
**-u***tag*
**\--untag***tag* Remove the given tag from the issue. Only available
with **mod**.
## Options for comment
**-s***pgp_key_fingerprint*
**\--sign-as***pgp_key_fingerprint* Use the private key matching the
fingerprint to sign (instead of the default key). Only available with
**comment**.
**-x***text*
**\--text***text* Add a text content part to the comment. Must be
enclosed by double quotes. Only available with **comment**.
**-y***file*
**\--file***file* Add file as content part to the comment. Can be any
type of file. Only available with **comment**. See the **COMMENT**
section for more information.
# STATES
The tracking of the issue lifetime is organized using a pre-defined set
of kanban-like states.
**PROPOSED**
: The initial state of an issue after being created by **piknik add**.
Is intended for review by issue board moderator.
**BACKLOG**
: The initial state of an issue after being \"accepted\" by a
moderator.
**PENDING**
: An issue has been queued for imminent processing.
**DOING**
: An issue is currently being worked on.
**REVIEW**
: Work that was done on an issue is currently in review.
**BLOCKED**
: Progress on a **PENDING** issue is currently not possible.
**FINISHED**
: Processing of an issue has been completed.
# ACTIONS
## Assignment
Indicates an individual or entity that is responsible for processing the
issue.
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). **piknik** will check that the value is hexadecimal, but
will not do additional verification.
The first assigned entity to an issue automatically becomes the issue
owner. The issue ownership may be changed using **\--owner**, but
ownership cannot be removed entirely after the initial assignment.
## Tagging
Any issue may be assigned any number of tags. Tags may be added and
removed individually.
## Dependencies
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.
# COMMENTING
Comments are stored as email-like Multipart MIME message logs. They may
include any number of plaintext and file attachment parts intermingled.
All comments must be **signed** using a PGP key. Unless the **-s** flag
is used, the default signing key will be used. It is currently not
possible to comment without a PGP key.
# RENDERING
There are currently two rendering options for displaying issue indices
and individual issue details, *plain* (plain text) and *html*.
Ideosyncracies for each are described below.
## PLAIN
When listing the issue index, output will be in the form:
[STATE]
<caption> <tags> <uuid> [(alias)]
Per-issue render should be self-explanatory.
## HTML
If rendered with **-o** *outdir* it creates a browseable version of
individual issues from the issue index in the specified directory.
Some image types will by default be displayed inline. There is currently
no way to toggle this behavior.
# EXAMPLE
This example illustrates a possible lifetime of an issue.
# propose new issue
piknik add Title describing the issue --alias myissue
# accept proposed issue (move to backlog state)
piknik mod -i myissue --accept
# move the issue to state "DOING"
piknik mod -i myissue --state doing
# tag the issue as a "BUG"
piknik mod -i myissue --tag bug
# Add a signed text comment to the issue
piknik comment -i myissue -x "This is a text comment"
# Add a comment with intermixed text and attachment contents to the issue
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"
# Write index of all issues as plain text to standard output
piknik show
# Write issue details as plain text to standard output
piknik show -i myissue
# Write index of all issues as html to standard output
piknik show --render html
# Write index and individual issue as browseable html to directory "outdir"
piknik show --render html -o outdir
# Mark issue as finished
piknik mod -i myissue --finish
# KNOWN ISSUES
Currently issues are tracked using - in fact - **piknik**. An HTML
(read-only) render can be found at
[](https://holbrook.no/issues/piknik)https://holbrook.no/issues/piknik
# LICENSE
This documentation and its source is licensed under the Creative Commons
Attribution-Sharealike 4.0 International license.
The source code of the tool this documentation describes is licensed
under the GNU General Public License 3.0.
# COPYRIGHT AND CONTACT
[Louis Holbrook](mailto:dev@holbrook.no)
[](https://holbrook.no)https://holbrook.no
PGP: 59A844A484AC11253D3A3E9DCDCBD24DD1D0E001
# SOURCE CODE
https://git.defalsify.org/piknik
# ABOUT THIS DOCUMENT
This document was generated using `pandoc -f man -t markdown ...`
Raw data
{
"_id": null,
"home_page": "https://git.defalsify.org/eth-cache",
"name": "piknik",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "bugs,issues,tracker,productivity,git,pgp",
"author": "Louis Holbrook",
"author_email": "dev@holbrook.no",
"download_url": "https://files.pythonhosted.org/packages/2c/d2/34b35cda913bd21bdc2b7afb74e62d55cfce0f254e64f30b1bfaf52ed597/piknik-0.3.17.tar.gz",
"platform": null,
"description": "# NAME\n\npiknik - Issue tracking using CLI\n\n# SYNOPSIS\n\n**piknik** add \\[ -d store_dir \\] \\[ \\--alias issue_alias \\] caption\n\n**piknik** show \\[ -i issue_id \\] \\[ -d store_dir \\] \\[ -r renderer \\]\n\\[ \\--state state\u00a0\\]\n\n**piknik** show \\[ -d store_dir \\] -r html \\[ -o output_dir \\]\n\n**piknik** mod \\< -i issue_id \\> \\[ -d store_dir \\] \\[ \\--state state\n\\]\u00a0\\[ -t tag \\] \\[ -u tag \\]\u00a0\\[ \\--dep issue_id \\] \\[ \\--undep issue_id\n\\] \\[ \\--assign id \\] \\[ \\--unassign id \\]\n\n**piknik** mod \\< -i issue_id \\> \\[ -d store_dir \\] \\[ \\--block \\]\n\n**piknik** mod \\< -i issue_id \\> \\[ -d store_dir \\] \\[ \\--unblock \\]\n\n**piknik** comment \\< -i issue_id \\> \\[ -d store_dir \\] \\[\u00a0\\[ -x \\\"text\ncontent\\\" \\... \\] \\[ -y file \\... \\] \\...\u00a0\\]\n\n# DESCRIPTION\n\nThis tool enables issue tracking by command line interface.\n\nAfter an issue has been created it can move through different\npre-defined, kanban-like states. They can also be tagged, assigned and\ncommented on.\n\n# COMMANDS\n\nThe following commands are available:\n\n> **show** - Output all issues for all or selected issue states.\n>\n> **add** - Propose a new issue.\n>\n> **mod** - Tag, assign, set dependencies and modify state of an\n> existing issue.\n>\n> **comment** - Add comment to an existing issue.\n\n## Common options\n\n**-d**\n\n: Issue state store directory.\n\n**-h**\n\n**\\--help** Command help summary.\n\n**-i***issue_id*\n\n**\\--issue-id***issue_id* Issue to operate on. Argument can be issue\nalias or full issue uuid. Only available with **mod** and **comment**.\n\n**-s***state*\n\n**\\--state***state* Limit output to issue having the given *state*.\n(Only valid with **show** or **mod**).\n\n-v\n\n: Write debugging log to standard error.\n\n## Options for add\n\n**\\--alias**\n\n: Specify alias used to refer to issue when using **-i**. If not\n specified, an alias will be auto-generated. See **ALIAS**. Only\n available with **add**.\n\n## Options for show\n\n**-f**\n\n**\\--files** Save attachments to filesystem. Can be used in the context\nof viewing details of a single issue, or in conjunction with **-r html\n-o**. Only available with **show**.\n\n**-o***dir*\n\n**\\--files-dir***dir* Output issue details to individual files in *dir*.\nOnly available with **show -r html \\...**.\n\n**-r***format*\n\n**\\--renderer***format* Output format. Valid values are *plain* and\n*html*.\n\n**-reverse**\n\n: Sort comments with oldest first. Only available with **show**.\n\n**\\--show-finished**\n\n: Include issues with state **FINISHED** in output. Only available\n with **show**.\n\n## Options for mod\n\n**\\--assign***key_id*\n\n: Assign the issue to entity defined by *key_id*. If it is the first\n assignment for an issue, the assigned will become the issue *owner*\n (see **\\--owner** and **ACTIONS/Assignment** below. Only available\n with **mod**.\n\n**\\--block**\n\n: Set the **BLOCKED** state on the issue. Preserves the previous\n state; a following **\\--unblock** instruction will return the issue\n to the pre-blocked state. Only available with **mod**.\n\n**\\--dep***issue_id*\n\n: Make the current issue (identified by **-i** dependent on\n *issue_id*. Only available with **mod**.\n\n**\\--owner***key_id*\n\n: Set the entity represented by *key_id* as issue owner.\n\n**-t***tag*\n\n**\\--tag***tag* Add the given tag to the issue. Only available with\n**mod**.\n\n**\\--unassign***key_id*\n\n: Remove the assignment of the issue to entity defined by *key_id*.\n Only available with **mod**.\n\n**\\--unblock**\n\n: Remove block on issue. Will return the issue to its previous state\n (before the block). Only available with **mod**.\n\n**\\--undep***issue_id*\n\n: Remove dependency on *issue_id*. Only available with **mod**.\n\n**-u***tag*\n\n**\\--untag***tag* Remove the given tag from the issue. Only available\nwith **mod**.\n\n## Options for comment\n\n**-s***pgp_key_fingerprint*\n\n**\\--sign-as***pgp_key_fingerprint* Use the private key matching the\nfingerprint to sign (instead of the default key). Only available with\n**comment**.\n\n**-x***text*\n\n**\\--text***text* Add a text content part to the comment. Must be\nenclosed by double quotes. Only available with **comment**.\n\n**-y***file*\n\n**\\--file***file* Add file as content part to the comment. Can be any\ntype of file. Only available with **comment**. See the **COMMENT**\nsection for more information.\n\n# STATES\n\nThe tracking of the issue lifetime is organized using a pre-defined set\nof kanban-like states.\n\n**PROPOSED**\n\n: The initial state of an issue after being created by **piknik add**.\n Is intended for review by issue board moderator.\n\n**BACKLOG**\n\n: The initial state of an issue after being \\\"accepted\\\" by a\n moderator.\n\n**PENDING**\n\n: An issue has been queued for imminent processing.\n\n**DOING**\n\n: An issue is currently being worked on.\n\n**REVIEW**\n\n: Work that was done on an issue is currently in review.\n\n**BLOCKED**\n\n: Progress on a **PENDING** issue is currently not possible.\n\n**FINISHED**\n\n: Processing of an issue has been completed.\n\n# ACTIONS\n\n## Assignment\n\nIndicates an individual or entity that is responsible for processing the\nissue.\n\nCurrently assigments are defined as hexadecimal values. By convention,\nthe value should correspond to e.g. a public key or a key fingerprint\n(e.g. PGP). **piknik** will check that the value is hexadecimal, but\nwill not do additional verification.\n\nThe first assigned entity to an issue automatically becomes the issue\nowner. The issue ownership may be changed using **\\--owner**, but\nownership cannot be removed entirely after the initial assignment.\n\n## Tagging\n\nAny issue may be assigned any number of tags. Tags may be added and\nremoved individually.\n\n## Dependencies\n\nAny issue may be set as dependent on another issue. Dependencies may be\nset or unset. Dependencies must be manually managed, and will not be\nmagically removed as a side-effect of state transitions.\n\n# COMMENTING\n\nComments are stored as email-like Multipart MIME message logs. They may\ninclude any number of plaintext and file attachment parts intermingled.\n\nAll comments must be **signed** using a PGP key. Unless the **-s** flag\nis used, the default signing key will be used. It is currently not\npossible to comment without a PGP key.\n\n# RENDERING\n\nThere are currently two rendering options for displaying issue indices\nand individual issue details, *plain* (plain text) and *html*.\nIdeosyncracies for each are described below.\n\n## PLAIN\n\nWhen listing the issue index, output will be in the form:\n\n [STATE]\n <caption>\t<tags>\t<uuid>\t[(alias)]\n\nPer-issue render should be self-explanatory.\n\n## HTML\n\nIf rendered with **-o** *outdir* it creates a browseable version of\nindividual issues from the issue index in the specified directory.\n\nSome image types will by default be displayed inline. There is currently\nno way to toggle this behavior.\n\n# EXAMPLE\n\nThis example illustrates a possible lifetime of an issue.\n\n # propose new issue\n piknik add Title describing the issue --alias myissue\n\n # accept proposed issue (move to backlog state)\n piknik mod -i myissue --accept\n\n # move the issue to state \"DOING\"\n piknik mod -i myissue --state doing\n\n # tag the issue as a \"BUG\"\n piknik mod -i myissue --tag bug\n\n # Add a signed text comment to the issue\n piknik comment -i myissue -x \"This is a text comment\"\n\n # Add a comment with intermixed text and attachment contents to the issue\n 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\"\n\n # Write index of all issues as plain text to standard output\n piknik show\n\n # Write issue details as plain text to standard output\n piknik show -i myissue\n\n # Write index of all issues as html to standard output\n piknik show --render html\n\n # Write index and individual issue as browseable html to directory \"outdir\"\n piknik show --render html -o outdir\n\n # Mark issue as finished\n piknik mod -i myissue --finish\n\n# KNOWN ISSUES\n\nCurrently issues are tracked using - in fact - **piknik**. An HTML\n(read-only) render can be found at\n[](https://holbrook.no/issues/piknik)https://holbrook.no/issues/piknik\n\n# LICENSE\n\nThis documentation and its source is licensed under the Creative Commons\nAttribution-Sharealike 4.0 International license.\n\nThe source code of the tool this documentation describes is licensed\nunder the GNU General Public License 3.0.\n\n# COPYRIGHT AND CONTACT\n\n[Louis Holbrook](mailto:dev@holbrook.no)\n\n[](https://holbrook.no)https://holbrook.no\n\nPGP: 59A844A484AC11253D3A3E9DCDCBD24DD1D0E001\n\n# SOURCE CODE\n\nhttps://git.defalsify.org/piknik\n\n\n# ABOUT THIS DOCUMENT\n\nThis document was generated using `pandoc -f man -t markdown ...`\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "CLI issue tracker",
"version": "0.3.17",
"project_urls": {
"Homepage": "https://git.defalsify.org/eth-cache"
},
"split_keywords": [
"bugs",
"issues",
"tracker",
"productivity",
"git",
"pgp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2cd234b35cda913bd21bdc2b7afb74e62d55cfce0f254e64f30b1bfaf52ed597",
"md5": "76209f9e2f9c732da883a96f412176f9",
"sha256": "13654c9d6bee63a9f2d373c4e04133af560d4920a1d2bd99bde290fb01493525"
},
"downloads": -1,
"filename": "piknik-0.3.17.tar.gz",
"has_sig": false,
"md5_digest": "76209f9e2f9c732da883a96f412176f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 40184,
"upload_time": "2023-08-10T08:14:25",
"upload_time_iso_8601": "2023-08-10T08:14:25.445209Z",
"url": "https://files.pythonhosted.org/packages/2c/d2/34b35cda913bd21bdc2b7afb74e62d55cfce0f254e64f30b1bfaf52ed597/piknik-0.3.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-10 08:14:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "piknik"
}
JSON