Document clone-in-kitty

docs/changelog.rst

@@ -37,6 +37,8 @@ Detailed list of changes
 0.25.1 [future]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+- Shell integration: Add a command to :ref:`clone_shell`
+
 - Remote control: Allow using :ref:`Boolean operators <search_syntax>` when constructing queries to match windows or tabs
 
 - Sessions: Fix :code:`os_window_size` and :code:`os_window_class` not applying to the first OS Window (:iss:`4957`)

docs/shell-integration.rst

@@ -30,6 +30,8 @@ Features
 
 * The text cursor is changed to a bar when editing commands at the shell prompt
 
+* :ref:`clone_shell` with all environment variables and the working directory copied
+
 * Glitch free window resizing even with complex prompts. Achieved by erasing
   the prompt on resize and allowing the shell to redraw it cleanly.
 
@@ -215,6 +217,39 @@ shell integration. Alternately, you can :ref:`setup shell integration manually
 the remote server and editing the shell rc files there, as described below.
 
 
+.. _clone_shell:
+
+Clone the current shell into a new window
+-----------------------------------------------
+
+You can clone the current shell into a new kitty window by simply running the
+command:
+
+.. code-block:: sh
+
+    clone-in-kitty
+
+This will open a new window running a new shell instance but with all
+environment variables and the current working directory copied. This even
+works over SSH when using :doc:`kittens/ssh`.
+
+The :file:`clone-in-kitty` command takes almost all the same arguments as the
+:doc:`launch <launch>` command, so you can open a new tab instead or a new OS
+window, etc. Arguments of launch that can cause code execution or that don't
+make sense when cloning are ignored. Most prominently, the following options
+are ignored: :option:`launch --allow-remote-control`, :option:`launch
+--copy-cmdline`, :option:`launch --copy-env`, :option:`launch
+--allow-remote-control`, :option:`launch --stdin-source`, :option:`launch
+--marker` and :option:`launch --watcher`.
+
+Some examples:
+
+.. code-block:: sh
+
+    clone-in-kitty --type=tab
+    clone-in-kitty --title "I am a clone"
+
+
 .. _manual_shell_integration:
 
 Manual shell integration

kitty/launch.py

@@ -529,7 +529,7 @@ def clone_and_launch(msg: str, window: Window) -> None:
         elif k == 'argv':
             cmdline = json.loads(v)
     opts = parse_opts_for_clone(args)
-    if cwd:
+    if cwd and not opts.cwd:
         opts.cwd = cwd
     opts.copy_colors = True
     if pid > -1: