Dirtt - Directory Tree Templater

What It Does

python-dirtt is a standalone tool and library used to generate directory and file structures from XML or JSON templates that describe repeatedly used filesystem layouts such as complex project structures.

The general problem being tackled is one of inconsistent directory structures for visual effects projects, from a lack of industry standards, resulting in lost assets, security risks, and most importantly wasted resources from inefficient production. python-dirtt doesn't solve that problem as a whole. It provides a simple way to describe a tree once and stamp it out consistently, wherever and whenever you need it.

Write the layout once as a template, then create it anywhere with variables filled in:

$ dirtt create -t project.xml --var project_root=/jobs --var project_path=commercial_spot
created tree: 81 actions

Zero runtime dependencies: pure Python standard library
Python 3.10+ (tested on 3.10 through 3.14)
Templates in XML (the classic dirtt dialect, unchanged since 0.x) or JSON
--dry-run prints the full plan without touching the filesystem
Introspection: point dirtt at an existing tree and get a template back

Install

pip install python-dirtt

Command Line

dirtt create -t TEMPLATE [--var KEY=VALUE ...] [--dest DIR] [--dry-run] [-i] [-w] [-v]
dirtt list                      # show the packaged example templates
dirtt placeholders -t TEMPLATE  # show the variables a template requires
dirtt introspect PATH [-o FILE] # generate a template from a real tree

create prompts interactively for any {{placeholder}} you don't pass with --var. --dry-run prints each planned action (mkdir, write, symlink) instead of performing it. -i/--interactive confirms each directory; answering no skips that directory and everything inside it. -w/--warn fails instead of continuing when a directory already exists.

Library

from dirtt import build

# create the tree
build("project.xml", {"project_root": "/jobs", "project_path": "myproject"})

# or preview first
for action in build("project.xml", context, dry_run=True):
    print(action.describe())

The stages are also available separately. Parse into an immutable tree, plan an ordered list of actions with absolute paths, then execute:

from dirtt import load_template, plan, execute, introspect

tree = load_template("project.xml", context)   # frozen dataclass Tree
actions = plan(tree, dest="/somewhere/else")   # ordered list[Action]
execute(actions)                               # apply (or dry_run=True)

xml = introspect("/jobs/existing_project")     # tree -> template

Errors raise dirtt.DirttError subclasses (TemplateError, BuildError); the library never prints or exits.

XML Templates

The dialect is unchanged from dirtt 0.x, and validates against the dirtt DTD:

<?xml version="1.0" encoding="UTF-8"?>
<dirtt name="Project Tree" version="1.0"
       dirname="{{project_root}}" basename="{{project_path}}"
       username="pipeline" group="artist" perms="02755"
       xmlns:xi="http://www.w3.org/2001/XInclude">
  <dir basename="src" perms="02755">
    <file basename="README.md" href="readme_snippet.md" perms="0644"/>
  </dir>
  <dir basename="renders" id="renders-dir"/>
  <link basename="latest" idref="renders-dir"/>
  <xi:include href="shared_structure.xml"/>
</dirtt>

dirtt — the root directory: dirname (parent path) + basename (directory name).
dir — a directory; nests dir, file, and link elements.
file — a file; href names a content template rendered with the same {{variables}}; without href the file is created empty.
link — a symlink; ref is a literal target path, idref points at the id of a dir in the same tree. Links are created last.
xi:include — splice another template's children in place.
perms is octal text; username/group are applied with chown only when running as root.

JSON Templates

The same schema as JSON, with children tagged by "type":

{
  "name": "Project Tree",
  "dirname": "{{project_root}}",
  "basename": "{{project_path}}",
  "perms": "02755",
  "children": [
    { "type": "dir", "basename": "src", "children": [
      { "type": "file", "basename": "notes.txt", "content": "for {{project_path}}" }
    ]},
    { "type": "dir", "basename": "renders", "id": "renders-dir" },
    { "type": "link", "basename": "latest", "idref": "renders-dir" },
    { "include": "shared_structure.json" }
  ]
}

Migrating from 0.2.x

Your existing XML templates work as-is. The commands changed:

mktree.py --template ... --interactive → dirtt create -t ... -i
mktemplate.py -p PATH → dirtt introspect PATH
DirectoryTreeHandler(verbose, template, kwargs).run() → build(template, kwargs)

The old template engine's {{if}}/{{for}}/{{py:}} constructs were never used by tree templates and are no longer supported; {{name}} placeholders are.

Authors

python-dirtt was written by Rob Moggach and is maintained by a group of developers. It is licensed under an MIT-style permissive license.

You can install it with pip install python-dirtt, or find it on PyPI.

Licensed under the MIT license