diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 30 |
1 files changed, 16 insertions, 14 deletions
@@ -159,7 +159,7 @@ 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 sub-maps, one per action verb. 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 or noun. Fetch is issue sources only; views, account switching, and setup each have their own group. The common ones appear in both places, so =d= and =e d= both edit the description. | Key | Command | |-----------+----------------------------------------------------------------------| @@ -169,12 +169,14 @@ The hot-path commands sit one key under the prefix; the rest are grouped into su | =s= / =S= | save the issue at point / save every issue in the file | | =d= | edit the description | | =m= | open the full transient menu | -| =f= ... | fetch: =s= pick source, =o= open issues, =p= by project, =f= filter, =l= run local view, =v= run Linear view, =u= publish, =d= save Linear view locally, =P= publish current | -| =e= ... | edit: =d= description, =s= state, =a= assignee, =l= labels, =c= comment, =v= local view | -| =c= ... | create: =t= issue, =c= comment, =v= local view | -| =k= ... | delete: =t= issue, =c= comment, =v= local view | +| =f= ... | fetch (issue sources): =s= pick source, =o= open issues, =p= by project, =f= filter | +| =v= ... | views: =l= run local, =L= run Linear, =c= create, =e= edit, =k= delete, =u= publish, =U= publish current, =d= save Linear view locally, =D= set default (reserved) | +| =e= ... | edit: =d= description, =s= state, =a= assignee, =l= labels, =c= comment | +| =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 | +| =w= ... | workspace: =a= switch account, =t= test connection, =c= check setup, =!= toggle debug, =x= clear cache | To reach the map outside a Pearl buffer, bind it globally as well: @@ -206,14 +208,14 @@ If the favorites fetch fails (network/auth/transport), the picker still offers a *** Publishing a local view as a Linear view -A local view is great for your own quick filters, but the team can't see it and the Linear web UI can't run it. =pearl-publish-local-view= (=C-; L f u=, or =u= in the transient's Views group) promotes a local view to a Linear Custom View so it's visible alongside your sidebar favorites and the rest of the team's views. This is the *copy up* direction of the lifecycle. +A local view is great for your own quick filters, but the team can't see it and the Linear web UI can't run it. =pearl-publish-local-view= (=C-; L v u=, or =u= in the transient's Views group) promotes a local view to a Linear Custom View so it's visible alongside your sidebar favorites and the rest of the team's views. This is the *copy up* direction of the lifecycle. Two commands publish: | Command | Binding | What it does | |------------------------------------+--------------------------------------+--------------------------------------------------------------------| -| =pearl-publish-local-view= | =C-; L f u=, =u= in the transient Views group | Pick a local view by name and publish (or update) it on Linear | -| =pearl-publish-current-view= | =C-; L f P=, =U= in the transient Views group | Read the buffer's =#+LINEAR-SOURCE=; if it names a local view, publish that one | +| =pearl-publish-local-view= | =C-; L v u=, =u= in the transient Views group | Pick a local view by name and publish (or update) it on Linear | +| =pearl-publish-current-view= | =C-; L v U=, =U= in the transient Views group | Read the buffer's =#+LINEAR-SOURCE=; if it names a local view, publish that one | The first time you publish a local view, Pearl asks where the view should live with one enriched prompt that spells out the full end-state per option: @@ -234,11 +236,11 @@ After a successful publish, the local-view entry gains four metadata keys (=:lin Pearl's =:sort= / =:order= on a local view don't publish up in v1 -- Linear's =CustomView= API has no sort input, so a published view renders in whatever order Linear's defaults give it. If sort order is load-bearing for the view, set it in the Linear web UI after the first publish. -=pearl-delete-local-view= (=C-; L k v=) on a published entry asks a second question after the local-delete confirmation: also delete the linked Linear view? Yes calls =customViewDelete=, which Linear handles as a soft delete (recoverable from the workspace trash). No unlinks the entry locally and leaves the Linear view in place. If the Linear delete fails (permissions, network), Pearl prompts to drop the local entry anyway -- accepting orphans the Linear view, and the message names the view id explicitly so you can clean it up by hand. Under multiple accounts, publish and delete refuse a local view tagged to a non-active account before touching Linear. +=pearl-delete-local-view= (=C-; L v k=) on a published entry asks a second question after the local-delete confirmation: also delete the linked Linear view? Yes calls =customViewDelete=, which Linear handles as a soft delete (recoverable from the workspace trash). No unlinks the entry locally and leaves the Linear view in place. If the Linear delete fails (permissions, network), Pearl prompts to drop the local entry anyway -- accepting orphans the Linear view, and the message names the view id explicitly so you can clean it up by hand. Under multiple accounts, publish and delete refuse a local view tagged to a non-active account before touching Linear. *** Saving a Linear view locally -The other direction -- *copy down* -- forks a Linear view into a new, editable local view. =pearl-save-linear-view-locally= (=C-; L f d=, or =d= in the transient's Views group) lists your favorited Linear views, fetches the chosen view's filter, and reverse-compiles it into a Pearl authoring filter you can then edit and rename. The new local view is independent: it carries no tracking link, so editing or renaming it never touches the Linear view (publish it back later to push your changes up as a new Linear view). +The other direction -- *copy down* -- forks a Linear view into a new, editable local view. =pearl-save-linear-view-locally= (=C-; L v d=, or =D= in the transient's Views group) lists your favorited Linear views, fetches the chosen view's filter, and reverse-compiles it into a Pearl authoring filter you can then edit and rename. The new local view is independent: it carries no tracking link, so editing or renaming it never touches the Linear view (publish it back later to push your changes up as a new Linear view). Linear stores a view's filter as an =and=/=or= tree that's richer than Pearl's AND-only local model. Copy-down works for any view inside that model -- a team / state / label / assignee filter, the common case. When a view uses something Pearl can't represent (OR logic, a label parent, a due-date filter, or a multi-value filter on a singular dimension like project or assignee), copy-down *refuses and names the construct* rather than silently saving a filter that matches a different set of issues; run such a view directly with =pearl-run-linear-view= instead. To copy down *all* Linear views (not just favorited ones) is a later addition; v1 lists favorites. @@ -246,9 +248,9 @@ Linear stores a view's filter as an =and=/=or= tree that's richer than Pearl's A | Command | Binding | What it does | |------------------------------+----------------+------------------------------------------------------| -| =pearl-create-local-view= | =C-; L c v= | Build a filter interactively and save it as a local view | -| =pearl-edit-local-view= | =C-; L e v= | Edit a local view's filter, name, sort, and order, preserving its metadata | -| =pearl-save-linear-view-locally= | =C-; L f d= | Copy a favorited Linear view down into a new editable local view | +| =pearl-create-local-view= | =C-; L v c= | Build a filter interactively and save it as a local view | +| =pearl-edit-local-view= | =C-; L v e= | Edit a local view's filter, name, sort, and order, preserving its metadata | +| =pearl-save-linear-view-locally= | =C-; L v d= | Copy a favorited Linear view down into a new editable local view | =pearl-list-issues-filtered= also offers to save its ad-hoc filter as a local view at the end. Create, edit, and copy-down all prompt Replace / Rename / Cancel on a name collision, and under multiple accounts stamp the active account on a new view and refuse a cross-account edit. @@ -419,7 +421,7 @@ For per-URL routing (e.g. "Linear goes to the work-account browser, everything e :CUSTOM_ID: multiple-accounts :END: -If you work more than one Linear workspace — say a work account and a personal one — set =pearl-accounts= and switch between them with =M-x pearl-switch-account=. Each account names where its key is found, which Org file holds its issues, and (optionally) a default team: +If you work more than one Linear workspace — say a work account and a personal one — set =pearl-accounts= and switch between them with =pearl-switch-account= (=C-; L w a=, or =M-x pearl-switch-account=). Each account names where its key is found, which Org file holds its issues, and (optionally) a default team: #+begin_src elisp (setq pearl-accounts |