#pragma section-numbers on <> = 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"); }}} = 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. == Variables == === session_dir === The default directory where sessions will be loaded and saved. This variable must be a [[https://developer.mozilla.org/En/NsIFile|nsIFile]] instance, or a subclass thereof. The default value is the {{{sessions}}} directory inside Conkeror's application profile directory. == Interactive Commands == === session-save === Prompts for a path and saves the current session there. === session-load-window-new === Prompts for a path and loads all windows in the session in new windows. === 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. === 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. === session-remove === Prompts for a path and removes the specified session. = 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. == Variables == === 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 [[https://developer.mozilla.org/En/NsIFile|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}}}. === 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}}}. === 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}}}. == Interactive Commands == === session-auto-save-load-window-new === Loads all windows of the auto-save session in new windows. === 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. === 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. === 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. == Caveats == === 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. === Daemon Mode === Auto-loading the auto-saved session at startup does not yet work properly with daemon mode.