Overhauled vim cmds and percent encoding session file names

doc/auto-session.txt

@@ -2,17 +2,17 @@ defaultConf                                                        *defaultConf*
     table default config for auto session
 
     Fields: ~
-        {log_level?}                         (string|integer)        "debug", "info", "warn", "error" or vim.log.levels.DEBUG, vim.log.levels.INFO, vim.log.levels.WARN, vim.log.levels.ERROR
-        {auto_session_enable_last_session?}  (boolean)
-        {auto_session_root_dir?}             (string)                root directory for session files, by default is `vim.fn.stdpath('data')/sessions/`
-        {auto_session_enabled?}              (boolean)               enable auto session
-        {auto_session_create_enabled}        (boolean|function|nil)  Enables/disables auto creating new sessions. Can take a function that should return true/false if a session should be created or not
-        {auto_save_enabled?}                 (boolean)               Enables/disables auto saving session
-        {auto_restore_enabled?}              (boolean)               Enables/disables auto restoring session
-        {auto_restore_lazy_delay_enabled?}   (boolean)               Automatically detect if Lazy.nvim is being used and wait until Lazy is done to make sure session is restored correctly. Does nothing if Lazy isn't being used. Can be disabled if a problem is suspected or for debugging
-        {auto_session_suppress_dirs?}        (table)                 Suppress auto session for directories
-        {auto_session_allowed_dirs?}         (table)                 Allow auto session for directories, if empty then all directories are allowed except for suppressed ones
-        {auto_session_use_git_branch?}       (boolean)               Include git branch name in session name to differentiate between sessions for different git branches
+        {auto_session_enabled?}              (boolean)           Enables/disables auto saving and restoring
+        {auto_session_root_dir?}             (string)            root directory for session files, by default is `vim.fn.stdpath('data') .. '/sessions/'`
+        {auto_save_enabled?}                 (boolean)           Enables/disables auto saving session on exit
+        {auto_restore_enabled?}              (boolean)           Enables/disables auto restoring session on start
+        {auto_session_suppress_dirs?}        (table)             Suppress auto session for directories
+        {auto_session_allowed_dirs?}         (table)             Allow auto session for directories, if empty then all directories are allowed except for suppressed ones
+        {auto_session_create_enabled}        (boolean|function)  Enables/disables auto creating new sessions. Can take a function that should return true/false if a session should be created or not
+        {auto_session_enable_last_session?}  (boolean)           On startup, loads the last saved session if session for cwd does not exist
+        {auto_session_use_git_branch?}       (boolean)           Include git branch name in session name to differentiate between sessions for different git branches
+        {auto_restore_lazy_delay_enabled?}   (boolean)           Automatically detect if Lazy.nvim is being used and wait until Lazy is done to make sure session is restored correctly. Does nothing if Lazy isn't being used. Can be disabled if a problem is suspected or for debugging
+        {log_level?}                         (string|integer)    "debug", "info", "warn", "error" or vim.log.levels.DEBUG, vim.log.levels.INFO, vim.log.levels.WARN, vim.log.levels.ERROR
 
 
 luaOnlyConf                                                        *luaOnlyConf*
@@ -46,155 +46,144 @@ session_control                                                *session_control*
 
 
 AutoSession.setup({config})                                  *AutoSession.setup*
-    Setup function for AutoSession
+    Setup function for AutoSession. Config is not marked as defaultConf so it doesn't
+    create a diagnostic about missing fields.
 
     Parameters: ~
-        {config}  (defaultConf)  config for auto session
+        {config}  (table|nil)  Config for auto session
 
 
-AutoSession.setup_session_lens()                *AutoSession.setup_session_lens*
-
-
-AutoSession.get_latest_session()                *AutoSession.get_latest_session*
-    Get latest session for the "last session" feature
+AutoSession.session_exists_for_cwd()        *AutoSession.session_exists_for_cwd*
+    Quickly checks if a session file exists for the current working directory.
+    This is useful for starter plugins which don't want to display 'restore session'
+    unless a session for the current working directory exists.
 
     Returns: ~
-        (string|nil)
+        (boolean)  if a session exists for the cwd
 
 
-AutoSession.session_exists_for_cwd()        *AutoSession.session_exists_for_cwd*
-
-
-                                                   *AutoSession.AutoSaveSession*
-AutoSession.AutoSaveSession({sessions_dir?})
+AutoSession.AutoSaveSession()                      *AutoSession.AutoSaveSession*
     AutoSaveSession
     Function called by auto_session to trigger auto_saving sessions, for example on VimExit events.
 
