mirror of
https://github.com/kovidgoyal/kitty.git
synced 2024-11-15 07:04:31 +03:00
Cleanup user docs for transfer kitten
This commit is contained in:
Kovid Goyal
parent
ffd997c338
commit
1c094a3b53
@ -1,10 +1,9 @@
|
||||
Transfer files
|
||||
================
|
||||
|
||||
.. _rsync: https://en.wikipedia.org/wiki/Rsync
|
||||
.. versionadded:: 0.30.0
|
||||
|
||||
.. warning::
|
||||
This kitten is currently experimental, use with care.
|
||||
.. _rsync: https://en.wikipedia.org/wiki/Rsync
|
||||
|
||||
Transfer files to and from remote computers over the ``TTY`` device itself.
|
||||
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
|
||||
|
||||
.. 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
|
||||
---------------
|
||||
|
||||
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.
|
||||
Simply ssh into a remote computer using the :doc:`ssh kitten </kittens/ssh>` and run the this kitten
|
||||
(which the ssh kitten makes available for you on the remote computer
|
||||
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
|
||||
you grant permission, the file will be copied.
|
||||
To copy a file from your local computer to the remote computer::
|
||||
|
||||
Similarly, to get a file from the remote computer to the local computer, use
|
||||
the :option:`--direction <kitty +kitten transfer --direction>` option::
|
||||
<local computer> $ kitten ssh my-remote-computer
|
||||
<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
|
||||
|
||||
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.
|
||||
For more detailed usage examples, see the command line interface section below.
|
||||
|
||||
.. 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
|
||||
------------------------------------
|
||||
@ -73,8 +55,7 @@ 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:
|
||||
is trusted, then you can disable the confirmation prompt by:
|
||||
|
||||
#. 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
|
||||
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.
|
||||
gain full access to your computer.
|
||||
|
||||
|
||||
Delta transfers
|
||||
@ -94,9 +73,9 @@ 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:`--transmit-deltas
|
||||
<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.
|
||||
<kitty +kitten transfer --transmit-deltas>` option. Note that this will
|
||||
actually be slower when transferring small files or on a very fast network, because
|
||||
of round trip overhead, so use with care.
|
||||
|
||||
|
||||
.. include:: ../generated/cli-kitten-transfer.rst
|
||||
|
||||
@ -9,48 +9,59 @@ usage = 'source_files_or_directories destination_path'
|
||||
help_text = '''\
|
||||
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.
|
||||
Supports copying files, directories (recursively), symlinks and hardlinks.
|
||||
Can even use an rsync like protocol to copy only changes between files.
|
||||
When 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
|
||||
with the ssh kitten:
|
||||
Supports copying files, directories (recursively), symlinks and hardlinks. Can
|
||||
even use an rsync like protocol to copy only changes between files. When
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
to :code:`remote-file` on the remote computer.
|
||||
$ kitten transfer --direction=upload /path/to/local-file remote-file
|
||||
|
||||
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:
|
||||
|
||||
$ 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
|
||||
:code:`/path/to/dir/` on the local computer.
|
||||
:file:`/path/to/dir/` on the local computer.
|
||||
|
||||
Directories can also be copied, recursively:
|
||||
|
||||
$ kitten transfer dir1 /path/to/dir/
|
||||
.. code::
|
||||
|
||||
This will put :code:`dir1` and all its contents into
|
||||
:code:`/path/to/dir/` on the local computer.
|
||||
$ kitten transfer dir1 /path/to/dir/
|
||||
|
||||
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
|
||||
must be an existing directory on the receiving computer. Relative file
|
||||
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.
|
||||
'''
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user