Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/glittershark/org-clubhouse

Simple, unopinionated integration between Emacs's org-mode and the Clubhouse issue tracker
https://github.com/glittershark/org-clubhouse

Last synced: 2 days ago
JSON representation

Simple, unopinionated integration between Emacs's org-mode and the Clubhouse issue tracker

Awesome Lists containing this project

README 

        
#+TITLE:Org-Shortcut



Simple, unopinionated integration between Emacs's [[https://orgmode.org/][org-mode]] and the [[https://shortcut.com/][Shortcut]]

issue tracker



* Installation



** [[https://github.com/quelpa/quelpa][Quelpa]]



#+BEGIN_SRC emacs-lisp

(quelpa '(org-shortcut

          :fetcher github

          :repo "glittershark/org-shortcut"))

#+END_SRC



** [[https://github.com/hlissner/doom-emacs/][DOOM Emacs]]



#+BEGIN_SRC emacs-lisp

;; in packages.el

(package! org-shortcut

  :recipe (:hohst github

           :repo "glittershark/org-shortcut"))



;; in config.el

(def-package! org-shortcut)

#+END_SRC



** [[http://spacemacs.org/][Spacemacs]]

#+BEGIN_SRC emacs-lisp

;; in .spacemacs (SPC+fed)

   dotspacemacs-additional-packages

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

#+END_SRC



* Setup



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



#+BEGIN_SRC emacs-lisp

(setq org-shortcut-auth-token ""

      org-shortcut-team-name ""

      org-shortcut-username "")

#+END_SRC



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 [[https://help.shortcut.com/hc/en-us/articles/360000046646-Searching-in-Shortcut-Story-Search][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:



#+BEGIN_SRC emacs-lisp

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

#+END_SRC



The mapping from org-mode todo-keywords is configured via the

~org-shortcut-state-alist~ variable, which should be an [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html][alist]] mapping (string)

[[https://orgmode.org/manual/Workflow-states.html][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:



#+BEGIN_SRC emacs-lisp

(setq org-shortcut-state-alist

      '(("TODO"   . "To Do")

        ("ACTIVE" . "In Progress")

        ("DONE"   . "Done")))

#+END_SRC



*** 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 [[https://github.com/urbint/org-shortcut/blob/master/org-shortcut.el][org-shortcut.el]] file in this repository for



documentation on all supported configuration variables