1.1 GNU ELPA

activities may be installed into Emacs versions 29.1 or later from GNU ELPA by using the command M-x package-install RET activities RET. This will install the latest stable release, which is recommended.

1.2 Quelpa

To install directly from git (e.g. to test a pre-release version), it’s recommended to use Quelpa:

1. Install quelpa-use-package (which can be installed directly from MELPA).
2. Add this form to your init file (see Configuration for more details):

(use-package activities
  :quelpa (activities :fetcher github :repo "alphapapa/activities.el"))

If you choose to install it otherwise, please note that the author can’t offer help with manual installation problems.

3.1 Activities

For the purposes of this library, an "activity" is a window configuration and its associated buffers. When an activity is "resumed," its buffers are recreated and loaded into the window configuration, which is loaded into a frame or tab.

From the user’s perspective, an "activity" should be thought of as something like, "reading my email," "working on my Emacs library," "writing my book," "working for this client," etc. The user arranges a set of windows and buffers according to what’s needed, then saves it as a new activity. Later, when the user wants to return to doing that activity, the activity is "resumed," which restores the activity’s last-seen state, allowing the user to pick up where the activity was left off; but the user may also revert the activity to its default state, which may be used as a kind of entry point to doing the activity in general.

3.2 Compatibility

This library is designed to not interfere with other workflows and tools; it is intended to coexist and allow integration with them. For example, when activities-tabs-mode is enabled, non-activity-related tabs are not affected by it; and the user may close any tab using existing tab commands, regardless of whether it is associated with an activity.

3.3 Modes

activities-mode

Automatically saves activities’ states when Emacs is idle and when Emacs exits. Should be enabled while using this package (otherwise you would have to manually call activities-save-all, which would defeat much of the purpose of this library).

activities-tabs-mode

Causes activities to be managed as tab-bar tabs rather than frames (the default). (This is what the author uses; bugs present when this mode is not enabled are less likely to be found, so please report them.)

3.4 Workflow

An example of a workflow using activities:

1. Arrange windows in a tab according to an activity you’re performing.
2. Call activities-new (C-x C-a n) to save the activity under a name.
3. Perform the activity for a while.
4. Change window configuration, change tab, close the tab, or even restart Emacs.
5. Call activities-resume (C-x C-a C-a) to resume the activity where you left off.
6. Return to the original activity state with activities-revert (C-x C-a g).
7. Rearrange windows and buffers.
8. Call activities-new with a universal prefix argument (C-u C-x C-a n) to redefine an activity’s default state.
9. Suspend the activity with activities-suspend (C-x C-a s) (which saves its last state and closes its frame/tab).

3.5 Bindings

Key bindings are, as always, ultimately up to the user. However, in Configuration, we suggest a set of bindings with a simple philosophy behind them:

• A binding ending in a C-prefixed key is expected to result in the set of active activities being changed (e.g. defining a new activity, activating one, or deactivating one).
• A binding not ending in a C-prefixed key is expected to merely change an active one (e.g. reverting it) or do something else (like listing activities.)

3.6 Commands

activities-list (C-x C-a l)

List activities in a vtable buffer in which they can be managed with various commands.

activities-new (C-x C-a C-n)

Define a new activity whose default state is the current frame’s or tab’s window configuration. With prefix argument, overwrite an existing activity (thereby updating its default state to the current state).

activities-suspend (C-x C-a C-s)

Save an activity’s state and close its frame or tab.

activities-kill (C-x C-a C-k)

Discard an activity’s last state (so when it is resumed, its default state will be used), and close its frame or tab.

activities-resume (C-x C-a C-a)

Resume an activity, switching to a new frame or tab for its window configuration, and restoring its buffers. With prefix argument, restore its default state rather than its last.

activities-revert (C-x C-a g)

Revert an activity to its default state.

activities-switch (C-x C-a RET)

Switch to an already-active activity.

activities-switch-buffer (C-x C-a b)

Switch to a buffer associated with the current activity (or, with prefix argument, another activity).

activities-rename

Rename an activity.

activities-discard

Discard an activity permanently.

activities-save-all

