TTREE(1p)

📦
version 3.106 · 12 versions
, in ubuntu stonking

🌸 ttree 🌸

okay so before we even get into it: this is the manual page for Template::Tools::ttree, and bestie, it's a lot, so go grab a snack. this is part one of two, so don't go anywhere. 💖

💖 NAME 💖

Template::Tools::ttree — process entire directory trees of templates. yes, entire. trees. plural. she's ambitious like that. 🌳✨

🎀 SYNOPSIS 🎀

ttree [options] [files]

that's it. that's the whole vibe check. 💅

✨ DESCRIPTION ✨

so ttree is the script you run when you've got a whole directory tree stuffed with template files and you want all of them handled, not just one. 🧚 every template gets processed, and the output of each one gets written to a matching file in a destination directory. like, a whole mirror situation.

and here's the part that's genuinely iconic: she compares the modification times of the source files and the destination files (for the ones that already exist, obviously) and only processes the files that have actually been modified. so she skips all the stuff you didn't touch. no cap. she is literally the equivalent of make for the Template Toolkit. 👑

she also supports a whole bunch of options for configuring behaviour, defining locations, and setting Template Toolkit options. here's the order of operations, and this order matters:

  1. the script first reads the .ttreerc configuration file in the HOME directory — or a different file if you told her about one via the TTREERC environment variable
  2. then she processes any command line arguments, which includes any extra configuration files you dropped in there via the -f (file) option

🌈 The .ttreerc Configuration File 🌈

the very first time you run ttree, she's gonna ask you if you want her to make you a .ttreerc file. and she makes it in your home directory, like a little welcome gift. 🎁

$ 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

what is this file for, you ask? it's for setting any global configuration options you want applied every single time ttree runs. like, your defaults. your whole personality, but for ttree. 💅

for example, you can use the ignore and copy / link options to give her regular expressions that say which files should be ignored and which should be copied or linked instead of getting processed as templates. you might also wanna set flags like verbose and recurse depending on how you like to live.

here's 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 what's going on
verbose

ngl, in most cases you're gonna want a different ttree config file for each project you're working on. and the cfg option is how you tell her where to look for those extra config files. 🗂️

cfg = /home/abw/.ttree

then the -f command line option lets you say which config file to actually use. absolute path, relative path, she's flexible:

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

and here's a lil rule you need to know about ⚠️: if the config file doesn't start with "/" or ".", or something that looks like an MS-DOS absolute path (like "C:\\etc\\ttree.cfg"), then ttree goes looking for it in the directory specified by the cfg option.

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

important: the cfg option can only be used in the .ttreerc file. every other option can live in the .ttreerc or in any other ttree config file. and honestly they can also all be specified as command line options. she's not picky. 🫶

and remember — literally tattoo this on your brain — .ttreerc is always processed before any config file you specify with the -f option. certain options like lib can be used any number of times and they just keep accumulating values. stacking. like a friendship bracelet situation. 🧵

ok watch, consider these config 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 gets invoked like this:

$ ttree -f myconfig

the lib option ends up set to these directories:

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

so any templates sitting under /usr/local/tt2/templates get used in preference to the ones under /home/abw/web/example/templates/lib. which... might be exactly what you want. or it might not. 🙈 and for that exact reason, it's good practice to keep your .ttreerc as simple as possible and use separate config files for each ttree project. do it. periodt.

📁 Directory Options 📁

the src option defines the directory holding the source templates that need processing. you can hand it over as a command line option or put it in a config file like this:

src = /home/abw/web/example/templates/src

each template in that directory typically corresponds to one single web page or document or whatever. one template, one output. cute. ✨

the dest option specifies the destination directory for the generated output:

dest = /home/abw/web/example/html

the lib option defines one or more directories containing extra library templates. these aren't documents in their own right — they're the little modular pieces like headers, footers and menus that get incorporated into the page templates. the supporting cast. 🌟

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

and like I said, lib can be used repeatedly to add more directories to the search path. stack 'em up. 🥞

you can also pass a list of templates to ttree as command line arguments:

$ ttree foo.html bar.html

she looks for those templates in the src directory, runs them through the Template Toolkit using any extra template components from the lib directories, and then writes the generated output to the corresponding file in the dest directory. 🦋

now — if you invoke ttree without explicitly naming any templates to process, she'll just do every single file in the src directory. and if the -r (recurse) option is set, she'll additionally iterate down through sub-directories and process and other template files it finds therein.

$ ttree -r
yes, that sentence is a little cursed but it's what the page says, bestie. we don't fix the lore. 💀

if a template has already been processed before, ttree compares the modification times of the source and destination files. if the source template (or one of the things it depends on) hasn't been modified more recently than the generated output file, she just... skips it. not today. and the -a (all) option forces her to process everything regardless of modification time:

$ tree -a
okay do NOT come at me, that's literally what's written there. spell it however you want in your own terminal, I'm just the messenger. 😭

and one last thing for this section: any templates explicitly named as command line arguments are always processed, and the modification time checking is bypassed entirely for them. she heard you say their name, she's doing it. 💅

🗂 File Options 🗂

the ignore, copy, link and accept options are how you specify Perl regexen to filter file names. here's the whole algorithm:

  • files that match any of the ignore options will not be processed
  • remaining files that match any of the copy or link regexen get copied or linked to the destination directory
  • files that reside in any of the copy_dir directories are also copied
  • remaining files that then match any of the accept criteria are processed via the Template Toolkit
  • and if no accept parameter is specified, then all files will be accepted for processing if they weren't already copied or ignored
# ignore these files
ignore = \b(CVS|RCS)\b
ignore = ^#
ignore = ~$

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

# accept only .tt2 templates
accept = \.tt2$

the suffix option defines the mappings between file extensions for source templates and the generated output files. this example says that source templates with a .tt2 suffix should come out as .html files:

suffix tt2=html

or on the command line:

--suffix tt2=html

and you can provide any number of different suffix mappings just by repeating the option. go off. 🎀

the binmode option sets the encoding of the output file. for example, use --binmode=:utf8 to set the output format to unicode. 🌈

🔗 Template Dependencies 🔗

the depend and depend_file options let you specify how any given template file depends on another file or group of files. depend expresses a single dependency:

$ ttree --depend foo=bar,baz

this one says the foo file is dependant on the bar and baz templates. and you can use this option many times on the command line:

$ ttree --depend foo=bar,baz --depend crash=bang,wallop

or in a config file:

depend foo=bar,baz
depend crash=bang,wallop

the file on the left of the = is specified relative to the src or lib directories. the file(s) on the right can be specified relative to any of those directories, or as absolute file paths. for example:

$ ttree --depend foo=bar,/tmp/baz

and listen — if you want a dependency that applies to all files, put a "*" on the left of the =:

$ ttree --depend *=header,footer

or in a config file:

depend *=header,footer

also, any templates defined in the pre_process, post_process, process or wrapper options automatically get added to the list of global dependencies that apply to all templates. automatic. no extra work. iconic. 👑

the depend_file option lets you point at a file that contains dependency information:

$ ttree --depend_file=/home/abw/web/example/etc/ttree.dep

here's what a dependency file looks like:

   # This is a comment. It is ignored.

   index.html: header footer menubar

   header: titlebar hotlinks

   menubar: menuitem

   # spanning multiple lines with the backslash
   another.html: header footer menubar \
   sidebar searchform

the rules, bestie, are these:

  • lines beginning with the "#" character are comments and are ignored
  • blank lines are also ignored
  • all other lines should provide a filename, followed by a colon, and then a list of dependant files separated by whitespace, commas, or both
  • whitespace around the colon is optional too
  • lines ending in the "\" character are continued onto the following line

files that contain spaces can be quoted. that is only necessary for files after the colon (':'). the file before the colon may be quoted if it contains a colon. 🫶

and just like with the command line options, the "*" character works as a wildcard for specifying a dependency for all templates:

* : config,header

🛠 Template Toolkit Options 🛠

ttree also gives you access to the usual range of Template Toolkit options. for example, the --pre_chomp and --post_chomp ttree options correspond to the PRE_CHOMP and POST_CHOMP options. ✨

run ttree -h for a summary of the options available. (and yes, there's a lot of them — that's what part two is for. 💅)

👑 AUTHORS 👑

Andy Wardley <abw@andywardley.com>

<http://www.andywardley.com/>

with contributions from Dylan William Hardison (support for dependencies), Bryce Harrington ("absolute" and "relative" options), Mark Anderson ("suffix" and "debug" options), Harald Joerg and Leon Brocard who gets everywhere, it seems. 😭

⭐ VERSION ⭐

2.68, distributed as part of the Template Toolkit version 2.19, released on 27 April 2007. 💖

Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. 🫶

Okay so bestie, this module is free software — you can redistribute it and/or modify it under the same terms as Perl itself. That's it, that's the whole deal ✨ Go forth and remix, no cap 💅

🌸 SEE ALSO 🌸

  • tpage — the other iconic little tool in this fam, go say hi 🦋

And that's the whole page, bb!! 🎀 This one's from perl v5.42.3, dated 2026-08-20, and it's the TTREE(1p) page — you read the whole thing, slay 👑✨ Go forth and build something gorgeous with it 💜

📦 where this page comes from