Project Tools

Useful non-core functionality, e.g. functions composing multiple operations.

fabric.contrib.project.rsync_project(remote_dir, local_dir=None, exclude=(), delete=False, extra_opts='', ssh_opts='', capture=False, upload=True, default_opts='-pthrvz')

Synchronize a remote directory with the current project directory via rsync.

Where upload_project() makes use of sftp to copy one’s entire project every time it is invoked, rsync_project() uses the rsync command-line utility, which only transfers files newer than those on the remote end.

rsync_project() is thus a simple wrapper around rsync; for details on how rsync works, please see its manpage. rsync must be installed on both your local and remote systems in order for this operation to work correctly.

This function makes use of Fabric’s local() operation, and returns the output of that function call; thus it will return the stdout, if any, of the resultant rsync call.

rsync_project() uses the current Fabric connection parameters (user, host, port) by default, adding them to rsync’s ssh options (then mixing in ssh_opts, if given – see below.)

rsync_project() takes the following parameters:

  • remote_dir: the only required parameter, this is the path to the directory on the remote server. Due to how rsync is implemented, the exact behavior depends on the value of local_dir:

    • If local_dir ends with a trailing slash, the files will be dropped inside of remote_dir. E.g. rsync_project("/home/username/project/", "foldername/") will drop the contents of foldername inside of /home/username/project.
    • If local_dir does not end with a trailing slash (and this includes the default scenario, when local_dir is not specified), remote_dir is effectively the “parent” directory, and a new directory named after local_dir will be created inside of it. So rsync_project("/home/username", "foldername") would create a new directory /home/username/foldername (if needed) and place the files there.

  • local_dir: by default, rsync_project uses your current working directory as the source directory. This may be overridden by specifying local_dir, which is 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.

  • 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: 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.

  • extra_opts: an optional, arbitrary string which you may use to pass custom arguments or options to rsync.

  • ssh_opts: Like extra_opts but specifically for the SSH options string (rsync’s --rsh flag.)

  • capture: Sent directly into an inner local call.

  • upload: a boolean controlling whether file synchronization is performed up or downstream. Upstream by default.

  • default_opts: the default rsync options -pthrvz, override if desired (e.g. to remove verbosity, etc).

Furthermore, this function transparently honors Fabric’s port and SSH key settings. Calling this function when the current host string contains a nonstandard port, or when env.key_filename is non-empty, will use the specified port and/or SSH key filename(s).

For reference, the approximate rsync command-line call that is constructed by this function is the following:

rsync [--delete] [--exclude exclude[0][, --exclude[1][, ...]]] \
    [default_opts] [extra_opts] <local_dir> <host_string>:<remote_dir>

New in version 1.4.0: The ssh_opts keyword argument.

New in version 1.4.1: The capture keyword argument.

New in version 1.8.0: The default_opts keyword argument.

fabric.contrib.project.upload_project(local_dir=None, remote_dir='', use_sudo=False)

Upload the current project to a remote system via tar/gzip.

local_dir specifies the local project directory to upload, and defaults to the current working directory.

remote_dir specifies the target directory to upload into (meaning that a copy of local_dir will appear as a subdirectory of remote_dir) and defaults to the remote user’s home directory.

use_sudo specifies which method should be used when executing commands remotely. sudo will be used if use_sudo is True, otherwise run will be used.

This function makes use of the tar and gzip programs/libraries, thus it will not work too well on Win32 systems unless one is using Cygwin or something similar. It will attempt to clean up the local and remote tarfiles when it finishes executing, even in the event of a failure.

Changed in version 1.7: Added the use_sudo kwarg.