stow/oh-my-zsh/.oh-my-zsh/plugins/jira/README.md

   1 #  Jira plugin  #
   2
   3 CLI support for JIRA interaction
   4
   5 ##  Description  ##
   6
   7 This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software.
   8
   9 The interaction is all done through the web. No local installation of JIRA is necessary.
  10
  11 In this document, "JIRA" refers to the JIRA issue tracking server, and `jira` refers to the command this plugin supplies.
  12
  13 ##  Usage  ##
  14
  15 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.
  16
  17 ```
  18 jira            # performs the default action
  19
  20 jira new        # opens a new issue
  21 jira dashboard  # opens your JIRA dashboard
  22 jira tempo      # opens your JIRA Tempo
  23 jira reported [username]  # queries for issues reported by a user
  24 jira assigned [username]  # queries for issues assigned to a user
  25 jira myissues   # queries for you own issues
  26 jira branch     # opens an existing issue matching the current branch name
  27                 # The branch name may have prefixes ending in "/": "feature/MP-1234",
  28                 # and also suffixes starting with "_": "MP-1234_fix_dashboard"
  29                 # In both these cases, the issue opened will be "MP-1234"
  30 jira ABC-123    # opens an existing issue
  31 jira ABC-123 m  # opens an existing issue for adding a comment
  32 ```
  33
  34 #### Debugging usage  ####
  35
  36 These calling forms are for developers' use, and may change at any time.
  37
  38 ```
  39 jira dumpconfig   # displays the effective configuration
  40 ```
  41
  42 ##  Setup  ##
  43
  44 The URL for your JIRA instance is set by `$JIRA_URL` or a `.jira_url` file.
  45
  46 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.
  47
  48 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.
  49
  50 For example:
  51
  52 ```
  53 cd to/my/project
  54 echo "https://jira.atlassian.com" >> .jira-url
  55 ```
  56
  57 (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.)
  58
  59 ###  Variables  ###
  60
  61 * `$JIRA_URL` - Your JIRA instance's URL
  62 * `$JIRA_NAME` - Your JIRA username; used as the default user for `assigned`/`reported` searches
  63 * `$JIRA_PREFIX` - Prefix added to issue ID arguments
  64 * `$JIRA_RAPID_BOARD` - Set to `true` if you use Rapid Board
  65 * `$JIRA_DEFAULT_ACTION` - Action to do when `jira` is called with no arguments; defaults to "new"
  66
  67
  68 ### Browser ###
  69
  70 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.