mirrors/kitty
1
0
Fork 0
mirror of https://github.com/kovidgoyal/kitty synced 2026-07-23 16:58:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

Cleanup user docs for transfer kitten

Browse Source
This commit is contained in:
Kovid Goyal
2023-07-26 18:52:09 +05:30
parent ffd997c338
commit 1c094a3b53
2 changed files with 57 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/kittens/transfer.rst
View File

@@ -1,10 +1,9 @@
Transfer files Transfer files
================ ================
.. _rsync: https://en.wikipedia.org/wiki/Rsync .. versionadded:: 0.30.0
.. warning:: .. _rsync: https://en.wikipedia.org/wiki/Rsync
This kitten is currently experimental, use with care.
Transfer files to and from remote computers over the ``TTY`` device itself. Transfer files to and from remote computers over the ``TTY`` device itself.
This means that file transfer works over nested SSH sessions, serial links, This means that file transfer works over nested SSH sessions, serial links,
@@ -19,53 +18,36 @@ to transfer only changes to large files.
.. seealso:: See the :doc:`remote_file` kitten .. seealso:: See the :doc:`remote_file` kitten
.. note::
This kitten must be installed on the other machine. The easiest way to do so
is to ssh into it using the :doc:`ssh kitten </kittens/ssh>`. Or just
download the kitten binary yourself from the `kitty releases page
<https://github.com/kovidgoyal/kitty/releases>`__ and put it somewhere in
PATH. If that is not possible you can use the :doc:`remote_file` kitten
instead. Or write your own script to use the underlying :doc:`file transfer
protocol </file-transfer-protocol>`.
.. versionadded:: 0.30.0
Basic usage Basic usage
--------------- ---------------
In what follows, the *local computer* is the computer running this kitten and Simply ssh into a remote computer using the :doc:`ssh kitten </kittens/ssh>` and run the this kitten
the *remote computer* is the computer connected to the other end of the TTY (which the ssh kitten makes available for you on the remote computer
pipe. automatically). Some illustrative examples are below. To copy a file from a
remote computer::
To send a file from the local computer to the remote computer, simply run:: <local computer> $ kitten ssh my-remote-computer
<remote computer> $ kitten transfer some-file /path/on/local/computer
kitty +kitten transfer /path/to/local/file /path/to/destination/on/remote/computer This, will copy :file:`some-file` from the computer into which you have SSHed
to your local computer at :file:`/path/on/local/computer`. kitty will ask you
for confirmation before allowing the transfer, so that the file transfer
protocol cannot be abused to read/write files on your computer.
You will be prompted by kitty for confirmation on allowing the transfer, and if To copy a file from your local computer to the remote computer::
you grant permission, the file will be copied.
Similarly, to get a file from the remote computer to the local computer, use <local computer> $ kitten ssh my-remote-computer
the :option:`--direction <kitty +kitten transfer --direction>` option:: <remote computer> $ kitten transfer --direction=upload /path/on/local/computer remote-file
kitty +kitten transfer --direction=receive /path/to/remote/file /path/to/destination/on/local/computer For more detailed usage examples, see the command line interface section below.
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.
Also, when transferring multiple files/directories it is a good idea to
use the :option:`--confirm-paths <kitty +kitten transfer --confirm-paths>`
option which will give you an opportunity to review and confirm the files that
will be touched.
.. note::
If you dont want to use the ssh kitten, you can install the kitten binary on
the remote machine yourself, it is a standalone, statically compiled binary
available from the `kitty releases page
<https://github.com/kovidgoyal/kitty/releases>`__. Or you can write your own
script/program to use the underlying :doc:`file transfer protocol
</file-transfer-protocol>`.
Avoiding the confirmation prompt Avoiding the confirmation prompt
------------------------------------ ------------------------------------
@@ -73,8 +55,7 @@ Avoiding the confirmation prompt
Normally, when you start a file transfer kitty will prompt you for confirmation. 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 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 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 is trusted, then you can disable the confirmation prompt by:
secure, then you can disable the confirmation prompt by:
#. Setting the :opt:`file_transfer_confirmation_bypass` option to some password. #. Setting the :opt:`file_transfer_confirmation_bypass` option to some password.
@@ -84,9 +65,7 @@ secure, then you can disable the confirmation prompt by:
.. warning:: Using a password to bypass confirmation means any software running .. warning:: Using a password to bypass confirmation means any software running
on the remote machine could potentially learn that password and use it to 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 gain full access to your computer.
stream between your computer and the remote machine can also learn this
password. So use it only with secure connections to trusted computers.
Delta transfers Delta transfers
@@ -94,9 +73,9 @@ Delta transfers
This kitten has the ability to use the rsync_ protocol to only transfer the This kitten has the ability to use the rsync_ protocol to only transfer the
differences between files. To turn it on use the :option:`--transmit-deltas differences between files. To turn it on use the :option:`--transmit-deltas
<kitty +kitten transfer --transmit-deltas>` option. Note that this will actually <kitty +kitten transfer --transmit-deltas>` option. Note that this will
be slower when transferring small files because of round trip overhead, so use actually be slower when transferring small files or on a very fast network, because
with care. of round trip overhead, so use with care.
.. include:: ../generated/cli-kitten-transfer.rst .. include:: ../generated/cli-kitten-transfer.rst

