In order to have a solid and nice design for jic and to be prepared for
bazaar style of development, I'm working on a full CLI specification for
jic. This is a first RFC for the document which is still of a "work in
progress" quality. I just want to "share early, share often".
I need all your thoughts and comments before I implement all that stuff.
Please throw your rotten tomatoes (or sweet mangos) at me! :)
And there is no TL;DR version of this document, sorry.
Signed-off-by: Serge Broslavsky <serge.broslavsky(a)linaro.org>
---
docs/command-line-interface | 1732 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 1732 insertions(+)
create mode 100644 docs/command-line-interface
diff --git a/docs/command-line-interface b/docs/command-line-interface
new file mode 100644
index 0000000..4f28939
--- /dev/null
+++ b/docs/command-line-interface
@@ -0,0 +1,1732 @@
+jic CLI (Command Line Interface) Specification
+----------------------------------------------
+
+1. ABSTRACT
+
+In order to help jic users learning its interface quickly and
+successfully by reusing their existing experience with other engineering
+tools, jic needs a well designed command line interface that is
+intuitive to use.
+
+Key qualities of desired CLI:
+
+1.1. Well-thought-out structure of the command line
+
+ All commands should be structured the same way, switches should have
+ the same meaning for all commands (when applicable) and different
+ functional segments should be grouped together for ease of use.
+
+1.2. Support for terminal text attributes and colors
+
+ When output goes to a terminal, user defined formatting should be
+ supported (attributes and colors).
+
+1.3. Well-thought-out use of pipes
+
+ All commands besides their ability to work with terminals, should
+ also be capable of both - receiving their input from and putting
+ their output into shell pipes.
+
+1.4. Well-thought-out use of command line completion
+
+ All commands should be provided with proper command line completion
+ for those shells that support this feature (bash is to start with).
+
+1.5. A decent man page
+
+ A decent CLI tool should have a decent man documentation.
+
+This document describes such a CLI.
+
+
+2. CLI STRUCTURE
+
+The structure of command line corresponds to the commonly used one:
+
+ $ jic <options> [<subject_of_action>] [<command> [<args> ...]]
+
+ where:
+
+ <options>
+ are listed in a separate OPTIONS as well as for each
+ command further below
+
+ <subject_of_action>
+ is one of the following:
+
+ <missing> equals to "issue" subject of action
+
+ "issue" for dealing with issues; the default
+ subject of action
+
+ <command> being one of (non-ambiguous shorter
+ versions are also accepted):
+
+ TODO: add time log support
+
+ "clone" for cloning issues
+ "create" for creating new issues
+ "delete" for deleting issues
+ "edit" for editing issues
+ "fetch" for caching issues locally
+ "fields" for listing issues' fields
+ "forget" for removing issues from the
+ local cache
+ "list" for listing issues
+ "link" for linking the issue to another
+ one
+ "move" for moving issues between types
+ and projects
+ "pull" for refreshing locally cached
+ issues
+ "push" for pushing local changes to the
+ server
+ "revert" for reverting one or more
+ changes made to issues
+ "show" for showing the issue
+ "transition" for transitioning issues
+ into JIRA workflow states
+ "tree" for showing the issue hierarchy
+ "unlink" for unlinking the issue from
+ another ones
+
+ "comment" for dealing with comments
+
+ <command> being one of:
+
+ "add" for adding a new comment
+ "delete" for deleting an existing comment
+ "edit" for editing an existing comment
+ "reply" for replying to an existing
+ comment (the quoted text is
+ inserted for editing)
+ "show" shows comments as requested
+
+ "link" for dealing with links
+
+ <command> being one of:
+
+ "create" for creating links between
+ issues
+ "delete" for deleting links between
+ issues
+ "list" for listing links for issues
+
+ "report" for dealing with reports
+
+ <command> being one of:
+
+ "create" for creating a report definition
+ "delete" for deleting a report definition
+ "edit" for editing a report definition
+ "generate" for generating a report
+
+ "template" for managing templates
+
+ <command> being one of:
+
+ "create" for creating a template
+ "delete" for deleting a template
+ "edit" for editing a template
+
+ "server" for managing servers
+
+ <command> being one of:
+
+ "add" for adding a server
+ "dance" for performing an oauth-dance
+ "delete" for deleting a server definition
+ "edit" for editing a server definition
+ "list" for listing known servers
+ "show" for showing a server definition
+
+ "list" for dealing with issue lists
+
+ <command> being one of:
+
+ "add" for adding issues into the list
+ "create" for creating a list of issues
+ "delete" for deleting a list of issues
+ "edit" for editing a list of issues
+ "list" for listing the issue lists
+ "receive" for creating a list of issues
+ from the information sent by the
+ "send" command
+ "remove" for removing issues from the
+ "send" for emailing a list of issues
+ "show" for showing the issues from
+ issue lists
+
+
+ "configuration" for dealing with configuration settings
+
+ <command> being one of:
+
+ "set" for setting configuration values
+ "show" for showing configuration values
+ "unset" for resetting configuration
+ values to their default values
+
+
+2.1. ISSUE COMMANDS
+
+ 2.1.1. CLONE
+
+ TODO: document
+
+ Examples:
+
+ # clone two issues using an editor to edit their clones'
+ # jicML representation
+ $ jic issue clone -e CARD-101 CARD-102
+
+ # clone an issue and change only it's component using pipes
+ # as action subject is omitted in this case, "issue" is
+ # assumed
+ $ echo "New component" | jic clone -F Component CARD-101
+
+
+ 2.1.2. CREATE
+
+ $ jic [issue] create <options> [<issue_key_list>]
+
+ creates one or more issues as requested using the information
+ provided by the means of:
+
+ * file with jicML representation of the issues being
+ created, which gets opened in the configured editor for
+ editing, and parsed and executed afterwards
+
+ any valid fields/issues can be added into or deleted
+ from the jicML file and desired issue field values
+ provided - all the requested modifications will be
+ performed in JIRA accordingly
+
+ if the file has not been changed or got truncated to
+ zero length, no operations will be performed
+
+ if there were errors reported by JIRA when trying to
+ apply the changes, an editor will be presented again
+ with unsuccessful parts of the change with inlined
+ error messages to allow the user correcting those errors
+ or cancelling the creation of the remainder of the
+ change set
+
+ * standard input
+
+ - if "-t" option is specified
+
+ values are read from the standard input and assigned
+ to the issue fields according to the order of
+ mentioning of those fields in the template
+
+ data from the standard input is expected to be a
+ steam of valid jicML values delimited by new line
+ characters; an empty line is treated as a request to
+ not update the corresponding field
+
+ if input provides less values than there are fields
+ in the template, all the remaining fields are left
+ intact
+
+ if input provides more values than needed according
+ to the template, then all the extra values are
+ appended to the last field's value
+
+ if input is a stream of jicML name:value pairs,
+ value assignment is done as in the case of none of
+ the options specified
+
+ - if "-F" option is specified
+
+ values are read from the standard input and assigned
+ to the issue fields listed by this option according
+ to the order of listing
+
+ data from the standard input is expected to be a
+ steam of valid jicML values delimited by new line
+ characters; an empty line is treated as a request
+ not to update the corresponding field
+
+ if input provides less values than there are fields
+ listed for this option, all the remaining fields are
+ assigned with the same value as the last one
+ received from the input
+
+ if input provides more values than needed according
+ to the template, then all the extra values are
+ appended to the last field's value using space as a
+ delimiter when needed
+
+ if input is a stream of jicML name:value pairs,
+ value assignment is done as in the case of none of
+ the options specified
+
+ - if none of the above are specified
+
+ fields and their respective values are read from the
+ standard input and assigned to corresponding issue
+ fields
+
+ data from the standard input is expected to be a
+ steam of valid jicML name:value pairs
+
+ if there were errors creating the issues in JIRA, the
+ command prints out the error messages and returns an
+ error code (TODO: specify)
+
+ New issues have issue keys that are composed according
+ to the following template:
+
+ <project_prefix>-NEW-<sequential_number>
+
+ where
+
+ <project_prefix> is defined in JIRA when
+ corresponding project gets created;
+ it is take from the parent issue
+
+ <sequential_number> is a one-based counter for all
+ the new issues defined in a
+ single jicML data set
+
+ options:
+
+ -d
+ --down
+ use children of the parent issue specified by other
+ means as parents for newly created issues; the number of
+ issues created for each parent depends on the number of
+ issue types specified using "-T" option
+
+ -D <issue_key_list>
+ --down-from <issue_key_list>
+ use children of the issues specified as parents
+ for newly created issues; the number of issues created
+ for each parent depends on the number of issue types
+ specified using "-T" option
+
+ -H <depth>
+ --depth <depth>
+ process as many levels up or down as specified; zero corresponds
+ only to the issue specified for -u or -d, immediate
+ parent/children correspond to depth 1, etc.
+
+ -e
+ --editor
+ invoke an editor to edit the jicML representation of the
+ issues being created before it gets parsed and executed
+
+ if file is not modified or is empty, the operation is
+ cancelled
+
+ -f <criteria_list>
+ --filter <criterion>
+ use only the issues matching the criteria as parents
+ for newly created issues; if multiple such options
+ specified, those criteria are combined using logical
+ "or" operation
+
+ -F <field_list>
+ --fields <field_list>
+ edit only the issue fields specified
+
+ overrides template (default or the one specified
+ explicitly using "-t" option) if specified
+
+ -k
+ --keys
+ get issue keys to be processed using the same method
+ (editor or standard input) as used for getting all the
+ other data for the operation
+
+ in this case all the non-empty lines of the input text
+ until the first empty line are interpreted as containing
+ a white-space or comma- separated issue keys; keys
+ listed this way are appended to the keys specified by
+ other means (arguments or options)
+
+ -L <link_type_list>
+ --link-type <link_type_list>
+ link newly created issues to their respective parent
+ issues using all the link types specified
+
+ -o
+ --online
+ perform an online operation (create issues on the
+ corresponding server as well as the local cache)
+
+ -O
+ --offline
+ perform an offline operation (create issues in the local
+ cache only)
+
+ -t <name>
+ --template <name>
+ create issues according to the template referred by <name>
+
+ -T <issue_type_list>
+ --issue-types <issue_type_list>
+ create as many new issues per each parent as the number
+ of specified issues types - one for each
+
+ -u <issue_key_list> --up <issue_key_list> process ancestors
+ of the issue specified by <issue_key>; the issue
+ specified is not processed
+
+ Examples:
+
+ # create two child issues of type "Sub-task" for CARD-100
+ # using an editor, using the default link type to link newly
+ # created issues to their parent and a default template
+ $ jic create -e -T Sub-task CARD-100
+
+ # create child issues of type "Sub-task" one for each child
+ # issue of the CARD-100 linking new issues to them using
+ # the link type specified while filling in only the Summary
+ # field
+ $ echo "Perform the preliminary research" | jic create \
+ -d CARD-100 -D 1 -T Sub-task -L implements -F Summary
+
+
+ 2.1.3. DELETE
+
+ TODO: document
+
+ Examples:
+
+ # delete the issue
+ $ jic issue delete CARD-100
+
+ # delete a couple of issues
+ $ jic delete CARD-100 CARD-101
+
+ # delete all the issues who's keys are listed in a text file
+ # this is an irreversible operation - be careful!
+ $ jic delete -k < massacre-victims
+
+
+ 2.1.4. EDIT
+
+ $ jic edit <options> [<issue_key_list>]
+
+ edits one or more issues specified using the information
+ provided by the means of:
+
+ * file with jicML representation of the issues being edited
+ opened in the configured editor for editing and parsed
+ afterwards
+
+ any valid fields/issues can be added into or deleted
+ from the file and issue field values changed to have
+ corresponding issues updated accordingly; in case if a
+ new issue is added it will be created too (see the
+ "issue create" command for details)
+
+ if the file has not been changed or got truncated to
+ zero length, no operations are performed
+
+ if there were errors reported by JIRA when trying to
+ apply the changes, an editor is presented with inlined
+ error messages to allow the user correcting those errors
+ or cancelling the erroneous bits of the change by not
+ changing the file
+
+ * standard input
+
+ - if "-t" option is specified
+
+ values are read from the standard input and assigned
+ to the issue fields according to the order of
+ mentioning of those fields in the template
+
+ data from the standard input is expected to be a
+ steam of valid jicML values delimited by new line
+ characters; an empty line is treated as a request to
+ not update the corresponding field
+
+ if input provides less values than there are fields
+ in the template, all the remaining fields are left
+ intact
+
+ if input provides more values than needed according
+ to the template, then all the extra values are
+ appended to the last field's value
+
+ if input is a stream of jicML name:value pairs,
+ value assignment is done as in the case of none of
+ the options specified
+
+ - if "-F" option is specified
+
+ values are read from the standard input and assigned
+ to the issue fields listed by this option according
+ to the order of listing
+
+ data from the standard input is expected to be a
+ steam of valid jicML values delimited by new line
+ characters; an empty line is treated as a request
+ not to update the corresponding field
+
+ if input provides less values than there are fields
+ listed for this option, all the remaining fields are
+ assigned with the same value as the last one
+ received from the input
+
+ if input provides more values than needed according
+ to the template, then all the extra values are
+ appended to the last field's value using space as a
+ delimiter when needed
+
+ if input is a stream of jicML name:value pairs,
+ value assignment is done as in the case of none of
+ the options specified
+
+ - if none of the above are specified
+
+ fields and their respective values are read from the
+ standard input and assigned to corresponding issue
+ fields
+
+ data from the standard input is expected to be a
+ steam of valid jicML name:value pairs
+
+ if there were errors applying the changes in JIRA, the
+ command prints out the error messages and returns an
+ error code (TODO: specify)
+
+ options:
+
+ -d <issue_key_list>
+ --down <issue_key_list>
+ process children of the parent specified by <issue_key>;
+ the issue specified is not processed
+
+ -D <depth>
+ --depth <depth>
+ process as many levels up or down as specified; zero
+ corresponds only to the issue specified for -u or -d,
+ immediate parent/children correspond to depth 1, etc.
+
+ -e
+ --editor
+ invoke an editor to edit the issues specified according
+ to the template (default one for the issue type or one
+ specified explicitly using "-t" option)
+
+ if file is not modified or is empty, the operation is
+ cancelled
+
+ -f <criteria>
+ --filter <criteria>
+ show only issues matching the criteria; if multiple
+ such options specified, those criteria are combined
+ using logical "or" operation
+
+ parent and child issues around those issues which are
+ not shown according to the criteria specified using this
+ option, are shown as connected (with an indication that
+ there are skipped issues)
+
+ -F <field_list>
+ --fields <field_list>
+ edit only the issue fields specified
+
+ overrides template (default or the one specified
+ explicitly using "-t" option) if specified
+
+ -k
+ --keys
+ get issue keys to be processed using the same method
+ (editor or standard input) as used for getting all the
+ other data for the operation
+
+ in this case all the non-empty lines of the input until
+ the first empty line are interpreted as containing a
+ white-space or comma- separated issue keys; keys listed
+ this way are appended to the keys specified by other
+ means (arguments or options)
+
+ -o
+ --online
+ perform an online operation (update the data on the
+ corresponding server as well as the local cache)
+
+ -O
+ --offline
+ perform an offline operation (update the data in the
+ local cache only)
+
+ -t <name>
+ --template <name>
+ edit issues according to the template referred by <name>
+
+ -u <issue_key_list>
+ --up <issue_key_list>
+ process ancestors of the issue specified by <issue_key>;
+ the issue specified is not processed
+
+ Examples:
+
+ # update two issues using an editor and a default template
+ $ jic edit -e CARD-100 CARD-101
+
+ # add FixVersion/s values for two cards using pipes
+ $ echo "+2014.12" | \
+ jic edit -F "FixVersion/s" CARD-100 CARD-101
+
+
+ 2.1.5. FETCH
+
+ TODO: document
+
+ Examples:
+
+ # fetch all the issues assigned to a person
+ $ jic fetch -f "assigned=some.person@host"
+
+ # fetch all the issues assigned to the user with their
+ # respective dependencies
+ $ jic fetch -f "assigned=$me" -L depends --up -H 1
+
+ # fetch specific issues and all their children linked by
+ # "implements" link type
+ $ jic fetch --self --down CARD-100,CARD-101 -L implements
+
+
+ 2.1.6. FIELDS
+
+ TODO: document
+
+ Examples:
+
+ # show issue fields
+ $ jic issue fields CARD-100
+
+
+ 2.1.7. FORGET
+
+ TODO: document
+
+ Examples:
+
+ # forget all the locally cached issues
+ $ jic issue forget -a
+
+ # forget only children of the issue that are linked using
+ # "implements" link type
+ $ jic issue forget -D CARD-100 -L implements
+
+
+ 2.1.8. LIST
+
+ $ jic list <options> [<issue_key_list>]
+
+ lists one or more issues specified
+
+ if there are no issue keys specified (either as <issue_key_list>
+ argument or as options) for the command, it shows nothing
+
+ options:
+
+ -d <issue_key_list>
+ --down <issue_key_list>
+ process children of the parent specified by <issue_key>;
+ the issue specified is not processed
+
+ -D <depth>
+ --depth <depth>
+ process as many levels up or down as specified; zero
+ corresponds only to the issue specified for -u or -d,
+ immediate parent/children correspond to depth 1, etc.
+
+ -e
+ invoke an editor to get (if none are provided) or edit
+ and confirm the list of issue keys to process; operation
+ is cancelled if the file is truncated to zero length
+
+ -f <criterion>
+ --filter <criterion>
+ show only issues matching the criterion; if multiple
+ such options specified, those criteria are combined
+ using logical "and" operation
+
+ -o
+ --online
+ perform an online operation (retrieve the data from the
+ corresponding server)
+
+ -O
+ --offline
+ perform an offline operation (retrieve the data from the
+ local cache only)
+
+ -s
+ --self
+ also include the issue mentioned for -u or -d
+
+ -t <name>
+ --template <name>
+ show issues according to the template referred by <name>
+
+ -u <issue_key_list>
+ --up <issue_key_list>
+ process ancestors of the issue specified by <issue_key>;
+ the issue specified is not processed
+
+ <issue_key_list>
+ an optional comma- or space- separated list of issue keys;
+ the output of this command is a combination of issues found
+ according to the criteria specified by options above and
+ ones specified by this argument
+
+ Examples:
+
+ # list all user's assigned issues of "Blueprint" and
+ # "Sub-task" issue types
+ # action subject is omitted so "issue" is assumed
+ $ jic list -f "assignee=$me" -T "Blueprint,Sub-task"
+
+ # list all user's authored or assigned issues
+ $ jic issue list -f "assignee=$me" -f "reporter=$me"
+
+
+ 2.1.9. LINK
+
+ TODO: document
+
+ Examples:
+
+ # link two issues using "implements" link type
+ $ jic link
+
+
+ 2.1.10. MOVE
+
+ TODO: document
+
+
+ 2.1.11. PULL
+
+ TODO: document
+
+ Examples:
+
+ # refresh from the server all the issues that are in local
+ # cache
+ $ jic pull
+
+
+ 2.1.12. PUSH
+
+ TODO: document
+
+ Examples:
+
+ # push all the local changes to the server
+ # as the subject of the action is omitted, "issue" is
+ # assumed
+ $ jic push
+
+ # push only changes for the listed issues to the server
+ $ jic issue push CARD-100 CARD-101
+
+ # push only last change to the server
+ $ jic issue push CARD-101:-1
+
+ # push listed changes to the server
+ $ jic issue push CARD-100:1,2,5 CARD-101:2-4
+
+
+ 2.1.13. REVERT
+
+ TODO: document
+
+ Examples:
+
+ # revert the last change for the issue
+ $ jic issue revert CARD-100:-1
+
+ # revert all the changes to the card
+ $ jic issue revert CARD-101
+
+
+ 2.1.14. SHOW
+
+ $ jic show <options> [<issue_key> [...]]
+
+ shows details for one or more issues specified
+
+ if <issue_key> equals to "-", standard input is used to get
+ issue list to process (can be white-space- or comma- separated)
+ until the EOF
+
+ if there are no issue keys specified (either as <issue_key_list>
+ argument or as options) for the command, it shows nothing
+
+ options:
+ -a
+ --all
+ show all parts of the issues (all fields, links,
+ comments, history); a synonym to "-p all"
+
+ -d <issue_key_list>
+ --down <issue_key_list>
+ process children of the parent specified by <issue_key>;
+ the issue specified is not processed
+
+ -D <depth>
+ --depth <depth>
+ process as many levels up or down as specified; zero
+ corresponds only to the issue specified for -u or -d,
+ immediate parent/children correspond to depth 1, etc.
+
+ -e
+ --editor
+ invoke an editor to get (if none are provided) or edit
+ and confirm the list of issue keys to process; operation
+ is cancelled if the file is truncated to zero length
+
+ -p <comma-separated-part-list>
+ --parts <comma-separated-part-list>
+ show all mentioned parts, options are:
+ "all", "header", "fields", "comments", "history", "links"
+
+ -s
+ --self
+ also include the issue mentioned for -u or -d
+
+ -t <name>
+ --template <name>
+ show issues according to the template referred by <name>
+
+ -u <issue_key_list>
+ --up <issue_key_list>
+ process ancestors of the issue specified by <issue_key>;
+ the issue specified is not processed
+
+
+ 2.1.15. TRANSITION
+
+ TODO: document
+
+ Examples:
+
+ # transition the issue into the "In Progress" state
+ $ jic issue transition -S "In Progress" CARD-100
+
+ # transition a set of issues into "Resolved" state with the
+ # resolution being "Fixed"
+ $ jic transition CARD-100 -S Resolved:Fixed
+
+ # transition all the immediate child issues of the issue
+ # specified using an editor
+ $ jic transition -D CARD-100 -H 1 -e
+
+
+ 2.1.16. TREE
+
+ $ jic tree <options> [<issue_key_list>]
+
+ shows hierarchy that surrounds the issues specified
+
+ if there are no issue keys specified (either as <issue_key_list>
+ argument or as options) for the command, it shows nothing
+
+ options:
+
+ -d <issue_key_list>
+ --down <issue_key_list>
+ process children of the parent specified by <issue_key>
+
+ -D <depth>
+ --depth <depth>
+ process as many levels up or down as specified; zero
+ corresponds only to the issue specified for -u or -d,
+ immediate parent/children correspond to depth 1, etc.
+
+ -e
+ --editor
+ invoke an editor to get (if none are provided) or edit
+ and confirm the list of issue keys to process; operation
+ is cancelled if the file is truncated to zero length
+
+ -f <criterion>
+ --filter <criterion>
+ show only issues matching the criterion; if multiple
+ such options specified, those criteria are combined
+ using logical "and" operation
+
+ parent and child issues around those issues which are
+ not shown (according to the criteria specified using
+ this option), still are shown as connected (with an
+ indication that there are skipped issues)
+
+ -t <name>
+ --template <name>
+ show issues according to the template referred by <name>
+
+ -u <issue_key_list>
+ --up <issue_key_list>
+ process ancestors of the issue specified by <issue_key>
+
+ <issue_key_list>
+ an optional comma- or space- separated list of issue keys;
+ the output of this command is a combination of issues found
+ according to the criteria specified by options above and
+ ones specified by this argument
+
+ Examples:
+
+ # show "implements" tree for the issue
+ $ jic tree -u -d -L implements CARD-100
+
+ # show dependencies tree for the issue
+ $ jic tree -a -L depends CARD-100
+
+ # show the full hierarchy for the issue (all link types)
+ $ jic tree -a CARD-100
+
+
+ 2.1.17. UNLINK
+
+ TODO: document
+
+
+2.2. COMMENT COMMANDS
+
+ 2.2.1. ADD
+
+ TODO: document
+
+ Examples:
+
+ # add a comment using an editor
+ $ jic comment add -e CARD-100
+
+ # add a comment using pipes
+ $ echo "This takes ~ 1 second" | jic comment add CARD-100
+
+ # add the same comment to a couple of issues
+ $ jic comment add CARD-100 CARD-101 <<EOF
+ This is a multi-line comment.
+ It eats up your stack when you are sleeping.
+ EOF
+
+ # get the last comment from one issue with an additional
+ # line appended to it into another issues comment
+ # please note that the comment retrieval operation is done
+ # in offline mode ("-O") to get a predictable result
+ $ ( jic show -O -p comments -R "-1" -r CARD-100 ; \
+ echo -e "\n\nThis is the additional line!" ) | \
+ jic comment add CARD-101
+
+
+ 2.2.2. DELETE
+
+ TODO: document
+
+ Examples:
+
+ # delete the last comment of the issue
+ $ jic comment delete -R -1 CARD-101
+
+ # delete specific card comment
+ $ jic comment delete CARD-101:2345
+
+ # delete three comments from two issues
+ $ jic comment delete CARD-100:123 CARD-101:2345,2346
+
+
+ 2.2.3. EDIT
+
+ TODO: document
+
+ Examples:
+
+ # edit the last comment of the issue using an editor
+ $ jic comment edit -e -R -1 CARD-100
+
+ # edit a specific comment using pipes and sed!
+ $ jic comment show -r CARD-101:2345 | \
+ sed s/bad/good/ | \
+ jic comment edit CARD-101:2345
+
+
+ 2.2.4. REPLY
+
+ TODO: document
+
+ Examples:
+
+ # reply to the last comment using editor
+ $ jic comment reply -e -R -1 CARD-100
+
+ # reply to the last comment using pipes
+ # the input provided is appended to the quoted text of the
+ # comment being replied to
+ $ echo -e "\nI like that cute embedded nonsense hack!" | \
+ jic comment reply CARD-100:2345
+
+
+ 2.2.5. SHOW
+
+ TODO: document
+
+ Examples:
+
+ # show the last three comments of the issue
+ $ jic comment show -R -3- CARD-100
+
+ # show specific comments by their IDs
+ $ jic comment show CARD-100:2345,2346
+
+ # show the last user's comment
+ $ jic comment show -f "author=$me" -R -1 CARD-100
+
+
+2.3. LINK COMMANDS
+
+ 2.3.1. CREATE
+
+ TODO: document
+
+ Examples:
+
+ # link two issues with "depends" link so that CARD-100 would
+ # depend on CARD-101
+ $ jic link create -L depends CARD-100 CARD-101
+
+ # link CARD-101/102/103 as implementing CARD-100
+ $ jic link create -L implements \
+ CARD-101,CARD-102,CARD-103 CARD-100
+
+
+ 2.3.2. DELETE
+
+ TODO: document
+
+ Examples:
+
+ # delete all links for the issue
+ $ jic link delete -a
+
+ # delete "depends" links to the issues that are depending on
+ # the specified one
+ $ jic link delete --down -L depends CARD-100
+
+ # delete "depends" links to the issues the specified issue
+ # is depending on
+ $ jic link delete --up -L depends CARD-101
+
+
+ 2.3.3. LIST
+
+ TODO: document
+
+ Examples:
+
+ # list all links for the issue
+ $ jic link list CARD-100
+
+ # list upward (towards parent) links
+ $ jic link list -u CARD-100
+
+
+2.4. REPORT COMMANDS
+
+ 2.4.1. CREATE
+
+ TODO: document
+
+
+ 2.4.2. DELETE
+
+ TODO: document
+
+
+ 2.4.3. EDIT
+
+ TODO: document
+
+
+ 2.4.4. GENERATE
+
+ TODO: document
+
+
+2.5. TEMPLATE
+
+ 2.5.1. CREATE
+
+ TODO: document
+
+
+ 2.5.2. DELETE
+
+ TODO: document
+
+
+ 2.5.3. EDIT
+
+ TODO: document
+
+
+2.6. SERVER COMMANDS
+
+ 2.6.1. ADD
+
+ TODO: document
+
+ Examples:
+
+ # add a server named "ServerName"
+ $ jic server add ServerName https://server.url user(a)server.url
+
+
+ 2.6.2. DANCE
+
+ TODO: document
+
+ Examples:
+
+ # perform the OAuth dance for the server
+ $ jic server dance ServerName
+
+
+ 2.6.3. DELETE
+
+ TODO: document
+
+ # delete a server named "ServerName" from the list of known
+ $ jic server delete ServerName
+
+
+ 2.6.4. EDIT
+
+ TODO: document
+
+ Examples:
+
+ # edit server information using an editor
+ $ jic server edit -e ServerName
+
+ # edit the server using pipes
+ $ jic server edit ServerName <<EOF
+ http://new.url
+ user(a)new.url
+ EOF
+
+
+ 2.6.5. LIST
+
+ TODO: document
+
+ Examples:
+
+ # list known servers
+ $ jic server list
+
+
+ 2.6.6. SHOW
+
+ TODO: document
+
+ Examples:
+
+ # show server information
+ $ jic server show ServerName
+
+
+2.7. LIST COMMANDS
+
+ 2.7.1. ADD
+
+ TODO: document
+
+ Examples:
+
+ # Add a couple of issues into the issue list named "MyList"
+ # without comments (comments are to be added later by
+ # "list edit" command
+ $ jic list add MyList CARD-100 CARD-101
+
+ # Add two issues into the issue list named "MyList" together
+ # with their respective comments
+ $ jic list add MyList <<EOF
+ Issue: CARD-101
+ Comment:
+ This is a comment for this issue. It is stored offline
+ and can only be handle by "list" commands. It is a jicML
+ value so any of the supported jicML value's syntaxes are
+ supported here.
+ Issue: CARD-102
+ Comment: {{{
+ This is a multi-line comment for the issue.
+ It can include any characters except the sequence of three
+ "}", which is a end-of-value token.
+ }}}
+ EOF
+
+ # Add issues matching the criteria into the "MyList" with
+ # the same comment provided using a pipe
+ $ echo "Urgent: FixVersion requires to be reevaluated!" | \
+ jic list add -f "reporter=$me,fixVersion<2014.06" \
+ -F comment MyList
+
+ # Add issues into "MyList" using an editor
+ $ jic add MyList -e
+
+
+ 2.7.2. CREATE
+
+ TODO: document
+
+ Examples:
+
+ # Create an issue list named "MyList"
+ $ jic list create MyList
+
+
+ 2.7.3. DELETE
+
+ TODO: document
+
+ Examples:
+
+ # Delete JIRA issue list named "MyList"
+ $ jic list delete MyList
+
+
+ 2.7.4. EDIT
+
+ TODO: document
+
+ Examples:
+
+ # Edit issues in the list using an editor
+ $ jic list edit -e MyList
+
+ # Edit issue's comment using sed
+ $ jic list show --raw CARD-100 | sed s/bad/improving/ | \
+ jic list edit CARD-100
+
+
+ 2.7.5. LIST
+
+ TODO: document
+
+ Examples:
+
+ # List all the issue lists that exist
+ $ jic list list
+
+ # List those issue lists that contain the issues mentioned
+ $ jic list list CARD-100 CARD-101
+
+
+ 2.7.6. RECEIVE
+
+ TODO: document
+
+ Examples:
+
+ # Receive issue list that was sent by "list send" command
+ $ jic list receive << file_that_was_sent
+
+
+ 2.7.7. REMOVE
+
+ TODO: document
+
+ Examples:
+
+ # Remove a JIRA issues from "MyList"
+ $ jic list remove CARD-100 CARD-101
+
+
+ 2.7.8. SEND
+
+ TODO: document
+
+ Examples:
+
+ # Send a JIRA issue list to someone else
+ $ jic list send MyList | sendmail someone.else@host
+
+
+ 2.7.9. SHOW
+
+ TODO: document
+
+ Examples:
+
+ # Show all issues in "MyList" and their respective comments
+ $ jic list show MyList
+
+ # Show only those issues which are listed as arguments
+ $ jic list show MyList CARD-100 CARD-101
+
+ # Show only a card and all its children if those are listed
+ # in the list
+ $ jic list show -d CARD-100
+
+
+2.8. CONFIGURATION COMMANDS
+
+ 2.8.1. SET
+
+ TODO: document
+
+
+ 2.8.2. SHOW
+
+ TODO: document
+
+
+ 2.8.3. UNSET
+
+ TODO: document
+
+
+3. OPTIONS
+
+ -a
+ --all
+ show all parts of the issues (all fields, links, comments,
+ history); a synonym to "-p all"
+
+ -d
+ --down
+ process children of the issues denoted by other means but not
+ those issues themselves unless there is a "-s" option specified
+
+ unless there are link types specified by the option "L", all
+ link types are included in the traversal operation
+
+ down means the following for different link types:
+ - implements: from the implemented issue to its implementors;
+ - depends: from the dependee to its dependants;
+ - clones: from the original to its clone.
+
+ examples:
+
+ # list the CARD-100 issue and all its children
+ $ jic list --self --down CARD-100
+
+ # show all children for KEY-123 and KEY-124
+ $ jic show -d KEY-123 KEY-124 -f "type=Sub-task"
+
+ -D <issue_key_list>
+ --down-from <issue_key_list>
+ process children of the parents specified by <issue_key_list>;
+ the issue specified is not processed
+
+ <issue_key_list> is a comma-separated list of issue keys
+
+ unless there are link types specified by the option "L", all
+ link types are included in the traversal operation
+
+ down means the following for different link types:
+ - implements: from the implemented issue to its implementors;
+ - depends: from the dependee to its dependants;
+ - clones: from the original to its clone.
+
+ examples:
+
+ # list the CARD-100 issue and all its children
+ $ jic list --self --down CARD-100
+
+ # show all children for KEY-123 and KEY-124
+ $ jic show -d KEY-123 KEY-124
+
+ -e
+ --editor
+ invoke an editor to get (if none are provided) or edit
+ and confirm the list of issue keys to process; operation
+ is cancelled if the file is truncated to zero length
+
+ specific semantics of this action and type of the information
+ that is being edited, as well as the reaction on all three
+ outcomes of editing operation (those being: unmodified file,
+ modified file, empty file) depend on the subject of action and
+ an action - see those for details
+
+ -f <criterion>
+ --filter <criteria_anded>
+ show only issues matching the criteria; if multiple such
+ options specified, those criteria are combined using logical
+ "or" operation
+
+ <criteria_anded> is a coma-separated list of <criterion>, which
+ are combined using logical "and"
+
+ criterion:
+ "<field><operation><value>"
+
+ where
+ <field> corresponds to JIRA field name
+ <operation> is one of the:
+ "<" for "less than",
+ "<=" for "less or equal than",
+ "=" for "equals",
+ ">" for "more than",
+ ">=" for "more or equal than",
+ "!=" for "not equal",
+ "[" for "in the list", list follows with the
+ first symbol used as a delimiter; the list
+ may be closed by an optional "]" symbol
+ "]" for "not in the list", list follows with the
+ first symbol used as a delimiter; the list
+ may be closed by an optional "[" symbol
+ <value> is anything following the <operation> the end of
+ the string (with an exception of optional
+ trailing "]" and "[" if present)
+
+ examples:
+ -f "assignee=some.user(a)some.host"
+ -f "project=Some Project"
+ -f "fixVersion[,2014.01,2014.02]"
+ -f "assignee],someone@host,anotherone@host["
+
+ -F <field_list>
+ --fields <field_list>
+ process only the issue fields specified
+
+ overrides template (default or the one specified explicitly
+ using "-t" option) if specified
+
+ -H <depth>
+ --depth <depth>
+ process as many levels up or down as specified; zero corresponds
+ only to the issue specified for -u/U or -d/D, immediate
+ parent/children correspond to depth 1, etc.
+
+ example:
+ -H 2
+ --depth 1
+
+ -k
+ --keys
+ get issue keys to be processed using the same method (editor or
+ standard input) as used for getting all the other data for the
+ operation
+
+ -L <link_type_list>
+ --link-type <link_type_list>
+ provide one or more link types (as a comma-separated list) to
+ work with; specifics of semantics of this option depend on the
+ specific subject of action and an action - see those for details
+
+ -o
+ --online
+ perform an online operation (update the data on the
+ corresponding server as well as the local cache)
+
+ -O
+ --offline
+ perform an offline operation (update the data in the local cache
+ only)
+
+ -p <comma-separated-part-list>
+ --parts <comma-separated-part-list>
+ show all mentioned parts, options are:
+ "all", "header", "fields", "comments", "history", "links"
+
+ -P [<item_list>]
+ --purge [<item_list>]
+ purge existing information and replace it with the one provided;
+ specifics of semantics of this option depend on specific subject
+ of action and an action - see those for details
+
+ <item_list> is a comma-separated list if unique identifiers of
+ the items to be purged; all items are purged if no argument
+ is provided
+
+ -r
+ --raw
+ output raw results of the command; typically useful for using in
+ automation; specifics of semantics of this option depend on
+ specific subject of action and an action - see those for details
+
+ -R <range_spec>
+ --range <range_spec>
+ specifies which items from the result set should be processed;
+ specifics of semantics of this option depend on specific subject
+ of action and an action - see those for details
+
+ -s
+ --self
+ also include the issue mentioned for -u or -d
+
+ -t <name>
+ --template <name>
+ show issues according to the template referred by <name>
+
+ templates are managed using template commands
+
+ -T <issue_type_list>
+ --issue-types <issue_type_list>
+ provide one or more issue types (as a comma-separated list) to
+ work with; specifics of semantics of this option depend on the
+ specific subject of action and an action - see those for details
+
+ -u
+ --up
+ process ancestors of the issues denoted by other means but not
+ those issues themselves unless there is a "-s" option specified
+
+ unless there are link types specified by the option "L", all
+ link types are included in the traversal operation
+
+ up means the following for different link types:
+ - implements: from implementor to its implemented issue;
+ - depends: from the dependant to its dependee;
+ - clones: from the the clone to its original.
+
+ examples:
+
+ # list the CARD-100 issue and all its ancestors
+ $ jic list --self --up CARD-100
+
+ # show all ancestors for KEY-123 and KEY-124
+ $ jic show -u KEY-123 KEY-124
+
+ -U <issue_key_list>
+ --up-from <issue_key_list>
+ process ancestors of the issue specified by <issue_key_list>;
+ the issue specified is not processed unless the "-s" option is
+ specified too
+
+ <issue_key_list> is a comma-separated list of issue keys
+
+ unless there are link types specified by the option "L", all
+ link types are included in the traversal operation
+
+ up means the following for different link types:
+ - implements: from implementor to its implemented issue;
+ - depends: from the dependant to its dependee;
+ - clones: from the the clone to its original.
+
+ examples:
+
+ # list ancestors of the issue KEY-123 but not the issue
+ $ jic list --up KEY-123
+
+ # list ancestors for KEY-123 and KEY-124 together with
+ # the issues
+ $ jic list -s -u KEY-123,KEY-124
+
+
+4. jicML
+
+jicML is a text based data markup language used to create and modify
+JIRA issues. It is a lightweight, intuitive and fast to learn. It also
+helps minimizing the amount of data duplication when editing multiple
+issues.
+
+ 4.1. jicML representation of JIRA issues
+
+ General structure of the jicML representation of JIRA issues has
+ one optional leading section (shared fields) and repeated pair of
+ sections (issue key and issue fields with their respective walues)
+
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+ <shared fields and values>
+ <issue key> # this and the next line can be repeated
+ <issue fields and values>
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+
+ where <* fields and values> are:
+
+ <field_name>: <field value>
+
+ where
+
+ <field_name> is imposed by JIRA but in any case can't contain
+ the ":" symbol
+
+ <field_value> is explained further below
+
+ Having a <shared fields and values> allows setting the same value
+ for a field in all the issues that have their keys mentioned further
+ in the file. For example, if one would like to set the
+ "FixVersion/s" and add the same comment for a set of known issues,
+ besides performing other modifications that are unique for each
+ issue, a jicML for such an editing operation might look like:
+
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+ FixVersion/s: 2020.01
+ Comment:
+ Moving into the future as the whole team is having a long
+ sabbatical leave.
+
+ Issue: CARD-101
+ Priority: Low
+
+ Issue: CARD-102
+ Labels: +MY_LABEL
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+
+ All the fields and their values that are mentioned after an "Issue:"
+ field and until the next "Issue:" field or the end of the data, are
+ related to the issue which key was mentioned in the previous
+ "Issue:" field. Thus, for the example jicML above, the issues
+ mentioned in it would get the following updates:
+
+ CARD-101
+ FixVersion/s: 2020.01
+ Comment:
+ Moving into the future as the whole team is having a
+ long sabbatical leave.
+ Priority: Low
+
+ CARD-102
+ FixVersion/s: 2020.01
+ Comment:
+ Moving into the future as the whole team is having a
+ long sabbatical leave.
+ Labels: +MY_LABEL
+
+
+ 4.2. jicML values
+
+ Values in jicML can be represented in three ways:
+
+ - a simple single line of text
+
+ the end of line character is denoting the end of line and is not
+ included into the value; it is possible to add line breaks using
+ "\n" combination though:
+
+ examples:
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+ Field: 12
+ Another Field: Some text with spaces
+ Yet Another Field: Some text with spaces\nand newlines
+ And Yet Another Field: +A_VALUE
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+
+ - a folded multi-line text
+
+ this is similar folding used for long email headers as defined
+ in rfc2822 - a long sequence of characters (including
+ whitespace) is folded with all but the first line having one or
+ more spaces as their first symbols; when such a value is parsed,
+ all the lines until the first one with non-whitespace first
+ character are joined together using one space as a delimiter
+
+ all the new line characters are treated as a whitespace within
+ the folded value and are replaced with spaces
+
+ examples:
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+ Field:
+ 12
+ Another Field: Some text
+ with spaces
+ Yet Another Field:
+ Some text with spaces\n
+ and newlines\n
+ consisting of three
+ lines of text
+ And Yet Another Field:
+ +NEW_VALUE,
+ +ANOTHER_NEW_VALUE,
+ -OLD_VALUE
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+
+ - a multi-line value within the "{{{" and "}}}" value markers
+
+ in this case, anything that is located between the markers is
+ treated as the value with just the following exceptions:
+
+ if value starts with whitespace, such whitespace is stripped
+ away - the following value
+
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+ {{{
+ Some text}}}
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+
+ is equal to
+
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+ {{{Some text}}}
+ -------- 8< -------- 8< -------- 8< -------- 8< --------
+
+ a simple text will be parsed as a stream of jicML values - one per
+ line - unless there are lines with leading spaces and some trailing
+ non-whitespace characters, when value unfolding will be performing,
+ consuming multiple whitespace prefixed lines into just one value
+
+
+ 4.3. Stream of jicML name:value pairs
+
+ For the cases when jic is expecting the user to provide new values
+ for the fields of the issues that are being created or edited, in
+ some cases it expects a stream of jicML name:value pairs. The format
+ of the stream is simple in this case:
+
+ <field_name>: <field_value> <newline>
+ ...
+
+ EOF denotes the end of the data.
+
+
+ 4.4. Stream of jicML values
+
+ For the cases when jic is expecting the user to provide new values
+ for the fields of the issues that are being created or edited, in
+ some cases it expects a stream of jicML values. The format of the
+ stream is simple in this case:
+
+ <field_value> <newline>
+ ...
+
+ EOF denotes the end of the data.
+
+
+ 4.3. Representing JIRA comments
+
+ TODO: document
+
+
+ 4.4. Representing JIRA links
+
+ TODO: document
+
+
+5. SHELL ENVIRONMENT INTEGRATION
+
+ In order to add flexibility jic also supports shell environment
+ variables. It is possible to provide values for jic options by using
+ environment variables with names corresponding to the following
+ pattern:
+
+ JIC_O_<uppercase_name_of_the_option>
+
+ Examples:
+
+ $ JIC_O_FILTER="project=CARD" jic list -f "assignee=$me"
+
+
+ It is also possible to provide field values for editing operations
+ (creation, modification) through environment variables using the
+ following name pattern:
+
+ JIC_F_<uppercase_name_of_the_field>
+
+ Please note, all the non-alphanumerical characters should be
+ replaced with underscore characters ("_").
+
+ Examples:
+
+ $ JIC_F_REPORTER="another.person@host" jic create -e
+
+ TODO: document
+
+
+6. SHELL COMMAND LINE COMPLETION
+
+ TODO: document
--
2.0.0.rc2
