diff options
Diffstat (limited to 'plugins/jira')
| -rw-r--r-- | plugins/jira/README.md | 66 | ||||
| -rw-r--r-- | plugins/jira/_jira | 2 | ||||
| -rw-r--r-- | plugins/jira/jira.plugin.zsh | 64 |
3 files changed, 92 insertions, 40 deletions
diff --git a/plugins/jira/README.md b/plugins/jira/README.md index d78ea15a4..f6e2e26f4 100644 --- a/plugins/jira/README.md +++ b/plugins/jira/README.md @@ -1,46 +1,68 @@ -# Jira plugin # +# Jira plugin -CLI support for JIRA interaction +This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software. -## Description ## +To use it, add `jira` to the plugins array in your zshrc file: -This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software. +```zsh +plugins=(... jira) +``` 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 ## +## 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. ## Commands -| Command | Description | -| :------------ | :-------------------------------------------------------- | -| `jira` | Performs the default action | -| `jira new` | Opens a new Jira issue dialogue | -| `jira ABC-123` | Opens an existing issue | -| `jira ABC-123 m` | Opens an existing issue for adding a comment | -| `jira dashboard [rapid_view]` | # opens your JIRA dashboard | -| `jira mine` | Queries for your own issues | -| `jira tempo` | Opens your JIRA Tempo | -| `jira reported [username]` | Queries for issues reported by a user | -| `jira assigned [username]` | Queries for issues assigned to a user | -| `jira branch` | Opens an existing issue matching the current branch name | +`jira help` or `jira usage` will print the below usage instructions + +| Command | Description | +| :---------------------------- | :------------------------------------------------------- | +| `jira` | Performs the default action | +| `jira new` | Opens a new Jira issue dialogue | +| `jira ABC-123` | Opens an existing issue | +| `jira ABC-123 m` | Opens an existing issue for adding a comment | +| `jira project ABC` | Opens JIRA project summary | +| `jira dashboard [rapid_view]` | Opens your JIRA dashboard | +| `jira mine` | Queries for your own issues | +| `jira tempo` | Opens your JIRA Tempo | +| `jira reported [username]` | Queries for issues reported by a user | +| `jira assigned [username]` | Queries for issues assigned to a user | +| `jira branch` | Opens an existing issue matching the current branch name | +| `jira help` | Prints usage instructions | ### Jira Branch usage notes -The branch name may have prefixes ending in "/": "feature/MP-1234", and also suffixes +The branch name may have prefixes ending in "/": "feature/MP-1234", and also suffixes starting with "_": "MP-1234_fix_dashboard". In both these cases, the issue opened will be "MP-1234" This is also checks if the prefix is in the name, and adds it if not, so: "MP-1234" opens the issue "MP-1234", "mp-1234" opens the issue "mp-1234", and "1234" opens the issue "MP-1234". +If your branch naming convention deviates, you can overwrite the jira_branch function to determine and echo the Jira issue key yourself. +Define a function `jira_branch` after sourcing `oh-my-zsh.sh` in your `.zshrc`. +Example: +```zsh +# Determine branch name from naming convention 'type/KEY-123/description'. +function jira_branch() { + # Get name of the branch + issue_arg=$(git rev-parse --abbrev-ref HEAD) + # Strip prefixes like feature/ or bugfix/ + issue_arg=${issue_arg#*/} + # Strip suffixes like /some-branch-description + issue_arg=${issue_arg%%/*} + # Return the value + echo $issue_arg +} +``` -#### Debugging usage #### +#### Debugging usage These calling forms are for developers' use, and may change at any time. @@ -48,7 +70,7 @@ These calling forms are for developers' use, and may change at any time. jira dumpconfig # displays the effective configuration ``` -## Setup ## +## Setup The URL for your JIRA instance is set by `$JIRA_URL` or a `.jira_url` file. @@ -65,7 +87,7 @@ 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 ### +### Variables * `$JIRA_URL` - Your JIRA instance's URL * `$JIRA_NAME` - Your JIRA username; used as the default user for `assigned`/`reported` searches @@ -76,6 +98,6 @@ echo "https://jira.atlassian.com" >> .jira-url * `$JIRA_TEMPO_PATH` - Your JIRA tempo url path; defaults to "/secure/Tempo.jspa" -### Browser ### +### 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 index 0e37b7e9d..617a3e501 100644 --- a/plugins/jira/_jira +++ b/plugins/jira/_jira @@ -5,12 +5,14 @@ local -a _1st_arguments _1st_arguments=( 'new:create a new issue' 'mine:open my issues' + 'project:open the project' 'dashboard:open the dashboard' 'tempo:open the tempo' 'reported:search for issues reported by a user' 'assigned:search for issues assigned to a user' 'branch:open the issue named after the git branch of the current directory' 'dumpconfig:display effective jira configuration' + 'help:print usage help to stdout' ) _arguments -C \ diff --git a/plugins/jira/jira.plugin.zsh b/plugins/jira/jira.plugin.zsh index b6ee9f100..0c90544d5 100644 --- a/plugins/jira/jira.plugin.zsh +++ b/plugins/jira/jira.plugin.zsh @@ -2,6 +2,46 @@ # # See README.md for details +function _jira_usage() { +cat <<EOF +jira Performs the default action +jira new Opens a new Jira issue dialogue +jira ABC-123 Opens an existing issue +jira ABC-123 m Opens an existing issue for adding a comment +jira project ABC Opens JIRA project summary +jira dashboard [rapid_view] Opens your JIRA dashboard +jira mine Queries for your own issues +jira tempo Opens your JIRA Tempo +jira reported [username] Queries for issues reported by a user +jira assigned [username] Queries for issues assigned to a user +jira branch Opens an existing issue matching the current branch name +EOF +} + +# If your branch naming convention deviates, you can partially override this plugin function +# to determine the jira issue key based on your formatting. +# See https://github.com/ohmyzsh/ohmyzsh/wiki/Customization#partially-overriding-an-existing-plugin +function jira_branch() { + # Get name of the branch + issue_arg=$(git rev-parse --abbrev-ref HEAD) + # Strip prefixes like feature/ or bugfix/ + issue_arg=${issue_arg##*/} + # Strip suffixes starting with _ + issue_arg=(${(s:_:)issue_arg}) + # If there is only one part, it means that there is a different delimiter. Try with - + if [[ ${#issue_arg[@]} = 1 && ${issue_arg} == *-* ]]; then + issue_arg=(${(s:-:)issue_arg}) + issue_arg="${issue_arg[1]}-${issue_arg[2]}" + else + issue_arg=${issue_arg[1]} + fi + if [[ "${issue_arg:l}" = ${jira_prefix:l}* ]]; then + echo "${issue_arg}" + else + echo "${jira_prefix}${issue_arg}" + fi +} + function jira() { emulate -L zsh local action jira_url jira_prefix @@ -44,9 +84,14 @@ function jira() { open_command "${jira_url}/secure/CreateIssue!default.jspa" elif [[ "$action" == "assigned" || "$action" == "reported" ]]; then _jira_query ${@:-$action} + elif [[ "$action" == "help" || "$action" == "usage" ]]; then + _jira_usage elif [[ "$action" == "mine" ]]; then echo "Opening my issues" open_command "${jira_url}/issues/?filter=-1" + elif [[ "$action" == "project" ]]; then + echo "Opening project" + open_command "${jira_url}/jira/software/c/projects/${2}/summary" elif [[ "$action" == "dashboard" ]]; then echo "Opening dashboard" if [[ "$JIRA_RAPID_BOARD" == "true" ]]; then @@ -74,24 +119,7 @@ function jira() { # but `branch` is a special case that will parse the current git branch local issue_arg issue if [[ "$action" == "branch" ]]; then - # Get name of the branch - issue_arg=$(git rev-parse --abbrev-ref HEAD) - # Strip prefixes like feature/ or bugfix/ - issue_arg=${issue_arg##*/} - # Strip suffixes starting with _ - issue_arg=(${(s:_:)issue_arg}) - # If there is only one part, it means that there is a different delimiter. Try with - - if [[ ${#issue_arg[@]} = 1 && ${issue_arg} == *-* ]]; then - issue_arg=(${(s:-:)issue_arg}) - issue_arg="${issue_arg[1]}-${issue_arg[2]}" - else - issue_arg=${issue_arg[1]} - fi - if [[ "${issue_arg:l}" = ${jira_prefix:l}* ]]; then - issue="${issue_arg}" - else - issue="${jira_prefix}${issue_arg}" - fi + issue=$(jira_branch) else issue_arg=${(U)action} issue="${jira_prefix}${issue_arg}" |