2. Symbolic links and Templates - SuperCuber/dotter GitHub Wiki

By default, deployed files are symbolic links, or symlink for short. Reading or writing to a symbolic link modifies the original file.

But sometimes, we want our source file in the repository to act as a template for how the file should look like in the target location, with differences on different machines.

Templating

Dotter uses Handlebars as its templating engine. Its core feature is variable substitution: any placeholder like {{variable_name}} will be replaced with the corresponding value from your configuration.

For example, if your configuration includes:

name = "Jack"
surname = "Black"

and your template contains:

Hello, {{name}} {{surname}}!

Dotter will render it as:

Hello, Jack Black!

This is useful for the same reason constants in code are - if you repeat the same value many times in a single or several files, it's useful to have it declared once then templated into everywhere it's used. Then, if you change it in the declaration, it will automatically change everywhere its referenced.

You could use it for example to keep colors and font sizes consistent across applications.

Handlebars also supports advanced features such as conditionals and loops — check out the documentation for more details.

Templated vs Symbolic

Files which have {{ in them are automatically detected as templates.
This can be overridden using a Complex Target, as we will see later.

• Template
  The file's content in the source location will differ from the desired contents in the target location.
  Templating features are avaiable: substitution, logic, helpers, complex target actions.
  This means that they have to be copied to the target location while rendering the template.
• Symlink
  The file's content in the source location will be the same as the target location, which means they can be symbolically linked.
  Changes in the source locations are automatically reflected in the target location and vice versa.

Caching

Dotter uses a cache to detect differences between the current configuration and the state on disk.
This means it will handle well situations like:

• Removing files and packages from configuration
• Accidentally editing the target location of a templated file
• Changing a templated file to non-templated and vice versa

By default, the cache state is stored in .dotter/cache.toml and .dotter/cache/. It is recommended you add those two to your .gitignore