How do I edit my dotfiles with chezmoi?
There are five popular approaches:
chezmoi edit $FILE. This will open the source file for
$FILEin your editor, including . For extra ease, use
chezmoi edit --apply $FILEto apply the changes when you quit your editor, and
chezmoi edit --watch $FILEto apply the changes whenever you save the file.
chezmoi cdand edit the files in the source directory directly. Run
chezmoi diffto see what changes would be made, and
chezmoi applyto make the changes.
If your editor supports opening directories, run
chezmoi editwith no arguments to open the source directory.
Edit the file in your home directory, and then either re-add it by running
chezmoi add $FILEor
Edit the file in your home directory, and then merge your changes with source state by running
chezmoi merge $FILE.
re-adddoesn't work with templates.
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?
Until you run
chezmoi apply your modified
~/.zshrc will remain in place.
When you run
chezmoi apply chezmoi will detect that
~/.zshrc has changed
since chezmoi last wrote it and prompt you what to do. You can resolve
differences with a merge tool by running
chezmoi merge ~/.zshrc.
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
How can I tell what dotfiles in my home directory are currently managed by chezmoi?
chezmoi managed will list everything managed by chezmoi.
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 added. If you
have files in your source directory that you don't want added to your
destination directory when you run
chezmoi apply add their names to a file
.chezmoiignore in the source state.
Patterns are supported, and you can change what's ignored from machine to machine. The full usage and syntax is described in the reference manual.
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
gitin the source directory and pass extra arguments to the command. 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".
You can configure chezmoi to automatically commit and push changes to your source state, as described in the how-to guide.
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.
Can I use chezmoi to manage my shell history across multiple machines?
No. Every change in a file managed by chezmoi requires an explicit command to
record it (e.g.
chezmoi add) or apply it somewhere else (e.g.
update), and is recorded as a commit in your dotfiles repository. Creating a
commit every time a command is entered would quickly become cumbersome. This
makes chezmoi unsuitable for sharing changes to rapidly-changing files like
Instead, consider using a dedicated tool for sharing shell history across
multiple machines, like
atuin. You can use chezmoi to
install and configure atuin.
How do I install pre-requisites for templates?
If you have a template that depends on some other tool, like
curl, you may need
to install it before chezmoi renders the template.
To do so, use a
run_before script that is not a template. Something like:
# Install curl if it's not already installed
if ! command -v curl >/dev/null; then
sudo apt update
sudo apt install -y curl
Chezmoi will make sure to execute it before templating other files.
How do I enable shell completions?
chezmoi includes shell completions for
zsh. If you have installed chezmoi via your
package manager then the shell completion should already be installed. Please
open an issue if this
is not working correctly.
chezmoi provides a
completion command and a
completion template function
which return the shell completions for the given shell. These can be used
either as a one-off or as part of your dotfiles repo. The details of how to use
these depend on your shell.