-    Parameters: ~
-        {sessions_dir?}  (string)  the session directory to auto_save a session for. If empty this function will end up using the cwd to infer what session to save for.
-
-
-                                                      *AutoSession.get_root_dir*
-AutoSession.get_root_dir({with_trailing_separator?})
-    Gets the root directory of where to save the sessions.
-    By default this resolves to `vim.fn.stdpath "data" .. "/sessions/"`
-
-    Parameters: ~
-        {with_trailing_separator?}  (boolean)  whether to incude the trailing separator. A few places (telescope picker don't expect a trailing separator)
-
     Returns: ~
-        (string)
+        (boolean)  if a session was saved
 
 
-AutoSession.get_cmds({typ})                               *AutoSession.get_cmds*
-    Get the hook commands to run
-    This function gets cmds from both lua and vimscript configs
+                                                *AutoSession.AutoRestoreSession*
+AutoSession.AutoRestoreSession({session_name?})
+    Function called by AutoSession when automatically restoring a session.
 
     Parameters: ~
-        {typ}  (string)
+        {session_name?}  (string)  An optional session to load
 
     Returns: ~
-        (function[]|string[])
-
+        (boolean)  returns whether restoring the session was successful or not.
 
-PickerItem                                                          *PickerItem*
 
-    Fields: ~
-        {display_name}  (string)
-        {path}          (string)
+AutoSession.PurgeOrphanedSessions()          *AutoSession.PurgeOrphanedSessions*
+     Deletes sessions where the original directory no longer exists
 
 
-AutoSession.format_file_name({path})              *AutoSession.format_file_name*
-     Formats an autosession file name to be more presentable to a user
+                                                       *AutoSession.SaveSession*
+AutoSession.SaveSession({session_name?}, {show_message?})
+    Saves a session to the dir specified in the config. If no optional
+    session name is passed in, it uses the cwd as the session name
 
     Parameters: ~
-        {path}  (string)
-
-    Returns: ~
-        (string)
-
-
-AutoSession.get_session_files()                  *AutoSession.get_session_files*
+        {session_name?}  (string|nil)  Optional session name
+        {show_message?}  (boolean)     Optional, whether to show a message on save (true by default)
 
     Returns: ~
-        (PickerItem[])
+        (boolean)
 
 
-                                                       *AutoSession.SaveSession*
-AutoSession.SaveSession({sessions_dir?}, {auto})
+                                                  *AutoSession.SaveSessionToDir*
+AutoSession.SaveSessionToDir({session_dir}, {session_name?}, {show_message?})
+    Saves a session to the passed in directory. If no optional
+    session name is passed in, it uses the cwd as the session name
 
     Parameters: ~
-        {sessions_dir?}  (string)
-        {auto}           (boolean)
+        {session_dir}    (string)      Directory to write the session file to
+        {session_name?}  (string|nil)  Optional session name
+        {show_message?}  (boolean)     Optional, whether to show a message on save (true by default)
 
+    Returns: ~
+        (boolean)
 
-                                                *AutoSession.AutoRestoreSession*
-AutoSession.AutoRestoreSession({session_dir})
-    Function called by AutoSession when automatically restoring a session.
 
-    Parameters: ~
-        {session_dir}  (any)
+                                                    *AutoSession.RestoreSession*
+AutoSession.RestoreSession({session_name?}, {show_message?})
+    Restores a session from the passed in directory. If no optional session name
+    is passed in, it uses the cwd as the session name
 
-    Returns: ~
-        (boolean)  returns whether restoring the session was successful or not.
+    Parameters: ~
+        {session_name?}  (string|nil)  Optional session name
+        {show_message?}  (boolean)     Optional, whether to show a message on restore (true by default)
 
 
-                                            *AutoSession.RestoreSessionFromFile*
-AutoSession.RestoreSessionFromFile({session_file})
+                                             *AutoSession.RestoreSessionFromDir*
+AutoSession.RestoreSessionFromDir({session_dir}, {session_name?}, {show_message?})
+    Restores a session from the passed in directory. If no optional session name
+    is passed in, it uses the cwd as the session name
 
     Parameters: ~
-        {session_file}  (string)
+        {session_dir}    (string)      Directory to write the session file to
+        {session_name?}  (string|nil)  Optional session name
+        {show_message?}  (boolean)     Optional, whether to show a message on restore (true by default)
 
 
-                                                    *AutoSession.RestoreSession*
-AutoSession.RestoreSession({sessions_dir_or_file})
-    Restores the session by sourcing the session file if it exists/is readable.
-    This function is intended to be called by the user but it is also called by `AutoRestoreSession`
+                                                *AutoSession.RestoreSessionFile*
+AutoSession.RestoreSessionFile({session_path}, {show_message?})
+    Restores a session from a specific file
 
     Parameters: ~
-        {sessions_dir_or_file}  (string)  a dir string or a file string
+        {session_path}   (string)   The session file to load
+        {show_message?}  (boolean)  Optional, whether to show a message on restore (true by default)
 
     Returns: ~
-        (boolean)  returns whether restoring the session was successful or not.
-
+        (boolean)  a session restored
 
-AutoSession.DisableAutoSave()                      *AutoSession.DisableAutoSave*
-    DisableAutoSave
-    Intended to be called by the user
 
+                                                     *AutoSession.DeleteSession*
+AutoSession.DeleteSession({session_name?})
+    Deletes a session from the config session dir. If no optional session name
+    is passed in, it uses the cwd as the session name
 
-AutoSession.CompleteSessions()                    *AutoSession.CompleteSessions*
-    CompleteSessions is used by the vimscript command for session name/path completion.
-
-    Returns: ~
-        (string)
+    Parameters: ~
+        {session_name?}  (string|nil)  Optional session name
 
 
-AutoSession.DeleteSessionByName({...})         *AutoSession.DeleteSessionByName*
-    DeleteSessionByName deletes sessions given a provided list of paths
+                                              *AutoSession.DeleteSessionFromDir*
+AutoSession.DeleteSessionFromDir({session_dir}, {session_name?})
+    Deletes a session from the passed in directory. If no optional session
+    name is passed in, it uses the cwd as the session name
 
     Parameters: ~
-        {...}  (string[])
+        {session_dir}    (string)      Directory to delete the session from
+        {session_name?}  (string|nil)  Optional session name
 
 
-AutoSession.DeleteSession({...})                     *AutoSession.DeleteSession*
-    DeleteSession delets a single session given a provided path
+                                                 *AutoSession.DeleteSessionFile*
+AutoSession.DeleteSessionFile({session_path}, {session_name})
+    Delete a session file
 
     Parameters: ~
-        {...}  (string[])
-
+        {session_path}  (string)  The filename to delete
+        {session_name}  (string)  Session name being deleted, just use to display messages
 
-AutoSession.PurgeOrphanedSessions()          *AutoSession.PurgeOrphanedSessions*
-    PurgeOrphanedSessions deletes sessions with no working directory exist
+    Returns: ~
+        (boolean)  the session file delted
 
 
-                                                              *M.setup_autocmds*
-M.setup_autocmds({config}, {AutoSession})
-    Setup autocmds for DirChangedPre and DirChanged
+AutoSession.DisableAutoSave({enable?})             *AutoSession.DisableAutoSave*
+    Disables autosave. Enables autosave if enable is true
 
     Parameters: ~
-        {config}       (table)  auto session config
-        {AutoSession}  (table)  auto session instance
+        {enable?}  (boolean)  Optional paramter to enable autosaving
+
+    Returns: ~
+        (boolean)  autosaving is enabled or not
 
 
 session_lens_config                                        *session_lens_config*
@@ -222,26 +211,4 @@ SessionLens.search_session({custom_opts})
         {custom_opts}  (any)
 
 
-M.setup()                                                              *M.setup*
-
-
-M.source_session({prompt_bufnr})                              *M.source_session*
-    Source session action
-    Source a selected session after doing proper current session saving and cleanup
-
-    Parameters: ~
-        {prompt_bufnr}  (number)  the telescope prompt bufnr
-
-
-M.delete_session({prompt_bufnr})                              *M.delete_session*
-    Delete session action
-    Delete a selected session file
-
-    Parameters: ~
-        {prompt_bufnr}  (number)  the telescope prompt bufnr
-
-
-M.alternate_session()                                      *M.alternate_session*
-
-
 vim:tw=78:ts=8:noet:ft=help:norl:

lua/auto-session/autocmds.lua

@@ -2,6 +2,7 @@ local Lib = require "auto-session.lib"
 
 local M = {}
 
+---@private
 ---Setup autocmds for DirChangedPre and DirChanged
 ---@param config table auto session config
 ---@param AutoSession table auto session instance
@@ -30,8 +31,8 @@ M.setup_autocmds = function(config, AutoSession)
         return
       end
 
-      if AutoSession.restore_in_progress then
-        Lib.logger.debug "DirChangedPre: restore_in_progress is true, ignoring this event"
+      if AutoSession.restore_in_progress or vim.g.SessionLoad then
+        Lib.logger.debug "DirChangedPre: restore_in_progress/vim.g.SessionLoad is true, ignoring this event"
         -- NOTE: We don't call the cwd_changed_hook here
         -- I think that's probably the right choice because I assume that event is mostly
         -- for preparing sessions for save/restoring but we don't want to do that when we're
@@ -41,16 +42,6 @@ M.setup_autocmds = function(config, AutoSession)
 
       AutoSession.AutoSaveSession()
 
-      -- Clear all buffers and jumps after session save so session doesn't blead over to next session.
-
-      -- BUG: I think this is probably better done in RestoreSession. If we do it here and the
-      -- directory change fails (e.g. it doesn't exist), we'll have cleared the buffers and still be
-      -- in the same directory. If autosaving is enabled, we'll save an empty session when we exit
-      -- blowing away the session we were trying to save
-      vim.cmd "%bd!"
-
-      vim.cmd "clearjumps"
-
       if type(conf.pre_cwd_changed_hook) == "function" then
         conf.pre_cwd_changed_hook()
       end
@@ -71,12 +62,12 @@ M.setup_autocmds = function(config, AutoSession)
           return
         end
 
-        if AutoSession.restore_in_progress then
+        if AutoSession.restore_in_progress or vim.g.SessionLoad then
           -- NOTE: We don't call the cwd_changed_hook here (or in the other case below)
           -- I think that's probably the right choice because I assume that event is mostly
           -- for preparing sessions for save/restoring but we don't want to do that when we're
           -- already restoring a session
-          Lib.logger.debug "DirChanged: restore_in_progress is true, ignoring this event"
+          Lib.logger.debug "DirChangedPre: restore_in_progress/vim.g.SessionLoad is true, ignoring this event"
           return
         end
 
@@ -89,7 +80,7 @@ M.setup_autocmds = function(config, AutoSession)
         local success = AutoSession.AutoRestoreSession()
 
         if not success then
-          Lib.logger.info("Could not load session. A session file is likely missing for this cwd." .. vim.fn.getcwd())
+          Lib.logger.info("Could not load session for: " .. vim.fn.getcwd())
           -- Don't return, still dispatch the hook below
         end
 

lua/auto-session/health.lua

@@ -0,0 +1,37 @@
+local AutoSession = require "auto-session"
+
+local M = {}
+
+---@diagnostic disable-next-line: deprecated
+local start = vim.health.start or vim.health.report_start
+---@diagnostic disable-next-line: deprecated
+local ok = vim.health.ok or vim.health.report_ok
+---@diagnostic disable-next-line: deprecated
+local warn = vim.health.warn or vim.health.report_warn
+---@diagnostic disable-next-line: deprecated, unused-local
+local error = vim.health.error or vim.health.report_error
+---@diagnostic disable-next-line: deprecated
+local info = vim.health.info or vim.health.report_info
+
+local function check_sesssion_options()
+  if not vim.tbl_contains(vim.split(vim.o.sessionoptions, ","), "localoptions") then
+    warn(
+      "`vim.o.sessionoptions` should contain 'localoptions' to make sure\nfiletype and highlighting work correctly after a session is restored.\n\n"
+        .. "Recommended setting is:\n\n"
+        .. 'vim.o.sessionoptions="blank,buffers,curdir,folds,help,tabpages,winsize,winpos,terminal,localoptions"\n'
+    )
+  else
+    ok "vim.o.sessionoptions"
+  end
+end
+
+function M.check()
+  start "auto-session"
+
+  info("Session directory: " .. AutoSession.get_root_dir())
+  info("Current session: " .. AutoSession.Lib.current_session_name())
+  info("Current sesssion file: " .. vim.v.this_session)
+  check_sesssion_options()
+end
+
+return M