From 01b55a55224aa243cebca061e99c9f5aad1bcd3f Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Mon, 26 Jun 2023 10:47:13 +0530
Subject: [PATCH] Document the new run-shell kitten

---
 docs/changelog.rst          |  2 ++
 docs/shell-integration.rst  | 28 ++++++++++++++++++++++++++--
 tools/cmd/run_shell/main.go |  4 ++--
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index d2422a2ae..5fdb18e66 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -40,6 +40,8 @@ Detailed list of changes
 
 - A new escape code ``<ESC>[22J`` that moves the current contents of the screen into the scrollback before clearing it
 
+- A new kitten :ref:`run-shell <run_shell>` to allow creating sub-shells with shell integration enabled
+
 - A new option :opt:`text_fg_override_threshold` to force text colors to have high contrast regardless of color scheme (:pull:`6283`)
 
 - When resizing OS Windows make the animation less jerky. Also show the window size in cells during the resize (:iss:`6341`)
diff --git a/docs/shell-integration.rst b/docs/shell-integration.rst
index 475e826e9..fe7bcb96e 100644
--- a/docs/shell-integration.rst
+++ b/docs/shell-integration.rst
@@ -292,6 +292,30 @@ In order to avoid remote code execution, kitty will only execute the configured
 editor and pass the file path to edit to it.
 
 
+.. _run_shell:
+
+Using shell integration in sub-shells, containers, etc.
+-----------------------------------------------------------
+
+To start a sub-shell with shell integration automatically setup, simply run::
+
+    kitten run-shell
+
+This will start a sub-shell using the same binary as the currently running
+shell, with shell-integration enabled. To start a particular shell use::
+
+    kitten run-shell --shell=/bin/bash
+
+To run a command before starting the shell use::
+
+    kitten run-shell ls .
+
+This will run ``ls .`` before starting the shell.
+
+This will even work on remote systems where kitty itself is not installed,
+provided you use the :doc:`SSH kitten <kittens/ssh>` to connect to the system.
+Use ``kitten run-shell --help`` to learn more.
+
 .. _manual_shell_integration:
 
 Manual shell integration
@@ -299,8 +323,8 @@ Manual shell integration
 
 The automatic shell integration is designed to be minimally intrusive, as such
 it won't work for sub-shells, terminal multiplexers, containers, etc.
-For such systems, you should setup manual shell integration by adding some code
-to your shells startup files to load the shell integration script.
+For such systems, you should either use the :ref:`run-shell <run_shell>` command described above or
+setup manual shell integration by adding some code to your shells startup files to load the shell integration script.
 
 First, in :file:`kitty.conf` set:
 
diff --git a/tools/cmd/run_shell/main.go b/tools/cmd/run_shell/main.go
index 62288e242..b6643153f 100644
--- a/tools/cmd/run_shell/main.go
+++ b/tools/cmd/run_shell/main.go
@@ -44,12 +44,12 @@ func EntryPoint(root *cli.Command) *cli.Command {
 	})
 	sc.Add(cli.OptionSpec{
 		Name: "--shell-integration",
-		Help: "Specify a value for the shell_integration option, overriding the one from kitty.conf.",
+		Help: "Specify a value for the :opt:`shell_integration` option, overriding the one from :file:`kitty.conf`.",
 	})
 	sc.Add(cli.OptionSpec{
 		Name:    "--shell",
 		Default: ".",
-		Help:    "Specify the shell command to run. The default value of :code:`.` will use the parent shell if recognized, falling back to the value of the :code:`shell` option from kitty.conf.",
+		Help:    "Specify the shell command to run. The default value of :code:`.` will use the parent shell if recognized, falling back to the value of the :opt:`shell` option from :file:`kitty.conf`.",
 	})
 	return sc
 }