1. Overview

A session is a representation of windows and buffers, and the URLs loaded in them. Sessions may be saved to and loaded from disk. There are two types of sessions: manual and auto-save.

To load the session module, add the following to your rc:

require("session.js");

2. Manual Sessions

Manual sessions are named sessions created by the user. There is no limit on the number of manual sessions as they are plain text files.

2.1. Variables

2.1.1. session_dir

The default directory where sessions will be loaded and saved. This variable must be a nsIFile instance, or a subclass thereof.

The default value is the sessions directory inside Conkeror's application profile directory.

2.1.2. session_save_buffer_access_order

When true, the last-access order of buffers will be preserved in the session.

2.2. Interactive Commands

2.2.1. session-save

Prompts for a path and saves the current session there.

2.2.2. session-load-window-new

Prompts for a path and loads all windows in the session in new windows.

2.2.3. session-load-window-current

Prompts for a path and loads the first window of the session in the current window without affecting existing buffers. Additional windows in the session will be opened in new windows.

2.2.4. session-load-window-current-replace

Prompts for a path, closes all buffers in the current window, and loads the first window of the session in the current window. Additional windows in the session will be opened in new windows.

2.2.5. session-remove

Prompts for a path and removes the specified session.

3. Auto-Save Session

The auto-save session is created automatically by the browser. When a buffer is created or delete, or when a buffer's location changes, the current session is automatically saved.

The auto-save session is controlled by a mode, session-auto-save-mode, which is enabled by default when the session.js module is required in the rc:

require("session.js");

The auto-save session can be loaded automatically at startup when session-auto-save-mode is enabled. See the variable session_auto_save_auto_load for details.

3.1. Variables

3.1.1. session_auto_save_file

Specifies the location where the auto-save session should be stored. Its value may be one of two types:

string

If the value is a string, it will be interpreted as the filename of the auto-save session relative to session_dir. It must be a filename, not a full path.

nsIFile

If the value is an nsIFile (or sub-class) instance, it will be interpreted as the the full path to the auto-save session file.

The default value is "auto-save", a filename relative to session_dir.

3.1.2. session_auto_save_auto_load

Controls automatic loading of the auto-save session at startup, and may have one of three values.

true

The auto-saved session will be automatically loaded at start-up.

false

The auto-save session will not be automatically loaded at start-up, though it can be manually loaded with the session-auto-save-load-* interactive commands.

"prompt"

A prompt will be displayed at start-up asking whether or not to load the auto-save session.

The default value is false.

3.1.3. session_auto_save_auto_load_fn

Holds a reference to the function which should be used to load the auto-saved session when conkeror is started with URLs given on the command-line. It may have one of three values.

session_auto_save_load_window_new

Load the session in a new window.

session_auto_save_load_window_current

Load the session in the current window after loading the URLs given on the command line, or after any existing buffers.

null

Do not load the session when URLs are given on the command line. The auto-saved session can be manually loaded using the session-auto-save-load-* interactive commands.

The default value is null.

3.2. Interactive Commands

3.2.1. session-auto-save-load-window-new

Loads all windows of the auto-save session in new windows.

3.2.2. session-auto-save-load-window-current

Loads the first window of the auto-save session in the current window without affecting existing buffers. Additional windows in the session will be opened in new windows.

3.2.3. session-auto-save-load-window-current-replace

Closes all buffers in the current window and loads the first window of the auto-save session in the current window. Additional windows in the session will be opened in new windows.

3.2.4. session-auto-save-remove

Remove the auto-save session from disk. The auto-save session which is loaded at start-up is still cached in memory, so the session-auto-save-load-* commands can still be used.

3.3. Caveats

3.3.1. Closing Conkeror Properly

Due to a bug in conkeror, when conkeror is closed via window manager events (like clicking the 'X' in the window decoration), the session is not automatically saved. For the session to be saved, you must exit using C-x C-c.

However, if conkeror crashes, the session will still be available, and buffers open at the time of the crash will be recoverable.

3.3.2. Daemon Mode

Auto-loading the auto-saved session at startup does not yet work properly with daemon mode.