More docs on file transfer

Author: kovidgoyal

docs/kittens/transfer.rst

@@ -1,6 +1,8 @@
 Transfer files
 ================
 
+.. _rsync: https://en.wikipedia.org/wiki/Rsync
+
 .. warning::
    This kitten is currently experimental, use with care.
 
@@ -12,9 +14,8 @@ etc. Anywhere you have a terminal device, you can transfer files.
    :alt: The transfer kitten at work
 
 This kitten supports transferring entire directory trees, preserving soft and
-hard links, file permissions, 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.
+hard links, file permissions, times, etc. It even supports the rsync_
+protocol to transfer only changes to large files.
 
 .. seealso:: See the :doc:`remote_file` kitten
 
@@ -24,6 +25,8 @@ large files and to automatically resume interrupted transfers.
    kitten instead. Or write your own script to use the underlying file transfer
    protocol.
 
+.. versionadded:: 0.24.0
+
 
 Basic usage
 ---------------
@@ -54,6 +57,10 @@ strictly necessary (kitty will infer the need for a destination directory from
 the fact that you are copying multiple things) it is good practice to always
 use a trailing slash when the destination is supposed to be a directory.
 
+Also, when transferring multiple files/directories it is a good idea to
+use the :option:`kitty +kitten transfer --confirm-paths` option which will give
+you an opportunity to review and confirm the files that will be touched.
+
 
 Avoiding the confirmation prompt
 ------------------------------------
@@ -77,6 +84,14 @@ by:
    stream between your computer and the remote machine can also learn this
    password. So use it only with secure connections to trusted computers.
 
-.. versionadded:: 0.24.0
+
+Delta transfers
+-----------------------------------
+
+This kitten has the ability to use the rsync_ protocol to only transfer the
+differences between files. To turn it on use the :option:`kitty +kitten
+transfer --transmit-deltas` option. Note that this will actually be slower when
+transferring small files because of round trip overhead, so use with care.
+
 
 .. include:: ../generated/cli-kitten-transfer.rst