possession.txt

*possession*  Flexible session management for Neovim.


COMMANDS                                                 *possession-commands*

In commands with optional `name` argument, if the argument is omitted then
currently loaded session is used (unless noted otherwise).

                                                             *:PossessionSave*
:PossessionSave [{name}]~

Save the current session information under `session_dir`. Use
`:PossessionSave! [{name}]` to avoid asking for confirmation when overwriting
existing session file. If [{name}] is omitted and a session does not
already exist, you will be prompted for a name. 

                                                             *:PossessionLoad*
:PossessionLoad [{name}]~

Load given session from disk. If `name` is omitted then use last
loaded session name.

                                                          *:PossessionSaveCwd*
:PossessionSaveCwd

Save session for current working directory. Use `!` to avoid confirmation
dialog. The session name will be the current working directory.

                                                          *:PossessionLoadCwd*
:PossessionLoadCwd [{name}]

Load given session for current working directory. If `name` is omitted
then use last session name for the current working directory.

                                                           *:PossessionRename*
:PossessionRename [{name} [{new_name}]]~

Rename session `name` to `new_name`. If `new_name` is omitted then it is taken
from |vim.ui.input|. If `name` is omitted then current session name is used.

                                                            *:PossessionClose*
:PossessionClose~

Close current session deleting all open buffers. To delete buffers with
unsaved changes use `:PossessionClose!`.

                                                           *:PossessionDelete*
:PossessionDelete [{name}]~

Delete given session file. `:PossessionDelete!` will not ask for confirmation.

                                                             *:PossessionShow*
:PossessionShow [{name}]~

Show given session info.

                                                             *:PossessionList*
:PossessionList~

List available sessions. `:PossessionList!` will not hide the `vimscript`
field that contains commands generated by |:mksession|.


:PossessionListCwd [{dir}]~

List available sessions with a cwd that matches the specified `dir`.
If `dir` is omitted the current working directory is used.
`:PossessionListCwd!` will not hide the `vimscript` field that contains
commands generated by |:mksession|.

                                                          *:PossessionMigrate*
:PossessionMigrate {dir_or_file}~

Migrate regular |:mksession|-based session file to current `session_dir`. If a
directory is specified all files inside it will be migrated. Migration tries
to generate valid possession JSON files. It is a best-effort algorithm that
tries to guess session name from file name (without extension) and parses
vimscript to find `cwd`.


CONFIGURATION                                              *possession-config*

To configure the plugin use:
>
    require('possession').setup { ... }
<
The following configuration options are available:

session_dir~
    `string`
    Path under which the session files are saved.

silent~
    `boolean`
    Suppress info/debug messages (still logged to file if enabled).

load_silent~
    `boolean`
    Suppress Vim output when sourcing vimscript that loads the session.

debug~
    `boolean`
    Show debug logs.

logfile~
    `boolean | string`
    Save logs to `stdpath('log') .. 'possession.log` if `true` or to the file
    with given name if `string`.

prompt_no_cr~
    `boolean`
    When this option is set to true, yes/no prompts will use |getchar()| so
    that there is no need to hit enter (`<CR>`) - just hit `y` or `n`. When
    `prompt_no_cr = false`, `vim.ui.input` is used and you must hit enter to
    confirm the answer.

commands~
    `table | nil`
    If set to falsy value then no commands will be created.

commands.*~
    `string | nil`
    Allows to change the name of the `:Possession*` commands (e.g.
    `commands.save = 'SSave'`) or disable the command if set to a falsy value.

                                                         *possession-autosave*
autosave.current~
    `boolean | function(name: string): boolean`
    Automatically save current session if it exists. If no session has been
    loaded yet, then `autosave.cwd` and `autosave.tmp` settings are checked.

autosave.cwd~
    `boolean | function(): boolean`
    Automatically save session based on current (global) working directory
    if no session has been loaded yet. Higher priority than `autosave.tmp`.

autosave.tmp~
    `boolean | function(): boolean`
    Automatically save a temporary session if no session has been loaded yet.
    `autosave.cwd` has higher priority if enabled.

autosave.tmp_name~
    `string | function(): string`
    Name used for the temporary session when `autosave.tmp` is enabled.

autosave.on_load~
    `boolean`
    Run auto-save when loading another session, e.g. when using the
    `PossessionLoad` command.

