[Breaking Change Tracking]

[rmagatti]

Subscribe to this issue to track breaking changes to auto-session!

I try my best to not break things along the way but sometimes that is not possible and sometimes I make mistakes, either way, when planned for or unforeseen breaking changes happen, I'll update this issue with comments on it!

[cameronr]

I introduced a breaking change in #320 where auto-session will now, by default, try to restore a session if launched with a single parameter that's a directory. You can disable this behavior by setting 'args_allow_single_directory = false'. More info here:

rmagatti/auto-session#argument-handling

[cameronr]

#334 was just merged and while it is largely compatible with existing setups, it does include some breaking changes (as discussed in #257) with how vim commands work with arguments. It also includes a new session filename format (percent encoding some characters) but it transparently handles converting between the old format (e.g. %some%dir on *nix/MacOS and C++-some-dir on Windows) and the new percent encoding (%2Fsome%2Fdir format on both on all platforms)

Command Overhaul

How the commands work with arguments has been updated. The argument to any function (Save/Restore/Delete) is strictly a session name, which means either a named session (e.g mysession) or a path (e.g. /my/proj). It is no longer possible to specify a directory to save in and a session name all in one argument. That was necessary because it was impossible to make that consistent in all cases. The benefit is that arguments to the commands and what you see in the session picker are all consistent. See "/my/proj" as the session name in the session picker? Great, you can restore it with :SessionRestore /my/proj

:SessionSave " saves a session based on the `cwd` in `auto_session_root_dir`
:SessionSave my_session " saves a session called `my_session` in `auto_session_root_dir`

:SessionRestore " restores a session based on the `cwd` from `auto_session_root_dir`
:SessionRestore my_session " restores `my_session` from `auto_session_root_dir`

:SessionDelete " deletes a session based on the `cwd` from `auto_session_root_dir`
:SessionDelete my_session " deletes `my_sesion` from `auto_session_root_dir`

I also added a :SessionSearch command that will pop the Telescope picker if it's installed and vim.ui.select otherwise. DisableAutoSave was renamed to SessionDisableAutoSave to make it consistent with the rest of the commands and I added a toggle cmd useful for a keymap:

:SessionSearch " open a session picker, uses Telescope if installed, vim.ui.select otherwise

:SessionDisableAutoSave " disables autosave
:SessionDisableAutoSave! " enables autosave (still does all checks in the config)
:SessionToggleAutoSave " toggles autosave

In addition, RestoreSessionFromFile has been removed as a vim command because it's no longer necessary.

I decided not to expose SessionSaveToDir/SessionRestoreFromDir/SessionDeleteFromDir versions as vim cmds as they seem like more niche uses cases and they clutter the autocomplete list. That functionality is available in Lua, tho, as SaveSessionToDir, RestoreSessionFromDir, DeleteSessionFromDir.

As a little bonus, :SessionRestore/:SessionDelete also now get session name completion when you're typing.

New session filename format

Session file names are now percent encoded rather than the custom and different escaping methods used between *nix/MacOS and Windows. The new format is the same across all platforms and will percent encode all /\:*?"'<>+ |.% characters. The immediate benefit is supporting session names with dashes on windows and some slightly better git branch naming. This should mean fewer encoding related issues going forward.

When restoring a session, it will transparently move an old format session file to the new format and all places the search/delete sessions are able to read both formats.

current_session_name

The return from require('auto-session.lib').current_session_name is now the full session name, consistent with what is displayed in session search and used for save/restore. That means if it's a session that was automatically named after the cwd, it will be longer than was previously returned. To get just the last part of the session name (like the previous behavior), just pass true as an argument. For example, for the session named /some/dir/myproj, then require('auto-session.lib').current_session_name(true) will return just myproj

Fixes

Fixes: #55, #73, #148, #195, #204, #242, #250, #257, #262

#116: Addresses 1-4 but not 5 or 6.

#273: Doesn't fully address, especially the way we're handling git branches, but the simplicity of just having a session file without requiring a mapping table is desirable enough that I think it's worth seeing if this is good enough. If not, we can add a mapping layer on top.

[cameronr]

While it's backwards compatible, it's a big enough change that I wanted to document here. I've over-hauled the configuration in #359 to be focused on Lua which allows cleaning up the configuration names. All of the info is available in the readme.