Managing files and directories

Files and Templates

The File component has been developed with Puppet’s file type in mind. It accepts a very similar parameter set and has almost identical features.

You can use it to manage files, directories, and symlinks, and you can specify content (literally or as Jinja templates). You can also manage the Unix attributes and control whether leading directories should be managed or not.

The most basic usage is simply:

self += File('myfile')

This example creates a file at work/mycomponent/myfile, taking the contents from a file of the same name in the component’s directory (i.e. components/mycomponent/myfile). By default, the source file is run through Jinja, with the file’s parent component made available as component.

class batou.lib.file.File(path)

Creates a file. The main parameter for File is the target path. A File instance has an attribute path containing the full, absolute path to the resulting file.

File accepts the following additional parameters:


Filename of the source file to be used as the File’s content (absolute path or relative to the component’s directory). [Default: same as target path]


Literal file contents as a string.


Process file contents as Jinja template. [Default: True]


Object to make available as component to the Jinja template. [Default: File’s parent component]


Dict of additional arguments to make available to the Jinja template.


Encoding for the file contents [Default: utf-8]


Unix owner username.


Unix group name.


Unix permission mode. Can be given as an integer value (0o755) or as an octal integer string (‘755’) or as a unix mode string similar to the output of ls -l (‘rwx–x–x’).


Create leading directories that were given in the target path. [Default: False]


Type of object to be created: ‘file’, ‘directory’, or ‘symlink’. This is useful for complex situations (e.g. creating a symlink with special ownership), for simple situations it’s probably more readable to use Directory or Symlink.

Source of symlink (for ensure = ‘symlink’)


Mark a file as sensitive so its content is not exposed by the (diff-)output of batou. This is useful in situations where the rendered file contains a password or other sensitive data. [Default: False]

class batou.lib.file.BinaryFile(path)

Subclass of batou.lib.file.File. Creates a non-template binary file.


class batou.lib.file.Directory(path)

Creates a directory. The main parameter is the target path.


Path to a source directory whose contents are to be synchronized to the target path (uses rsync internally).


List of file names or patterns that should not be synchronized to the target path (passed to rsync as --exclude argument, see the rsync documentation for details).

Creates a symlink at target by linking to source.

Removing files

Removal of obsolete things is a difficult topic in the convergence paradigm. If in the past we created a file foo, but now it is not used anymore, the code that originally said, “please manage foo”, will not be there anymore. This means that nobody knows that the file foo that is still lying around on the production system is not actually in use anymore. In most cases, a few stray files do not matter, but in case they do, the deployment code has to explicitly state that something should not be present anymore.

class batou.lib.file.Purge(pattern)

Ensures that a set of files (given as a glob pattern) does not exist.

Extracting archive files

batou can extract archive files in Tar, Zip, and DMG (on OSX target machines) format:

class batou.lib.archive.Extract(archive)

The main parameter is the archive filename (relative to the component’s directory). The archive format is determined according to the file name extension (‘.tar’, ‘.tar.gz’, ‘.tgz’, ‘.tar.bz2’, ‘.tar.xz’ use tar, ‘.zip’ uses unzip and ‘.dmg’ uses hdiutil). The following additional parameters are supported:


Target directory to extract the archive into. Directory is created if it does not exist (compare create_target_dir). [Default: base name of the archive file]


Extract into the directory given in target. Set to False to extract directly into the work directory. [Default: True]


Only for tar archives: number of directories contained in the archive to strip off (see the tar documentation for details) [Default: 0]

VFS mapping (TODO)

XXX writeme