diff --git a/docs/changelog.rst b/docs/changelog.rst index 345d147b2..de1a302c2 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -189,6 +189,10 @@ Detailed list of changes or a match expression for flexible tab selection, allowing sessions to preserve the active tab state (:doc:`sessions`) +- :ac:`save_as_session`: Add ``--base-dir`` option to specify a base directory + for saving session files with relative paths, useful when the current working + directory is not the desired location (:doc:`sessions`) + 0.43.1 [2025-10-01] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/sessions.rst b/docs/sessions.rst index 8b379c35a..85379d0c1 100644 --- a/docs/sessions.rst +++ b/docs/sessions.rst @@ -102,6 +102,17 @@ for a path at which to save the session file. Specify the path and the session will be saved there with the exact setup you created. The saved file will even be opened in your editor for you to review, automatically. +.. tip:: + If you want session files to be saved to a specific directory regardless of + your current working directory, use the ``--base-dir`` option. For example:: + + map f7>s save_as_session --use-foreground-process --base-dir ~/.local/share/kitty/sessions + + This is particularly useful when kitty is launched from system-wide shortcuts + where the working directory might not be your home directory. Note that + ``--relocatable`` is typically not used with ``--base-dir``, since relocatable + is meant for session files that are co-located with their project directories. + If instead, you want to create these by hand, see the example below which shows all the major keywords you can use in kitty session files: diff --git a/kitty/session.py b/kitty/session.py index e6e175dd4..4922f352c 100644 --- a/kitty/session.py +++ b/kitty/session.py @@ -627,6 +627,14 @@ If specified, only save all windows (and their parent tabs/OS Windows) that matc search expression. See :ref:`search_syntax` for details on the search language. In particular if you want to only save windows that are present in the currently active session, use :code:`--match=session:.`. + + +--base-dir +When specified, relative session filenames will be saved to this directory instead of the current +working directory. This is useful when kitty is launched from locations where the working directory +is not your home directory, such as from system-wide shortcuts. Note that :code:`--relocatable` is +typically not used with :code:`--base-dir`, since relocatable is meant for session files that are +co-located with their project directories. ''' @@ -634,6 +642,9 @@ def save_as_session_part2(boss: BossType, opts: SaveAsSessionOptions, path: str) if not path: return from .config import atomic_save + if opts.base_dir and not os.path.isabs(path): + base_dir = os.path.abspath(os.path.expanduser(opts.base_dir)) + path = os.path.join(base_dir, path) path = os.path.abspath(os.path.expanduser(path)) session = '\n'.join(boss.serialize_state_as_session(path, opts)) os.makedirs(os.path.dirname(path), exist_ok=True)