Usage

Table of Contents

• What is a "purpose"?
• Basic usage
• Creating Custom Commands
  • Imitate purpose-find-file-overload
• Combining with other Emacs features and packages
  • winner-mode
  • windmove
  • golden-ratio

What is a "purpose"?

Before you understand how to use Purpose, you need to understand what we call a "purpose":

Every window and every buffer has a purpose.
When we use buffers, we use them for something - we call that a "purpose". Some buffers you edit (code, text), others are a terminal (shell, python interpreter, etc.), and so on.
The purpose of a buffer doesn't change - it is determined by the purpose configuration. However, the purpose of a window does change - it always has its buffer's purpose.

The default purpose of buffer, if it couldn't be determined by the purpose configuration, is 'general.

Basic usage

Purpose works as a global minor mode. Turn it on and off with M-x purpose-mode.
The main thing that Purpose does is keep your window layout the way you like it, even when you switch buffers.
Using Purpose has four aspects:

1. Setting your window layout
   Open, close and resize windows however you like, so the window layout is comfortable. You can also save your window layout (M-x purpose-save-window-layout), or load a previously saved layout (M-x purpose-load-window-layout).

2. Switching buffers
   Don't worry about it. You decide which buffer to open, Purpose opens it in the correct window. Purpose overrides the regular switching commands (C-x b, C-x 4 b, C-x C-f, etc.), so you don't have to learn new keybindings.
   But how Purpose knows where to put your buffer? It checks the buffer's purpose, then looks for a window with the same purpose. If it can't find one, it will use another window or create a new one.

3. Dedicated windows
   You can dedicate a window to its current buffer (C-c , D), which means that Purpose will not use it to display other buffers, even if they have the same purpose.
   You can also dedicate a window to its current purpose (C-c , d), which means that Purpose will use it only for buffers with the same purpose.
   In short: the purpose of non-dedicated windows can change, the purpose of dedicated windows can't change.
   If you want a window to retain its purpose, dedicate it with C-c , d.
   By the way, C-c , d and C-c , D` also undedicate dedicated windows.

4. Configuration
   Purpose comes with a default configuration. This configuration determines the purpose of each buffer. You can change this configuration. See Purpose Configuration for more.

For a full list of keys and commands, see Keys & Commands.

Creating Custom Commands

Purpose ships with some macros to help you write your own purpose-related commands.

• without-purpose: For code that needs Purpose to be disabled temporarily

  Example: open *Messages* buffer in current window, even if the current window is purpose-dedicated or if there is another window that matches *Messages* buffer's purpose:

  (without-purpose (switch-to-buffer "*Messages*"))

• without-purpose-command: To run a command with Purpose temporarily disabled

  Example: open window according to original dired-find-file rules:

  (defalias 'dired-find-file-without-purpose
    (without-purpose-command #'dired-find-file))

  Running M-x dired-find-file-without-purpose from Dired will usually open the file in the same window instead of Dired buffer.

• define-purpose-prefix-overload: Bind several commands to the same key, distinguish by prefix argument

  Example: C-. to call switch-to-buffer, C-u C-. to call find-file, and C-u C-u C-. to call recentf-open-files:

  (define-purpose-prefix-overload open-stuff
    '(switch-to-buffer find-file recentf-open-files))
  
  (global-set-key (kbd "C-.") #'open-stuff)

  C-u 2 C-. or C-2 C-. will work the same as C-u C-u C-.

Imitate purpose-find-file-overload

Command purpose-find-file-overload lets you use C-x C-f to open a file, and use C-u C-x C-f to open a file with Purpose temporarily disabled. You can create your own commands with similar behavior.

For example, RET in a Dired buffer normally calls dired-find-file. But what if sometimes you don't want Purpose to decide where to display the file? The following code snippet lets you invoke dired-find-file with Purpose disabled via C-u RET, while retaining regular dired-find-file at RET:

(defalias 'dired-find-file-without-purpose
  (without-purpose-command #'dired-find-file))

(define-purpose-prefix-overload dired-find-file-overload
  '(dired-find-file dired-find-file-without-purpose))

(with-eval-after-load 'dired
  (define-key dired-mode-map [remap dired-find-file] #'dired-find-file-overload))

Combining with other Emacs features and packages

Here are several Emacs features and packages that might go well with Purpose.

winner-mode

Winner-mode is good for undoing (and redoing) changes in the window layout, which could come in handy, and works well with Purpose. You can read about it in EmacsWiki and Irreal.

windmove

Windmove lets you use <shift> + <arrow key> to switch between windows, which is really convenient for selecting windows. You can read about it in Irreal too.

golden-ratio

golden-ratio is a package that automatically resizes windows according to the golden-ratio, so that the selected window is always more prominent than the other windows. If you use purpose-x-golden-ratio-setup from window-purpose-x.el it actually works pretty well with Purpose.

Desktop Save Mode

Desktop Save Mode is a built-in feature that persists your Emacs session across restarts. You can read about it here. When restoring a previous session, the purpose-dedication state of a window is also restored.