Org-Shortcut

Simple, unopinionated integration between Emacs’s org-mode and the Shortcut issue tracker

Installation

Quelpa

(quelpa '(org-shortcut
          :fetcher github
          :repo "glittershark/org-shortcut"))

DOOM Emacs

;; in packages.el
(package! org-shortcut
  :recipe (:hohst github
           :repo "glittershark/org-shortcut"))

;; in config.el
(def-package! org-shortcut)

Spacemacs

;; in .spacemacs (SPC+fed)
   dotspacemacs-additional-packages
    '((org-shortcut :location (recipe :fetcher github :repo "glittershark/org-shortcut")))

Setup

Once installed, you’ll need to set three global config vars:

(setq org-shortcut-auth-token "<your-token>"
      org-shortcut-team-name "<your-team-name>"
      org-shortcut-username "<your-username>")

You can generate a new personal API token by going to the “API Tokens” tab on the “Settings” page in the shortcut UI.

Note that org-shortcut-username needs to be set to your mention name, not your username, as currently there’s no way to get the ID of a user given their username in the shortcut API

Usage

Reading from shortcut

org-shortcut-headlines-from-query Create org-mode headlines from a shortcut query at the cursor’s current position, prompting for the headline indentation level and shortcut query text
org-shortcut-headline-from-story Prompts for headline indentation level and the title of a story (which will complete using the titles of all stories in your Shortcut workspace) and creates an org-mode headline from that story
org-shortcut-headline-from-story-id Creates an org-mode headline directly from the ID of a shortcut story

Writing to shortcut

org-shortcut-create-story Creates a new Shortcut story from the current headline, or if a region of headlines is selected bulk-creates stories with all those headlines
org-shortcut-create-epic Creates a new Shortcut epic from the current headline, or if a region of headlines is selected bulk-creates epics with all those headlines
org-shortcut-create-story-with-task-list Creates a Shortcut story from the current headline, making all direct children of the headline into tasks in the task list of the story
org-shortcut-push-task-list Writes each child element of the current shortcut element as a task list item of the associated shortcut ID.
org-shortcut-update-story-title Updates the title of the Shortcut story linked to the current headline with the text of the headline
org-shortcut-update-description Update the status of the Shortcut story linked to the current element with the contents of a drawer inside the element called DESCRIPTION, if any exists
org-shortcut-update-labels Update the labels of the Shortcut stories or epics linked to either the element at point or all selected elements. Follows the rules specified in org-shortcut-create-story-with-labels - see “Story labels” below
org-shortcut-claim Adds the user configured in org-shortcut-username as the owner of the shortcut story associated with the headline at point

Automatically updating Shortcut story statuses

Org-shortcut can be configured to update the status of stories as you update their todo-keyword in org-mode. To opt-into this behavior, set the org-shortcut-mode minor-mode:

(add-hook 'org-mode-hook #'org-shortcut-mode nil nil)

The mapping from org-mode todo-keywords is configured via the org-shortcut-state-alist variable, which should be an alist mapping (string) org-mode todo-keywords to the (string) names of their corresponding workflow state. You can have todo-keywords that don’t map to a workflow state (I use this in my workflow extensively) and org-shortcut will just preserve the previous state of the story when moving to that state.

An example config:

(setq org-shortcut-state-alist
      '(("TODO"   . "To Do")
        ("ACTIVE" . "In Progress")
        ("DONE"   . "Done")))

Story labels

By default, org-shortcut will ignore all tags on org headlines when creating stories and epics. If you want to set labels when creating or updating stories and epics, you can set the value of org-shortcut-create-stories-with-labels to either t or ~’existing~. When set to t, all commands will create new labels in shortcut for all org-mode tags, following all tag inheritance rules in org mode (inheriting tags from parents, and respecting FILETAGS). When set to ~’existing~, commands will only set write tags that already exist as shortcut labels.

Philosophy

I use org-mode every single day to manage tasks, notes, literate programming, etc. Part of what that means for me is that I already have a system for the structure of my .org files, and I don’t want to sacrifice that system for any external tool. Updating statuses, org-shortcut-create-story, and org-shortcut-headline-from-story are my bread and butter for that reason - rather than having some sort of bidirectional sync that pulls down full lists of all the stories in Shortcut (or whatever issue tracker / project management tool I’m using at the time). I can be in a mode where I’m taking meeting notes, think of something that I need to do, make it a TODO headline, and make that TODO headline a shortcut story. That’s the same reason for the DESCRIPTION drawers rather than just sending the entire contents of a headline to Shortcut - I almost always want to write things like personal notes, literate code, etc inside of the tasks I’m working on, and don’t always want to share that with Shortcut.

Configuration

Refer to the beginning of the org-shortcut.el file in this repository for

documentation on all supported configuration variables

glittershark/org-clubhouse