Start documenting the file transfer kitten

docs/kittens/remote_file.rst

@@ -22,12 +22,15 @@ transferred to the remote computer. Note that this happens without needing
 to install *any* special software on the server, beyond ``ls`` that supports
 hyperlinks.
 
+.. seealso:: See the :doc:`transfer` kitten
+
 .. versionadded:: 0.19.0
 
 .. note::
    Nested SSH sessions are not supported. The kitten will always try to copy
    remote files from the first SSH host. This is because there is no way for
-   |kitty| to detect and follow a nested SSH session robustly.
+   |kitty| to detect and follow a nested SSH session robustly. Use the
+   :doc:`transfer` kitten for such situations.
 
 .. note::
    If you have not setup automatic password-less SSH access, then, when

docs/kittens/transfer.rst

@@ -0,0 +1,26 @@
+Transfer files
+================
+
+.. warning::
+   This kitten is currently experimental, use with care.
+
+Transfer files to and from remote computers over the ``TTY`` device itself.
+This means that file transfer works over nested SSH sessions, serial links,
+etc. Anywhere you have a terminal device, you can transfer files.
+
+This kitten support transferring entire directory trees, preserving soft and
+hard links, file permissions and times, etc. It even supports the `rsync
+<https://en.wikipedia.org/wiki/Rsync>`_ protocol to transfer only changes to
+large files and to automatically resume interrupted transfers.
+
+.. seealso:: See the :doc:`remote_file` kitten
+
+.. note::
+   This kitten (which practically means kitty) must be installed on the remote
+   machine. If that is not possible you can use the :doc:`remote_file` kitten
+   instead. Or write your own script to use the underlying file transfer
+   protocol.
+
+.. versionadded:: 0.24.0
+
+.. include:: ../generated/cli-kitten-transfer.rst

docs/kittens_intro.rst

@@ -14,6 +14,7 @@ Extend with kittens
    kittens/hints
    kittens/remote_file
    kittens/hyperlinked_grep
+   kittens/transfer
    kittens/custom
    kittens/*
 
@@ -45,6 +46,11 @@ Some prominent kittens:
     the filename.
 
 
+:doc:`Transfer files <kittens/transfer>`
+    Transfer files and directories seamlessly and easily from remote machines over your existing
+    SSH sessions with a simple command.
+
+
 :doc:`Hyperlinked grep <kittens/hyperlinked_grep>`
     Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`_
     and open the results directly in your favorite editor in the terminal,