Skip to main content

Synchronize a file tree with text file substitutions

Project description

File Tree Subs

Tests badge Codecov badge

Allows to synchronize a destination file tree from a source file tree while allowing certain substitutions to take place.

File Tree Subs uses doit under the hood to keep track of changes, so that files are only changed if necessary.

See the following three examples for typical use cases of filetreesubs. I'm personally using it to preprocess the output of Nikola, a static blog/site generator, to insert a sidebar into all generated HTML pages, and a tag cloud into the sidebar and the tag overview page.

To install, use pip install filetreesubs.


Assume you have the following file tree:


In the .html files, you put placeholder strings INSERT_MENU_HERE for where the content of input/ should be inserted, and INSERT_TESTIMONIALS for where the content of input/ should be inserted. Also, you want COPYRIGHT_YEAR to be replaced by 2017. The result should be a tree like this, without the .inc files:


with the placeholder string replaced. To do this with filetreesubs, create a config file filetreesubs-config.yaml:

# Source directory
source: input
# Destination directory
destination: output
  # The following is a regular expression to match the filenames:
    # The strings to replace
      # With what to replace them
      text: '2017'

Then running filetreesubs will synchronize output/ so that it contains the files from input/, except, and makes sure the substitutions take place.

Example: Sidebar in Nikola

You can find an example site for Nikola using the sidebar plugin in the Github repository felixfontein/filetreesubs-nikola-demo.

A more complex, but less explicit example can be found in my blog, which also includes a tag cloud (rendered by the static_tag_cloud pugin) into the sidebar.

Example: Substitution chains

Assume that in the above example, you want to use INSERT_TESTIMONIALS also in itself. Running the above example, this substitution will not be done, also if you extend the regular expression matching all HTML files to .* to match all files.

To apply substitutions to included files, you need to use substitution chains. Append the following to the configuration above:

- template:

This will apply the substitution for INSERT_TESTIMONIALS also to

Example: Creating index files

Assume that you have folder structure:


You want to upload the output to a web server so it is available under, but if someone accesses or, you don't want the persons to see a file listing or some error page, but show them a nice message to check out the home page. You can use filetreesubs for this. Add the following to the configuration:

create_index_filename: index.html
create_index_content: |
  <!DOCTYPE html>
      <title>There's nothing to see here.</title>
      <meta http-equiv="refresh" content="10; url=..">
      There's nothing to see here. Go <a href="..">here</a> instead.
      You will be automatically redirected there in 10 seconds.

Then in every folder not containing a file index.html, a file index.html will be created with the specified content.

Configuration file format

The configuration file is in YAML format. By default, the configuration is assumed to be in filetreesubs-config.yaml in the current directory. If you want to specify a different configuration file name, you can simply specify it on the command line:

filetreesubs my-config-file.yaml

The following commented YAML file shows all available options:

# The source directory. Specify a path here.
source: input

# The destination directory. Specify a path here.
destination: output

# The substitutions to make
  # For every substitution, you need to specify a regex pattern
  # matching the file name. Use '.*' to match everything, and
  # '.*\.html' to match all files ending with '.html'.
    # Now you can specify a number of strings which shall be replaced
      # In this case, we want to replace the string by the contents
      # of the file Note that won't be copied
      # to the destination directory anymore.
      # In this case, we want to replace the string by another string
      # we explicitly specify here.
      text: '(replacement text)'
  # Now we can specify more filename matching patterns ...
    # ... and more replacements
      text: '(some more)'

# To do substitutions in files like, we need substitution
# chains.
# Each substitution chain consists of the name of the file to
# substitute in, like
- template:
  # As well as a list of substitutions, using the same syntax as above:
    # The string to replace:
      # What to replace it with
      text: '...'
# You can have as many substitution chains as you want
- template:
      text: '(...)'

# To create index files (when not already existing), you must
# specify the name of these files:
create_index_filename: index.html

# This allows to specify the content of index files.
create_index_content: |
  <!DOCTYPE html>
  <html lang="en">
      <title>there's nothing to see here.</title>
      <meta name="robots" content="noindex">
      <meta http-equiv="refresh" content="0; url=..">
    <body style="background-color:black; color:white;">
      <div style="position:absolute; top:0; left:0; right:0; bottom:0;">
        <div style="width:100%; height:100%; display:table;">
            there's nothing to see here. go <a href=".." style="color:#AAA;">here</a> instead.

# By default, filetreesubs assumes that all text files it processes
# are UTF-8 encoded. If that's not the case, you can change another
# encoding here.
encoding: utf-8

# In case you need to do so, you can insert configurations for doit
# directly here. See `here <>`__
# for possible configurations.
  # The following option sets the filename for the dependency database.
  # If you want to execute different filetreesubs commands concurrently
  # from a folder, you need to specify different dependency database
  # names per project config.
  dep_file: '.doit-myproject.db'

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

filetreesubs-1.2.0.tar.gz (12.6 kB view hashes)

Uploaded Source

Built Distribution

filetreesubs-1.2.0-py3-none-any.whl (13.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page