47
kittens/transfer/main.py
View File

@@ -9,48 +9,59 @@ usage = 'source_files_or_directories destination_path'
help_text = '''\ help_text = '''\
Transfer files over the TTY device. Can be used to send files between any two Transfer files over the TTY device. Can be used to send files between any two
computers provided there is a TTY connection between them, such as over SSH. computers provided there is a TTY connection between them, such as over SSH.
Supports copying files, directories (recursively), symlinks and hardlinks. Supports copying files, directories (recursively), symlinks and hardlinks. Can
Can even use an rsync like protocol to copy only changes between files. even use an rsync like protocol to copy only changes between files. When
When copying multiple files, use the --confirm-paths option to see what exactly will copying multiple files, use the --confirm-paths option to see what exactly will
be copied. The easiest way to use this kitten is to first ssh into the remote computer be copied. The easiest way to use this kitten is to first ssh into the remote
with the ssh kitten: computer with the ssh kitten:
$ kitten ssh my-remote-computer .. code::
$ kitten ssh my-remote-computer
Then, on the remote computer run the transfer kitten to do your copying. Then, on the remote computer run the transfer kitten to do your copying.
To copy a file from the remote computer to the local computer, run: To copy a file from the remote computer to the local computer, run:
$ kitten transfer remote-file /path/to/local-file .. code::
This will copy :code:`remote-file` from the remote computer to :code:`/path/to/local-file` $ kitten transfer remote-file /path/to/local-file
This will copy :file:`remote-file` from the remote computer to :file:`/path/to/local-file`
on the local computer. on the local computer.
Similarly, to copy a file from the local computer to the remote one, run: Similarly, to copy a file from the local computer to the remote one, run:
$ kitten transfer --direction=upload /path/to/local-file remote-file .. code::
This will copy :code:`/path/to/local-file` from the local computer $ kitten transfer --direction=upload /path/to/local-file remote-file
to :code:`remote-file` on the remote computer.
This will copy :file:`/path/to/local-file` from the local computer
to :file:`remote-file` on the remote computer.
Multiple files can be copied: Multiple files can be copied:
$ kitten transfer file1 file2 /path/to/dir/ .. code::
$ kitten transfer file1 file2 /path/to/dir/
This will put :code:`file1` and :code:`file2` into the directory This will put :code:`file1` and :code:`file2` into the directory
:code:`/path/to/dir/` on the local computer. :file:`/path/to/dir/` on the local computer.
Directories can also be copied, recursively: Directories can also be copied, recursively:
$ kitten transfer dir1 /path/to/dir/ .. code::
This will put :code:`dir1` and all its contents into $ kitten transfer dir1 /path/to/dir/
:code:`/path/to/dir/` on the local computer.
This will put :file:`dir1` and all its contents into
:file:`/path/to/dir/` on the local computer.
Note that when copying multiple files or directories, the destination Note that when copying multiple files or directories, the destination
must be an existing directory on the receiving computer. Relative file must be an existing directory on the receiving computer. Relative file
paths are resolved with respect to the current directory on the computer paths are resolved with respect to the current directory on the computer
running the kitten and the home directory on the other computer. running the kitten and the home directory on the other computer. It is
a good idea to use the :option:`--confirm-paths` command line flag to verify
the kitten will copy the files you expect it to.
''' '''