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

File and Directory Management

Module providing easy API for working with remote files and folders.

fabric.contrib.files.append(text, filename, use_sudo=False, partial=True)

Append string (or list of strings) text to filename.

When a list is given, each string inside is handled independently (but in the order given.)

If text is already found in filename, the append is not run, and None is returned immediately. Otherwise, the given text is appended to the end of the given filename via e.g. echo '$text' >> $filename.

The test for whether text already exists defaults to being partial only, as in ^<text>. Specifying partial=False will change the effective regex to ^<text>$.

Because text is single-quoted, single quotes will be transparently backslash-escaped.

If use_sudo is True, will use sudo instead of run.

Changed in version 0.9.1: Added the partial keyword argument.

fabric.contrib.files.comment(filename, regex, use_sudo=False, char='#', backup='.bak')

Attempt to comment out all lines in filename matching regex.

The default commenting character is # and may be overridden by the char argument.

This function uses the sed function, and will accept the same use_sudo and backup keyword arguments that sed does.

comment will prepend the comment character to the beginning of the line, so that lines end up looking like so:

this line is uncommented
#this line is commented
#   this line is indented and commented

In other words, comment characters will not “follow” indentation as they sometimes do when inserted by hand. Neither will they have a trailing space unless you specify e.g. char='# '.


In order to preserve the line being commented out, this function will wrap your regex argument in parentheses, so you don’t need to. It will ensure that any preceding/trailing ^ or $ characters are correctly moved outside the parentheses. For example, calling comment(filename, r'^foo$') will result in a sed call with the “before” regex of r'^(foo)$' (and the “after” regex, naturally, of r'#\1'.)

fabric.contrib.files.contains(text, filename, exact=False, use_sudo=False)

Return True if filename contains text.

By default, this function will consider a partial line match (i.e. where the given text only makes up part of the line it’s on). Specify exact=True to change this behavior so that only a line containing exactly text results in a True return value.

Double-quotes in either text or filename will be automatically backslash-escaped in order to behave correctly during the remote shell invocation.

If use_sudo is True, will use sudo instead of run.

fabric.contrib.files.exists(path, use_sudo=False, verbose=False)

Return True if given path exists on the current remote host.

If use_sudo is True, will use sudo instead of run.

exists will, by default, hide all output (including the run line, stdout, stderr and any warning resulting from the file not existing) in order to avoid cluttering output. You may specify verbose=True to change this behavior.

fabric.contrib.files.first(*args, **kwargs)

Given one or more file paths, returns first one found, or None if none exist. May specify use_sudo which is passed to exists.

fabric.contrib.files.sed(filename, before, after, limit='', use_sudo=False, backup='.bak')

Run a search-and-replace on filename with given regex patterns.

Equivalent to sed -i<backup> -r -e "/<limit>/ s/<before>/<after>/g <filename>".

For convenience, before and after will automatically escape forward slashes (and only forward slashes) for you, so you don’t need to specify e.g. http:\/\/foo\.com, instead just using http://foo\.com is fine.

If use_sudo is True, will use sudo instead of run.

sed will pass shell=False to run/sudo, in order to avoid problems with many nested levels of quotes and backslashes.

fabric.contrib.files.uncomment(filename, regex, use_sudo=False, char='#', backup='.bak')

Attempt to uncomment all lines in filename matching regex.

The default comment delimiter is # and may be overridden by the char argument.

This function uses the sed function, and will accept the same use_sudo and backup keyword arguments that sed does.

uncomment will remove a single whitespace character following the comment character, if it exists, but will preserve all preceding whitespace. For example, # foo would become foo (the single space is stripped) but `` # foo`` would become `` foo`` (the single space is still stripped, but the preceding 4 spaces are not.)

fabric.contrib.files.upload_template(filename, destination, context=None, use_jinja=False, template_dir=None, use_sudo=False)

Render and upload a template text file to a remote host.

filename should be the path to a text file, which may contain Python string interpolation formatting and will be rendered with the given context dictionary context (if given.)

Alternately, if use_jinja is set to True and you have the Jinja2 templating library available, Jinja will be used to render the template instead. Templates will be loaded from the invoking user’s current working directory by default, or from template_dir if given.

The resulting rendered file will be uploaded to the remote file path destination (which should include the desired remote filename.) If the destination file already exists, it will be renamed with a .bak extension.

By default, the file will be copied to destination as the logged-in user; specify use_sudo=True to use sudo instead.