![][image]

## About

`eyebrowse` is a global minor mode for Emacs that allows you to manage
your window configurations in a simple manner, just like tiling window
managers like i3wm with their workspaces do.  It displays their
current state in the modeline by default.  The behaviour is modeled
after [ranger], a file manager written in Python.

## Screenshot

![][screenshot]

See the lighter and the modeline indicator at the right side of the
bottom modeline?  That's what you get to see after enabling eyebrowse.

## Installation

Install via `package.el` from the [MELPA (stable)] repository by
setting them up if you haven't already and executing `M-x
package-install RET eyebrowse RET`.

## Quick Tutorial

Use `M-x eyebrowse-mode` to enable `eyebrowse` interactively.  If you
want to enable it automatically on startup, add `(eyebrowse-mode t)`
to your init file (either `~/.emacs` or `~/.emacs.d/init.el`).

You start with your current window config on slot 1.  Once you hit
`C-c C-w 2`, you will see the modeline indicator appearing and showing
slot 1 and 2 with slot 2 slightly emphasized.  Slot 1 has been saved
automatically for you and contains your last window config.  Do
something meaningful like a window split, then hit `C-c C-w 1`.  The
window config on slot 2 is saved and the window config from slot 1 is
loaded.  Try switching back and forth between them with `C-c C-w '` to
get a feeling for how subsequent window manipulations are handled.

To make keeping track of workspaces easier, a tagging feature was
added.  Use `C-c C-w ,` to set a tag for the current window config, it
will both appear in the modeline indicator and when using `M-x
eyebrowse-switch-to-window-config`.  Setting the tag to an empty value
will undo this change.

## Key bindings

The default key bindings are:

| Key bind  | Function                         |
|-----------+----------------------------------|
| C-c C-w < | Switch to previous window config |
| C-c C-w > | Switch to next window config     |
| C-c C-w ' | Switch to last window config     |
| C-c C-w " | Close current window config      |
| C-c C-w , | Rename current window config     |
| C-c C-w 0 | Switch to window config 0        |
| ...       | ...                              |
| C-c C-w 9 | Switch to window config 9        |

## Further Customization

Use `M-x customize-group RET eyebrowse` for a list of customizable
options.  The more interesting ones would be `eyebrowse-wrap-around`
and `eyebrowse-switch-back-and-forth` which affect both wrap around
and lazier switching.  It is also possible to change the behaviour of
creation of new workspaces by customizing `eyebrowse-new-workspace`.
By default the last one is simply cloned, setting it to `t` will start
out with as empty of a slate as possible (by just displaying a single
window with the scratch buffer in it).

The prefix for each binding defaults to `C-c C-w`, but you can change
it to something else by customizing `eyebrowse-keymap-prefix`.  If you
want to change it in your init file, insert the customization before
loading `eyebrowse.el`.  This includes enabling it with an auto-loaded
function, such as `eyebrowse-setup-evil-keys`,
`eyebrowse-setup-opinionated-keys` or `eyebrowse-mode`.

If you're not happy with the default keybindings, a riskier set can be
enabled additionally either by executing `M-:
(eyebrowse-setup-opinionated-keys)` interactively or inserting
`(eyebrowse-setup-opinionated-keys)` in your init file.  If the
function detects the [evil] package, it will enable extra key bindings
for it as well.

The extra key bindings are:

| Key bind | Function                         |
|----------+----------------------------------|
| C-<, gT  | Switch to previous window config |
| C->, gt  | Switch to next window config     |
| C-', zx  | Switch to last window config     |
| C-", gc  | Close current window config      |
| M-0      | Switch to window config 0        |
| ...      | ...                              |
| M-9      | Switch to window config 9        |

## Internals

This mode basically wraps what `C-x r w` and `C-x r j` would do, but
takes care of automatically saving and loading to a separate data
structure for you and does it in a slightly different manner (see
`window-state-put` and `window-state-get` for more details) to allow for
features like persistency in combination with [desktop.el].

## Notes

The `window-state-put` and `window-state-get` functions do not save
all window parameters.  If you use features like side windows that
store the window parameters `window-side` and `window-slot`, you will
need to customize `window-persistent-parameters` for them to be saved
as well:

    (add-to-list 'window-persistent-parameters '(window-side . writable))
    (add-to-list 'window-persistent-parameters '(window-slot . writable))

See [\#52] for further discussion.

## Persistence

[desktop.el] provides a built-in solution for saving and restoring
window configurations. See [eyebrowse-restore] for an alternative
solution to selectively restore window configurations, for example
when using several frames.

## Alternatives

The two most popular window configuration packages are [elscreen] and
[escreen].  Both are fairly old and have their share of bugs.  The
closest package I've found so far to eyebrowse with workspace-specific
buffers would be [perspective].  [wconf] is a minimal alternative with
half the lines of code (and features).  To have fancy features such as
morphing, try [workgroups] or [workgroups2].

## Name

Actually, I wanted to name this mode "eyebrows" for no real reason,
but then a silly typo happened.  The typo stuck.  So did the new name.

[image]: img/eyebrows.gif
[ranger]: https://ranger.github.io/
[screenshot]: img/scrot.png
[MELPA (stable)]: http://melpa.org/
[evil]: https://bitbucket.org/lyro/evil/wiki/Home
[desktop.el]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Saving-Emacs-Sessions.html#Saving-Emacs-Sessions
[\#52]: https://github.com/wasamasa/eyebrowse/issues/52
[eyebrowse-restore]: https://github.com/FrostyX/eyebrowse-restore
[elscreen]: https://github.com/shosti/elscreen
[escreen]: https://github.com/emacsattic/escreen
[perspective]: https://github.com/nex3/perspective-el
[wconf]: https://github.com/ilohmar/wconf
[workgroups]: https://github.com/tlh/workgroups.el
[workgroups2]: https://github.com/pashinin/workgroups2