Save all active activities’ states. (activities-mode does this automatically, so this command should rarely be needed.)

3.7 Bookmarks

When option activities-bookmark-store is enabled, an Emacs bookmark is stored when a new activity is made. This allows the command bookmark-jump (C-x r b) to be used to resume an activity (helping to universalize the bookmark system).

5.1 v0.6

Additions

• Command activities-switch-buffer switches to a buffer associated with the current activity (or, with prefix argument, another activity). (A buffer is considered to be associated with an activity if it has been displayed in its tab. Note that this feature currently requires activities-tabs-mode.)
• Command activities-rename renames an activity.
• Option activities-after-switch-functions, a hook called after switching to an activity.
• Option activities-set-frame-name sets the frame name after switching to an activity. (#33. Thanks to JD Smith.)
• Option activities-kill-buffers, when suspending an activity, kills buffers that were only shown in that activity.

Changes

• Default time format in activities list.
• When saving all activities, don’t persist to disk for each activity. (#34. Thanks to Al M. for reporting.)

5.2 v0.5.1

Fixes

• Listing activities without last-saved states.

5.3 v0.5

Additions

• Suggest setting variable edebug-inhibit-emacs-lisp-mode-bindings to avoid conflicts with suggested keybindings.
• Option activities-bookmark-warnings enables warning messages when a non-file-visiting buffer can’t be bookmarked (for debugging purposes).
• Option activities-resume-into-frame controls whether resuming an activity opens a new frame or uses the current one (when activities-tabs-mode is disabled). (#22. Thanks to Icy-Thought for suggesting.)

Changes

• Command activities-kill now discards an activity’s last state (while activities-suspend saves its last state), and closes its frame or tab.
• Face activities-tabs-face is renamed to activities-tabs, and now inherits from another face by default, which allows it to adjust with the loaded theme. (#24. Thanks to Karthik Chikmagalur for suggesting.)

Fixes

• Show a helpful error if a bookmark’s target file is missing. (#17. Thanks to JD Smith for reporting.)
• Sort order in activities-list.
• When discarding an inactive activity, don’t switch to it first. (#18. Thanks to JD Smith for reporting.)
• Don’t signal an error when debug-on-error is enabled and a buffer is not visiting a file. (#25. Thanks to Karthik Chikmagalur for reporting.)

5.4 v0.4

Additions

• Option activities-anti-save-predicates prevents saving activity states at inappropriate times.

Fixes

• Don’t save activity state if a minibuffer is active.
• Offer only active activities for suspending.
• Don’t raise frame when saving activity states. (See #4. Thanks to JD Smith for reporting.)

5.5 v0.3.3

Fixes

• Command activities-list shows a helpful message if no activities are defined. (#11. Thanks to fuzy112 for reporting.)
• Link in documentation (which works locally but not on GNU ELPA at the moment).

5.6 v0.3.2

Updated documentation, etc.

5.7 v0.3.1

Fixes

• Handle case in which activities-tabs-mode is enabled again without having been disabled (which caused an error in tab-bar-mode). (#7)

5.8 v0.3

Additions

• Command activities-list lists activities in a vtable buffer in which they can be managed.
• Offer current activity name by default when redefining an activity with activities-new.
• Record times at which activities’ states were updated.

5.9 v0.2

Additions

• Offer current project name by default for new activities. (Thanks to Joseph Turner.)
• Use current activity as default for various completions. (Thanks to Joseph Turner.)

Fixes

• Raise frame after selecting it. (Thanks to JD Smith for suggesting.)

5.10 v0.1.3

Fixes

• Autoloads.
• Command aliases.

5.11 v0.1.2

Fixes

• Some single-window configurations were not restored properly.

5.12 v0.1.1

Fixes

• Silence message about non-file-visiting buffers.

5.13 v0.1

Initial release.

6.1 Copyright assignment

This package is part of GNU Emacs, being distributed in GNU ELPA. Contributions to this project must follow GNU guidelines, which means that, as with other parts of Emacs, patches of more than a few lines must be accompanied by having assigned copyright for the contribution to the FSF. Contributors who wish to do so may contact emacs-devel@gnu.org to request the assignment form.