Template::Tools::ttree 2.19

Template::Tools::ttree module can process entire directory trees of templates.

SYNOPSIS
ttree [options] [files]

The ttree script is used to process entire directory trees containing template files. The resulting output from processing each file is then written to a corresponding file in a destination directory. The script compares the modification times of source and destination files (where they already exist) and processes only those files that have been modified. In other words, it is the equivalent of make for the Template Toolkit.

It supports a number of options which can be used to configure behaviour, define locations and set Template Toolkit options. The script first reads the .ttreerc configuration file in the HOME directory, or an alternative file specified in the TTREERC environment variable. Then, it processes any command line arguments, including any additional configuration files specified via the -f (file) option.

The .ttreerc Configuration File

When you run ttree for the first time it will ask you if you want it to create a .ttreerc file for you. This will be created in your home directory.

$ ttree

Do you want me to create a sample .ttreerc file for you?

(file: /home/abw/.ttreerc) [y/n]: y
/home/abw/.ttreerc created. Please edit accordingly and re-run ttree

The purpose of this file is to set any global configuration options that you want applied every time ttree is run. For example, you can use the ignore and copy option to provide regular expressions that specify which files should be ignored and which should be copied rather than being processed as templates. You may also want to set flags like verbose and recurse according to your preference.

A minimal .ttreerc:

# ignore these files
ignore = b(CVS|RCS)b
ignore = ^#
ignore = ~$

# copy these files
copy = .(gif|png|jpg|pdf)$

# recurse into directories
recurse

# provide info about whats going on
verbose

In most cases, youll want to create a different ttree configuration file for each project youre working on. The cfg option allows you to specify a directory where ttree can find further configuration files.

cfg = /home/abw/.ttree

The -f command line option can be used to specify which configuration file should be used. You can specify a filename using an absolute or relative path:

$ ttree -f /home/abw/web/example/etc/ttree.cfg
$ ttree -f ./etc/ttree.cfg
$ ttree -f ../etc/ttree.cfg

If the configuration file does not begin with / or . or something that looks like a MS-DOS absolute path (e.g. C:etcttree.cfg) then ttree will look for it in the directory specified by the cfg option.

$ ttree -f test1 # /home/abw/.ttree/test1

The cfg option can only be used in the .ttreerc file. All the other options can be used in the .ttreerc or any other ttree configuration file. They can all also be specified as command line options.

Remember that .ttreerc is always processed before any configuration file specified with the -f option. Certain options like lib can be used any number of times and accumulate their values.

For example, consider the following configuration files:
/home/abw/.ttreerc:

cfg = /home/abw/.ttree
lib = /usr/local/tt2/templates

/home/abw/.ttree/myconfig:

lib = /home/abw/web/example/templates/lib

When ttree is invoked as follows:

$ ttree -f myconfig

the lib option will be set to the following directories:

/usr/local/tt2/templates
/home/abw/web/example/templates/lib

Any templates located under /usr/local/tt2/templates will be used in preference to those located under /home/abw/web/example/templates/lib. This may be what you want, but then again, it might not. For this reason, it is good practice to keep the .ttreerc as simple as possible and use different configuration files for each ttree project.