Frequently Asked Questions
How can I quickly check for problems with chezmoi on my machine?
ok is fine, anything
warning is only a problem if you want to use
the related feature, and anything
error indicates a definite problem.
What are the consequences of “bare” modifications to the target files? If my
.zshrc is managed by chezmoi and I edit
~/.zshrc without using
chezmoi edit, what happens?
chezmoi will overwrite the file the next time you run
chezmoi apply. Until you
chezmoi apply your modified
~/.zshrc will remain in place.
How can I tell what dotfiles in my home directory aren’t managed by chezmoi? Is there an easy way to have chezmoi manage a subset of them?
chezmoi unmanaged will list everything not managed by chezmoi. You can add
entire directories with
chezmoi add -r.
If there’s a mechanism in place for the above, is there also a way to tell chezmoi to ignore specific files or groups of files (e.g. by directory name or by glob)?
By default, chezmoi ignores everything that you haven’t explicitly
chezmoi added. If have files in your source directory that you don’t want added to your
destination directory when you run
chezmoi apply add them to a
.chezmoiignore file (which supports globs and is also a template).
If the target already exists, but is “behind” the source, can chezmoi be configured to preserve the target version before replacing it with one derived from the source?
chezmoi add will update the source state with the target. To see
diffs of what would change, without actually changing anything, use
Once I’ve made a change to the source directory, how do I commit it?
You have several options:
chezmoi cdopens a shell in the source directory, where you can run your usual version control commands, like
chezmoi gitarguments and
chezmoi hgarguments run
hgrespectively in the source directory with arguments, for example
chezmoi git add .. If you’re passing any flags, you’ll need to use
--to prevent chezmoi from consuming them, for example
chezmoi git -- commit -m "Update dotfiles".
chezmoi sourcearguments runs your configured version control system in your source directory. It works in the same was as the
chezmoi has experimental support for automatically committing and pushing changes to your git repo whenever you run a command. See the “Explore experimental features” section in the how-to for more information.
How do I only run a script when a file has changed?
A common example of this is that you’re using Homebrew and
.Brewfile listing all the packages that you want installed and only want
brew bundle --global when the contents of
chezmoi has two types of scripts: scripts that run every time, and scripts that only run when their contents change. chezmoi does not have a mechanism to run a script when an arbitrary file has changed, but there are some ways to achieve the desired behavior:
Have the script create
.Brewfileinstead of chezmoi, e.g. in your
#!/bin/sh cat > $HOME/.Brewfile <<EOF brew "imagemagick" brew "openssl" EOF brew bundle --global
.Brewfile, and instead install the packages explicitly in
#!/bin/sh brew install imagemagick || true brew install openssl || true
|| trueis necessary because
brew installexits with failure if the package is already installed.
Use a script that runs every time (not just once) and rely on
brew bundle --globalbeing idempotent.
Use a script that runs every time, records a checksum of
.Brewfilein another file, and only runs
brew bundle --globalif the checksum has changed, and updates the recorded checksum after.
I’ve made changes to both the destination state and the source state that I want to keep. How can I keep them both?
chezmoi merge will open a merge tool to resolve differences between the source
state, target state, and destination state. Copy the changes you want to keep in
to the source state.
chezmoi’s source file naming system cannot handle all possible filenames
This is correct. Certain target filenames, for example
incompatible with chezmoi’s
used in the source state.
This is a deliberate, practical compromise. Target state metadata (private, encrypted, etc.) need to be stored for each file. Using the source state filename for this means that the contents of the file are untouched, there is no need to maintain the metadata in a separate file, is independent of the underlying filesystem and version control system, and unambiguously associates the metadata with a single file.
In practice, dotfile filenames are unlikely to conflict with chezmoi’s attributes. If this does cause a genuine problem for you, please open an issue on GitHub.
gpg encryption fails. What could be wrong?
gpg.recipient key should be ultimately trusted, otherwise encryption will
fail because gpg will prompt for input, which chezmoi does not handle. You can
check the trust level by running:
The trust level for the recipient’s key should be
6. If it is not, you can
change the trust level by running:
gpg --edit-key $recipient
trust at the prompt and chose
5 = I trust ultimately.
I’m getting errors trying to build chezmoi from source
chezmoi requires Go version 1.13 or later and Go modules enabled. You can check the version of Go with:
Enable Go modules by setting
GO111MODULE=on when running
GO111MODULE=on go get -u github.com/twpayne/chezmoi
For more details on building chezmoi, see the Contributing Guide.
What inspired chezmoi?
chezmoi was inspired by Puppet, but created because Puppet is a slow overkill for managing your personal configuration files. The focus of chezmoi will always be personal home directory management. If your needs grow beyond that, switch to a whole system configuration management tool.
Can I use chezmoi outside my home directory?
chezmoi, by default, operates on your home directory, but this can be overridden
--destination command line flag or by specifying
destDir in your config
file. In theory, you could use chezmoi to manage any aspect of your filesystem.
That said, although you can do this, you probably shouldn’t. Existing
configuration management tools like Puppet,
Chef, Ansible, and
Salt are much better suited to whole system
Where does the name “chezmoi” come from?
“chezmoi” splits to “chez moi” and pronounced /ʃeɪ mwa/ (shay-moi) meaning “at my house” in French. It’s seven letters long, which is an appropriate length for a command that is only run occasionally.
What other questions have been asked about chezmoi?
See the issues on GitHub.
Where do I ask a question that isn’t answered here?
Please open an issue on GitHub.