doomemacs/modules/feature/workspaces/README.org

#+TITLE: :feature workspaces

This module adds support for workspaces, powered by persp_mode, as well as a API
for manipulating them.

#+begin_quote
There are many ways to use workspaces. I spawn a workspace per task. Say I'm
working in the main workspace, when I realize there is a bug in another part of
my project. I open a new workspace and deal with it in there. In the meantime, I
need to check my email, so mu4e gets its own workspace.

Once I've completed the task, I close the workspace and return to main.
#+end_quote

* Table of Contents :TOC:
- [[#install][Install]]
- [[#features][Features]]
  - [[#isolated-buffer-list][Isolated buffer-list]]
  - [[#automatic-workspaces][Automatic workspaces]]
  - [[#session-persistence][Session persistence]]
  - [[#workspace-persistence][Workspace persistence]]
- [[#appendix][Appendix]]
  - [[#commands--keybindings][Commands & Keybindings]]
  - [[#api][API]]

* Install
This module has no additional dependencies.

* Features
** Isolated buffer-list
When persp-mode is active, ~doom-buffer-list~ becomes workspace-restricted. You
can overcome this by using ~buffer-list~.

** Automatic workspaces
A workspace is automatically created (and switched to) when you:

+ Create a new frame (with =make-frame=; bound to =M-N= by default).
+ Switch to a project using ~projectile-switch-project~.

** Session persistence
By default, your session is autosaved when you quit Emacs (or disable
~persp-mode~). You can load a previous session with ~M-x
+workspace/load-session~ or ~:sl[oad]~ (ex command).

You can supply either a name to load a specific session to replace your current
one.

** Workspace persistence
If you'd like to save a specific workspace, use ~M-x +workspace/save~, which can
be loaded into the current session (as another workspace) with ~M-x
+workspace/load~.

* Appendix
** Commands & Keybindings
Here is a list of available commands, their default keybindings (defined in
[[../../private/default/+bindings.el][private/default/+bindings.el]]), and corresponding ex commands (if any -- defined
in [[../../private/default/+evil-commands.el][private/default/+evil-commands.el]]).

| command                   | key / ex command           | description                                                |
|---------------------------+----------------------------+------------------------------------------------------------|
| ~+workspace/new~          | =SPC TAB n=                | Create a new, blank workspace                              |
| ~+workspace/display~      | =SPC TAB TAB=              | Display open workspaces in the mode-line                   |
| ~+workspace/load~         | =SPC TAB l=                | Load a saved workspace into the current session            |
| ~doom/quicksave-load~     | =SPC TAB L= / =:sl[oad]=   | Replace current session with a saved one                   |
| ~+workspace/save~         | =SPC TAB s=                | Save the current workspace to a file                       |
| ~doom/quicksave-save~     | =SPC TAB S= / =:ss[ave]=   | Save current session                                       |
| ~+workspace/switch-to~    | =SPC TAB .=                | Switch to an open workspace                                |
| ~+workspace/switch-left~  | =SPC TAB [= / =[ w= / =gT= | Switch to previous workspace                               |
| ~+workspace/switch-right~ | =SPC TAB [= / =] w= / =gt= | Switch to next workspace                                   |
| ~+workspace/kill-session~ | =SPC TAB X= / =:sclear=    | Clears the current session (kills all windows and buffers) |

** API
+ ~+workspace-list~ -> list<Struct>
+ ~+workspace-list-names~ -> list<string>
+ ~+workspace-buffer-list &optional PERSP~ -> bool
+ ~+workspace-p OBJ~ -> bool
+ ~+workspace-exists-p NAME~ -> bool
+ ~+workspace-get NAME &optional NOERROR~ -> Struct
+ ~+workspace-current &optional FRAME WINDOW~ -> Struct
+ ~+workspace-current-name~ -> string
+ ~+workspace-load NAME~
+ ~+workspace-load-session NAME~
+ ~+workspace-save NAME~
+ ~+workspace-save-session NAME~
+ ~+workspace-new NAME~
+ ~+workspace-rename NAME NEW-NAME~
+ ~+workspace-delete NAME &optional INHIBIT-KILL-P~
+ ~+workspace-switch NAME &optional AUTO-CREATE-P~
+ ~+workspace-protected-p NAME~ -> bool