autosave.on_quit~
    `boolean`
    Run auto-save when quitting Neovim during the |VimLeavePre| autocmd.
    Note: to properly save current session when quitting, use |:quitall|, this
    way the current window layout will be preserved.

                                                         *possession-autoload*
autoload~
    `string | function(): string
    Automatically load a session. Valid string values are:
    - `last` loads the last saved session
    - `auto_cwd` loads the session saved by `autosave.cwd` or `:PossessionSaveCwd`
    - `last_cwd` loads the last session for the current working directory

    If a function is provided, it needs to return the name of a session file
    or a directory. If it is a directory, the last session for that directory
    is loaded. The function can also return one of the above strings, in
    which case the behaviour is as defined for that string.

    Autoload is skipped when:
    - Neovim is passed any files or folders as arguments
    - `stdin` is piped to Neovim

                                                            *possession-hooks*
hooks.before_save~
    `function(name: string) => table | nil`
    Invoked on `possession.save` before any actions. Receives session name as
    an argument. Should return a table of `user_data` to be stored in the
    session file. This hook can also return a falsy value to abort session
    saving.

hooks.after_save~
    `function(name: string, user_data: table, aborted: boolean)`
    Invoked just before `possession.save` returns. Receives the final
    `user_data` that has been used for saving. If `aborted` is `true` then the
    session haven't been saved.

hooks.before_load~
    `function(name: string, user_data: table): table | nil`
    Invoked on `possession.load` just after retrieving session data. Receives
    session name and `user_data` for the session to be loaded. This hook
    can modify `user_data` or return it as is. If a falsy value is returned
    then loading will be aborted.

hooks.after_load~
    `function(name: string, user_data: table)`
    Invoked just before `possession.load` returns. Receives the `user_data`
    from the `before_load` hook.

                                                   *possession-plugins-config*
plugins~
    `table`
    This table contains configuration options for |possession-plugins|. Some
    keys are common to each plugin. The rest depends on a specific plugin.

plugins.*~
    `table | boolean`
    This is plugin configuration table. It can be set to `false` to disable a
    plugin. If set to `true` the plugin will be enabled with an empty table,
    which is sufficient with plugins that take no options.

plugins.*.hooks~
    `table { string } | nil`
    List of hook names which are enabled for this plugin. If set to `nil` then
    all hooks will be enabled (only the ones actually used by the plugin).
    Setting this to an empty table (`{}`) will disable all hooks.

                                                    *possession-close-windows*

Plugin that simply closes Vim windows on given hooks. Windows to close are
determined by configured matching rules.

Note: to delete buffers match them with |possession-close-windows| and wait
for |possession-delete-hidden-buffers| to do its job.

plugins.close_windows.preserve_layout~
    `boolean | function(window: number): boolean`
    When deleting a window preserve overall windows layout by replacing the
    window's buffer with a throwaway scratch buffer.

plugins.close_windows.match~
    `table`
    Rules for selecting windows to be closed.

plugins.close_windows.match.floating~
    `boolean`
    Match floating windows. It is recommended to set this to `true` as
    floating window may cause |:mksession| to mess up windows layout.

plugins.close_windows.match.buftype~
    `table { string }`
    List of 'buftype's that will match window's buffer.

plugins.close_windows.match.filetype~
    `table { string }`
    List of 'filetype's that will match window's buffer.

plugins.close_windows.match.custom~
    `boolean | function(window: number): boolean`
    Can be used for arbitrary window matching logic. Windows for which the
    function returns `true` will be closed.

                                            *possession-delete-hidden-buffers*

Plugin that deletes hidden buffers (buffers with no associated windows).
It will always run after |possession-close-windows| so all the previously
closed windows will also have their buffers deleted.

Note: instead of using this plugin on `before_save`, one could remove
`buffers` from 'sessionoptions' (or have both), which would ignore any
hidden buffers when saving sessions.

plugins.delete_hidden_buffers.force~
    `boolean | function(buffer: number): boolean`
    Delete buffers even if they contain changes.

    WARNING: this may lead to loosing unsaved changes. Instead of using this
    option consider removing `buffers` from 'sessionoptions'.

                                                   *possession-delete-buffers*

This plugin forcefully deletes all buffers before loading new session (on
`before_load` hook). This may be especially useful if using `buffers` in
'sessionopts' (if you need to store hidden buffers in sessions).

                                                        *possession-nvim-tree*

Saves nvim-tree explorer windows and restores them when loading the session.
Currently no configuration options beside enabling/disabling are available.

                                                         *possession-neo-tree*

Saves neo-tree windows and restores them when loading the session.

                                                  *possession-symbols-outline*
                                                          *possession-outline*

Saves symbols-outline.nvim/outline.nvim windows and restores when loading
session. NOTE: currently this only works for a single outline due to
symbols-outline.nvim limitations

                                                            *possession-tabby*

Saves tabby.nvim tab page names when saving the sessions and restores them
when loading.
Currently no configuration options beside enabling/disabling are available.

                                                              *possession-dap*

Saves nvim-dap breakpoints by filename and restores them when loading a
session.
                                                            *possession-dapui*

Closes and restores dapui view in a tab.

                                                          *possession-neotest*

Closes and restores the summary window.

                                                 *possession-stop-lsp-clients*

Stops all attached language server protocol clients.

                                                        *possession-telescope*

telescope~
    `table`
    Configuration for builtin possession telescope pickers.

telescope.previewer.enabled~
    `boolean`
    Show previewer in telescope picker.

telescope.previewer.previewer~
    `'pretty'|'raw'|function(opts):Previewer`
    Select previewer to use, either one of the ones included in this plugin or
    a custom previewer that will be returned from the function.

telescope.previewer.wrap_lines~
    `boolean`
    |wrap| lines in the preview window.

telescope.previewer.include_empty_plugin_data~
    `boolean`
    Remove keys in `plugin_data` with no important data.

telescope.previewer.cwd_colors.cwd~
    `string`
    Color to use when highlighting sesion cwd in paths. Interpreted as hex
    color if it starts with `#`, otherwise as a name of a highlight group.

