A template next to the file: .clt

Updated 5 November 2026

Contents

A .clt template is a way to override a specific configuration file without creating a template directory and without remembering which directory it lives in. Such a template sits next to the file being configured and differs from it by its extension. Whether it changes the file in place depends on the state of the target: if the file differs from what is recorded in the package file list (it was edited by hand or it was recreated), the engine preserves your version and puts the result alongside it - in a file of the form .cfg0000[HTML_REMOVED] - while the target stays as it was. On an untouched file, the same template changes the target in place; the equery b <file> and qcheck <package> help you identify the package and the divergences.

/etc/conf.d/consolefont          the file being configured
/etc/conf.d/consolefont.clt      the template that configures it

The path and the target name are derived from the location of the template itself: the .clt extension is stripped, and everything else becomes the address of the configuration file. So the template header needs no path=, no name= - they follow from the file name. The utilities merge .clt templates by recursively scanning /etc and the directories from CONFIG_PROTECT.

Minimal example

You need to set the console font size. A bad option is to copy the whole file: without format= the template is treated as "raw", it overwrites the target completely and leaves no header. A good option is two lines:

/etc/conf.d/consolefont.clt

# Calculate format=openrc
consolefont="ter-v12n"

The format is specified, so only this parameter will change, the rest of the file will be preserved, and a note will appear at the top that the file is managed by a template:

#------------------------------------------------------------------------------
# Modified Calculate Utilities 3.7.6.8
# Processed template files:
# /etc/conf.d/consolefont.clt
#------------------------------------------------------------------------------

When .clt is applied

The file name up to .clt is itself the binding: it must match exactly the name of the file being configured (smb.conf.clt configures smb.conf). Then the utility takes the path, the name (path=, name=), and the package the targeted file belongs to from the location of the template - you do not need to specify it in the template header: it is filled in in advance and works in mergepkg(), merge() and pkg().

Mechanics from the code: when configuring a package, the utilities collect a list of the files owned by the packages being configured (from the CONTENTS databases, plus files already changed by regular templates). A .clt template is picked up for processing if its target is in this list - that is, if a file with that name really belongs to the package being configured. Hence the practical consequence: an arbitrarily named .clt sitting in /etc will simply be skipped.

The second way to get processed is an explicit binding in the template header: if merge( or belong( appears in it, the file is taken for processing regardless of name matching. You need it when the targeted file is not going to be configured in this run anyway:

/etc/conf.d/consolefont.clt
# Calculate format=openrc merge(sys-apps/openrc)!=
consolefont="ter-v12n"

The third case is a full reconfiguration of the system, not of a single package: then .clt without an explicit binding are processed too.

You can check the explicit binding in advance, without waiting for emerge:

grep -l 'merge(' /etc/conf.d/*.clt

It is convenient to check the application in the verbose output of package configuration:

cl-core-setup -n openrc

During system installation, .clt templates are copied into the system being installed: the installer walks the .clt directories separately and transfers them to the target, so your override reaches the installed machine and does not live only in the live environment.

Расхождение со старыми руководствами

Note the discrepancy with the old guides: they state that for .clt "set by default" are env=install, and ac_install_merge==on. In fact, these parameters are simply not needed: the path, the name and the package are derived from the location of the template and from the ownership of the targeted file, and the conditions of the template header during a .clt pass are read from the install module - the engine itself sets install for the duration of this pass (cl_template.py, line 5080). So there is also no need to "add ac_install_merge==on just in case": written out explicitly, it is an ordinary condition, and with the variable off the template will not be applied.

Specifics and limitations

  • User profile - when configuring a user profile, the .clt layer does not take part - .clt is meant for system files. For ~/.config, use regular templates in 6_ac_desktop_profile.
  • The header - a .clt has none by definition: the file is itself the source. To make the file "look as if it were configured by a template", specify format= or comment=.
  • Several .clt for one file - they are not meaningfully supported: keep one.
  • Turning off - to stop managing the file, delete the .clt and restore the configuration file to the state of the package: etc-update/dispatch-conf or emerge -1 <package>.

.clt or a template directory

Use .clt when:

  • the edit concerns one specific file on one specific machine;
  • you need to override a setting that the system template sets, and you do not want to sort out layer priorities;
  • it is a one-off administrative fix that is convenient to keep next to the file.

Use a regular template in /var/calculate/templates when:

  • there are several settings and it makes sense to group them (see template directories);
  • the templates must move to other machines together with the overlay;
  • you need conditions, overlay functions and a binding to install/update events.

See also