transfers
¶
File transfer functionality above and beyond basic put
/get
.
-
patchwork.transfers.
rsync
(c, source, target, exclude=(), delete=False, strict_host_keys=True, rsync_opts='', ssh_opts='')¶ Convenient wrapper around your friendly local
rsync
.Specifically, it calls your local
rsync
program via a subprocess, and fills in its arguments with Fabric’s current target host/user/port. It provides Python level keyword arguments for some common rsync options, and allows you to specify custom options via a string if required (see below.)For details on how
rsync
works, please see its manpage.rsync
must be installed on both the invoking system and the target in order for this function to work correctly.Note
This function transparently honors the given
Connection
’s connection parameters such as port number and SSH key path.Note
For reference, the approximate
rsync
command-line call that is constructed by this function is the following:rsync [--delete] [--exclude exclude[0][, --exclude[1][, ...]]] \ -pthrvz [rsync_opts] <source> <host_string>:<target>
Parameters: - c –
Connection
object upon which to operate. - source (str) – The local path to copy from. Actually a string passed verbatim to
rsync
, and thus may be a single directory ("my_directory"
) or multiple directories ("dir1 dir2"
). See thersync
documentation for details. - target (str) –
The path to sync with on the remote end. Due to how
rsync
is implemented, the exact behavior depends on the value ofsource
:- If
source
ends with a trailing slash, the files will be dropped inside oftarget
. E.g.rsync(c, "foldername/", "/home/username/project")
will drop the contents offoldername
inside of/home/username/project
. - If
source
does not end with a trailing slash,target
is effectively the “parent” directory, and a new directory named aftersource
will be created inside of it. Sorsync(c, "foldername", "/home/username")
would create a new directory/home/username/foldername
(if needed) and place the files there.
- If
- exclude – Optional, may be a single string or an iterable of strings, and is
used to pass one or more
--exclude
options torsync
. - delete (bool) – A boolean controlling whether
rsync
’s--delete
option is used. If True, instructsrsync
to remove remote files that no longer exist locally. Defaults to False. - strict_host_keys (bool) – Boolean determining whether to enable/disable the SSH-level option
StrictHostKeyChecking
(useful for frequently-changing hosts such as virtual machines or cloud instances.) Defaults to True. - rsync_opts (str) – An optional, arbitrary string which you may use to pass custom
arguments or options to
rsync
. - ssh_opts (str) – Like
rsync_opts
but specifically for the SSH options string (rsync’s--rsh
flag.)
- c –