|2.2.3||Nov 4, 2023|
|2.2.2||Oct 31, 2023|
|2.1.3||Aug 27, 2023|
|2.1.1||Jul 31, 2023|
|0.0.2||Apr 18, 2023|
#66 in Configuration
154 downloads per month
Modify script helper addon for chezmoi
NOTE! This is version 2, which is a rewrite in Rust. See the migration guide if you are upgrading from the previous Python version. Good news: This version is ~50x faster.
Addon for chezmoi for deals with settings files that contain a mix of settings and state. So far handling INI-style files are supported.
A typical example of this is KDE settings files. These contain (apart from settings) state like recently opened files and positions of windows and dialog boxes. Other programs (such as PrusaSlicer) also do the same thing.
The program in this repository allows you to ignore certain sections of those INI files when managing the configuration files with chezmoi.
Theory of operation
For each settings file you want to manage with
will be two files in your chezmoi source directory:
modify_<config file>.tmpl, eg.
This is the modify script/configuration file that calls
chezmoi_modify_manager. It contains the directives describing what to ignore.
<config file>.src.ini, eg.
This is the source state of the INI file.
modify_ script is responsible for generating the new state of the file
given the current state in your home directory. The
modify_ script is set
up to use
chezmoi_modify_manager as an interpreter to do so.
chezmoi_modify_manager will read the modify script to read configuration and
.src.ini file and by default will apply that file exactly (ignoring blank
lines and comments).
However, by giving additional directives to
chezmoi_modify_manager in the
modify_ script you can tell it to ignore certain sections (see
chezmoi_modify_manager --help-syntax for details). For example:
ignore "KFileDialog Settings" "Show Inline Previews" ignore section "DirSelect Dialog"
will tell it to ignore the key
Show Inline Previews in the section
KFileDialog Settings and the entire section
Note! If a key appears before the first section, use
<NO_SECTION> as the
Feature: Merging & filtering INI files
This is the main mode and reason for the existance of this tool.
chezmoi_modify_manager allows you to:
- Ignore an entire section.
- Ignore a specific key in specific section.
- Ignore a key in section based on regular expressions.
- Force set a value (useful together with templating).
- Force remove a section, key or entries matching a regex (useful together with templating).
- Apply a transformation to the value of a specified key. These are special
operations that are built in and provide more complicated transformations.
A list of transforms is available via
--help-transforms. Some examples that this can do:
- Look up a password in the platform keyring
- Ignore the sorting order of a list style value (
For detailed usage instructions see
Feature: Assisted adding to the chezmoi source state
The command can also be used to add files (see
chezmoi_ini_add --help for details):
- Smart re-add mode (re-add files as managed
.src.iniif they are already managed, otherwise add with plain chezmoi).
- Conversion mode (convert from plain chezmoi to managed to
chezmoi_modify_manager also allows filtering the added files when re-adding
them after they changed:
- Any ignored keys will be removed (since we always use the system version of these, this reduces churn and the diff size in git).
- The value can be hidden (
add:hidedirective), useful in case of passwords that comes from keyrings.
- Or they can be removed entirely using the
add:removedirective (useful in combination with
setand a templated modify script).
See the section on
--help-syntax for more details.
Feature: Self updater
Finally, the command has a built-in updater (similar to
Note! This can (and should) be configured out using cargo features if you are building a distro package.
To your root
**/*.src.ini. These files should not be checked out into your target directory, but acts as the "source of truth" for the modify script.
Do one of these:
- Recommended: Install
$PATH. This can be done by one of (in descending order of preference):
- Not recommended: Install
chezmoi_modify_managerfrom the releases page into
x86-64. If you use another path, the template modify script that is added will be wrong.
- Recommended: Install
You are in control of updates. Nothing will happen unless you pass
--upgrade. Consider subscribing to be notified of new releases on the github repository. This can be done via
Customin the top right corner. Or just remember to check with
Optionally you can install tab completion. The tab completion can be generated
using the hidden command line flag
--bpaf-complete-style-bash, ...). As this is
handled internally by the command line parsing library we use, please see
for detailed instructions.
Depending on the installation method:
- With your package manager
- For each OS and architecture, update the file
.utils/chezmoi_modify_manager-<os>-<arch>. Note! For executables that you can run (i.e. the native one) you can still use
--upgradeto do this.
Details of supported actions can be seen with
Some example usages to add new files:
# Add configs to be handled by chezmoi_modify_manager (or convert configs # managed by chezmoi to be managed by chezmoi_modify_manager). chezmoi_modify_manager --add ~/.config/kdeglobals ~/.config/kwinrc # Re-add config after changes in the live system. chezmoi_modify_manager --add ~/.config/kdeglobals # Don't remember if chezmoi_modify_manager handles the file or if it is raw chezmoi? # Use smart mode (-s/--smart-add) to update the file! chezmoi_modify_manager --smart-add ~/.config/PrusaSlicer/PrusaSlicer.ini
Some examples on various ignore flags and transforms can be found in examples.md.
Platform support and requirements
The binary is self contained with no non-optional dependencies. For certain platforms where RustTLS isn't supported, the optional self-updater needs OpenSSL, which can be from either the system or built and linked statically.
Requirements to build (if there is no native binary for your platform):
- Rust 1.70 or newer
|Platform||Architecture||Continuous Integration||Tested manually|
|Linux with Glibc||All major||Yes||Yes (x86-64, i686, ARMv7)|
|Linux with Musl||All major||Yes||Yes (x86-64)|
The above table is limited to what I myself have access to (and use) as well as what works in GitHub CI. Other Unixes are likely to work, if Rust has support.
The first step should be to run
chezmoi_modify_manager --doctor and correct any issues reported.
This will help identify the two common issues:
- chezmoi_modify_manager needs to be in
**/*.src.inineeds to be ignored in the root
- When a key exists in the
.src.inifile but not in the target state it will be added to the end of the relevant section. This is not an issue as the program will usually just resort the file next time it writes out its settings.
modify_scripts bypass the check for "Did the file change in the target state" that chezmoi performs. This is essential for proper operation. However it also means that you will not be asked about overwriting changes. Always look at
chezmoi difffirst! I do have some ideas on how to mitigate this in the future. See also this chezmoi bug for a more detailed discussion on this.