Good localtime,
I'm glad to present you an excerpt from the jic CLI specification
document I'm working on, which covers a new high level `frontend` mode,
which supplements the previously presented `plumbing` mode.
It was created based on the feedback I've received during KWG/PMWG
sprint in Le Mans two weeks ago.
I would like to get some feedback from you to confirm that this mode
covers all the essential most frequent operations engineers will be
using for their daily operations in the way that is matching your
expectations.
I'll be waiting for your feedback till 28 July 2014 when I'll continue
working on its implementation for the next version of jic.
-------- 8< -------- 8< -------- 8< -------- 8< --------
2. CLI STRUCTURE
To allow both - having a concise and easy to learn interface for the
most frequent operations and a powerful but requiring more time to learn
one, jic has modal command line interface with the following two modes:
1. Front end - the concise but limited one
2. Plumbing - the powerful but verbose one
It is possible to choose which one of the above will be the default one
and switching between the two is done using the following switches:
--frontend
--plumbing
Mode setting switch should be on the first place after jic's name as it
defines how all the following switches and arguments are going to be
interpreted.
Examples:
# let's assume for these examples that the default mode is
# configured to be frontend.
# list issues reported by the user
$ jic list reported
# list issues assigned to the user using a symlinked jic
$ jls assigned
# add new command 'my week'
$ jic --plumbing command add <<EOF
my week,wee,we,wk,w
plumbing:report generate MyWeekly -1w
EOF
To set the default mode the following option should be changed:
Name: cli.mode
Values: `frontend`, `plumbing`
Default value: `plumbing`
That can be done using the following commands:
# set `frontend` to be the default mode
$ jic --plumbing configuration set cli.mode frontend
# set `plumbing` to be the default mode
$ jic --plumbing configuration set cli.mode plumbing
Alternative and more convenient way of using frontend commands is using
symbolic links pointing to jic with their names matching the frontend
commands defined. In this case the mode is set to be `frontend`
regardless the default mode in configuration. Adding an explicit
`--plumbing` switch in this case will however result in `plumbing` mode
being selected.
After setting default mode to `plumbing` and adding proper symlinks for
`frontend` mode commands, it is possible to use both modes with no need
to explicitly specify each mode:
# access `plumbing` mode commands
$ jic issue tree PMWG-100
# access `frontend` mode commands
$ jadd PMWG-101 -m 'This comment is added using frontend mode!'
2.1. Frontend mode CLI structure
This mode is fully defined by the commands defined in the configuration
file. To help users being productive without a need to spend lots of
time reading through the plumbing commands' documentation and building
their own frontend mode CLI, jic comes with a set of pre-configured
commands that are listed below.
The structure of frontend mode command line:
$ jic word [word...] [<switches>] args
Preconfigured commands:
All the pre-configured `frontend` mode commands are listed below:
jadd
add a comment
jedc
edit a comment
jdel
delete a comment
jsh [comments,history,links,worklog,all]
show JIRA issues
jls [assigned,reported]
list JIRA issues
jcr (sub-task,blueprint)
create JIRA issues
jed
edit JIRA issues
jtr
transition JIRA issues
jwt
log time spent on an issue
jul [depends,implements'
unlink issues
Those are described in more details in the following sub-chapters.
2.1.1. Add comments
$ jadd [<issue_key> [<issue_key>...]] [-e] [-k] [-m <message>]
Adds comments, one per issue specified, using the text
provided:
- by `-m` switch is present;
- using an editor (if `-e` is specified);
- from stdin if no parameters are specified.
If `-k` switch is specified, issue keys for the issues to be
processed are also read using the same method - all the
lines of text till the first empty line will be parsed as a
space or comma separated list of issue keys.
Examples:
# add a comment using an editor
$ jadd CARD-100 -e
# add a comment for two cards using the message provided
$ jadd CARD-100 CARD-101 -m 'This is\na multiline message'
# add a comment using stdin
$ echo 'This is\na multiline comment' | jadd CARD-100
# add a comment into a set of cards
$ jadd -k <<EOF
CARD-100, CARD-101
CARD-102
This is a folded comment that will be added for the issues
that are listed above.
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
# define command aliases (the first one being the name of the
# command)
jadd,add,ad,a
# list allowed options
e,k,m
# what does this command mean
# possible types are:
# plumbing for mapping to a plumbing command
# frontend for mapping to a frontend command
# python for defining a function that implements the
# command
plumbing:comments add $keys $args
EOF
which is an equivalent of:
$ jic --plumbing command add jadd,add,ad,a e,k,m \
'plumbing:comments add $keys $args'
2.1.2. Edit comments
$ jedc [<issue_key:cmt_id[,<cmt_id>...>...]] [-e] [-k] [-m <message>]
Edits comments using the text provided:
- by `-m` switch is present;
- using an editor (if `-e` is specified);
- from stdin if no parameters are specified.
If `-k` switch is specified, issue keys and comment ids for
the comments to be processed are also read using the same
method - all the lines of text till the first empty line
will be parsed as a space or comma separated list of issue
keys and comment ids.
Examples:
# edit a comment using an editor
$ jedc CARD-100:2345 -e
# edit two comments for two cards using the message provided
$ jedc CARD-100:2345 CARD-101:2445 -m 'This is a message'
# edit a comment using stdin
$ echo 'This is\na multiline comment' | jedc CARD-100:2345
# edit a set of comments for a few cards
$ jadd -k <<EOF
CARD-100:2345,2346 CARD-101:3425
CARD-102:3446
This is the text that will replace the existing comments
whose ids are listed above.
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jedc,editc,edic,edc,ec
e,k,m
plumbing:comments edit $keys $args
EOF
2.1.3. Delete comments
$ jdel [<issue_key:cmt_id[,<cmt_id>...>...]] [-e] [-k]
Delete comments whose ids are specified using:
- using an editor (if `-e` is specified);
- from stdin if no parameters are specified.
If `-k` switch is specified, issue keys and comment ids for
the comments to be deleted are read from stdin - all the
lines of text till the first empty line will be parsed as a
space or comma separated list of issue keys and comment ids.
Examples:
# delete a comment using an editor to edit the list of
# issues and comment ids
$ jdel CARD-100:2345 -e
# delete two comments for two cards using the message provided
$ jdel CARD-100:2345 CARD-101:2346
# edit a set of comments for a few cards
$ jdel -k <<EOF
CARD-100:2345,2346 CARD-101:3425
CARD-102:3446
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jdel,delete,delet,dele,del,de,d
e,k
plumbing:comments delete $keys $args
EOF
2.1.4. Show issue (essential)
$ jsh [<issue_key> [<issue_key>...]] [-k]
Show essential issue information (fields).
Examples:
# show an issue
$ jsh CARD-100
# show issues whose keys are provided using stdin
$ echo 'CARD-100 CARD-101' | jsh
# show issues whose keys are provided using stdin and edited
# using an editor
$ jsh -e <<EOF
CARD-100 CARD-101
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jsh,show,sho,sh,s
k
plumbing:issue show -p fields $keys $args
EOF
2.1.5. Show issue comments
$ jsh comments [<issue_key> [<issue_key>...]] [-k]
Show issue comments.
Examples:
# show issue's comments
$ jsh comments CARD-100
# show comments for the issues whose keys are provided using
# stdin
$ echo 'CARD-100 CARD-101' | jsh c
# show comments for the issues whose keys are provided using
# stdin and edited using an editor
$ jsh comm -e <<EOF
CARD-100 CARD-101
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jsh,show,sho,sh,s comments,comment,commen,comme,comm,com,cmts,cmt,co,c
k
plumbing:issues show -p comments $keys $args
EOF
2.1.6. Show issue (history)
$ jsh history [<issue_key> [<issue_key>...]] [-k]
Show issue change history.
Examples:
# show issue's change history
$ jsh history CARD-100
# show change history for the issues whose keys are provided
# using stdin
$ echo 'CARD-100 CARD-101' | jsh h
# show change history for the issues whose keys are provided
# using stdin and edited using an editor
$ jshh -e <<EOF
CARD-100 CARD-101
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jsh,show,sho,sh,s history,histor,histo,hist,his,hi,h
k
plumbing:issues show -p history $keys $args
EOF
2.1.7. Show issue (links)
$ jsh links [<issue_key> [<issue_key>...]] [-k]
Show issue links.
Examples:
# show issue's links
$ jsh links CARD-100
# show links for the issues whose keys are provided
# using stdin
$ echo 'CARD-100 CARD-101' | jsh l
# show links for the issues whose keys are provided using
# stdin and edited using an editor
$ jsh l -e <<EOF
CARD-100 CARD-101
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jsh,show,sho,sh,s links,link,lin,lnk,li,ln,l
k
plumbing:issues show -p links $keys $args
EOF
2.1.8. Show issue (worklog)
$ jsh worklog [<issue_key> [<issue_key>...]] [-k]
Show essential issue information (fields).
Examples:
# show issue's worklog
$ jsh worklog CARD-100
# show worklogs for the issues whose keys are provided
# using stdin
$ echo 'CARD-100 CARD-101' | jsh w
# show worklogs for the issues whose keys are provided using
# stdin and edited using an editor
$ jsh w -e <<EOF
CARD-100 CARD-101
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jsh,show,sho,sh,s worklog,worklo,workl,work,wor,wo,w
k
plumbing:issues show -p worklog $keys $args
EOF
2.1.9. Show issue (all information)
$ jsh all [<issue_key> [<issue_key>...]] [-k]
Show essential issue information (fields).
Examples:
# show all issue's information
$ jsh all CARD-100
# show all information for the issues whose keys are provided
# using stdin
$ echo 'CARD-100 CARD-101' | jsh a
# show all information for the issues whose keys are
# provided using stdin and edited using an editor
$ jsh a -e <<EOF
CARD-100 CARD-101
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jsh,show,sho,sh,s all,al,a
k
plumbing:issues show -p all $keys $args
EOF
2.1.10. List my assigned issues
$ jls assigned
Show list of the issues assigned to the user.
Examples:
# list all assigned issues
$ jls assigned
# list all assigned issues using shortened form
$ jls a
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jls,list,lis,li,ls,l assigned,assigne,assign,assig,assi,ass,as,a
k
plumbing:issues list -f 'assigned=$me' $keys $args
EOF
2.1.11. List my reported issues
$ jls reported
Show list of the issues reported by the user.
Examples:
# list all reported issues
$ jls reported
# list all reported issues using shortened form
$ jls r
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jls,list,lis,li,ls,l reported,reporte,report,repor,repo,rep,re,r
k
plumbing:issues list -f 'reported=$me' $keys $args
EOF
2.1.12. Create a new sub-task
$ jcr sub-task [<parent_issue_keys>] [-k] [-e] [-n <number>]
Create a new sub-task.
Examples:
# create a new sub-task in PMWG project for PMWG-100 using
# an editor to get summary from the user
$ jcr sub-task CARD-100 PMWG -e
# create a new sub-task in KWG project for KWG-100 using
# stdin to get summary from the user
$ echo 'Summary for a new sub-task' | jcr-st CARD-100 KWG
# create 5 new sub-tasks in SWG project for the same
# SWG-101 using stdin to get new sub-tasks' summaries from
# the user
$ jcr st CARD-101 -n 5 <<EOF
This is a summary for the first sub-task.
This is a summary for the second sub-task. This one is
folded using leading whitespace on lines with
continuation of the text.
Third sub-task.
{{{Fourth sub-task's summary.}}}
Fifth sub-task.
EOF
# create as many sub-tasks in VIRT project for CARD-102 as
# provided summaries using stdin
$ jcr st CARD-101 VIRT -n EOF <<EOF
First issue's summary...
Second issue's summary..
Third issue's summary...
...
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jcr,create,creat,crea,cre,cr,c sub-task,sub,st,s
k,e,n
plumbing:issues create -T Sub-Task -L Implements \
-F Summary,assignee=$me $keys $args
EOF
2.1.13. Create a new Blueprint
$ jcr blueprint [<parent_issue_keys>] [-k] [-e] [-n <number>]
Create a new sub-task.
Examples:
# create a new blueprint for CARD-100 using an editor to get
# field values from the user
$ jcr blueprint CARD-100 -e
# create a new blueprint for CARD-100 using stdin to get
# summary from the user
$ jcr bp CARD-100 <<EOF
Summary: This is a new summary
Description: {{{
This is a multiline description for the blueprint.
....
}}}
Depends on: CARD-120
Labels: SOME_LABEL
EOF
# create 5 new blueprints for the same CARD-101 using stdin
# to get new blueprint's field values from the user
$ jcr bp CARD-101 -n 5 <<EOF
Issue:
EOF
# create as many blueprints for CARD-102 as provided
# summaries using stdin
$ jcr bp CARD-101 -n EOF <<EOF
First blueprint's summary...
Second blueprint's summary..
Third blueprint's summary...
...
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jcr,create,creat,crea,cre,cr,c blueprint,blue,blu,bl,bp,b
k,e,n
plumbing:issues create -T Blueprint -L Implements -F \
Summary,Description,assignee=$me $keys $args
EOF
2.1.14. Edit an issue
$ jed [-k] [-e] [<issue_keys...>]
Edit a JIRA issue.
Examples:
# edit an issue using an editor
$ jed PMWG-100 -e
# edit an issue by setting its listed fields
$ echo 'This is a new summary' | jed PMWG-100 -F Summary
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jed,edit,edi,ed,e blueprint,blue,blu,bl,bp,b
k,e
plumbing:issues edit $keys $args
EOF
2.1.15. Start working on an issue
$ jtr start [-k] [-e] [-m <msg>] [<issue_keys...>]
Transition a JIRA issue into the `In Progress` status.
Examples:
# Start working on an issue
$ jtr start PMWG-100
# Start working on a couple of issues and add a comment
$ jtr PMWG-100,PMWG-101 -c <<EOF
This is a comment to be added to both issues after their
statuses are changed to `In Progress`.
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jtr,transition,transitio,transiti,transit,transi,trans,tran,tra,tr,t
k,e,m
plumbing:issues transition $keys 'In Progress' $args
EOF
2.1.16. Resolve an issue
$ jtr resolve [-k] [-e] -m <msg>] [<issue_keys...>] <resolution>
Transition a JIRA issue into the `Resolved` status and set
its resolution to the one provided.
Examples:
# Resolve an issue as Delivered also adding a comment to it
$ echo 'Finally!' | jtr resolve PMWG-100 Delivered -c
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jtr,transition,transitio,transiti,transit,transi,trans,tran,tra,tr,t\
resolve,resolv,resol,reso,res,re,r
plumbing:issues transition $keys $args
k,e,m
EOF
2.1.17. Log time spent on an issue
$ jwt [-k] [<issue_keys...>] <from_date> <effort>
Add work log entry for the issue specified reporting
<effort> hours spent starting from <from_date>.
Examples:
# Log time spent on an issue during this week (on Friday)
$ jwt KWG-100 -5d 3.5h
# Log time spent on a few issues during the week
$ jwt -k <<EOF
# issue key to report time against
KWG-100
# date when the reported chunk of work was started
-5d
# Amount of time spent
2h
KWG-101
-3d
50m
KWG-102
-1d
1d
EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jcr,create,creat,crea,cre,cr,c blueprint,blue,blu,bl,bp,b
plumbing:worklog add $keys $args
EOF
2.1.18. Link dependencies
$ jln depends [<issues_to_link...>] [<issues_to_link_to...>]
Link <issues_to_link...> as depending on
<issues_to_link_to...>
Examples:
# Link PMWG-101 as depending on PMWG-100
$ jln depends PMWG-101 PMWG-100
# Link PMWG-101,PMWG-102 and PMWG-103 as depending on
# PMWG-100
$ jln dep PMWG-101,PMWG-102,PMWG-103 PMWG-100
# Links PMWG-105 as depending on PMWG-101 and PMWG-102
$ jln d PMWG-105 PMWG-101,PMWG102
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jcr,create,creat,crea,cre,cr,c blueprint,blue,blu,bl,bp,b
plumbing:issues link -L Implements $keys $args
k,e,n
EOF
2.1.19. Link implementors
$ jln implements [<issues_to_link...>] [<issue_to_link_to>]
Link <issues_to_link...> as depending on
<issue_to_link_to>
Examples:
# Link PMWG-101 as implementing PMWG-100
$ jln implements PMWG-101 PMWG-100
# Link PMWG-101,PMWG-102 and PMWG-103 as implementing
# PMWG-100
$ jln impl PMWG-101,PMWG-102,PMWG-103 PMWG-100
# Links PMWG-105 as depending on PMWG-101 and PMWG-102
$ jln d PMWG-105 PMWG-101,PMWG102
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jcr,create,creat,crea,cre,cr,c blueprint,blue,blu,bl,bp,b
issues link -L Implements $keys $args
k,e,n
EOF
2.1.20. Unlink dependencies
$ jul depends [<issues_to_unlink...>] [<issues_to_unlink_from...>]
Unlink <issues_to_unlink...> as depending on
<issues_to_unlink_from...>
Examples:
# Unlink PMWG-101 as depending on PMWG-100
$ jul depends PMWG-101 PMWG-100
# Unlink PMWG-101,PMWG-102 and PMWG-103 as depending on
# PMWG-100
$ jul dep PMWG-101,PMWG-102,PMWG-103 PMWG-100
# Unlink PMWG-105 as depending on PMWG-101 and PMWG-102
$ jul d PMWG-105 PMWG-101,PMWG102
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jul,unlink,unlin,unli,unl,un,ul,u blueprint,blue,blu,bl,bp,b
plumbing:issues unlink -L Implements $keys $args
k,e,n
EOF
2.1.21. Unlink implementors
$ jul implements [<issues_to_unlink...>] [<issue_to_unlink_from>]
Unlink <issues_to_unlink...> as depending on
<issue_to_unlink_from>
Examples:
# Link PMWG-101 as implementing PMWG-100
$ jln implements PMWG-101 PMWG-100
# Link PMWG-101,PMWG-102 and PMWG-103 as implementing
# PMWG-100
$ jln impl PMWG-101,PMWG-102,PMWG-103 PMWG-100
# Links PMWG-105 as depending on PMWG-101 and PMWG-102
$ jln d PMWG-105 PMWG-101,PMWG102
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF
jul,unlink,unlin,unli,unl,un,ul,u blueprint,blue,blu,bl,bp,b
issues unlink -L Implements $keys $args
k,e,n
EOF
-------- 8< -------- 8< -------- 8< -------- 8< --------
Thank you for reading through down to this place. It is important for
everyone involved to get jic capable of doing the most needed things
first.
Please, send me your feedback (whatever it is, including "looks sane"
kind of it). :)
--
Best Regards,
Serge Broslavsky <serge.broslavsky(a)linaro.org>
Project Manager, Linaro
M: +37129426328 IRC: ototo Skype: serge.broslavsky
http://linaro.org | Open source software for ARM SoCs
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
