More file transfer docs

Author: kovidgoyal

docs/kittens/transfer.rst

@@ -19,11 +19,64 @@ 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
+   This kitten (which practically means kitty) must be installed on the other
+   machine as well. 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.
 
+
+Basic usage
+---------------
+
+In what follows, the *local computer* is the computer running this kitten and
+the *remote computer* is the computer connected to the other end of the TTY pipe.
+
+To send a file from the local computer to the remote computer, simply run::
+
+    kitty +kitten transfer /path/to/local/file /path/to/destination/on/remote/computer
+
+You will be prompted by kitty for confirmation on allowing the transfer, and if
+you grant permission, the file will be copied.
+
+Similarly, to get a file from the remote computer to the local computer, use
+the :option:`kitty +kitten transfer --direction` option::
+
+    kitty +kitten transfer --direction=receive /path/to/remote/file /path/to/destination/on/local/computer
+
+Multiple files and even directories can be transferred::
+
+    kitty +kitten transfer file1 dir1 destination/
+
+Here :file:`file1` will be copied inside :file:`destination` and :file:`dir1`
+will be recursively copied into :file:`destination`. Note the trailing slash on
+:file:`destination`. This tells kitty the destination is a directory. While not
+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.
+
+
+Avoiding the confirmation prompt
+------------------------------------
+
+Normally, when you start a file transfer kitty will prompt you for
+confirmation. This is to ensure that hostile programs running on a remote
+machine cannot read/write files on your computer without your permission.
+If the remote machine is trusted and the connection between your computer
+and the remote machine is secure, then you can disable the confirmation prompt
+by:
+
+#. Setting the :opt:`file_transfer_confirmation_bypass` option to some
+   password.
+
+#. When invoking the kitten use the :option:`kitty +kitten transfer --permissions-bypass`
+   to supply the password you set in step one.
+
+.. warning:: Using a password to bypass confirmation means any software running
+   on the remote machine could potentially learn that password and use it to
+   gain full access to your computer. Also anyone that can intercept the data
+   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
 
 .. include:: ../generated/cli-kitten-transfer.rst