telescope.previewer.cwd_colors.tab_cwd~
    `string[]`
    Colors to use when highlighting sesion tab_cwd in paths. Interpreted as hex
    color if it starts with `#`, otherwise as a name of a highlight group.
    The colors will be assigned to consecutive tab cwds, modulo-wrapping to
    start if there are move tab cwds than colors defined for this settings.

telescope.list~
    `table`
    List available sessions.

telescope.default_action~
    `string`
    Action (key from `telescope.list.mappings`) that is executed on `<cr>`.

telescope.mappings.*~
    `string|table`
    Keys used to bind given action. Can be a table of bindings for normal/insert
    mode or a string to use the same binding for both.


PLUGINS                                                   *possession-plugins*

Plugins are extensions that perform additional actions on hooks, similarly to
how user hooks work. Possession plugins are not equivalent to Vim plugins,
i.e. a possession plugin can implement actions related to an actual Vim
plugin (like closing/restoring `nvlm-tree` windows), but it could also do
any other work that is not related to any particular Vim plugin.

Plugins work by exposing hooks equivalent to the hooks provided to the user,
with some notable differences:

1. Hook functions take additional `config` parameter as first argument. It
contains current plugin configuration as defined under `plugins.<name>` in the
configuration table (set by `setup`, see |possession-config|).
Note: There is NO need to check if the plugin is enabled. This will be done
earlier, so if a plugin hook is called it means that it is enabled.

2. Instead of `user_data`, a `plugin_data` table is used. The plugin can use
it to store/retrieve data between sessions. Any hooks that would return
`user_data` should return this table. Returning `nil` will abort
saving/loading the session! The `plugin_data` table will be stored under
`plugins.<name>` path in the JSON file automatically.


SESSION FILE                                         *possession-session-file*

Session files are stored in JSON format with the following keys:

name~
    `string`
    Session name. The session file name should be in the format `<name>.json`,
    so the information is redundant and mismatch may sometimes lead to
    unexpected results.

cwd~
    `string`
    Vim's current working directory (|getcwd()|) at the moment of session
    creation.

vimscript~
    `string`
    Code genereated by |:mksession| that is used to restore a session.

user_data~
    `table`
    Used to store arbitrary user data. Value of this table is
    generated/available in |possession-hooks|.


AUTOCOMMANDS                                         *possession-autocommands*

The recommended way of integrating with session save/load events is to use the
provided |possession-hooks| or to create |possession-plugins| and define hooks
there. But there is also an option to perform simple actions using Neovim
|autocmd|. Neovim has a builtin |SessionLoadPost| autocmd which is executed
after loading the session. possession.nvim also defines |User| autocmd with
pattern `SessionSavePre` that will be executed just before |:mksession|.


vim:tw=78:et:ft=help:norl: