Please note

This documentation is for the latest stable (0.9.3) release of Fabric. To view documentation for the in-development (1.0) version, please click here.

Previous stable versions: 0.9.0, 0.9.1, 0.9.2

Project Tools

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

fabric.contrib.project.rsync_project(*args, **kwargs)

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

Where upload_project() makes use of scp 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() takes the following parameters:

  • remote_dir: the only required parameter, this is the path to the parent directory on the remote server; the project directory will be created inside this directory. For example, if one’s project directory is named myproject and one invokes rsync_project('/home/username/'), the resulting project directory will be /home/username/myproject/.
  • local_dir: by default, rsync_project uses your current working directory as the source directory; you may override this with local_dir, which should be a directory path.
  • 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.

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][, ...]]] \
    -pthrvz [extra_opts] <local_dir> <host_string>:<remote_dir>

Upload the current project to a remote system, tar/gzipping during the move.

This function makes use of the /tmp/ directory and the tar and gzip programs/libraries; thus it will not work too well on Win32 systems unless one is using Cygwin or something similar.

upload_project will attempt to clean up the tarfiles when it finishes executing.