Merge branch 'feature-save-as-session' of https://github.com/jackielii/kitty

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]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

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:
 

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)