Merge pull request #428 from cameronr/watch-git-branch-changes

feat(git): branch tracking with auto-save/restore

Author: cameronr

README.md

@@ -64,7 +64,8 @@ Here are the default settings:
   suppressed_dirs = nil, -- Suppress session restore/create in certain directories
   allowed_dirs = nil, -- Allow session restore/create in certain directories
   auto_restore_last_session = false, -- On startup, loads the last saved session if session for cwd does not exist
-  use_git_branch = false, -- Include git branch name in session name
+  git_use_branch_name = false, -- Include git branch name in session name
+  git_auto_restore_on_branch_change = false, -- Should we auto-restore the session when the git branch changes. Requires git_use_branch_name
   lazy_support = true, -- 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
   bypass_save_filetypes = nil, -- List of filetypes to bypass auto save when the only buffer open is one of the file types listed, useful to ignore dashboards
   close_unsupported_windows = true, -- Close windows that aren't backed by normal file before autosaving a session

doc/auto-session.txt

@@ -11,44 +11,45 @@ Config                                                     *auto-session.config*
 AutoSession.Config                                          *AutoSession.Config*
 
     Fields: ~
-        {enabled?}                      (boolean)           Enables/disables auto saving and restoring
-        {root_dir?}                     (string)            root directory for session files, by default is `vim.fn.stdpath('data') .. '/sessions/'`
-        {auto_save?}                    (boolean)           Enables/disables auto saving session on exit
-        {auto_restore?}                 (boolean)           Enables/disables auto restoring session on start
-        {auto_create?}                  (boolean|function)  Enables/disables auto creating new session files. Can take a function that should return true/false if a new session file should be created or not
-        {auto_delete_empty_sessions?}   (boolean)           Enables/disables deleting the session if there no named, non-empty buffers when auto-saving
-        {suppressed_dirs?}              (table)             Suppress auto session for directories
-        {allowed_dirs?}                 (table)             Allow auto session for directories, if empty then all directories are allowed except for suppressed ones
-        {auto_restore_last_session?}    (boolean)           On startup, loads the last saved session if session for cwd does not exist
-        {use_git_branch?}               (boolean)           Include git branch name in session name to differentiate between sessions for different git branches
-        {lazy_support?}                 (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
-        {bypass_save_filetypes?}        (table)             List of file types to bypass auto save when the only buffer open is one of the file types listed, useful to ignore dashboards
-        {close_unsupported_windows?}    (boolean)           Whether to close windows that aren't backed by a real file
-        {args_allow_single_directory?}  (boolean)           Follow normal sesion save/load logic if launched with a single directory as the only argument
-                                                            Argv Handling
-        {args_allow_files_auto_save?}   (boolean|function)  Allow saving a session even when launched with a file argument (or multiple files/dirs). It does not load any existing session first. While you can just set this to true, you probably want to set it to a function that decides when to save a session when launched with file args. See documentation for more detail
-        {continue_restore_on_error?}    (boolean)           Keep loading the session even if there's an error. Set to false to get the line number of an error when loading a session
-        {show_auto_restore_notif?}      (boolean)           Whether to show a notification when auto-restoring
-        {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
-        {cwd_change_handling?}          (boolean)           Follow cwd changes, saving a session before change and restoring after
-        {lsp_stop_on_restore?}          (boolean|function)  Should language servers be stopped when restoring a session. Can also be a function that will be called if set. Not called on autorestore from startup
-        {restore_error_handler?}        (restore_error_fn)  Called when there's an error restoring. By default, it ignores fold errors otherwise it displays the error and returns false to disable auto_save
-
-        {purge_after_minutes?}          (number|nil)        -- Sessions older than purge_after_minutes will be deleted asynchronously on startup, e.g. set to 14400 to delete sessions that haven't been accessed for more than 10 days, defaults to off (no purging), requires >= nvim 0.10
-        {session_lens?}                 (SessionLens)       Session lens configuration options
-
-        {pre_save_cmds?}                (table)             executes before a session is saved
-
-                                                            Hooks
-        {save_extra_cmds?}              (table)             executes before a session is saved
-        {post_save_cmds?}               (table)             executes after a session is saved
-        {pre_restore_cmds?}             (table)             executes before a session is restored
-        {post_restore_cmds?}            (table)             executes after a session is restored
-        {pre_delete_cmds?}              (table)             executes before a session is deleted
-        {post_delete_cmds?}             (table)             executes after a session is deleted
-        {no_restore_cmds?}              (table)             executes at VimEnter when no session is restored
-        {pre_cwd_changed_cmds?}         (table)             executes before cwd is changed if cwd_change_handling is true
-        {post_cwd_changed_cmds?}        (table)             executes after cwd is changed if cwd_change_handling is true
+        {enabled?}                            (boolean)           Enables/disables auto saving and restoring
+        {root_dir?}                           (string)            root directory for session files, by default is `vim.fn.stdpath('data') .. '/sessions/'`
+        {auto_save?}                          (boolean)           Enables/disables auto saving session on exit
+        {auto_restore?}                       (boolean)           Enables/disables auto restoring session on start
+        {auto_create?}                        (boolean|function)  Enables/disables auto creating new session files. Can take a function that should return true/false if a new session file should be created or not
+        {auto_delete_empty_sessions?}         (boolean)           Enables/disables deleting the session if there no named, non-empty buffers when auto-saving
+        {suppressed_dirs?}                    (table)             Suppress auto session for directories
+        {allowed_dirs?}                       (table)             Allow auto session for directories, if empty then all directories are allowed except for suppressed ones
+        {auto_restore_last_session?}          (boolean)           On startup, loads the last saved session if session for cwd does not exist
+        {git_use_branch_name?}                (boolean)           Include git branch name in session name to differentiate between sessions for different git branches
+        {git_auto_restore_on_branch_change?}  (boolean)           Should we auto-restore the session when the git branch changes. Requires git_use_branch_name
+        {lazy_support?}                       (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
+        {bypass_save_filetypes?}              (table)             List of file types to bypass auto save when the only buffer open is one of the file types listed, useful to ignore dashboards
+        {close_unsupported_windows?}          (boolean)           Whether to close windows that aren't backed by a real file
+        {args_allow_single_directory?}        (boolean)           Follow normal sesion save/load logic if launched with a single directory as the only argument
+                                                                  Argv Handling
+        {args_allow_files_auto_save?}         (boolean|function)  Allow saving a session even when launched with a file argument (or multiple files/dirs). It does not load any existing session first. While you can just set this to true, you probably want to set it to a function that decides when to save a session when launched with file args. See documentation for more detail
+        {continue_restore_on_error?}          (boolean)           Keep loading the session even if there's an error. Set to false to get the line number of an error when loading a session
+        {show_auto_restore_notif?}            (boolean)           Whether to show a notification when auto-restoring
+        {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
+        {cwd_change_handling?}                (boolean)           Follow cwd changes, saving a session before change and restoring after
+        {lsp_stop_on_restore?}                (boolean|function)  Should language servers be stopped when restoring a session. Can also be a function that will be called if set. Not called on autorestore from startup
+        {restore_error_handler?}              (restore_error_fn)  Called when there's an error restoring. By default, it ignores fold errors otherwise it displays the error and returns false to disable auto_save
+
+        {purge_after_minutes?}                (number|nil)        -- Sessions older than purge_after_minutes will be deleted asynchronously on startup, e.g. set to 14400 to delete sessions that haven't been accessed for more than 10 days, defaults to off (no purging), requires >= nvim 0.10
+        {session_lens?}                       (SessionLens)       Session lens configuration options
+
+        {pre_save_cmds?}                      (table)             executes before a session is saved
+
+                                                                  Hooks
+        {save_extra_cmds?}                    (table)             executes before a session is saved
+        {post_save_cmds?}                     (table)             executes after a session is saved
+        {pre_restore_cmds?}                   (table)             executes before a session is restored
+        {post_restore_cmds?}                  (table)             executes after a session is restored
+        {pre_delete_cmds?}                    (table)             executes before a session is deleted
+        {post_delete_cmds?}                   (table)             executes after a session is deleted
+        {no_restore_cmds?}                    (table)             executes at VimEnter when no session is restored
+        {pre_cwd_changed_cmds?}               (table)             executes before cwd is changed if cwd_change_handling is true
+        {post_cwd_changed_cmds?}              (table)             executes after cwd is changed if cwd_change_handling is true
 
 
 SessionLens                                                        *SessionLens*

lua/auto-session/config.lua

@@ -16,7 +16,8 @@ local M = {}
 ---@field suppressed_dirs? table Suppress auto session for directories
 ---@field allowed_dirs? table Allow auto session for directories, if empty then all directories are allowed except for suppressed ones
 ---@field auto_restore_last_session? boolean On startup, loads the last saved session if session for cwd does not exist
----@field use_git_branch? boolean Include git branch name in session name to differentiate between sessions for different git branches
+---@field git_use_branch_name? boolean Include git branch name in session name to differentiate between sessions for different git branches
+---@field git_auto_restore_on_branch_change? boolean Should we auto-restore the session when the git branch changes. Requires git_use_branch_name
 ---@field lazy_support? 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
 ---@field bypass_save_filetypes? table List of file types to bypass auto save when the only buffer open is one of the file types listed, useful to ignore dashboards
 ---@field close_unsupported_windows? boolean Whether to close windows that aren't backed by a real file
@@ -79,7 +80,8 @@ local defaults = {
   suppressed_dirs = nil, -- Suppress session restore/create in certain directories
   allowed_dirs = nil, -- Allow session restore/create in certain directories
   auto_restore_last_session = false, -- On startup, loads the last saved session if session for cwd does not exist
-  use_git_branch = false, -- Include git branch name in session name
+  git_use_branch_name = false, -- Include git branch name in session name
+  git_auto_restore_on_branch_change = false, -- Should we auto-restore the session when the git branch changes. Requires git_use_branch_name
   lazy_support = true, -- 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
   bypass_save_filetypes = nil, -- List of filetypes to bypass auto save when the only buffer open is one of the file types listed, useful to ignore dashboards
   close_unsupported_windows = true, -- Close windows that aren't backed by normal file before autosaving a session
@@ -142,7 +144,7 @@ local function check_for_vim_globals(config)
     auto_session_suppress_dirs = "suppressed_dirs",
     auto_session_create_enabled = "auto_create",
     auto_session_enable_last_session = "auto_restore_last_session",
-    auto_session_use_git_branch = "use_git_branch",
+    auto_session_use_git_branch = "git_use_branch_name",
     pre_save_cmds = "pre_save_cmds",
     save_extra_cmds = "save_extra_cmds",
     post_save_cmds = "post_save_cmds",
@@ -176,7 +178,8 @@ local function check_old_config_names(config)
     auto_session_suppress_dirs = "suppressed_dirs",
     auto_session_create_enabled = "auto_create",
     auto_session_enable_last_session = "auto_restore_last_session",
-    auto_session_use_git_branch = "use_git_branch",
+    auto_session_use_git_branch = "git_use_branch_name",
+    use_git_branch = "git_use_branch_name",
     auto_restore_lazy_delay_enabled = "lazy_support",
     bypass_session_save_file_types = "bypass_save_filetypes",
     silent_restore = "continue_restore_on_error",
@@ -244,6 +247,10 @@ function M.check(logger)
     logger.warn "the purge_after_minutes options requires nvim >= 0.10"
   end
 
+  if not M.git_use_branch_name and M.git_auto_restore_on_branch_change then
+    logger.error "git_auto_restore_on_branch_change requires git_use_branch_name = true"
+  end
+
   -- TODO: At some point, we should pop up a warning about old config if
   -- M.has_old_config but let's make sure everything is working well before doing that
 end

lua/auto-session/git.lua

@@ -0,0 +1,102 @@
+local AutoSession = require "auto-session"
+local Config = require "auto-session.config"
+local Lib = require "auto-session.lib"
+
+local uv = vim.uv or vim.loop
+
+local M = {}
+
+M.uv_git_watcher = nil
+
+function M.on_git_watch_event(cwd, current_branch)
+  local new_branch = Lib.get_git_branch_name(cwd)
+
+  if new_branch == current_branch then
+    return
+  end
+
+  Lib.logger.debug("Git: branch changed, cur: " .. current_branch .. ", new: " .. new_branch)
+
+  -- need to save session for existing branch but can't use normal flow since
+  -- the branch name has already changed so we make the session name here and pass it in
+
+  -- NOTE: Generating the session name this way won't work with named sessions but we
+  -- don't support named sessions + git branch names together anyway
+
+  if Config.auto_save then
+    local session_name = Lib.combine_session_name_with_git_branch(cwd, current_branch)
+    AutoSession.SaveSession(session_name)
+  end
+
+  if Lib.has_modified_buffers() then
+    vim.ui.select({ "Yes", "No" }, {
+      prompt = 'Unsaved changes! Really restore session for branch: "' .. new_branch .. '"?',
+      format_item = function(item)
+        return item
+      end,
+    }, function(choice)
+      if choice == "Yes" then
+        AutoSession.AutoRestoreSession()
+      else
+        AutoSession.DisableAutoSave()
+        vim.notify(
+          "Session restore cancelled. Auto-save disabled.\nAfter saving your changes, run :SessionRestore\nto load the session for branch: "
+            .. new_branch
+        )
+      end
+    end)
+  else
+    -- No modified buffers, proceed with auto-restore
+    AutoSession.AutoRestoreSession()
+  end
+end
+
+---Watch for git branch changes
+---@param cwd string current working directory
+---@param towatch string file to watch, should be something like .git/HEAD
+function M.start_watcher(cwd, towatch)
+  if M.uv_git_watcher then
+    M.uv_git_watcher:stop()
+    Lib.logger.debug "Git: stopped old watcher so we can start a new one"
+  end
+
+  M.uv_git_watcher = assert(uv.new_fs_event())
+  local current_branch = Lib.get_git_branch_name(cwd)
+
+  Lib.logger.debug("Git: starting watcher", { cwd, current_branch })
+
+  -- Watch .git/HEAD to detect branch changes
+  M.uv_git_watcher:start(
+    towatch,
+    {},
+    Lib.debounce(function(err)
+      if err then
+        vim.schedule(function()
+          Lib.logger.err "Error watching for git branch changes"
+        end)
+        return
+      end
+
+      vim.schedule(function()
+        M.on_git_watch_event(cwd, current_branch)
+
+        -- git often (always?) replaces .git/HEAD which can change the inode being
+        -- watched so we need to stop the current watcher and start another one to
+        -- make sure we keep getting future events
+        M.start_watcher(cwd, towatch)
+      end)
+    end, { ms = 100 })
+  )
+end
+
+function M.stop_watcher()
+  if not M.uv_git_watcher then
+    return
+  end
+
+  M.uv_git_watcher:stop()
+  Lib.logger.debug "Git: stopped watcher"
+  M.uv_git_watcher = nil
+end
+
+return M

lua/auto-session/health.lua

@@ -73,10 +73,14 @@ local function check_lazy_settings()
   end
 end
 
-function check_features()
-  if Config.purge_after_minutes and vim.fn.has "nvim-0.10" ~= 1 then
-    warn "The purge_after_minutes config option requires nvim 0.10 or greater to work"
-  end
+local function check_features()
+  local loggerObj = {
+    error = error,
+    info = info,
+    warn = warn,
+  }
+
+  Config.check(loggerObj)
 end
 
 function M.check()