diff options
Diffstat (limited to 'plugins/jira')
| -rw-r--r-- | plugins/jira/README.md | 64 | ||||
| -rw-r--r-- | plugins/jira/_jira | 22 | ||||
| -rw-r--r-- | plugins/jira/jira.plugin.zsh | 143 |
3 files changed, 160 insertions, 69 deletions
diff --git a/plugins/jira/README.md b/plugins/jira/README.md new file mode 100644 index 000000000..efb8a743a --- /dev/null +++ b/plugins/jira/README.md @@ -0,0 +1,64 @@ +# Jira plugin # + +CLI support for JIRA interaction + +## Description ## + +This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software. + +The interaction is all done through the web. No local installation of JIRA is necessary. + +In this document, "JIRA" refers to the JIRA issue tracking server, and `jira` refers to the command this plugin supplies. + +## Usage ## + +This plugin supplies one command, `jira`, through which all its features are exposed. Most forms of this command open a JIRA page in your web browser. + +``` +jira # performs the default action + +jira new # opens a new issue +jira dashboard # opens your JIRA dashboard +jira reported [username] # queries for issues reported by a user +jira assigned [username] # queries for issues assigned to a user +jira ABC-123 # opens an existing issue +jira ABC-123 m # opens an existing issue for adding a comment +``` + +#### Debugging usage #### + +These calling forms are for developers' use, and may change at any time. + +``` +jira dumpconfig # displays the effective configuration +``` + +## Setup ## + +The URL for your JIRA instance is set by `$JIRA_URL` or a `.jira_url` file. + +Add a `.jira-url` file in the base of your project. You can also set `$JIRA_URL` in your `~/.zshrc` or put a `.jira-url` in your home directory. A `.jira-url` in the current directory takes precedence, so you can make per-project customizations. + +The same goes with `.jira-prefix` and `$JIRA_PREFIX`. These control the prefix added to all issue IDs, which differentiates projects within a JIRA instance. + +For example: + +``` +cd to/my/project +echo "https://jira.atlassian.com" >> .jira-url +``` + +(Note: The current implementation only looks in the current directory for `.jira-url` and `.jira-prefix`, not up the path, so if you are in a subdirectory of your project, it will fall back to your default JIRA URL. This will probably change in the future though.) + +### Variables ### + +* `$JIRA_URL` - Your JIRA instance's URL +* `$JIRA_NAME` - Your JIRA username; used as the default user for `assigned`/`reported` searches +* `$JIRA_PREFIX` - Prefix added to issue ID arguments +* `$JIRA_RAPID_BOARD` - Set to `true` if you use Rapid Board +* `$JIRA_DEFAULT_ACTION` - Action to do when `jira` is called with no arguments; defaults to "new" + + +### Browser ### + +Your default web browser, as determined by how `open_command` handles `http://` URLs, is used for interacting with the JIRA instance. If you change your system's URL handler associations, it will change the browser that `jira` uses. diff --git a/plugins/jira/_jira b/plugins/jira/_jira new file mode 100644 index 000000000..03fe6a499 --- /dev/null +++ b/plugins/jira/_jira @@ -0,0 +1,22 @@ +#compdef jira +#autoload + +local -a _1st_arguments +_1st_arguments=( + 'new:create a new issue' + 'dashboard:open the dashboard' + 'reported:search for issues reported by a user' + 'assigned:search for issues assigned to a user' + 'dumpconfig:display effective jira configuration' +) + +_arguments -C \ + ':command:->command' \ + '*::options:->options' + +case $state in + (command) + _describe -t commands "jira subcommand" _1st_arguments + return + ;; +esac diff --git a/plugins/jira/jira.plugin.zsh b/plugins/jira/jira.plugin.zsh index ca540c84c..341e23ec0 100644 --- a/plugins/jira/jira.plugin.zsh +++ b/plugins/jira/jira.plugin.zsh @@ -1,97 +1,102 @@ -# To use: add a .jira-url file in the base of your project -# You can also set JIRA_URL in your .zshrc or put .jira-url in your home directory -# .jira-url in the current directory takes precedence +# CLI support for JIRA interaction # -# If you use Rapid Board, set: -#JIRA_RAPID_BOARD="true" -# in you .zshrc -# -# Setup: cd to/my/project -# echo "https://name.jira.com" >> .jira-url -# Usage: jira # opens a new issue -# jira ABC-123 # Opens an existing issue -open_jira_issue () { - local open_cmd - if [[ "$OSTYPE" = darwin* ]]; then - open_cmd='open' - else - open_cmd='xdg-open' - fi +# See README.md for details + +: ${JIRA_DEFAULT_ACTION:=new} + +function jira() { + emulate -L zsh + local action=${1:=$JIRA_DEFAULT_ACTION} - if [ -f .jira-url ]; then + local jira_url jira_prefix + if [[ -f .jira-url ]]; then jira_url=$(cat .jira-url) - elif [ -f ~/.jira-url ]; then + elif [[ -f ~/.jira-url ]]; then jira_url=$(cat ~/.jira-url) - elif [[ "x$JIRA_URL" != "x" ]]; then - jira_url=$JIRA_URL + elif [[ -n "${JIRA_URL}" ]]; then + jira_url=${JIRA_URL} else - echo "JIRA url is not specified anywhere." + _jira_url_help return 1 fi - if [ -f .jira-prefix ]; then + if [[ -f .jira-prefix ]]; then jira_prefix=$(cat .jira-prefix) - elif [ -f ~/.jira-prefix ]; then + elif [[ -f ~/.jira-prefix ]]; then jira_prefix=$(cat ~/.jira-prefix) + elif [[ -n "${JIRA_PREFIX}" ]]; then + jira_prefix=${JIRA_PREFIX} else jira_prefix="" fi - if [ -z "$1" ]; then + + if [[ $action == "new" ]]; then echo "Opening new issue" - $open_cmd "${jira_url}/secure/CreateIssue!default.jspa" - elif [[ "$1" = "assigned" || "$1" = "reported" ]]; then - jira_query $@ - else - local addcomment='' + open_command "${jira_url}/secure/CreateIssue!default.jspa" + elif [[ "$action" == "assigned" || "$action" == "reported" ]]; then + _jira_query $@ + elif [[ "$action" == "dashboard" ]]; then + echo "Opening dashboard" + open_command "${jira_url}/secure/Dashboard.jspa" + elif [[ "$action" == "dumpconfig" ]]; then + echo "JIRA_URL=$jira_url" + echo "JIRA_PREFIX=$jira_prefix" + echo "JIRA_NAME=$JIRA_NAME" + echo "JIRA_RAPID_BOARD=$JIRA_RAPID_BOARD" + echo "JIRA_DEFAULT_ACTION=$JIRA_DEFAULT_ACTION" + else + # Anything that doesn't match a special action is considered an issue name + local issue_arg=$action + local issue="${jira_prefix}${issue_arg}" + local url_fragment='' if [[ "$2" == "m" ]]; then - addcomment="#add-comment" - echo "Add comment to issue #$1" + url_fragment="#add-comment" + echo "Add comment to issue #$issue" else - echo "Opening issue #$1" + echo "Opening issue #$issue" fi - - if [[ "x$JIRA_RAPID_BOARD" = "xtrue" ]]; then - $open_cmd "$jira_url/issues/$jira_prefix$1$addcomment" + if [[ "$JIRA_RAPID_BOARD" == "true" ]]; then + open_command "${jira_url}/issues/${issue}${url_fragment}" else - $open_cmd "$jira_url/browse/$jira_prefix$1$addcomment" + open_command "${jira_url}/browse/${issue}${url_fragment}" fi fi } -jira_name () { - if [[ -z "$1" ]]; then - if [[ "x${JIRA_NAME}" != "x" ]]; then - jira_name=${JIRA_NAME} - else - echo "JIRA_NAME not specified" - return 1 - fi +function _jira_url_help() { + cat << EOF +error: JIRA URL is not specified anywhere. + +Valid options, in order of precedence: + .jira-url file + \$HOME/.jira-url file + \$JIRA_URL environment variable +EOF +} + +function _jira_query() { + emulate -L zsh + local verb="$1" + local jira_name lookup preposition query + if [[ "${verb}" == "reported" ]]; then + lookup=reporter + preposition=by + elif [[ "${verb}" == "assigned" ]]; then + lookup=assignee + preposition=to else - jira_name=$@ + echo "error: not a valid lookup: $verb" >&2 + return 1 + fi + jira_name=${2:=$JIRA_NAME} + if [[ -z $jira_name ]]; then + echo "error: JIRA_NAME not specified" >&2 + return 1 fi -} -jira_query () { - verb="$1" - if [[ "${verb}" = "reported" ]]; then - lookup=reporter - preposition=by - elif [[ "${verb}" = "assigned" ]]; then - lookup=assignee - preposition=to - else - echo "not a valid lookup $verb" - return 1 - fi - shift 1 - jira_name $@ - if [[ $? = 1 ]]; then - return 1 - fi - echo "Browsing issues ${verb} ${preposition} ${jira_name}" - $open_cmd "${jira_url}/secure/IssueNavigator.jspa?reset=true&jqlQuery=${lookup}+%3D+%22${jira_name}%22+AND+resolution+%3D+unresolved+ORDER+BY+priority+DESC%2C+created+ASC" + echo "Browsing issues ${verb} ${preposition} ${jira_name}" + query="${lookup}+%3D+%22${jira_name}%22+AND+resolution+%3D+unresolved+ORDER+BY+priority+DESC%2C+created+ASC" + open_command "${jira_url}/secure/IssueNavigator.jspa?reset=true&jqlQuery=${query}" } -alias jira='open_jira_issue' - |