diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 34 |
1 files changed, 17 insertions, 17 deletions
@@ -7,7 +7,7 @@ " /We like lists because we don't want to die./ " — /Umberto Eco/ -Pearl (backronym: *Pearl Edits and Reflects Linear*) brings Linear issues into Emacs as a working Org file. Fetch your open issues, a project, a Linear Custom View, an ad-hoc filter, or a saved local query; Pearl renders each issue as an Org heading with the description and comments in the body and Linear metadata in a namespaced property drawer. Edit what you need in the buffer, then save the ticket; Pearl reconciles each changed field against the remote with a conflict check. +Pearl (backronym: *Pearl Edits and Reflects Linear*) brings Linear issues into Emacs as a working Org file. Fetch your open issues, a project, a Linear Custom View, an ad-hoc filter, or a saved local query; Pearl renders each issue as an Org heading with the description and comments in the body and Linear metadata in a namespaced property drawer. Edit what you need in the buffer, then save the issue; Pearl reconciles each changed field against the remote with a conflict check. ** Features :PROPERTIES: @@ -48,7 +48,7 @@ Pearl is not on MELPA yet. #+begin_src emacs-lisp (use-package pearl :vc (:url "https://git.cjennings.net/pearl.git" :rev :newest) - :commands (pearl-menu pearl-list-issues pearl-run-view pearl-new-issue) + :commands (pearl-menu pearl-list-issues pearl-run-view pearl-create-issue) :bind ("C-c L" . pearl-menu) :custom (pearl-org-file-path (expand-file-name "gtd/linear.org" org-directory)) @@ -76,7 +76,7 @@ In =config.el=: #+begin_src emacs-lisp (use-package! pearl - :commands (pearl-menu pearl-list-issues pearl-new-issue + :commands (pearl-menu pearl-list-issues pearl-create-issue pearl-run-view pearl-save-issue) :init (setq pearl-org-file-path (expand-file-name "gtd/linear.org" org-directory)) @@ -144,7 +144,7 @@ Pearl writes one active Org file. Running a different query or view replaces tha *** Command menu -=M-x pearl-menu= opens a transient dispatcher. Ticket actions are grouped as save, edit, new, and delete; workspace actions as fetch, view, and setup. Bind that command if you use Pearl regularly: +=M-x pearl-menu= opens a transient dispatcher. Issue actions are grouped as save, edit, create, and delete; workspace actions as fetch, view, and setup. Bind that command if you use Pearl regularly: #+begin_src emacs-lisp (global-set-key (kbd "C-c L") #'pearl-menu) @@ -158,22 +158,22 @@ Pearl is fully keyboard-drivable. =pearl-mode=, a minor mode, turns on automatic (setq pearl-keymap-prefix "C-c l") ; or nil to bind nothing #+end_src -The hot-path commands sit one key under the prefix; the rest are grouped into category sub-maps. The common ones appear in both places, so =d= and =e d= both edit the description. +The hot-path commands sit one key under the prefix; the rest are grouped into sub-maps, one per action verb. The common ones appear in both places, so =d= and =e d= both edit the description. | Key | Command | |-----------+----------------------------------------------------------------------| | =l= | list my open issues | | =g= | refresh the view | | =r= | refresh the issue at point | -| =s= / =S= | save the ticket at point / save every ticket in the file | +| =s= / =S= | save the issue at point / save every issue in the file | | =d= | edit the description | -| =c= | add a comment | | =m= | open the full transient menu | | =f= ... | fetch: =o= open issues, =p= by project, =f= filter, =v= view, =q= saved query | | =e= ... | edit: =d= description, =s= state, =a= assignee, =l= labels, =c= comment | -| =n= ... | new: =t= ticket, =c= comment | -| =k= ... | delete: =t= ticket, =c= comment | -| =u= ... | url: =o= open issue in browser, =v= open view in Linear | +| =c= ... | create: =t= issue, =c= comment | +| =k= ... | delete: =t= issue, =c= comment | +| =o= ... | open: =i= issue in browser, =v= view in Linear | +| =y= ... | copy: =u= issue URL | To reach the map outside a Pearl buffer, bind it globally as well: @@ -207,17 +207,17 @@ Sorting is local and deterministic. Query filters are AND-only; use a Linear Cus *** Editing issues -Pearl has one write path. Edit a ticket however you like in the buffer, then save it -- Pearl diffs each field against what it last fetched and pushes only what changed. Nothing pushes the moment you pick a value, and there is no per-field "push" command to remember. All issue commands work from anywhere inside an issue subtree. +Pearl has one write path. Edit an issue however you like in the buffer, then save it -- Pearl diffs each field against what it last fetched and pushes only what changed. Nothing pushes the moment you pick a value, and there is no per-field "push" command to remember. All issue commands work from anywhere inside an issue subtree. | Command | What it does | |-----------------------------------+-------------------------------------------------------| -| =pearl-save-issue= | Save every changed field of the ticket at point | -| =pearl-save-all= | Save every changed ticket in the file (confirms once) | +| =pearl-save-issue= | Save every changed field of the issue at point | +| =pearl-save-all= | Save every changed issue in the file (confirms once) | | =pearl-edit-description= | Edit the description in a focused compose buffer | | =pearl-edit-state= | Pick a workflow state (reaches any of the team's) | | =pearl-edit-assignee= | Pick a team member as assignee | | =pearl-edit-labels= | Pick labels; an empty selection clears them | -| =pearl-add-comment= | Add a new Linear comment | +| =pearl-create-comment= | Add a new Linear comment | | =pearl-edit-current-comment= | Edit one of your own comments | | =pearl-delete-current-comment= | Delete one of your own comments after confirming | | =pearl-delete-current-issue= | Soft-delete the current issue after confirmation | @@ -230,7 +230,7 @@ How each field is edited: - *Priority* -- the Org priority cookie (=C-c ,=, or =S-up= / =S-down=). =[#A]/[#B]/[#C]/[#D]= are Urgent/High/Medium/Low; no cookie is None. - *State* -- =pearl-edit-state=, completing over the team's workflow states. - *Assignee and labels* -- =pearl-edit-assignee= / =pearl-edit-labels=, completing over the team's members and labels. Labels also render as Org tags on the heading (=:bug:backend:=), so you can filter, sparse-tree, and build agendas on them. The =:LINEAR-LABELS:= drawer stays the source of truth; hand-edited heading tags are ignored and rewritten from Linear on the next change or fetch, so change labels with =pearl-edit-labels=. -- *Comments* -- edit your own in place, or =pearl-add-comment= for a new one. +- *Comments* -- edit your own in place, or =pearl-create-comment= for a new one. Picking a constrained field writes the value into the buffer and marks it changed; it doesn't push until you save. The display name or label text is there to read -- Pearl reconciles by the underlying id, and a refresh rewrites the display from the remote, so hand-editing the visible name has no effect. @@ -242,9 +242,9 @@ Only comments you authored are editable or deletable. Pearl refuses edits and de A fetched issue renders with a TODO keyword derived from its Linear state name: the name is slugified (upcased, non-alphanumeric runs collapsed to hyphens), so "In Progress" becomes =IN-PROGRESS= and "Dev Review" becomes =DEV-REVIEW=. The buffer's =#+TODO= line is built from the real workflow states of the teams on display, so every keyword you see is a state that team actually has, partitioned active / done by Linear's state type. -You change a ticket's state two ways, both reconciled and pushed at the next save: +You change an issue's state two ways, both reconciled and pushed at the next save: -- Cycle the keyword with =C-c C-t= (or =S-<right>= / =S-<left>=). The keyword you cycle to is matched back to a team state by the same slug rule, so cycling =TODO= → =IN-PROGRESS= moves the ticket to the "In Progress" state. A keyword no team state slugifies to can't be resolved, so that save is reported skipped. +- Cycle the keyword with =C-c C-t= (or =S-<right>= / =S-<left>=). The keyword you cycle to is matched back to a team state by the same slug rule, so cycling =TODO= → =IN-PROGRESS= moves the issue to the "In Progress" state. A keyword no team state slugifies to can't be resolved, so that save is reported skipped. - =pearl-edit-state= completes over every state on the team and writes the keyword for you. Use it to reach a state whose keyword you don't remember, or one the visible keyword set doesn't cover. ** The Org File |