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 the rsync 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 of source:

    • If source ends with a trailing slash, the files will be dropped inside of target. E.g. rsync(c, "foldername/", "/home/username/project") will drop the contents of foldername 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 after source will be created inside of it. So rsync(c, "foldername", "/home/username") would create a new directory /home/username/foldername (if needed) and place the files there.
  • exclude – Optional, may be a single string or an iterable of strings, and is used to pass one or more --exclude options to rsync.
  • delete (bool) – A boolean controlling whether rsync’s --delete option is used. If True, instructs rsync 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.)