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 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; 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>

fabric.contrib.project.upload_project()

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.