warnf prints a message to stderr prefixed by chezmoi: warning: and returns
+the empty string. format is interpreted as a printf-style format
+string with the given args.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/reference/templates/github-functions/gitHubKeys/index.html b/reference/templates/github-functions/gitHubKeys/index.html
index 903c6200fd3..1b6602ed3c7 100644
--- a/reference/templates/github-functions/gitHubKeys/index.html
+++ b/reference/templates/github-functions/gitHubKeys/index.html
@@ -4416,6 +4416,8 @@
+
+
@@ -5199,6 +5201,27 @@
+
+
+
+
+
+
+
Manage your dotfiles across multiple diverse machines, securely.
The latest version of chezmoi is 2.58.0 (release notes, release history).
"},{"location":"#what-does-chezmoi-do","title":"What does chezmoi do?","text":"
chezmoi helps you manage your personal configuration files (dotfiles, like ~/.gitconfig) across multiple machines.
chezmoi provides many features beyond symlinking or using a bare git repo including:
templates (to handle small differences between machines)
password manager support (to store your secrets securely)
importing files from archives (great for shell and editor plugins)
full file encryption (using gpg or age)
running scripts (to handle everything else)
With chezmoi, pronounced /\u0283e\u026a mwa/ (shay-mwa), you can install chezmoi and your dotfiles from your GitHub dotfiles repo on a new, empty machine with a single command:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --apply $GITHUB_USERNAME\n
As well as the curl | sh installation, you can install chezmoi with your favorite package manager.
Updating your dotfiles on any machine is a single command:
chezmoi update\n
chezmoi runs on all popular operating systems, is distributed as a single statically-linked binary with no dependencies, and does not require root access.
"},{"location":"#how-do-i-start-with-chezmoi","title":"How do I start with chezmoi?","text":"
Install chezmoi then read the quick start guide. The user guide covers most common tasks. For a full description, consult the reference.
"},{"location":"#should-i-use-chezmoi","title":"Should I use chezmoi?","text":"
See what other people think about chezmoi by reading articles, listening to podcasts, and watching videos about chezmoi. Read how chezmoi compares to other dotfile managers. Explore other people's dotfile repos that use chezmoi.
"},{"location":"#how-do-i-get-help-using-chezmoi","title":"How do I get help using chezmoi?","text":"
chezmoi has extensive documentation. First, use the search bar at the top of this page using a few, short, and specific keywords related to your problem.
chezmoi is an open source project with tens of thousands of users, so it is very likely that someone else has already encountered and solved your problem. Search chezmoi's GitHub repo for issues and discussions with keywords related to your problem.
If your question is still unanswered, please open a GitHub issue for support.
"},{"location":"#i-like-chezmoi-how-do-i-say-thanks","title":"I like chezmoi. How do I say thanks?","text":"
Please give chezmoi a star on GitHub.
Share chezmoi and, if you're happy to share your public dotfiles repo, then tag your repo with chezmoi.
Contributions are very welcome and every bug report, support request, and feature request helps make chezmoi better. Thank you :)
chezmoi does not accept financial contributions. Instead, please make a donation to a charity or cause of your choice.
"},{"location":"comparison-table/","title":"Comparison table","text":"chezmoi dotbot rcm vcsh yadm bare git Distribution Single binary Python package Multiple files Single script or package Single script - Install method Many git submodule Many Many Many Manual Non-root install on bare system \u2705 \u2049\ufe0f \u2705 \u2705 \u2705 \u2705 Windows support \u2705 \u2705 \u274c \u274c \u2705 \u2705 Bootstrap requirements None Python, git Perl sh, git git git Source repos Single Single Multiple Multiple Single Single dotfiles are... Files Symlinks Files Files Files Files Config file Optional Required Optional None Optional Optional Private files \u2705 \u274c \u274c \u274c \u2705 \u274c Show differences without applying \u2705 \u274c \u274c \u2705 \u2705 \u2705 Whole file encryption \u2705 \u274c \u274c \u274c \u2705 \u274c Password manager integration \u2705 \u274c \u274c \u274c \u274c \u274c Machine-to-machine file differences Templates Alternative files Alternative files Branches Alternative files, templates \u2049\ufe0f Custom variables in templates \u2705 \u274c \u274c \u274c \u274c \u274c Executable files \u2705 \u2705 \u2705 \u2705 \u2705 \u2705 File creation with initial contents \u2705 \u274c \u274c \u2705 \u274c \u274c Externals \u2705 \u274c \u274c \u274c \u274c \u274c Manage partial files \u2705 \u274c \u274c \u2049\ufe0f \u2705 \u2049\ufe0f File removal \u2705 \u274c \u274c \u2705 \u2705 \u274c Directory creation \u2705 \u2705 \u2705 \u2705 \u2705 \u2705 Run scripts \u2705 \u2705 \u2705 \u2705 \u2705 \u274c Run once scripts \u2705 \u274c \u274c \u2705 \u2705 \u274c Machine-to-machine symlink differences \u2705 \u274c \u274c \u2049\ufe0f \u2705 \u2049\ufe0f Shell completion \u2705 \u274c \u274c \u2705 \u2705 \u2705 Archive import \u2705 \u274c \u274c \u2705 \u274c \u2705 Archive export \u2705 \u274c \u274c \u2705 \u274c \u2705 Implementation language Go Python Perl POSIX Shell Bash C
\u2705 Supported, \u2049\ufe0f Possible with significant manual effort, \u274c Not supported
For more comparisons, visit dotfiles.github.io/utilities.
If you already have a dotfiles repo using chezmoi on GitHub at https://github.com/$GITHUB_USERNAME/dotfiles then you can install chezmoi and your dotfiles with the single command:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --apply $GITHUB_USERNAME\n
Private GitHub repos require other authentication methods:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --apply git@github.com:$GITHUB_USERNAME/dotfiles.git\n
Hint
If you want to install chezmoi in ./.local/bin instead of ./bin you can use get.chezmoi.io/lb or chezmoi.io/getlb instead.
Hint
To install the chezmoi binary in a different directory, use the -b option, for example:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- -b $HOME/.local/bin\n
"},{"location":"install/#download-a-pre-built-linux-package","title":"Download a pre-built Linux package","text":"
Download a package for your distribution and architecture.
Verify the that the SHA256 sum of your downloads matches the SHA256 sum in the verified checksum file. All the downloaded files must be in the current directory.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"migrating-from-another-dotfile-manager/","title":"Migrating from another dotfile manager","text":""},{"location":"migrating-from-another-dotfile-manager/#migrate-from-a-dotfile-manager-that-uses-symlinks","title":"Migrate from a dotfile manager that uses symlinks","text":"
Many dotfile managers replace dotfiles with symbolic links to files in a common directory. If you chezmoi add such a symlink, chezmoi will add the symlink, not the file. To assist with migrating from symlink-based systems, use the --follow option to chezmoi add, for example:
chezmoi add --follow ~/.bashrc\n
This will tell chezmoi add that the target state of ~/.bashrc is the target of the ~/.bashrc symlink, rather than the symlink itself. When you run chezmoi apply, chezmoi will replace the ~/.bashrc symlink with the file contents.
Roughly speaking, chezmoi stores the desired state of your dotfiles in the directory ~/.local/share/chezmoi. When you run chezmoi apply, chezmoi calculates the desired contents for each of your dotfiles and then makes the minimum changes required to make your dotfiles match your desired state. chezmoi's concepts are described more accurately in the reference manual.
"},{"location":"quick-start/#start-using-chezmoi-on-your-current-machine","title":"Start using chezmoi on your current machine","text":"
Assuming that you have already installed chezmoi, initialize chezmoi with:
chezmoi init\n
This will create a new git local repository in ~/.local/share/chezmoi where chezmoi will store its source state. By default, chezmoi only modifies files in the working copy.
Manage your first file with chezmoi:
chezmoi add ~/.bashrc\n
This will copy ~/.bashrc to ~/.local/share/chezmoi/dot_bashrc.
Edit the source state:
chezmoi edit ~/.bashrc\n
This will open ~/.local/share/chezmoi/dot_bashrc in your $EDITOR. Make some changes and save the file.
Hint
You don't have to use chezmoi edit to edit your dotfiles. See this FAQ entry for more details.
See what changes chezmoi would make:
chezmoi diff\n
Apply the changes:
chezmoi -v apply\n
All chezmoi commands accept the -v (verbose) flag to print out exactly what changes they will make to the file system, and the -n (dry run) flag to not make any actual changes. The combination -n-v is very useful if you want to see exactly what changes would be made.
Next, open a shell in the source directory, to commit your changes:
chezmoi can be configured to automatically add, commit, and push changes to your repo.
chezmoi can also be used with GitLab, or BitBucket, Source Hut, or any other git hosting service.
Finally, exit the shell in the source directory to return to where you were:
exit\n
These commands are summarized in this sequence diagram:
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo H->>L: chezmoi init H->>W: chezmoi add <file> W->>W: chezmoi edit <file> W-->>H: chezmoi diff W->>H: chezmoi apply H-->>W: chezmoi cd W->>L: git add W->>L: git commit L->>R: git push W-->>H: exit"},{"location":"quick-start/#using-chezmoi-across-multiple-machines","title":"Using chezmoi across multiple machines","text":"
On a second machine, initialize chezmoi with your dotfiles repo:
This will check out the repo and any submodules and optionally create a chezmoi config file for you.
Check what changes that chezmoi will make to your home directory by running:
chezmoi diff\n
If you are happy with the changes that chezmoi will make then run:
chezmoi apply -v\n
If you are not happy with the changes to a file then either edit it with:
chezmoi edit $FILE\n
Or, invoke a merge tool (by default vimdiff) to merge changes between the current contents of the file, the file in your working copy, and the computed contents of the file:
chezmoi merge $FILE\n
On any machine, you can pull and apply the latest changes from your repo with:
chezmoi update -v\n
These commands are summarized in this sequence diagram:
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi init <repo> W-->>H: chezmoi diff W->>H: chezmoi apply W->>W: chezmoi edit <file> W->>W: chezmoi merge <file> R->>H: chezmoi update"},{"location":"quick-start/#set-up-a-new-machine-with-a-single-command","title":"Set up a new machine with a single command","text":"
You can install your dotfiles on new machine with a single command:
This command is summarized in this sequence diagram:
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>H: chezmoi init --apply <repo>"},{"location":"quick-start/#next-steps","title":"Next steps","text":"
For a full list of commands run:
chezmoi help\n
chezmoi has much more functionality. Good starting points are reading what other people say about chezmoi, adding more dotfiles, and using templates to manage files that vary from machine to machine and retrieve secrets from your password manager. Read the user guide to explore and see how people use chezmoi for inspiration.
"},{"location":"what-does-chezmoi-do/","title":"What does chezmoi do?","text":"
chezmoi helps you manage your personal configuration files (dotfiles, like ~/.gitconfig) across multiple machines.
chezmoi is helpful if you have spent time customizing the tools you use (e.g. shells, editors, and version control systems) and want to keep machines running different accounts (e.g. home and work) and/or different operating systems (e.g. Linux, macOS, and Windows) in sync, while still being able to easily cope with differences from machine to machine.
chezmoi scales from the trivial (e.g. copying a few dotfiles onto a Raspberry Pi, development container, or virtual machine) to complex long-lived multi-machine development environments (e.g. keeping any number of home and work, Linux, macOS, and Windows machines in sync). In all cases you only need to maintain a single source of truth (a single branch in git) and getting started only requires adding a single binary to your machine (which you can do with curl, wget, or scp).
chezmoi has strong support for security, allowing you to manage secrets (e.g. passwords, access tokens, and private keys) securely and seamlessly using a password manager and/or encrypt whole files with your favorite encryption tool.
If you do not personalize your configuration or only ever use a single operating system with a single account and none of your dotfiles contain secrets then you don't need chezmoi. Otherwise, read on...
"},{"location":"what-does-chezmoi-do/#what-are-chezmois-key-features","title":"What are chezmoi's key features?","text":""},{"location":"what-does-chezmoi-do/#flexible","title":"Flexible","text":"
You can share as much configuration across machines as you want, while still being able to control machine-specific details.Your dotfiles can be templates (using text/template syntax). Predefined variables allow you to change behavior depending on operating system, architecture, and hostname. chezmoi runs on all commonly-used platforms, like Linux, macOS, and Windows. It also runs on less commonly-used platforms, like FreeBSD, OpenBSD, and Termux.
"},{"location":"what-does-chezmoi-do/#personal-and-secure","title":"Personal and secure","text":"
Nothing leaves your machine, unless you want it to. Your configuration remains in a git repo under your control. You can write the configuration file in the format of your choice. chezmoi can retrieve secrets from 1Password, AWS Secrets Manager, Azure Key Vault, Bitwarden, Dashlane, Doppler, gopass, HCP Vault Secrets, KeePassXC, Keeper, LastPass, pass, passage, passhole, Vault, Keychain, Keyring, or any command-line utility of your choice. You can encrypt individual files with GnuPG or age. You can checkout your dotfiles repo on as many machines as you want without revealing any secrets to anyone.
chezmoi includes verbose and dry run modes so you can review exactly what changes it will make to your home directory before making them. chezmoi's source format uses only regular files and directories that map one-to-one with the files, directories, and symlinks in your home directory that you choose to manage. If you decide not to use chezmoi in the future, it is easy to move your data elsewhere.
"},{"location":"what-does-chezmoi-do/#declarative-and-robust","title":"Declarative and robust","text":"
You declare the desired state of files, directories, and symbolic links in your source of truth and chezmoi updates your home directory to match that state. What you want is what you get. chezmoi updates all files and symbolic links atomically. You will never be left with incomplete files that could lock you out, even if the update process is interrupted.
"},{"location":"what-does-chezmoi-do/#fast-and-easy-to-use","title":"Fast and easy to use","text":"
Using chezmoi feels like using git: the commands are similar and chezmoi runs in fractions of a second. chezmoi makes most day-to-day operations one line commands, including installation, initialization, and keeping your machines up-to-date. chezmoi can pull and apply changes from your dotfiles repo in a single command, and automatically commit and push changes.
"},{"location":"why-use-chezmoi/","title":"Why use chezmoi?","text":""},{"location":"why-use-chezmoi/#why-should-i-use-a-dotfile-manager","title":"Why should I use a dotfile manager?","text":"
Dotfile managers give you the combined benefit of a consistent environment everywhere with an undo command and a restore from backup.
As the core of our development environments become increasingly standardized (e.g. using git at both home and work), and we further customize them, at the same time we increasingly work in ephemeral environments like Docker containers, virtual machines, and GitHub Codespaces.
In the same way that nobody would use an editor without an undo command, or develop software without a version control system, chezmoi brings the investment that you have made in mastering your tools to every environment that you work in.
"},{"location":"why-use-chezmoi/#i-already-have-a-system-to-manage-my-dotfiles-why-should-i-use-chezmoi","title":"I already have a system to manage my dotfiles, why should I use chezmoi?","text":"
Quote
I\u2019ve been using Chezmoi for more than a year now, across at least 3 computers simultaneously, and I really love it. Most of all, I love how fast I can configure a new machine when I use it. In just a couple minutes of work, I can kick off a process on a brand-new computer that will set up my dotfiles and install all my usual software so it feels like a computer I\u2019ve been using for years. I also appreciate features like secrets management, which allow me to share my dotfiles while keeping my secrets safe. Overall, I love the way Chezmoi fits so perfectly into the niche of managing dotfiles.
\u2014 @mike_kasberg
Quote
I had initially been turned off when I first encountered [chezmoi], because [chezmoi] seemed overkill for (what appeared to me) a simple task.
But the problem of managing a relatively small number of dotfiles across a relatively small number of machines with small differences between them and keeping them up to date proved to be MUCH more complex than I imagined. Copy things around by hand, and then later distributing them via source control got hairy very quickly.
I finally realized all those features were absolutely necessary to manage things sanely, and once I took some time to learn how to do things with chezmoi, I have never looked back.
\u2014 njt
Quote
Regular reminder that chezmoi is the best dotfile manager utility I've used and you can too
\u2014 @mbbroberg
If you're using any of the following methods:
A custom shell script.
An existing dotfile manager like dotbot, rcm, homesick, vcsh, yadm, or GNU Stow.
A bare git repo.
Then you've probably run into at least one of the following problems.
"},{"location":"why-use-chezmoi/#if-coping-with-differences-between-machines-requires-extra-effort","title":"...if coping with differences between machines requires extra effort","text":"
If you want to synchronize your dotfiles across multiple operating systems or distributions, then you may need to manually perform extra steps to cope with differences from machine to machine. You might need to run different commands on different machines, maintain separate per-machine files or branches (with the associated hassle of merging, rebasing, or copying each change), or hope that your custom logic handles the differences correctly.
chezmoi uses a single source of truth (a single branch) and a single command that works on every machine. Individual files can be templates to handle machine to machine differences, if needed.
"},{"location":"why-use-chezmoi/#if-you-have-to-keep-your-dotfiles-repo-private","title":"...if you have to keep your dotfiles repo private","text":"
Quote
And regarding dotfiles, I saw that. It's only public dotfiles repos so I have to evaluate my dotfiles history to be sure. I have secrets scanning and more, but it was easier to keep it private for security, I'm ok mostly though. I'm using chezmoi and it's easier now
\u2014 @sheldon_hull
If your system stores secrets in plain text, then you must be very careful about where you clone your dotfiles. If you clone them on your work machine then anyone with access to your work machine (e.g. your IT department) will have access to your home secrets. If you clone it on your home machine then you risk leaking work secrets.
With chezmoi you can store secrets in your password manager or encrypt them, and even store passwords in different ways on different machines. You can clone your dotfiles repository anywhere, and even make your dotfiles repo public, without leaving personal secrets on your work machine or work secrets on your personal machine.
"},{"location":"why-use-chezmoi/#if-you-have-to-maintain-your-own-tool","title":"...if you have to maintain your own tool","text":"
Quote
I've offloaded my dotfiles deployment from a homespun shell script to chezmoi. I'm quite happy with this decision.
\u2014 @gotgenes
Quote
I discovered chezmoi and it's pretty cool, just migrated my old custom multi-machine sync dotfile setup and it's so much simpler now
in case you're wondering I have written 0 code
\u2014 @buritica
Quote
Chezmoi is like what you might get if you re-wrote my bash script in Go, came up with better solutions than diff for managing config on multiple machines, added in secrets management and other useful dotfile tools, and tweaked and perfected it over years.
@mike_kasberg
If your system was written by you for your personal use, then it probably has the functionality that you needed when you wrote it. If you need more functionality then you have to implement it yourself.
chezmoi includes a huge range of battle-tested functionality out-of-the-box, including dry-run and diff modes, script execution, conflict resolution, Windows support, and much, much more. chezmoi is used by thousands of people and has a rich suite of both unit and integration tests. When you hit the limits of your existing dotfile management system, chezmoi already has a tried-and-tested solution ready for you to use.
"},{"location":"why-use-chezmoi/#if-setting-up-your-dotfiles-requires-more-than-one-short-command","title":"...if setting up your dotfiles requires more than one short command","text":"
If your system is written in a scripting language like Python, Perl, or Ruby, then you also need to install a compatible version of that language's runtime before you can use your system.
chezmoi is distributed as a single stand-alone statically-linked binary with no dependencies that you can simply copy onto your machine and run. You don't even need git installed. chezmoi provides one-line installs, pre-built binaries, packages for Linux and BSD distributions, Homebrew formulae, Scoop and Chocolatey support on Windows, and a initial config file generation mechanism to make installing your dotfiles on a new machine as painless as possible.
If you use an LLM (Large Language Model, like ChatGPT, Claude, Gemini, GitHub Copilot, or Llama) to make a contribution then you must say so in your contribution and you must carefully review your contribution for correctness before sharing it. If you share un-reviewed LLM-generated content then you will be immediately banned. See CODE_OF_CONDUCT.md for more information.
chezmoi is written in Go and development happens on GitHub. chezmoi is a standard Go project, using standard Go tooling. chezmoi requires Go 1.23 or later.
chezmoi's tests include integration tests with other software. If the other software is not found in $PATH the tests will be skipped. Running the full set of tests requires age, base64, bash, bzip2, git, gpg, gzip, perl, python3, rage, ruby, sed, sha256sum, tr, true, unzip, xz, zip, and zstd.
Run chezmoi:
go run .\n
Run a set of smoke tests, including cross-compilation, tests, and linting:
make smoke-test\n
Test building chezmoi for all architectures:
make test-release\n
Hint
If you use fish as your primary shell, you may get warnings from Fish during tests:
error: can not save history\nwarning-path: Unable to locate data directory derived from $HOME: '/home/user/.local/share/fish'.\nwarning-path: The error was 'Operation not supported'.\nwarning-path: Please set $HOME to a directory where you have write access.\n
These can be avoided with by running tests with SHELL=bash or SHELL=zsh:
SHELL=bash make test\nSHELL=zsh make smoke-test\nSHELL=bash go test ./...\n
Directory Contents assets/chezmoi.io/docs/ The documentation single source of truth. Help text, examples, and the chezmoi.io website are generated from the files in this directory internal/chezmoi/ chezmoi's core functionality internal/cmd/ Code for the chezmoi command internal/cmd/testdata/scripts/ High-level tests of chezmoi's commands using testscript"},{"location":"developer-guide/architecture/#key-concepts","title":"Key concepts","text":"
As described in the reference manual, chezmoi evaluates the source state to compute a target state for the destination directory (typically your home directory). It then compares the target state to the actual state of the destination directory and performs any changes necessary to update the destination directory to match the target state. These concepts are represented directly in chezmoi's code.
chezmoi uses the generic term entry to describe something that it manages. Entries can be files, directories, symlinks, scripts, amongst other things.
All of chezmoi's interaction with the operating system is abstracted through the System interface. A System includes functionality to read and write files and directories and execute commands. chezmoi makes a distinction between idempotent commands that can be run multiple times without modifying the underlying system and arbitrary commands that may modify the underlying system.
The real underlying system is implemented via a RealSystem struct. Other Systems are composed on top of this to provide further functionality. For example, the --debug flag is implemented by wrapping the RealSystem with a DebugSystem that logs all calls to the underlying RealSystem. --dry-run is implemented by wrapping the RealSystem with a DryRunSystem that allows reads to pass through but silently discards all writes.
The SourceState struct represents a source state, including reading a source state from the source directory, executing templates, applying the source state (i.e. updating a System to match the desired source state), and adding more entries to the source state.
Entries in the source state are abstracted by the SourceStateEntry interface implemented by the SourceStateFile and SourceStateDir structs, as the source state only consists of regular files and directories.
A SourceStateFile includes a FileAttr struct describing the attributes parsed from its file name. Similarly, a SourceStateDir includes a DirAttr struct describing the directory attributes parsed from a directory name.
SourceStateEntrys can compute their target state entries, i.e. what the equivalent entry should be in the target state, abstracted by the TargetStateEntry interface.
Actual target state entries include TargetStateFile structs, representing a file with contents and permissions, TargetStateDir structs, representing a directory, TargetStateSymlink for symlinks, TargetStateRemove for entries that should be removed, and TargetStateScript for scripts that should be run.
The actual state of an entry in the target state is abstracted via the ActualStateEntry interface, with ActualStateAbsent, ActualStateDir, ActualStateFile, ActualStateSymlink structs implementing this interface.
Finally, an EntryState struct represents a serialization of an ActualEntryState for storage in and retrieval from chezmoi's persistent state. It stores a SHA256 of the entry's contents, rather than the full contents, to avoid storing secrets in the persistent state.
With these concepts, chezmoi's apply command is effectively:
Read the source state from the source directory.
For each entry in the source state (SourceStateEntry), compute its TargetStateEntry and read its actual state in the destination state (ActualStateEntry).
If the ActualStateEntry is not equivalent to the TargetStateEntry then apply the minimal set of changes to the ActualStateEntry so that they are equivalent.
Furthermore, chezmoi stores the EntryState of each entry that it writes in its persistent state. chezmoi can then detect if a third party has updated a target since chezmoi last wrote it by comparing the actual state entry in the target state with the entry state in the persistent state.
internal/cmd/*cmd.go files contain the code for each individual command. internal/cmd/*templatefuncs.go files contain the template functions.
Commands are defined as methods on the Config struct. The Config struct is large, containing all configuration values read from the config file, command line arguments, and computed and cached values.
The Config.persistentPreRunRootE and Config.persistentPostRunRootE methods set up and tear down state for individual commands based on the command's Annotations field, which defines how the command interacts with the file system and persistent state.
chezmoi uses separate types for absolute paths (AbsPath) and relative paths (RelPath) to avoid errors where paths are combined (e.g. joining two absolute paths is an error). The type SourceRelPath is a relative path within the source directory and handles file and directory attributes.
Internally, chezmoi normalizes all paths to use forward slashes with an optional upper-cased Windows volume so they can be compared with string comparisons. Paths read from the user may include tilde (~) to represent the user's home directory, use forward or backward slashes, and are treated as external paths (ExtPath). These are normalized to absolute paths. chezmoi is case-sensitive internally and makes no attempt to handle case-insensitive or case-preserving filesystems.
Persistent state is treated as a two-level key-value store with the pseudo-structure map[Bucket]map[Key]Value, where Bucket, Key, and Value are all []bytes. The PersistentState interface defines interaction with them. Sometimes temporary persistent states are used. For example, in dry run mode (--dry-run) the actual persistent state is copied into a temporary persistent state in memory which remembers writes but does not persist them to disk.
Encryption tools are abstracted by the Encryption interface that contains methods of encrypting and decrypting files and []bytes. Implementations are the AGEEncryption and GPGEncryption structs. A DebugEncryption struct wraps an Encryption interface and logs the methods called.
"},{"location":"developer-guide/architecture/#run_once_-and-run_onchange_-scripts","title":"run_once_ and run_onchange_ scripts","text":"
The execution of a run_once_ script is recorded by storing the SHA256 of its contents in the scriptState bucket in the persistent state. On future invocations the script is only run if no matching contents SHA256 is found in the persistent state.
The execution of a run_onchange_ script is recorded by storing its target name in the entryState bucket along with its contents SHA256 sum. On future invocations the script is only run if its contents SHA256 sum has changed, and its contents SHA256 sum is then updated in the persistent state.
chezmoi has a mix of, unit, integration, and end-to-end tests. Unit and integration tests use the github.com/alecthomas/assert/v2 framework. End-to-end tests use github.com/rogpeppe/go-internal/testscript with the test scripts themselves in internal/cmd/testdata/scripts/$TEST_NAME.txtar.
You can run individual end-to-end tests with
go test ./internal/cmd -run=TestScript/$TEST_NAME\n
Tests should, if at all possible, run unmodified on all operating systems tested in CI (Linux, macOS, Windows, and FreeBSD). Windows will sometimes need special handling due to its path separator and lack of POSIX-style file permissions.
"},{"location":"developer-guide/building-on-top-of-chezmoi/","title":"Building on top of chezmoi","text":"
chezmoi is designed with UNIX-style composability in mind, and the command line tool is semantically versioned. Building on top of chezmoi should primarily be done by executing the chezmoi binary with arguments and the standard input and output configured appropriately. The chezmoi dump and chezmoi state commands allows the inspection of chezmoi's internal state.
Bug reports, bug fixes, and documentation improvements are always welcome. Please open an issue or create a pull request with your report, fix, or improvement.
If you want to make a more significant change, please first open an issue to discuss the change that you want to make. Dave Cheney gives a good rationale as to why this is important.
All changes are made via pull requests. In your pull request, please make sure that:
All existing tests pass. You can ensure this by running make test.
There are appropriate additional tests that demonstrate that your PR works as intended.
The documentation is updated, if necessary. For new features you should add an entry in assets/chezmoi.io/docs/user-guide/ and a complete description in assets/chezmoi.io/docs/reference/. See website for instructions on how to build and view a local version of the documentation.
All generated files are up to date. You can ensure this by running make generate and including any modified files in your commit.
The code is correctly formatted, according to gofumpt. You can ensure this by running make format.
The code passes golangci-lint. You can ensure this by running make lint.
The commit messages follow the conventional commits specification. chezmoi's release notes are generated directly from the commit messages. For trivial or user-invisible changes, please use the prefix chore:.
Commits are logically separate, with no merge or \"fixup\" commits.
chezmoi generates the install script from a single source of truth. You must run
go generate\n
if your change includes any of the following:
Modifications to the install script template.
Additions or modifications to the list of supported OSs and architectures.
chezmoi's continuous integration verifies that all generated files are up to date. Changes to generated files should be included in the commit that modifies the source of truth.
If you're packaging chezmoi for an operating system or distribution:
chezmoi has no build dependencies other than the standard Go toolchain.
chezmoi has no runtime dependencies, but is usually used with git, so many packagers choose to make git an install dependency or recommended package.
Please set the version number, git commit, and build time in the binary. This greatly assists debugging when end users report problems or ask for help. You can do this by passing the following flags to go build:
$VERSION should be the chezmoi version, e.g. 1.7.3. Any v prefix is optional and will be stripped, so you can pass the git tag in directly.
Hint
The command git describe --abbrev=0 --tags will return a suitable value for $VERSION.
$COMMIT should be the full git commit hash at which chezmoi is built, e.g. 4d678ce6850c9d81c7ab2fe0d8f20c1547688b91.
Hint
The assets/scripts/generate-commit.go script will return a suitable value for $COMMIT. You can run it with go run assets/scripts/generate-commit.go.
Hint
The source archive contains a file called COMMIT containing the commit hash.
$DATE should be the date of the build as a UNIX timestamp or in RFC3339 format.
Hint
The command git show -s --format=%ct HEAD returns the UNIX timestamp of the last commit, e.g. 1636668628.
The command date -u +%Y-%m-%dT%H:%M:%SZ returns the current time in RFC3339 format, e.g. 2019-11-23T18:29:25Z.
$BUILT_BY should be a string indicating what system was used to build the binary. Typically it should be the name of your packaging system, e.g. homebrew.
Please enable cgo, if possible. chezmoi can be built and run without cgo, but the .chezmoi.username and .chezmoi.group template variables may not be set correctly on some systems.
chezmoi includes an upgrade command which attempts to self-upgrade. You can remove this command completely by building chezmoi with the noupgrade build tag.
chezmoi includes shell completions in the completions directory. Please include these in the package and install them in the shell-appropriate directory, if possible.
If the instructions for installing chezmoi in chezmoi's install guide are absent or incorrect, please open an issue or submit a PR to correct them.
brew automation will automatically detect new releases of chezmoi within a few hours and open a pull request in github.com/Homebrew/homebrew-core to bump the version.
If needed, the pull request can be created with:
brew bump-formula-pr --tag=v1.2.3 chezmoi\n
Note
chezmoi is in Scoop's Main bucket. Scoop's automation will automatically detect new releases within a few hours.
chezmoi uses GoReleaser's support for signing to sign the checksums of its release assets with cosign.
Details:
The cosign private key was generated with cosign v1.12.1 on a private recently-installed Ubuntu 22.04.1 system with a single user and all available updates applied.
The private key uses a long (more than 32 character) password generated locally by a password manager.
The password-protected private key is stored in chezmoi's public GitHub repo.
The private key's password is stored as a GitHub Actions secret and only available to the release step of release job of the main workflow.
The cosign public key is included in the release assets and also uploaded to https://chezmoi.io/cosign.pub. Since https://chezmoi.io is served by GitHub pages, it probably has equivalent security to chezmoi's GitHub Releases page, which is also managed by GitHub.
Virus scanning software, especially on Windows machines, occasionally report viruses or trojans in the chezmoi binary. This is almost certainly a false positive.
For more information see Why does my virus-scanning software think my Go distribution or compiled binary is infected? in the Go FAQ.
"},{"location":"developer-guide/security/#reporting-a-vulnerability","title":"Reporting a vulnerability","text":"
Please report vulnerabilities by opening a GitHub issue or sending an email to twpayne+chezmoi-security@gmail.com.
Unit testing, using testing, and github.com/alecthomas/assert/v2, tests that functions and small components behave as expected for a wide range of inputs, especially edge cases. These are generally found in internal/chezmoi/*_test.go.
Filesystem integration tests, using testing and github.com/twpayne/go-vfs/v5, test chezmoi's effects on the filesystem. This include some tests in internal/chezmoi/*_test.go, and higher level command tests in internal/cmd/*cmd_test.go.
High-level integration tests using github.com/rogpeppe/go-internal/testscript are in internal/cmd/testdata/scripts/*.txtar and are run by internal/cmd/main_test.go.
Linux distribution and OS tests run the full test suite using Docker for different Linux distributions (in assets/docker) and Vagrant for different OSes (in assets/vagrant). Windows tests are run in GitHub Actions.
"},{"location":"developer-guide/using-make/","title":"Building and installing with make","text":"
chezmoi can be built with GNU make, assuming you have the Go toolchain installed.
Running make will build a chezmoi binary in the current directory for the host OS and architecture. To embed version information in the binary and control installation the following variables are available:
Variable Example Purpose $VERSIONv2.0.0 Set version $COMMIT3895680a... Set the git commit at which the code was built $DATE2019-11-23T18:29:25Z The time of the build $BUILT_BYhomebrew The packaging system performing the build $PREFIX/usr Installation prefix $DESTDIRinstall-root Fake installation root
Running make install will install the chezmoi binary in ${DESTDIR}${PREFIX}/bin.
The website is generated with Material for MkDocs from the contents of the assets/chezmoi.io/docs/ directory. It is hosted by GitHub pages from the gh-pages branch.
To build the website locally, Go 1.23 (or later) and uv 0.4.15 (or later) must be installed. Python 3.10 (or later) is required, but may be installed with uv:
If Python 3.10 (or later) is not currently installed, install it with uv:
uv python install 3.10\n
Install the dependencies (the --frozen is optional but recommended):
The website is automatically deployed when new releases are created, but manual deployments can be triggered by maintainers with appropriate access using:
Recommended article: Fedora Magazine: Take back your dotfiles with Chezmoi
Date Version Language Title 2024-12-19 2.56.0 JP chezmoi\u3067dotfiles\u3092\u7ba1\u7406\u3059\u308b 2024-12-18 2.56.0 EN Exploring Tools For Managing Your Dotfiles 2024-12-02 2.55.0 JP chezmoi\u3092\u4f7f\u3063\u305f\u30ed\u30fc\u30ab\u30eb\u74b0\u5883\u7206\u901f\u69cb\u7bc9 2024-11-19 2.54.0 AR \u0634\u064a\u0645\u0648\u0627 (chezmoi) \u0628\u0628\u0633\u0627\u0637\u0629 2024-11-16 2.54.0 EN Swapping to Chezmoi 2024-11-07 2.53.1 EN dotfiles management: chezmoi 2024-01-07 2.52.3 EN How I manage Neovim configuration with Chezmoi 2024-09-15 2.52.2 EN Cross-Platform Dotfiles with Chezmoi, Nix, Brew, and Devpod 2024-09-09 2.52.2 EN Keeping your Dotfiles in Sync and your Secrets in Gopass 2024-09-08 2.52.1 EN Managing dotfiles with chezmoi 2024-08-30 2.52.1 JP dotfiles\u7ba1\u7406\u3092chezmoi\u306b\u79fb\u884c\u3059\u308b 2024-07-31 2.51.0 EN Managing dotfiles with chezmoi 2024-07-28 2.51.0 EN Development Environment Setup with Chezmoi 2024-06-26 2.49.1 EN Automate Your Dotfiles with Chezmoi 2024-05-27 2.48.1 EN Managing Dotfiles with Chezmoi 2024-05-01 2.48.0 TH \u0e08\u0e31\u0e14\u0e01\u0e32\u0e23 dotfiles \u0e14\u0e49\u0e27\u0e22 chezmoi 2024-04-27 2.48.0 CN \u4f7f\u7528 chezmoi & vscode, \u7ba1\u7406\u4f60\u7684 dotfiles 2024-04-24 2.47.4 EN Chezmoi: Manage Your Dotfiles Across Multiple Linux Systems 2024-03-25 2.47.2 EN Whatever happened to dotfiles? 2024-03-23 2.47.2 EN A tour around chezmoi 2024-03-23 2.47.2 CN \u4f7f\u7528 chezmoi & vscode, \u7ba1\u7406\u4f60\u7684 dotfiles 2024-03-11 2.47.1 CN Chezmoi\uff1a\u512a\u96c5\u7ba1\u7406Linux\u7684dotfile\uff0c\u4f7f\u7528Git\u5132\u5b58\u5eab\u5099\u4efd\uff0c\u985e\u4f3cGNU Stow 2024-03-02 2.47.0 EN The Ultimate Dotfiles Management Tool 2024-02-25 2.47.0 EN Atuin and chezmoi are the dog's bollocks 2024-01-07 2.43.0 EN Chezmore Chezmoi 2023-12-23 2.42.3 DE Lokale Kofigurationsdateien sicher mit chezmoi und Git synchronisieren 2023-12-18 2.42.3 JP chezmoi \u7ba1\u7406\u306edotfiles \u3067\u30de\u30b7\u30f3\u6bce\u306b\u8a2d\u5b9a\u3092\u5909\u3048\u305f\u3044 2023-12-17 2.42.3 JP chezmoi \u3092 \u30b5\u30d6\u30de\u30b7\u30f3\u306b\u3082\u5c0e\u5165\u3059\u308b 2023-12-16 2.42.3 JP chezmoi \u3092\u4f7f\u3063\u305f dotfiles \u306e\u7ba1\u7406\u65b9\u6cd5 2023-12-10 2.42.2 JP chezmoi \u3067 dotfiles \u3092\u7ba1\u7406\u3059\u308b\u3068\u304d\u306b\u4fbf\u5229\u306a\u6a5f\u80fd\u306b\u3064\u3044\u3066\u307e\u3068\u3081\u308b 2023-10-29 2.40.4 CN \u7528 chezmoi \u7ba1\u7406 dotfiles 2023-09-13 2.39.1 JP \u8907\u6570OS\u306b\u5bfe\u5fdc\u3057\u3066\u3044\u308bchezmoi\u3092\u4f7f\u3063\u3066dotfiles\u3092\u52b9\u7387\u7684\u306b\u7ba1\u7406\u3059\u308b 2023-09-07 2.39.1 JP \u3010chezmoi\u3011dotfile\u306e\u30bb\u30ad\u30e5\u30a2\u306a\u5024\u3092dashlane\u304b\u3089\u53c2\u7167\u3067\u304d\u308b\u3088\u3046\u306b\u3059\u308b 2023-08-05 2.36.1 EN Dotfiles with chezmoi 2023-06-14 2.34.1 RU chezmoi 2023-05-16 2.33.6 JP chezmoi 2023-04-29 2.33.1 JP chezmoi \u306e\u30c6\u30f3\u30d7\u30ec\u30fc\u30c8\u6a5f\u80fd\u3092\u4f7f\u3063\u3066\u30b7\u30a7\u30eb\u306e\u8d77\u52d5\u3092\u9ad8\u901f\u5316\u3059\u308b 2023-04-26 2.33.1 EN Managing my /home directory 2023-04-15 2.33.1 JP dotfiles \u306e\u7ba1\u7406\u306b chezmoi \u3092\u5c0e\u5165\u3057\u3066 fswatch \u3067\u81ea\u52d5 apply \u3067\u304d\u308b\u3088\u3046\u306b\u3057\u305fg 2023-04-08 2.33.1 KR chezmoi, \ubcf8\uaca9\uc801\uc73c\ub85c \ud65c\uc6a9\ud558\uae30 2023-03-25 2.33.0 KR chezmoi, \uc138\uc0c1 \ud3b8\ub9ac\ud558\uac8c dotfile \uad00\ub9ac\ud558\uae30 2023-03-17 2.32.0 EN Automating the Setup of a New Mac With All Your Apps, Preferences, and Development Tools 2023-03-21 2.32.0 JP AWS CLI \u306e\u30d7\u30ed\u30d5\u30a1\u30a4\u30eb\u3092 chezmoi \u3068Bitwarden \u3067\u7ba1\u7406\u3059\u308b 2023-02-26 2.31.0 EN Managing dotfiles with chezmoi 2023-01-22 2.29.3 EN Managing dotfiles 2023-01-22 2.29.3 JP dotfile manager \u306e chezmoi \u306b\u79fb\u884c\u3057\u3066\u307f\u308b 2023-01-13 2.29.1 EN Making the most out of distrobox and toolbx 2023-01-12 2.29.1 JP Chezmoi\u3067\u304b\u3093\u305f\u3093\u30af\u30ed\u30b9\u30d7\u30e9\u30c3\u30c8\u30d5\u30a9\u30fc\u30e0dotfiles\u7ba1\u7406\u306e\u30b9\u30b9\u30e1 2023-01-05 2.29.1 JP \u65e2\u5b58\u306e dotfiles \u3092 chezmoi \u3067\u7ba1\u7406\u3059\u308b 2022-09-28 2.24.0 EN Shit Hot Dotfiles 2022-09-13 2.22.1 IT Come installare Chezmoi: gestisci in modo sicuro i dotfile su pi\u00f9 macchine 2022-08-11 2.20.0 EN Chezmoi - a very cool tool to manage your dotfiles 2022-08-05 2.20.0 CN \u4f7f\u7528chezmoi\u7ba1\u7406dotfiles 2022-06-11 2.17.1 JP chezmoi \u3067 Linux \u3068 macOS \u4e21\u65b9\u3067\u4f7f\u3048\u308b dotfiles \u3092\u4f5c\u308b 2022-06-02 2.17.1 EN Local Env as Code: Is it possible yet 2022-05-16 2.16.0 EN Chezmoi for DotFiles 2022-04-25 2.15.1 EN Easily moving Linux installs 2022-03-13 2.14.0 EN Tools I love: Chezmoi 2022-03-03 2.13.0 EN Local Environment-as-Code: Is It Possible Yet? 2022-02-22 2.12.1 JP chezmoi \u3092\u4f7f\u3063\u3066 VSCode devcontainer \u5bfe\u5fdc dotfiles \u3092\u4f5c\u308b 2022-02-17 2.12.0 ES Qu\u00e9 son y c\u00f3mo gestionar archivos dotfiles con chezmoi 2022-02-12 2.11.2 EN How To Manage Dotfiles With Chezmoi 2022-02-02 2.11.0 FR Controler ses dotfiles en environnement \u00e9ph\u00e9m\u00e8re 2022-02-01 2.10.1 JP chezmoi \u3067 dotfiles \u3092\u624b\u8efd\u306b\u67d4\u8edf\u306b\u30bb\u30ad\u30e5\u30a2\u306b\u7ba1\u7406\u3059\u308b 2022-01-26 2.10.1 JP chezmoi \u3067 dotfiles \u3092\u7ba1\u7406\u3059\u308b 2022-01-12 2.9.5 IT Come funzionano i miei Mac 2021-12-23 2.9.3 EN Use Chezmoi to guarantee idempotency of terminal 2021-12-20 2.9.3 EN How chezmoi Implements Cross-Platform CI 2021-12-13 2.9.3 EN Managing Dotfiles With Chezmoi 2021-12-04 2.9.2 EN Advanced features of Chezmoi 2021-12-01 2.9.1 EN Chezmoi 2 2021-11-26 2.8.0 EN Weekly Journal 47 - chezmoi, neovim 2021-10-26 2.7.3 RU \u0421\u0438\u043d\u0445\u0440\u043e\u043d\u0438\u0437\u0430\u0446\u0438\u044f \u0441\u0438\u0441\u0442\u0435\u043c\u043d\u044b\u0445 \u043d\u0430\u0441\u0442\u0440\u043e\u0435\u043a 2021-10-25 2.7.3 EN Share credentials across machines using chezmoi and bitwarden 2021-09-18 2.1.2 EN PBS 125 of X \u2014 Chezmoi on Multiple Computers 2021-09-14 2.2.0 EN Managing preference plists under Chezmoi 2021-09-06 2.2.0 EN chezmoi dotfile management 2021-09-04 2.2.0 EN Configuration Management 2021-09-04 2.1.2 EN PBS 124 of X \u2014 Chezmoi Templates 2021-08-22 2.1.2 EN PBS 123 of X \u2014 Backing up and Syncing Dot Files with Chezmoi 2021-08-08 2.1.2 EN PBS 122 of X \u2014 Managing Dot Files with Chezmoi 2021-08-04 2.1.2 PT Como instalar o Chezmoi, um gerenciador de dotfiles, no Ubuntu, Linux Mint, Fedora, Debian 2021-07-23 2.1.2 EN PBS 121 of X \u2014 Managing Dot Files and an Introduction to Chezmoi 2021-07-15 2.1.2 CN \u4f7f\u7528Chezmoi\u7ba1\u7406\u914d\u7f6e\u6587\u4ef6 2021-05-14 2.0.12 EN A brief history of my dotfile management 2021-05-12 2.0.12 EN My Dotfiles Story: A Journey to Chezmoi 2021-05-10 2.0.11 EN Development Environment (2021) 2021-04-08 2.0.9 FR Bienvenue chez moi 2021-04-01 2.0.7 EN ChezMoi 2021-02-17 1.8.11 JP chezmoi \u3067 dotfiles \u3092\u624b\u8efd\u306b\u67d4\u8edf\u306b\u30bb\u30ad\u30e5\u30a2\u306b\u7ba1\u7406\u3059\u308b 2021-02-07 1.8.10 JP chezmoi\u59cb\u3081\u305f 2021-01-29 1.8.10 CN \u7528 Chezmoi \u7ba1\u7406\u914d\u7f6e\u6587\u4ef6 2021-01-12 1.8.10 EN Automating the Setup of a New Mac With All Your Apps, Preferences, and Development Tools 2020-11-06 1.8.8 EN Chezmoi \u2013 Securely Manage dotfiles across multiple machines 2020-11-05 1.8.8 EN Using chezmoi to manage dotfiles 2020-10-05 1.8.6 EN Dotfiles with Chezmoi 2020-10-03 1.8.6 EN Chezmoi Merging 2020-08-13 1.8.3 EN Using BitWarden and Chezmoi to manage SSH keys 2020-08-09 1.8.3 EN Automating and testing dotfiles 2020-08-03 1.8.3 EN Automating a Linux in Windows Dev Setup 2020-07-03 1.8.3 EN Feeling at home in a LXD container 2020-06-15 1.8.2 EN Dotfiles management using chezmoi - How I Use Linux Desktop at Work Part5 2020-04-27 1.8.0 EN Managing my dotfiles with chezmoi 2020-04-20 1.8.0 FR Gestion des dotfiles et des secrets avec chezmoi 2020-04-19 1.7.19 FR Git & dotfiles : versionner ses fichiers de configuration 2020-04-16 1.7.19 FR Chezmoi, visite guid\u00e9e 2020-04-17 1.7.17 CN \u7528 Chezmoi \u53d6\u56de\u4f60\u7684\u70b9\u6587\u4ef6 2020-04-03 1.7.17 EN Fedora Magazine: Take back your dotfiles with Chezmoi 2020-04-01 1.7.17 EN Managing dotfiles and secret with chezmoi 2019-01-10 0.0.11 EN Linux Fu: The kitchen sync"},{"location":"links/dotfile-repos/","title":"Dotfile repos","text":"
Recommended podcast: Managing Dot Files and an Introduction to Chezmoi
Date Version Language Title 2024-10-17 2.52.4 EN Releasing more BSDs 2023-05-22 2.33.6 ES 491 - Tres herramientas que han revolucionado mi terminal Linux 2023-01-30 2.29.3 ES 459 - Soy un zoquete, otra vez hice un rm -rf 2022-05-27 2.17.0 EN F\u00e9d\u00e9rer une communaut\u00e9 technique autour d'un projet Open Source 2022-03-11 2.14.0 EN The Real Python Podcast: Episode 101: Tools for Setting Up Python on a New Machine 2021-09-18 2.1.2 EN CCATP #699 \u2013 Bart Busschots on PBS 125 of X \u2013 Chezmoi on Multiple Computers 2021-09-04 2.1.2 EN CCATP #698 \u2013 Bart Busschots on PBS 124 of X \u2013 Chezmoi Templates 2021-08-22 2.1.2 EN CCATP #696 \u2013 Bart Busschots on PBS 123 of X \u2014 Backing up and Syncing Dot Files with Chezmoi 2021-08-08 2.1.2 EN CCATP #695 \u2013 Bart Busschots on PBS 122 \u2013 Managing Dot Files with Chezmoi 2021-07-23 2.1.2 EN CCATP #693 \u2013 Bart Busschots on PBS 121 of X \u2014 Managing Dot Files and an Introduction to Chezmoi 2019-11-20 1.7.2 EN FLOSS weekly episode 556: chezmoi"},{"location":"links/related-software/","title":"Related software","text":""},{"location":"links/related-software/#editor-integration","title":"Editor integration","text":""},{"location":"links/related-software/#githubcomandre-kotakenvim-chezmoi","title":"github.com/andre-kotake/nvim-chezmoi","text":"
An add-on to deal with config files that contain a mix of settings and transient state, such as with GUI program settings files also containing recently used files and window positions.
Recommended video: chezmoi: manage your dotfiles across multiple, diverse machines, securely
Date Version Language Title 2024-11-18 2.54.0 AR Chezmoi, Dotfiles, Workflow, Templates and Encryption Arabic \u0634\u0631\u062d 2024-06-22 2.47.1 EN Automating Development Environments with Ansible & Chezmoi 2024-02-17 2.47.0 EN 12 GREAT command line programs YOU recommended! 2024-01-14 2.24.0 EN managing dotfiles: a guided tour through my own setup 2023-12-03 2.42.2 EN The ultimate dotfiles setup 2022-12-15 2.27.3 ES Archivos de configuraci\u00f3n f\u00e1cil con chezmoi 2022-09-13 2.22.1 EN Using chezmoi to automate dotfiles / config files (+ my bashrc) 2022-04-27 2.15.1 EN Easily moving Linux installs 2021-12-08 2.9.3 EN How Go makes chezmoi possible 2021-11-27 2.8.0 TH Command \u0e44\u0e23 2021-11-27 : \u0e22\u0e49\u0e32\u0e22 dotfiles \u0e44\u0e1b chezmoi 2021-09-06 2.2.0 EN chezmoi: Organize your dotfiles across multiple computers 2021-02-06 1.8.10 EN chezmoi: manage your dotfiles across multiple, diverse machines, securely 2020-07-06 1.8.3 EN Conf42: chezmoi: Manage your dotfiles across multiple machines, securely 2020-03-12 1.7.16 EN Managing Dotfiles with ChezMoi 2019-11-20 1.7.2 EN FLOSS weekly episode 556: chezmoi"},{"location":"reference/","title":"Reference","text":"
Welcome to the reference section of the chezmoi documentation.
chezmoi is deterministic in its order of application. The order is:
Read the source state.
Read the destination state.
Compute the target state.
Run run_before_ scripts in alphabetical order.
Update entries in the target state (files, directories, externals, scripts, symlinks, etc.) in alphabetical order of their target name. Directories (including those created by externals) are updated before the files they contain.
Run run_after_ scripts in alphabetical order.
Target names are considered after all attributes are stripped.
Example
Given create_alpha and modify_dot_beta in the source state, .beta will be updated before alpha because .beta sorts before alpha.
chezmoi assumes that the source or destination states are not modified while chezmoi is being executed. This assumption permits significant performance improvements, including allowing chezmoi to only read files from the source and destination states if they are needed to compute the target state.
chezmoi's behavior when the above assumptions are violated is undefined. For example, using a run_before_ script to update files in the source or destination states violates the assumption that the source and destination states do not change while chezmoi is running.
Note
External sources are updated during the update phase; it is inadvisable for a run_before_ script to depend on an external applied during the update phase. run_after_ scripts may freely depend on externals.
chezmoi computes the target state for the current machine and then updates the destination directory, where:
The destination directory is the directory that chezmoi manages, usually your home directory, ~.
A target is a file, directory, or symlink in the destination directory.
The destination state is the current state of all the targets in the destination directory.
The source state declares the desired state of your home directory, including templates that use machine-specific data. It contains only regular files and directories.
The source directory is where chezmoi stores the source state. By default it is ~/.local/share/chezmoi.
The config file contains machine-specific data. By default it is ~/.config/chezmoi/chezmoi.toml.
The target state is the desired state of the destination directory. It is computed from the source state, the config file, and the destination state. The target state includes regular files and directories, and may also include symbolic links, scripts to be run, and targets to be removed.
The working tree is the git working tree. Normally it is the same as the source directory, but can be a parent of the source directory.
If you run chezmoi command where command is not a builtin chezmoi command then chezmoi will look for a binary called chezmoi-command in your $PATH. If such a binary is found then chezmoi will execute it. Otherwise, chezmoi will report an unknown command error.
chore: Bump golangci-lint to v1.51.2 by @twpayne in #2782
docs: Improve documentation on git-repo externals by @twpayne in #2785
chore: Update dependencies by @twpayne in #2788
chore: Enable most govet linters by @twpayne in #2794
chore: Update dependencies by @twpayne in #2795
feat: Add Dashlane password manager support by @twpayne in #2792
fix: Detect absolute paths in externals on Windows by @twpayne in #2796
feat: Add Dashlane secure notes support by @XaF in #2797
chore(deps): bump cpina/github-action-push-to-another-repository from 9e487f29582587eeb4837c0552c886bb0644b6b9 to 0a14457bb28b04dfa1652e0ffdfda866d2845c73 by @dependabot in #2802
chore(deps): bump github/codeql-action from 2.2.1 to 2.2.5 by @dependabot in #2803
chore(deps): bump actions/cache from 3.2.4 to 3.2.6 by @dependabot in #2804
feat: Improve handling of include and exclude for externals and encrypted files by @twpayne in #2451
feat: Extend --include and --exclude flags to include templates by @twpayne in #2455
feat: Add per-template configurable delimiters by @twpayne in #2457
chore: Fix user guide link in support issue template by @bradenhilton in #2464
chore(deps): bump github/codeql-action from 2.1.26 to 2.1.27 by @dependabot in #2459
docs: Update homepage by @twpayne in #2458
chore(deps): bump dorny/paths-filter from 2.10.2 to 2.11.1 by @dependabot in #2460
chore(deps): bump actions/cache from 3.0.9 to 3.0.11 by @dependabot in #2461
chore(deps): bump sigstore/cosign-installer from 2.7.0 to 2.8.0 by @dependabot in #2462
chore(deps): bump cpina/github-action-push-to-another-repository from 9e487f29582587eeb4837c0552c886bb0644b6b9 to 940a2857e598a6392bd336330b07416c1ae8ea1f by @dependabot in #2466
chore: Update dependencies by @twpayne in #2465
chore(deps): bump actions/checkout from 3.0.2 to 3.1.0 by @dependabot in #2463
chore: Tweak template directive implementation by @twpayne in #2467
chore: Miscellaneous fixes by @twpayne in #2469
feat: Add option to exclude scripts that are always run by @twpayne in #2473
fix: Extend template directives functionality by @halostatue in #2471
chore: Update dependencies by @twpayne in #2474
docs: Add faq entry for templates pre-requisites by @felipecrs in #2476
docs: Add release notes and release history by @twpayne in #2477
docs: Add note on setting .ps1 interpreter to pwsh by @bradenhilton in #2478
chore: Fix comments that start from an incorrect name by @alexandear in #2481
chore: Add package descriptions by @twpayne in #2485
fix: Include git repo external state in state dump output by @twpayne in #2487
docs: Add FAQ entry on snap stdin/stdout redirect bug by @twpayne in #2488
chore: Use fs.ModePerm instead of 0o777 for all permissions by @twpayne in #2489
chore: GitHub Actions fixes by @twpayne in #2492
docs(bitwarden): Correct bitwardenFields example by @choznerol in #2493
feat: Populate VERSIONINFO on Windows builds by @bradenhilton in #2479
chore: Update dependencies by @twpayne in #2494
docs: Remove duplicate words by @bradenhilton in #2497
chore: Improve error messages from git-repo externals by @twpayne in #2501
fix: Construct templateDataMap manually by @halostatue in #2503
feat: Add --recurse-submodules flag to init command by @twpayne in #2511
feat: Add --recurse-submodules flag to update command by @twpayne in #2512
chore: Reorder eqFold template function reference page by @bradenhilton in #2513
chore: Fix refactored --include and --exclude flags by @twpayne in #2514
chore: Add test for .chezmoiignore and scripts by @twpayne in #2515
chore: Update dependencies by @twpayne in #2516
chore: Minor documentation tweaks by @twpayne in #2518
chore: Release improvements by @twpayne in #2517
chore(deps): bump goreleaser/goreleaser-action from 3.1.0 to 3.2.0 by @dependabot in #2519
chore(deps): bump actions/upload-artifact from 3.1.0 to 3.1.1 by @dependabot in #2520
chore(deps): bump actions/setup-go from 3.3.0 to 3.3.1 by @dependabot in #2522
chore(deps): bump github/codeql-action from 2.1.27 to 2.1.29 by @dependabot in #2523
chore(deps): bump sigstore/cosign-installer from 2.8.0 to 2.8.1 by @dependabot in #2521
817d3e7 feat: Stop building snaps\\n ab6bc8d feat: Make add command add empty files, remove --empty flag\\n 755e02f fix: Don't return an error when the user chooses quit from a prompt\\n b554329 feat: Implement documented add --prompt flag\\n b95449f docs: Remove stray whitespace\\n ebeebcb docs: Add extra documentation to autotemplate\\n 991a630 docs: Clarify what 'source state' means\\n 2421da8 fix: Check .chezmoiversion in init command\\n 25b32fb feat: Give more context in Windows errors\\n 9605e40 feat: Make --autotemplate escape template markers\\n 2c89541 feat: Support determining FQDN via /etc/myname\\n 281e770 feat: Support multiple GPG recipients\\n cbed719 feat: Include git working tree state in doctor output\\n 87c1a91 docs: Use modeline to set filetype in VIM\\n 1af0576 feat: Include last modified time of config file in doctor output\\n 44762fd feat: Add quoteList template function\\n 2bf1210 feat: Add textconv configuration for friendlier binary diffs\\n 814f1f2 docs: Refactor Windows chassisType template\\n 7199cb2 docs: Add link to blog\\n d29344f fix: Improve quality of POSIX shell scripts\\n f2f8d87 docs: Add link to blog post\\n
"},{"location":"reference/source-state-attributes/","title":"Source state attributes","text":"
chezmoi stores the source state of files, symbolic links, and directories in regular files and directories in the source directory (~/.local/share/chezmoi by default). This location can be overridden with the -S flag or by giving a value for sourceDir in the configuration file. Directory targets are represented as directories in the source state. All other target types are represented as files in the source state. Some state is encoded in the source names.
The following prefixes and suffixes are special, and are collectively referred to as \"attributes\":
Prefix Effect after_ Run script after updating the destination before_ Run script before updating the destination create_ Ensure that the file exists, and create it with contents if it does not dot_ Rename to use a leading dot, e.g. dot_foo becomes .fooempty_ Ensure the file exists, even if is empty. By default, empty files are removed encrypted_ Encrypt the file in the source state external_ Ignore attributes in child entries exact_ Remove anything not managed by chezmoi executable_ Add executable permissions to the target file literal_ Stop parsing prefix attributes modify_ Treat the contents as a script that modifies an existing file once_ Only run the script if its contents have not been run before onchange_ Only run the script if its contents have not been run before with the same filename private_ Remove all group and world permissions from the target file or directory readonly_ Remove all write permissions from the target file or directory remove_ Remove the file or symlink if it exists or the directory if it is empty run_ Treat the contents as a script to run symlink_ Create a symlink instead of a regular file Suffix Effect .literal Stop parsing suffix attributes .tmpl Treat the contents of the source file as a template
Different target types allow different prefixes and suffixes. The order of prefixes is important.
Target type Source type Allowed prefixes in order Allowed suffixes Directory Directory remove_, external_, exact_, private_, readonly_, dot_ none Regular file File encrypted_, private_, readonly_, empty_, executable_, dot_.tmpl Create file File create_, encrypted_, private_, readonly_, empty_, executable_, dot_.tmpl Modify file File modify_, encrypted_, private_, readonly_, executable_, dot_.tmpl Remove file File remove_, dot_ none Script File run_, once_ or onchange_, before_ or after_.tmpl Symbolic link File symlink_, dot_.tmpl
The literal_ prefix and .literal suffix can appear anywhere and stop attribute parsing. This permits filenames that would otherwise conflict with chezmoi's attributes to be represented.
In addition, if the source file is encrypted, the suffix .age (when age encryption is used) or .asc (when gpg encryption is used) is stripped. These suffixes can be overridden with the age.suffix and gpg.suffix configuration variables.
chezmoi ignores all files and directories in the source directory that begin with a . with the exception of files and directories that begin with .chezmoi.
chezmoi will create, update, and delete files, directories, and symbolic links in the destination directory, and run scripts. chezmoi deterministically performs actions in ASCII order of their target name.
Example
Given a file dot_a, a script run_z, and a directory exact_dot_c, chezmoi will first create .a, create .c, and then execute run_z.
Files are represented by regular files in the source state. The encrypted_ attribute determines whether the file in the source state is encrypted. The executable_ attribute will set the executable bits in the target state, and the private_ attribute will clear all group and world permissions. The readonly_ attribute will clear all write permission bits in the target state. Files with the .tmpl suffix will be interpreted as templates. If the target contents are empty then the file will be removed, unless it has an empty_ prefix.
Files with the create_ prefix will be created in the target state with the contents of the file in the source state if they do not already exist. If the file in the destination state already exists then its contents will be left unchanged.
Files with the modify_ prefix are treated as scripts that modify an existing file.
If the file contains a line with the text chezmoi:modify-template then that line is removed and the rest of the script is executed template with the existing file's contents passed as a string in .chezmoi.stdin. The result of executing the template are the new contents of the file.
Otherwise, the contents of the existing file (which maybe empty if the existing file does not exist or is empty) are passed to the script's standard input, and the new contents are read from the script's standard output.
Directories are represented by regular directories in the source state. The exact_ attribute causes chezmoi to remove any entries in the target state that are not explicitly specified in the source state, and the private_ attribute causes chezmoi to clear all group and world permissions. The readonly_ attribute will clear all write permission bits.
Symbolic links are represented by regular files in the source state with the prefix symlink_. The contents of the file will have a trailing newline stripped, and the result be interpreted as the target of the symbolic link. Symbolic links with the .tmpl suffix in the source state are interpreted as templates. If the target of the symbolic link is empty or consists only of whitespace, then the target is removed.
Scripts are represented as regular files in the source state with prefix run_. The file's contents (after being interpreted as a template if it has a .tmpl suffix) are executed.
Scripts are executed on every chezmoi apply, unless they have the once_ or onchange_ attribute. run_once_ scripts are only executed if a script with the same contents has not been run before, i.e. if the script is new or if its contents have changed. run_onchange_ scripts are executed whenever their contents change, even if a script with the same contents has run before.
Scripts with the before_ attribute are executed before any files, directories, or symlinks are updated. Scripts with the after_ attribute are executed after all files, directories, and symlinks have been updated. Scripts without an before_ or after_ attribute are executed in ASCII order of their target names with respect to files, directories, and symlinks.
Scripts will normally run with their working directory set to their equivalent location in the destination directory. If the equivalent location in the destination directory either does not exist or is not a directory, then chezmoi will walk up the script's directory hierarchy and run the script in the first directory that exists and is a directory.
Example
A script in ~/.local/share/chezmoi/dir/run_script will be run with a working directory of ~/dir.
chezmoi sets a number of CHEZMOI* environment variables when running scripts, corresponding to commonly-used template data variables. Extra environment variables can be set in the env or scriptEnv configuration variables.
Scripts are executed using an interpreter, if configured. See the section on interpreters.
By default, chezmoi will create regular files and directories. Setting mode = \"symlink\" will make chezmoi behave more like a dotfile manager that uses symlinks by default, i.e. chezmoi apply will make dotfiles symlinks to files in the source directory if the target is a regular file and is not encrypted, executable, private, or a template.
"},{"location":"reference/command-line-flags/","title":"Command line flags","text":"
Command line flags override any values set in the configuration file.
"},{"location":"reference/command-line-flags/common/","title":"Common command line flags","text":"
The following flags apply to multiple commands where they are relevant.
Print paths in the given style. The default is relative.
Style Description absolute Absolute paths in the destination directory relative Relative paths to the destination directory source-absolute Absolute paths in the source tree directory source-relative Relative paths to the source tree directory all All path styles, indexed by relative"},{"location":"reference/command-line-flags/common/#-r-recursive","title":"-r, --recursive","text":"
You can provide a list of entry types, separated by commas. Types can be preceded with no to remove them, e.g. scripts,noalways.
Type Description all All entries none No entries dirs Directories files Files remove Removes scripts Scripts symlinks Symbolic links always Scripts that are always run encrypted Encrypted entries externals External entries templates Templates"},{"location":"reference/command-line-flags/developer/","title":"Developer command line flags","text":"
The following flags are global but only relevant for developers and debugging.
Colorize diffs, value can be on, off, auto, or any boolean-like value recognized by promptBool. The default is auto which will colorize diffs only if the environment variable $NO_COLOR is not set and stdout is a terminal.
Assume the configuration file is in the given format. This is only needed if the config filename does not have an extension, for example when it is /dev/stdin. Supported formats: json, jsonc, toml, yaml.
Set dry run mode. In dry run mode, the destination directory is never modified. This is most useful in combination with the -v (verbose) flag to print changes that would be made without making them.
Read and write the persistent state from filename. By default, chezmoi stores its persistent state in chezmoistate.boltdb in the same directory as its configuration file.
Control the refresh of the externals cache. value can be any of always, auto, or never and defaults to always if no value is specified. If no --refresh-externals flag is specified then chezmoi defaults to auto.
always (or any truthy value as accepted by parseBool) causes chezmoi to re-download externals.
auto means only re-download externals that have not been downloaded within their refresh periods.
never (or any other falsey value accepted by parseBool) means only download if no cached external is available.
Use chezmoi's builtin age encryption instead of an external age command. value can be on, off, auto, or any boolean-like value recognized by promptBool. The default is auto which will only use the builtin age if age.command cannot be found in $PATH.
The builtin age command does not support passphrases, symmetric encryption, or the use of SSH keys.
Use chezmoi's builtin git instead of git.command for the init and update commands. value can be on, off, auto, or any boolean-like value recognized by promptBool. The default is auto which will only use the builtin git if git.command cannot be found in $PATH.
Info
chezmoi's builtin git has only supports the HTTP and HTTPS transports and does not support git-repo externals.
Set verbose mode. In verbose mode, chezmoi prints the changes that it is making as approximate shell commands, and any differences in files between the target state and the destination set are printed as unified diffs.
Use directory as the git working tree directory. By default, chezmoi searches the source directory and then its ancestors for the first directory that contains a .git directory.
Add targets to the source state. If any target is already in the source state, then its source state is replaced with its current state in the destination directory.
Automatically generate a template by replacing strings that match variable values from the data section of the config file with their respective config names as a template string. Longer substitutions occur before shorter ones. This implies the --template option.
Warning
--autotemplate uses a greedy algorithm which occasionally generates templates with unwanted variable substitutions. Carefully review any templates it generates.
When adding symlink to an absolute path in the source directory or destination directory, create a symlink template with .chezmoi.sourceDir or .chezmoi.homeDir. This is useful for creating portable absolute symlinks.
Ensure that target... are in the target state, updating them if necessary. If no targets are specified, the state of all targets are ensured. If a target has been modified since chezmoi last wrote it then the user will be prompted if they want to overwrite the file.
Write the target contents of targets to stdout. targets must be files, scripts, or symlinks. For files, the target file contents are written. For scripts, the script's contents are written. For symlinks, the target is written.
Launch a shell in the working tree (typically the source directory). chezmoi will launch the command set by the cd.command configuration variable with any extra arguments specified by cd.args. If this is not set, chezmoi will attempt to detect your shell and finally fall back to an OS-specific default.
If the optional argument path is present, the shell will be launched in the source directory corresponding to path.
The shell will have various CHEZMOI* environment variables set, as for scripts.
Hint
This does not change the current directory of the current shell. To do that, instead use:
Change the attributes and/or type of targets. modifier specifies what to modify.
Add attributes by specifying them or their abbreviations directly, optionally prefixed with a plus sign (+). Remove attributes by prefixing them or their attributes with the string no or a minus sign (-). The available attribute modifiers and their abbreviations are:
The type of a target can be changed using a type modifier:
Type modifier createmodifyscriptsymlink
The negative form of type modifiers, e.g. nocreate, changes the target to be a regular file if it is of that type, otherwise the type is left unchanged.
Multiple modifications may be specified by separating them with a comma (,). If you use the -modifier form then you must put modifier after a -- to prevent chezmoi from interpreting -modifier as an option.
Decrypt files using chezmoi's configured encryption. If no files are given, decrypt the standard input. The decrypted result is written to the standard output or a file if the --output flag is set.
Print the difference between the target state and the destination state for targets. If no targets are specified, print the differences for all targets.
If a diff.pager command is set in the configuration file then the output will be piped into it.
If diff.command is set then it will be invoked to show individual file differences with diff.args passed as arguments. Each element of diff.args is interpreted as a template with the variables .Destination and .Target available corresponding to the path of the file in the source and target state respectively. The default value of diff.args is [\"{{ .Destination }}\", \"{{ .Target }}\"]. If diff.args does not contain any template arguments then {{ .Destination }} and {{ .Target }} will be appended automatically.
Edit the configuration file template. If no configuration file template exists, then a new one is created with the contents of the current config file.
Edit the source state of targets, which must be files or symlinks. If no targets are given then the working tree of the source directory is opened.
Encrypted files are decrypted to a private temporary directory and the editor is invoked with the decrypted file. When the editor exits the edited decrypted file is re-encrypted and replaces the original file in the source state.
If the operating system supports hard links, then the edit command invokes the editor with filenames which match the target filename, unless the edit.hardlink configuration variable is set to false or the --hardlink=false command line flag is set.
Invoke the editor with a hard link to the source file with a name matching the target filename. This can help the editor determine the type of the file correctly. This is the default.
Encrypt files using chezmoi's configured encryption. If no files are given, encrypt the standard input. The encrypted result is written to the standard output or a file if the --output flag is set.
Execute templates. This is useful for testing templates or for calling chezmoi from other scripts. templates are interpreted as literal templates, with no whitespace added to the output between arguments. If no templates are specified, the template is read from stdin.
Simulate the promptBool template function with a function that returns values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptBool is called with a prompt that does not match any of pairs, then it returns false.
Simulate the promptChoice template function with a function that returns values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptChoice is called with a prompt that does not match any of pairs, then it returns false.
Simulate the promptInt template function with a function that returns values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptInt is called with a prompt that does not match any of pairs, then it returns zero.
Simulate the promptString template function with a function that returns values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptString is called with a prompt that does not match any of pairs, then it returns prompt unchanged.
Generates output for use with chezmoi. The currently supported outputs are:
Output Description git-commit-message A git commit message, describing the changes to the source directory. install.sh An install script, suitable for use with GitHub Codespaces"},{"location":"reference/commands/generate/#examples","title":"Examples","text":"
Import the source state from an archive file in to a directory in the source state. This is primarily used to make subdirectories of your home directory exactly match the contents of a downloaded archive. You will generally always want to set the --destination, --exact, and --remove-destination flags.
The supported archive formats are tar, tar.gz, tgz, tar.bz2, tbz2, txz, tar.zst, and zip.
Setup the source directory, generate the config file, and optionally update the destination directory to match the target state.
By default, if repo is given, chezmoi will guess the full git repo URL, using HTTPS by default, or SSH if the --ssh option is specified, according to the following patterns:
To disable git repo URL guessing, pass the --guess-repo-url=false option.
First, if the source directory does not already contain a repository, then if repo is given, it is checked out into the source directory; otherwise a new repository is initialized in the source directory.
Second, if a file called .chezmoi.$FORMAT.tmpl exists, where $FORMAT is one of the supported file formats (e.g. json, jsonc, toml, or yaml) then a new configuration file is created using that file as a template.
Then, if the --apply flag is passed, chezmoi apply is run.
Then, if the --purge flag is passed, chezmoi will remove its source, config, and cache directories.
Finally, if the --purge-binary is passed, chezmoi will attempt to remove its own binary.
Include existing template data when creating the config file. This defaults to true. Set this to false to simulate creating the config file with no existing template data.
--one-shot is the equivalent of --apply, --depth=1, --force, --purge, and --purge-binary. It attempts to install your dotfiles with chezmoi and then remove all traces of chezmoi from the system. This is useful for setting up temporary environments (e.g. Docker containers).
Populate the promptBool template function with values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptBool is called with a prompt that does not match any of pairs, then it prompts the user for a value.
Populate the promptChoice template function with values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptChoice is called with a prompt that does not match any of pairs, then it prompts the user for a value.
Populate the promptInt template function with values from pairs. pairs is a comma-separated list of prompt=value pairs. If prompInt is called with a prompt that does not match any of pairs, then it prompts the user for a value.
Populate the promptString template function with values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptString is called with a prompt that does not match any of pairs, then it prompts the user for a value.
List all managed entries in the destination directory under all paths in alphabetical order. When no paths are supplied, list all managed entries in the destination directory in alphabetical order.
Print paths in the given style. The default is relative.
Style Description absolute Absolute paths in the destination directory relative Relative paths to the destination directory source-absolute Absolute paths in the source tree directory source-relative Relative paths to the source tree directory all All path styles, indexed by relative"},{"location":"reference/commands/managed/#-t-tree","title":"-t, --tree","text":"
Perform a three-way merge between the destination state, the target state, and the source state for each target. The merge tool is defined by the merge.command configuration variable, and defaults to vimdiff. If multiple targets are specified the merge tool is invoked separately and sequentially for each target. If the target state cannot be computed (for example if source is a template containing errors or an encrypted file that cannot be decrypted) a two-way merge is performed instead.
The order of arguments to merge.command is set by merge.args. Each argument is interpreted as a template with the variables .Destination, .Source, and .Target available corresponding to the path of the file in the destination state, the source state, and the target state respectively. The default value of merge.args is [\"{{ .Destination }}\", \"{{ .Source }}\", \"{{ .Target }}\"]. If merge.args does not contain any template arguments then {{ .Destination }}, {{ .Source }}, and {{ .Target }} will be appended automatically.
Re-add modified files in the target state, preserving any encrypted_ attributes. chezmoi will not overwrite templates, and all entries that are not files are ignored. Directories are recursed into by default.
If no targets are specified then all modified files are re-added. If one or more targets are given then only those targets are re-added.
Run a secret manager's CLI, passing any extra arguments to the secret manager's CLI. This is primarily for verifying chezmoi's integration with a custom secret manager. Normally you would use chezmoi's existing template functions to retrieve secrets.
Note
If you need to pass flags to the secret manager's CLI you must separate them with -- to prevent chezmoi from interpreting them.
On FreeBSD, the secret keyring command is only available if chezmoi was compiled with cgo enabled. The official release binaries of chezmoi are not compiled with cgo enabled, and secret keyring command is not available.
chezmoi state data\nchezmoi state delete --bucket=$BUCKET --key=$KEY\nchezmoi state delete-bucket --bucket=$BUCKET\nchezmoi state dump\nchezmoi state get --bucket=$BUCKET --key=$KEY\nchezmoi state get-bucket --bucket=$BUCKET\nchezmoi state set --bucket=$BUCKET --key=$KEY --value=$VALUE\nchezmoi state reset\n
Print the status of the files and scripts managed by chezmoi in a format similar to git status.
The first column of output indicates the difference between the last state written by chezmoi and the actual state. The second column indicates the difference between the actual state and the target state, and what effect running chezmoi apply will have.
Character Meaning First column Second column Space No change No change No change A Added Entry was created Entry will be created D Deleted Entry was deleted Entry will be deleted M Modified Entry was modified Entry will be modified R Run Not applicable Script will be run"},{"location":"reference/commands/status/#common-flags","title":"Common flags","text":""},{"location":"reference/commands/status/#-x-exclude-types","title":"-x, --exclude types","text":"
Exclude target state entries of specific types. The default is none.
Types can be explicitly included with the --include flag.
Example
--exclude=scripts will cause the command to not run scripts and --exclude=encrypted will exclude encrypted files.
Print paths in the given style. The default is relative.
Style Description absolute Absolute paths in the destination directory relative Relative paths to the destination directory source-absolute Absolute paths in the source tree directory source-relative Relative paths to the source tree directory all All path styles, indexed by relative"},{"location":"reference/commands/status/#-r-recursive","title":"-r, --recursive","text":"
Recurse into subdirectories. Enabled by default. Can be disabled with --recursive=false.
Print paths in the given style. The default is relative.
Style Description absolute Absolute paths in the destination directory relative Relative paths to the destination directory"},{"location":"reference/commands/unmanaged/#-t-tree","title":"-t, --tree","text":"
Pull changes from the source repo and apply any changes.
If update.command is set then chezmoi will run update.command with update.args in the working tree. Otherwise, chezmoi will run git pull --autostash --rebase [--recurse-submodules] , using chezmoi's builtin git if useBuiltinGit is true or if git.command cannot be found in $PATH.
Upgrade chezmoi by downloading and installing the latest released version. This will call the GitHub API to determine if there is a new version of chezmoi available, and if so, download and attempt to install it in the same way as chezmoi was previously installed.
If the any of the $CHEZMOI_GITHUB_ACCESS_TOKEN, $CHEZMOI_GITHUB_TOKEN, $GITHUB_ACCESS_TOKEN, or $GITHUB_TOKEN environment variables are set, then the first value found will be used to authenticate requests to the GitHub API, otherwise unauthenticated requests are used which are subject to stricter rate limiting. Unauthenticated requests should be sufficient for most cases.
Warning
If you installed chezmoi using a package manager, the upgrade command might have been removed by the package maintainer.
Override the upgrade method that was automatically detected by chezmoi.
Danger
This flag should only be used when recommended by chezmoi developers.
Methods Description brew-upgrade Run brew upgrade chezmoi. replace-executable Download the latest released executable from Github. snap-refresh Run snap refresh chezmoi. sudo-upgrade-package Same as upgrade-package but use sudo. upgrade-package Download and install .apk, .deb or .rpm package. Run pacman on Arch Linux."},{"location":"reference/commands/verify/","title":"verify [target...]","text":"
Verify that all targets match their target state. chezmoi exits with code 0 (success) if all targets match their target state, or 1 (failure) otherwise. If no targets are specified then all targets are checked.
chezmoi searches for its configuration file according to the XDG Base Directory Specification and supports JSON, JSONC, TOML, and YAML. The basename of the config file is chezmoi. If multiple configuration file formats are present, chezmoi will report an error.
In most installations, the config file will be read from $HOME/.config/chezmoi/chezmoi.$FORMAT (%USERPROFILE%/.config/chezmoi/chezmoi.$FORMAT), where $FORMAT is one of json, jsonc, toml, or yaml. The config file can be set explicitly with the --config command line option. By default, the format is detected based on the extension of the config file name, but can be overridden with the --config-format command line option.
The editor used is the first non-empty string of the edit.command configuration variable, the $VISUAL environment variable, the $EDITOR environment variable. If none are set then chezmoi falls back to notepad.exe on Windows systems and vi on non-Windows systems.
When the edit.command configuration variable is used, extra arguments can be passed to the editor with the edit.args configuration variable.
chezmoi will emit a warning if the editor returns in less than edit.minDuration (default 1s). To disable this warning, set edit.minDuration to 0.
Hook commands are executed before and after events. Unlike scripts, hooks are always run, even if --dry-run is specified. Hooks should be fast and idempotent.
The following events are defined:
Event Trigger command, e.g. add Running chezmoi command, e.g. chezmoi addread-source-state Reading the source state
Each event can have a .pre and/or a .post command. The event.pre command is executed before event occurs and the event.post command is executed after event has occurred.
A command contains a command or script and an optional array of strings args. commands are executed directly. scripts are executed with configured interpreter for the script's extension, see the section on interpreters.
When running hooks, the CHEZMOI=1 and CHEZMOI_* environment variables will be set. CHEZMOI_COMMAND is set to the chezmoi command being run, CHEZMOI_COMMAND_DIR is set to the directory where chezmoi was run from, and CHEZMOI_ARGS contains the full arguments to chezmoi, starting with the path to chezmoi's executable.
The execution of scripts and hooks on Windows depends on the file extension. Windows will natively execute scripts with a .bat, .cmd, .com, and .exe extensions. Other extensions require an interpreter, which must be in your %PATH%.
Script interpreters can be added or overridden by adding the corresponding extension (without the leading dot) as a key under the interpreters section of the configuration file.
Note
The leading . is dropped from extension, for example to specify the interpreter for .pl files you configure interpreters.pl (where . in this case just means \"a child of\" in the configuration file, however that is specified in your preferred format).
Example
To change the Python interpreter to C:\\Python39\\python3.exe and add a Tcl/Tk interpreter, include the following in your config file:
Note that the TOML version can also be written like this, which resembles the YAML version more and makes it clear that the key for each file extension should not have a leading .:
If the script in the source state is a template (with a .tmpl extension), then chezmoi will strip the .tmpl extension and use the next remaining extension to determine the interpreter to use.
By default, chezmoi will request passwords from the terminal.
If the --no-tty option is passed, then chezmoi will instead read passwords from the standard input.
Otherwise, if the configuration variable pinentry.command is set then chezmoi will instead used the given command to read passwords, assuming that it follows the Assuan protocol like GnuPG's pinentry. The configuration variable pinentry.args specifies extra arguments to be passed to pinentry.command and the configuration variable pinentry.options specifies extra options to be set. The default pinentry.options is [\"allow-external-password-cache\"].
A section called textconv in the configuration file controls how file contents are modified before being passed to diff.
The textconv must contain an array of objects where each object has the following properties:
Name Type Description pattern string Target path pattern to match command string Command to transform contents args []string Extra arguments to command
Files whose target path matches pattern are transformed by passing them to the standard input of command with args, and new contents are read from the command's standard output.
If a target path does not match any patterns then the file contents are passed unchanged to diff. If a target path matches multiple patterns then element with the longest pattern is used.
By default, chezmoi uses your current umask as set by your operating system and shell. chezmoi only stores crude permissions in its source state, namely in the executable and private attributes, corresponding to the umasks of 0o111 and 0o077 respectively.
For machine-specific control of umask, set the umask configuration variable in chezmoi's configuration file.
The following configuration variables are available:
Section Variable Type Default value Description Top level cacheDir string $XDG_CACHE_HOME/chezmoi$HOME/.cache/chezmoi%USERPROFILE%/.cache/chezmoi Cache directory color string auto Colorize output data object none Template data destDir string $HOME%USERPROFILE% Destination directory encryption string none Encryption type, either age or gpgenv object none Extra environment variables for scripts and commands format string json Format for data output, either json or yamlinteractive string false Prompt for all changes mode string file Mode in target dir, either file or symlinkpager string $PAGER Default pager CLI command persistentState string $XDG_CONFIG_HOME/chezmoi/chezmoi.boltdb$HOME/.config/chezmoi/chezmoi.boltdb%USERPROFILE%/.config/chezmoi/chezmoi.boltdb Location of the persistent state file progress bool false Display progress bars scriptEnv object none Extra environment variables for scripts and commands scriptTempDir string none Temporary directory for scripts sourceDir string $XDG_SHARE_HOME/chezmoi$HOME/.local/share/chezmoi%USERPROFILE%/.local/share/chezmoi Source directory tempDir string from system Temporary directory umask int from system Umask useBuiltinAge string auto Use builtin age if age command is not found in $PATHuseBuiltinGit string auto Use builtin git if git command is not found in $PATHverbose bool false Make output more verbose workingTree string source directory git working tree directory addencrypt bool false Encrypt by default secrets string warning Action when secrets are found when adding files templateSymlinks bool false Template symlinks to source and home dirs ageargs []string none Extra args to age CLI command command string age age CLI command identities []string none age identity files identity string none age identity file passphrase bool false Use age passphrase instead of identity recipient string none age recipient recipients []string none age recipients recipientsFile string none age recipients file recipientsFiles []string none age recipients files suffix string .age Suffix appended to age-encrypted files symmetric bool false Use age symmetric encryption awsSecretsManagerprofile string none AWS shared profile name region string none AWS region azureKeyVaultdefaultVault string none Default Azure Key Vault name bitwardencommand string bw Bitwarden CLI command bitwardenSecretscommand string bws Bitwarden Secrets CLI command cdargs []string none Extra args to shell in cd command command string none Shell to run in cd command completioncustom bool false Enable custom shell completions dashlaneargs []string none Extra args to Dashlane CLI command command string dcli Dashlane CLI command diffargs []string see diff Extra args to external diff command command string none External diff command exclude []string none Entry types to exclude from diffs pager string none Diff-specific pager reverse bool false Reverse order of arguments to diff scriptContents bool true Show script contents dopplerargs []string none Extra args to Doppler CLI command command string doppler Doppler CLI command config string none Default config (aka environment) if none is specified project string none Default project name if none is specified editapply bool false Apply changes on exit args []string none Extra args to edit command command string $EDITOR / $VISUAL Edit command hardlink bool true Invoke editor with a hardlink to the source file minDuration duration 1s Minimum duration for edit command watch bool false Automatically apply changes when files are saved ejsonkey string none The private key to use for decryption, will supersede using the keyDir if set. keyDir string none Path to directory containing private keys. Defaults to /opt/ejson/keys. Setting the EJSON_KEYDIR environment will also set this value, with lower precedence. gitautoAdd bool false Add changes to the source state after any change autoCommit bool false Commit changes to the source state after any change autoPush bool false Push changes to the source state after any change command string git git CLI command commitMessageTemplate string none Commit message template commitMessageTemplateFile string none Commit message template file (relative to source directory) lfs bool false Run git lfs pull after cloning gitHubrefreshPeriod duration 1m Minimum duration between identical GitHub API requests gopasscommand string gopass gopass CLI command mode string none See gopass functions gpgargs []string none Extra args to GPG CLI command command string gpg GPG CLI command recipient string none GPG recipient recipients []string none GPG recipients suffix string .asc Suffix appended to GPG-encrypted files symmetric bool false Use symmetric GPG encryption hcpVaultSecretsapplicationName string none Default application name if none is specified args []string none Extra args to HCP Vault Secrets CLI command command string vlt HCP Vault Secrets CLI command organizationId string none Default organization ID if none is specified projectId string none Default project ID if none is specified hooks command.post.args []string none Extra arguments to command to run after command command.post.command []string none Command to run after command command.pre.args []string none Extra arguments to command to run before command command.pre.command []string none Command to run before command interpreters extension.args []string none See Interpreters extension.command string special See Interpreters keepassxcargs []string none Extra args to KeePassXC CLI command command string keepassxc-cli KeePassXC CLI command database string none KeePassXC database mode string cache-password See KeePassXC functions prompt bool true Prompt for password keeperargs []string none Extra args to Keeper CLI command command string keeper Keeper CLI command lastpasscommand string lpass LastPass CLI command mergeargs []string See merge Extra args to three-way merge CLI command command string none Three-way merge CLI command onepasswordcache bool true Enable optional caching provided by opcommand string op 1Password CLI command mode string account See 1Password Secrets Automation prompt bool true Prompt for sign-in when no valid session is available onepasswordSDKtoken string none See 1Password SDK functions tokenEnvVar string none See 1Password SDK functions passcommand string pass Pass CLI command passholeargs []string none Extra args to Passhole CLI command command string ph Passhole CLI command prompt bool true Prompt for password pinentryargs []string none Extra args to pinentry CLI command command string none pinentry CLI command options []string See pinentry Extra options for pinentry rbwcommand string rbw Unofficial Bitwarden CLI command secretargs []string none Extra args to secret CLI command command string none Generic secret CLI command statusexclude []string none Entry types to exclude from status pathStyle string relative How to present the path to files in status output templateoptions []string [\"missingkey=error\"] Template options textconv []object none See textconv updateapply bool true Apply after pulling args []string none Extra args to update command command string none Update command recurseSubmodules bool true Update submodules recursively vaultcommand string vault Vault CLI command verifyexclude []string none Entry types to exclude from verify warnings object none See Warnings"},{"location":"reference/configuration-file/warnings/","title":"Warnings","text":"
By default, chezmoi will warn you when it encounters potential problems. Some of these warnings can be suppressed by setting values in configuration file.
Variable Type Default Description configFileTemplateHasChanged bool true Warn when the config file template has changed
All directories in the source state whose name begins with . are ignored by default, unless they are one of the special directories listed here. .chezmoitemplates is read before all other files so that they can be used in templates.
If a directory called .chezmoidata exists in the source state, then all files in it are interpreted as template data in the format given by their extension.
If a directory called .chezmoiscripts exists in the root of the source directory then any scripts in it are executed as normal scripts without creating a corresponding directory in the target state.
If a directory called .chezmoitemplates exists, then all files in this directory are available as templates with a name equal to the relative path to the .chezmoitemplates directory.
The template action can be used to include these templates in another template. The value of . must be set explicitly if needed, otherwise the template will be executed with nil data.
All files in the source state whose name begins with . are ignored by default, unless they are one of the special files listed here. .chezmoidata.$FORMAT is read before all other files so that it can be used in templates.
If a file called .chezmoi.$FORMAT.tmpl exists then chezmoi init will use it to create an initial config file. $FORMAT must be one of the supported config file formats, e.g. json, jsonc, toml, or yaml. Templates defined in .chezmoitemplates are not available because the template is executed before the source state is read.
If a file called .chezmoiexternal.$FORMAT (with an optional .tmpl extension) exists anywhere in the source state (either ~/.local/share/chezmoi or directory defined inside .chezmoiroot), it is interpreted as a list of external files and archives to be included as if they were in the source state.
$FORMAT must be one of chezmoi's supported configuration file formats, e.g. json, jsonc, toml, or yaml.
.chezmoiexternal.$FORMAT is interpreted as a template. This allows different externals to be included on different machines.
If a .chezmoiexternal.$FORMAT file is located in an ignored directory (one listed in .chezmoiignore), all entries within the file are also ignored.
Entries are indexed by target name relative to the directory of the .chezmoiexternal.$FORMAT file, and must have a type and a url and/or a urls field. type can be either file, archive, archive-file, or git-repo. If the entry's parent directories do not already exist in the source state then chezmoi will create them as regular directories.
Entries may have the following fields:
Variable Type Default value Description type string none External type (file, archive, archive-file, or git-repo) decompress string none Decompression for file encrypted bool false Whether the external is encrypted exact bool false Add exact_ attribute to directories in archive exclude []string none Patterns to exclude from archive executable bool false Add executable_ attribute to file private bool false Add private_ attribute to file readonly bool false Add readonly_ attribute to file format string autodetect Format of archive path string none Path to file in archive include []string none Patterns to include from archive refreshPeriod duration 0 Refresh period stripComponents int 0 Number of leading directory components to strip from archives url string none URL urls []string none Extra URLs to try, in order checksum.sha256 string none Expected SHA256 checksum of data checksum.sha384 string none Expected SHA384 checksum of data checksum.sha512 string none Expected SHA512 checksum of data checksum.size int none Expected size of data clone.args []string none Extra args to git clonefilter.command string none Command to filter contents filter.args []string none Extra args to command to filter contents pull.args []string none Extra args to git pullarchive.extractAppleDouble bool false If true, AppleDouble files are extracted
url must be an https://, http://, or file:// URL. If urls is specified then they are tried in order and the first URL that succeeds is used.
If any of the optional checksum.sha256, checksum.sha384, or checksum.sha512 fields are set, chezmoi will verify that the downloaded data has the given checksum.
The optional boolean encrypted field specifies whether the file or archive is encrypted.
The optional string decompress specifies how the file should be decompressed. Supported compression formats are bzip2, gzip, xz, and zstd. Note the .zip files are archives and you must use the archive-file type to extract a single file from a .zip archive.
If optional string filter.command and array of strings filter.args are specified, the file or archive is filtered by piping it into the command's standard input and reading the command's standard output.
If type is file then the target is a file with the contents of url. The optional boolean field executable may be set, in which case the target file will be executable.
If type is archive then the target is a directory with the contents of the archive at url. The optional boolean field exact may be set, in which case the directory and all subdirectories will be treated as exact directories, i.e. chezmoi apply will remove entries not present in the archive. The optional integer field stripComponents will remove leading path components from the members of archive. The optional string field format sets the archive format. The supported archive formats are tar, tar.gz, tgz, tar.bz2, tbz2, xz, .tar.zst, and zip. If format is not specified then chezmoi will guess the format using firstly the path of the URL and secondly its contents.
When type is archive or archive-file, the optional setting archive.extractAppleDouble controls whether AppleDouble files are extracted. It is false by default, so AppleDouble files will not be extracted.
The optional include and exclude fields are lists of patterns specify which archive members to include or exclude respectively. Patterns match paths in the archive, not the target state. chezmoi uses the following algorithm to determine whether an archive member is included:
If the archive member name matches any exclude pattern, then the archive member is excluded. In addition, if the archive member is a directory, then all contained files and sub-directories will be excluded, too (recursively).
Otherwise, if the archive member name matches any include pattern, then the archive member is included.
Otherwise, if only include patterns were specified then the archive member is excluded.
Otherwise, if only exclude patterns were specified then the archive member is included.
Otherwise, the archive member is included.
Excluded archive members do not generate source state entries, and, if they are directories, all of their children are also excluded.
If type is archive-file then the target is a file or symlink with the contents of the entry path in the archive at url. The optional integer field stripComponents will remove leading path components from the members of the archive before comparing them with path. The behavior of format is the same as for archive. If executable is true then chezmoi will set the executable bits on the target file, even if they are not set in the archive.
If type is git-repo then chezmoi will run git clone $URL $TARGET_NAME with the optional clone.args if the target does not exist. If the target exists, then chezmoi will run git pull with the optional pull.args to update the target.
For file and archive externals, chezmoi will cache downloaded URLs. The optional duration refreshPeriod field specifies how often chezmoi will re-download the URL. The default is zero meaning that chezmoi will never re-download unless forced. To force chezmoi to re-download URLs, pass the -R/--refresh-externals flag. Suitable refresh periods include one day (24h), one week (168h), or four weeks (672h).
If a file called .chezmoiignore (with an optional .tmpl extension) exists in the source state then it is interpreted as a set of patterns to ignore. Patterns are matched using doublestar.Match and match against the target path, not the source path.
Patterns can be excluded by prefixing them with a ! character. All excludes take priority over all includes.
Comments are introduced with the # character and run until the end of the line.
.chezmoiignore is interpreted as a template, whether or not it has a .tmpl extension. This allows different files to be ignored on different machines.
.chezmoiignore files in subdirectories apply only to that subdirectory.
Example
~/.local/share/chezmoi/.chezmoiignore
README.md\n\n*.txt # ignore *.txt in the target directory\n*/*.txt # ignore *.txt in subdirectories of the target directory\n # but not in subdirectories of subdirectories;\n # so a/b/c.txt would *not* be ignored\n\nbackups/ # ignore the backups folder, but not its contents\nbackups/** # ignore the contents of backups folder but not the folder itself\n\n{{- if ne .email \"firstname.lastname@company.com\" }}\n# Ignore .company-directory unless configured with a company email\n.company-directory # note that the pattern is not dot_company-directory\n{{- end }}\n\n{{- if ne .email \"me@home.org\" }}\n.personal-file\n{{- end }}\n
If a file called .chezmoiremove (with an optional .tmpl extension) exists in the source state then it is interpreted as a list of targets to remove. .chezmoiremove is interpreted as a template, whether or not it has a .tmpl extension.
If a file called .chezmoiroot exists in the root of the source directory then the source state is read from the directory specified in .chezmoiroot interpreted as a relative path to the source directory. .chezmoiroot is read before all other files in the source directory.
If a file called .chezmoiversion exists, then its contents are interpreted as a semantic version defining the minimum version of chezmoi required to interpret the source state correctly. chezmoi will refuse to interpret the source state if the current version is too old.
chezmoi executes templates using text/template. The result is treated differently depending on whether the target is a file or a symlink.
If target is a file, then:
If the result is an empty string, then the file is removed.
Otherwise, the target file contents are result.
If the target is a symlink, then:
Leading and trailing whitespace are stripped from the result.
If the result is an empty string, then the symlink is removed.
Otherwise, the target symlink target is the result.
chezmoi executes templates using text/template's missingkey=error option, which means that misspelled or missing keys will raise an error. This can be overridden by setting a list of options in the configuration file.
Hint
For a full list of template options, see Template.Option.
File-specific template options can be set using template directives in the template of the form:
chezmoi:template:$KEY=$VALUE\n
which sets the template option $KEY to $VALUE. $VALUE must be quoted if it contains spaces or double quotes. Multiple key/value pairs may be specified on a single line.
Lines containing template directives are removed to avoid parse errors from any delimiters. If multiple directives are present in a file, later directives override earlier ones.
Then the delimiters $LEFT and $RIGHT are used instead. Either or both of left-delimiter=$LEFT and right-delimiter=$RIGHT may be omitted. If either $LEFT or $RIGHT is empty then the default delimiter ({{ and }} respectively) is set instead.
The delimiters are specific to the file in which they appear and are not inherited by templates called from the file.
Many of the template functions available in chezmoi primarily use UNIX-style line endings (lf/\\n), which may result in unexpected output when running chezmoi diff on a modify_ template. These line endings can be overridden with a template directive:
chezmoi:template:line-endings=$VALUE\n
$VALUE can be an arbitrary string or one of:
Value Effect crlf Use Windows line endings (\\r\\n) lf Use UNIX-style line endings (\\n) native Use platform-native line endings (crlf on Windows, lf elsewhere)"},{"location":"reference/templates/directives/#missing-keys","title":"Missing keys","text":"
By default, chezmoi will return an error if a template indexes a map with a key that is not present in the map. This behavior can be changed globally with the template.options configuration variable or with a template directive:
chezmoi:template:missing-key=$VALUE\n
$VALUE can be one of:
Value Effect error Return an error on any missing key (default) invalid Ignore missing keys. If printed, the result of the index operation is the string <no value>zero Ignore missing keys. If printed, the result of the index operation is the zero value"},{"location":"reference/templates/variables/","title":"Variables","text":"
chezmoi provides the following automatically-populated variables:
Variable Type Value .chezmoi.arch string Architecture, e.g. amd64, arm, etc. as returned by runtime.GOARCH .chezmoi.args []string The arguments passed to the chezmoi command, starting with the program command .chezmoi.cacheDir string The cache directory .chezmoi.config object The configuration, as read from the config file .chezmoi.configFile string The path to the configuration file used by chezmoi .chezmoi.destDir string The destination directory .chezmoi.executable string The path to the chezmoi executable, if available .chezmoi.fqdnHostname string The fully-qualified domain name hostname of the machine chezmoi is running on .chezmoi.gid string The primary group ID .chezmoi.group string The group of the user running chezmoi .chezmoi.homeDir string The home directory of the user running chezmoi .chezmoi.hostname string The hostname of the machine chezmoi is running on, up to the first ..chezmoi.kernel object Contains information from /proc/sys/kernel. Linux only, useful for detecting specific kernels (e.g. Microsoft's WSL kernel) .chezmoi.os string Operating system, e.g. darwin, linux, etc. as returned by runtime.GOOS .chezmoi.osRelease object The information from /etc/os-release, Linux only, run chezmoi data to see its output .chezmoi.pathListSeparator string The path list separator, typically ; on Windows and : on other systems. Used to separate paths in environment variables. ie /bin:/sbin:/usr/bin.chezmoi.pathSeparator string The path separator, typically \\ on windows and / on unix. Used to separate files and directories in a path. ie c:\\see\\dos\\run.chezmoi.sourceDir string The source directory .chezmoi.sourceFile string The path of the template relative to the source directory .chezmoi.targetFile string The absolute path of the target file for the template .chezmoi.uid string The user ID .chezmoi.username string The username of the user running chezmoi .chezmoi.version.builtBy string The program that built the chezmoi executable, if set .chezmoi.version.commit string The git commit at which the chezmoi executable was built, if set .chezmoi.version.date string The timestamp at which the chezmoi executable was built, if set .chezmoi.version.version string The version of chezmoi .chezmoi.windowsVersion object Windows version information, if running on Windows .chezmoi.workingTree string The working tree of the source directory
.chezmoi.windowsVersion contains the following keys populated from the registry key Computer\\HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion.
Additional variables can be defined in the config file in the data section. Variable names must consist of a letter and be followed by zero or more letters and/or digits.
The onepassword* template functions return structured data from 1Password using the 1Password CLI (op).
Info
When using the 1Password CLI with biometric authentication, chezmoi derives values from op account list that can resolves into the appropriate 1Password account-uuid.
As an example, if op account list --format=json returns the following structure:
The following values can be used in the account parameter and the value some-account-uuid will be passed as the --account parameter to op.
some-account-uuid
some-user-uuid
account1.1password.ca
account1
my@email.com
my
my@account1.1password.ca
my@account1
If there are multiple accounts and any value exists more than once, that value will be removed from the account mapping. That is, if you are signed into my@email.com and your@email.com for account1.1password.ca, then account1.1password.ca will not be a valid lookup value, but my@account1, my@account1.1password.ca, your@account1, and your@account1.1password.ca would all be valid lookups.
Warning
chezmoi has experimental support for 1Password secrets automation modes. These modes change how the 1Password CLI works and affect all functions. Most notably, account parameters are not allowed on all 1Password template functions.
onepassword returns structured data from 1Password using the 1Password CLI (op). uuid is passed to op item get $UUID --format json and the output from op is parsed as JSON. The output from op is cached so calling onepassword multiple times with the same uuid will only invoke op once. If the optional vault is supplied, it will be passed along to the op item get call, which can significantly improve performance. If the optional account is supplied, it will be passed along to the op item get call, which will help it look in the right account, in case you have multiple accounts (e.g., personal and work accounts).
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
The 1password CLI command can be set with the onePassword.command config variable, and extra arguments can be specified with the onePassword.args config variable.
onepasswordDetailsFields returns structured data from 1Password using the 1Password CLI (op). uuid is passed to op get item $UUID, the output from op is parsed as JSON, and elements of details.fields are returned as a map indexed by each field's id (if set) or label (if set and id is not present).
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
The output from op is cached so calling onepasswordDetailsFields multiple times with the same uuid will only invoke op once. If the optional vault is supplied, it will be passed along to the op get call, which can significantly improve performance. If the optional account is supplied, it will be passed along to the op get call, which will help it look in the right account, in case you have multiple accounts (e.g. personal and work accounts).
onepasswordDocument returns a document from 1Password using the 1Password CLI (op). uuid is passed to op get document $UUID and the output from op is returned. The output from op is cached so calling onepasswordDocument multiple times with the same uuid will only invoke op once. If the optional vault is supplied, it will be passed along to the op get call, which can significantly improve performance. If the optional account is supplied, it will be passed along to the op get call, which will help it look in the right account, in case you have multiple accounts (e.g., personal and work accounts).
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
onepasswordItemFields returns structured data from 1Password using the 1Password CLI (op). uuid is passed to op item get $UUID --format json, the output from op is parsed as JSON, and each element of details.sections are iterated over and any fields are returned as a map indexed by each field's n.
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
onepasswordRead returns data from 1Password using the 1Password CLI (op). url is passed to the op read --no-newline command. If account is specified, the extra arguments --account $ACCOUNT are passed to op.
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
Example
The result of
{{ onepasswordRead \"op://vault/item/field\" }}\n
is equivalent to calling
$ op read --no-newline op://vault/item/field\n
Warning
When using 1Password secrets automation, the account parameter is not allowed.
1Password SDK template functions are experimental and may change.
The onepasswordSDK* template functions return structured data from 1Password using the 1Password SDK.
By default, the 1Password service account token is taken from the $OP_SERVICE_ACCOUNT_TOKEN environment variable. The name of the environment variable can be set with onepasswordSDK.tokenEnvVar configuration variable, or the token can be set explicitly by setting the onepasswordSDK.token configuration variable.
onepasswordSDKItemsGet is an experimental function and may change.
onepasswordSDKItemsGet returns an item from 1Password using the 1Password SDK.
The output of onepasswordSDKItemsGet is cached so multiple calls to onepasswordSDKItemsGet with the same vault-id and item-id will return the same value.
The awsSecretsManager* functions return data from AWS Secrets Manager using the GetSecretValue API.
The profile and region are pulled from the standard environment variables and shared config files but can be overridden by setting awsSecretsManager.profile and awsSecretsManager.region configuration variables respectively.
awsSecretsManager returns structured data retrieved from AWS Secrets Manager. arn specifies the SecretId passed to GetSecretValue. This can either be the full ARN or the simpler name if applicable.
awsSecretsManager returns the raw string value retrieved from AWS Secrets Manager. arn specifies the SecretId passed to GetSecretValue. This can either be the full ARN or the simpler name if applicable.
"},{"location":"reference/templates/azure-key-vault-functions/azureKeyVault/","title":"azureKeyVault secret name [vault-name]","text":"
azureKeyVault returns a secret value retrieved from an Azure Key Vault.
The mandatory secret name argument specifies the name of the secret to retrieve.
The optional vault name argument specifies the name of the vault, if not set, the default vault name will be used.
Warning
The current implementation will always return the latest version of the secret. Retrieving a specific version of a secret is not supported.
bitwarden returns structured data retrieved from Bitwarden using the Bitwarden CLI (bw). args are passed to bw get unchanged and the output from bw get is parsed as JSON.
The output from bw get is cached so calling bitwarden multiple times with the same arguments will only invoke bw once.
bitwardenAttachment returns a document from Bitwarden using the Bitwarden CLI (bw). filename and itemid are passed to bw get attachment $FILENAME --itemid $ITEMID and the output is returned.
The output from bw is cached so calling bitwardenAttachment multiple times with the same filename and itemid will only invoke bw once.
bitwardenFields returns structured data retrieved from Bitwarden using the Bitwarden CLI (bw). args are passed to bw get unchanged, the output from bw get is parsed as JSON, and the elements of fields are returned as a dict indexed by each field's name.
The output from bw get is cached so calling bitwardenFields multiple times with the same arguments will only invoke bw get once.
bitwardenSecrets returns structured data from Bitwarden using the Bitwarden Secrets CLI (bws). secret-id is passed to bws secret get and the output from bws secret get is parsed as JSON and returned.
If the additional access-token argument is given, it is passed to bws secret get with the --access-token flag.
The output from bws secret get is cached so calling bitwardenSecrets multiple times with the same secret-id and access-token will only invoke bws secret get once.
"},{"location":"reference/templates/bitwarden-functions/rbw/","title":"rbw name [arg...]","text":"
rbw returns structured data retrieved from Bitwarden using rbw. name is passed to rbw get --raw, along with any extra args, and the output is parsed as JSON.
The output from rbw get --raw is cached so calling rbw multiple times with the same arguments will only invoke rbw once.
"},{"location":"reference/templates/bitwarden-functions/rbwFields/","title":"rbwFields name [arg...]","text":"
rbw returns structured data retrieved from Bitwarden using rbw. name is passed to rbw get --raw, along with any extra args, the output is parsed as JSON, and the elements of fields are returned as a dict indexed by each field's name.
The output from rbw get --raw is cached so calling rbwFields multiple times with the same arguments will only invoke rbwFields once.
dashlaneNote returns the content of a secure note from Dashlane using the Dashlane CLI (dcli). filter is passed to dcli note, and the output from dcli note is just read as a multiline string.
The output from dcli note is cached so calling dashlaneNote multiple times with the same filter will only invoke dcli note once.
dashlanePassword returns structured data from Dashlane using the Dashlane CLI (dcli). filter is passed to dcli password --output json, and the output from dcli password is parsed as JSON.
The output from dcli password cached so calling dashlanePassword multiple times with the same filter will only invoke dcli password once.
doppler returns the secret for the specified project and configuration from Doppler using doppler secrets download --json --no-file.
If either of project or config are empty or omitted, then chezmoi will use the value from the doppler.project and doppler.config config variables if they are set and not empty.
dopplerProjectJson returns the secret for the specified project and configuration from Doppler using doppler secrets download --json --no-file as json structured data.
If either of project or config are empty or omitted, then chezmoi will use the value from the doppler.project and doppler.config config variables if they are set and not empty.
ejsonDecrypt returns the decrypted content of an ejson-encrypted file.
filePath indicates where the encrypted file is located.
The decrypted file is cached so calling ejsonDecrypt multiple times with the same filePath will only run through the decryption process once. The cache is shared with ejsonDecryptWithKey.
ejsonDecryptWithKey returns the decrypted content of an ejson-encrypted file.
filePath indicates where the encrypted file is located, and key is used to decrypt the file.
The decrypted file is cached so calling ejsonDecryptWithKey multiple times with the same filePath will only run through the decryption process once. The cache is shared with ejsonDecrypt.
deleteValueAtPath modifies dict to delete the value at path and returns dict. path can be either a string containing a .-separated list of keys or a list of keys.
If path does not exist in dict then deleteValueAtPath returns dict unchanged.
eqFold returns the boolean truth of comparing string1 with string2 and any number of extraStrings under Unicode case-folding.
Example
{{ $commandOutput := output \"path/to/output-FOO.sh\" }}\n{{ if eqFold \"foo\" $commandOutput }}\n# $commandOutput is \"foo\"/\"Foo\"/\"FOO\"...\n{{ else if eqFold \"bar\" $commandOutput }}\n# $commandOutput is \"bar\"/\"Bar\"/\"BAR\"...\n{{ end }}\n
findExecutable searches for an executable named file in directories identified by path-list. The result will be the executable file concatenated with the matching path. If an executable file cannot be found in path-list, findExecutable returns an empty string.
findExecutable is provided as an alternative to lookPath so that you can interrogate the system PATH as it would be configured after chezmoi apply. Like lookPath, findExecutable is not hermetic: its return value depends on the state of the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
The return value of the first successful call to findExecutable is cached, and future calls to findExecutable with the same parameters will return this path.
Info
On Windows, the resulting path will contain the first found executable extension as identified by the environment variable %PathExt%.
Example
{{ if findExecutable \"rtx\" (list \"bin\" \"go/bin\" \".cargo/bin\" \".local/bin\") }}\n# $HOME/.cargo/bin/rtx exists and will probably be in $PATH after apply\n{{ end }}\n
findOneExecutable searches for an executable from file-list in directories identified by path-list, finding the first matching executable in the first matching directory (each directory is searched for matching executables in turn). The result will be the executable file concatenated with the matching path. If an executable from file-list cannot be found in path-list, findOneExecutable returns an empty string.
findOneExecutable is provided as an alternative to lookPath so that you can interrogate the system PATH as it would be configured after chezmoi apply. Like lookPath, findOneExecutable is not hermetic: its return value depends on the state of the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
The return value of the first successful call to findOneExecutable is cached, and future calls to findOneExecutable with the same parameters will return this path.
Info
On Windows, the resulting path will contain the first found executable extension as identified by the environment variable %PathExt%.
Example
{{ if findOneExecutable (list \"eza\" \"exa\") (list \"bin\" \"go/bin\" \".cargo/bin\" \".local/bin\") }}\n# $HOME/.cargo/bin/exa exists and will probably be in $PATH after apply\n{{ end }}\n
fromJson parses jsontext as JSON and returns the parsed value.
JSON numbers that can be represented exactly as 64-bit signed integers are returned as such. Otherwise, if the number is in the range of 64-bit IEEE floating point values, it is returned as such. Otherwise, the number is returned as a string. See RFC7159 Section 6.
includeTemplate returns the result of executing the contents of filename with the optional data. Relative paths are first searched for in .chezmoitemplates and, if not found, are interpreted relative to the source directory.
joinPath joins any number of path elements into a single path, separating them with the OS-specific path separator. Empty elements are ignored. The result is cleaned. If the argument list is empty or all its elements are empty, joinPath returns an empty string. On Windows, the result will only be a UNC path if the first non-empty element is a UNC path.
lookPath searches for an executable named file in the directories named by the PATH environment variable. If file contains a slash, it is tried directly and the PATH is not consulted. The result may be an absolute path or a path relative to the current directory. If file is not found, lookPath returns an empty string.
lookPath is not hermetic: its return value depends on the state of the environment and the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
The return value of the first successful call to lookPath is cached, and future calls to lookPath for the same file will return this path.
Example
{{ if lookPath \"diff-so-fancy\" }}\n# diff-so-fancy is in $PATH\n{{ end }}\n
lstat runs os.Lstat on name. If name exists it returns structured data. If name does not exist then it returns a false value. If os.Lstat returns any other error then it raises an error. The structured value returned if name exists contains the fields name, size, mode, perm, modTime, isDir, and type.
lstat is not hermetic: its return value depends on the state of the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
Example
{{ if eq (joinPath .chezmoi.homeDir \".xinitrc\" | lstat).type \"symlink\" }}\n# ~/.xinitrc exists and is a symlink\n{{ end }}\n
mozillaInstallHash returns the Mozilla install hash for path. This is a convenience function to assist the management of Firefox profiles.
"},{"location":"reference/templates/functions/output/","title":"output name [arg...]","text":"
output returns the output of executing the command name with args. If executing the command returns an error then template execution exits with an error. The execution occurs every time that the template is executed. It is the user's responsibility to ensure that executing the command is both idempotent and fast.
Example
current-context: {{ output \"kubectl\" \"config\" \"current-context\" | trim }}\n
pruneEmptyDicts modifies dict to remove nested empty dicts. Properties are pruned from the bottom up, so any nested dicts that themselves only contain empty dicts are pruned.
replaceAllRegex returns text with all substrings matching the regular expression expr replaced with repl. It is an alternative to sprig's regexpReplaceAll function with a different argument order that supports pipelining.
"},{"location":"reference/templates/functions/setValueAtPath/","title":"setValueAtPath path value dict","text":"
setValueAtPath modifies dict to set the value at path to value and returns dict. path can be either a string containing a .-separated list of keys or a list of keys. The function will create new key/value pairs in dict if needed.
This is an alternative to sprig's set function with a different argument order that supports pipelining.
stat runs os.Stat on name. If name exists it returns structured data. If name does not exist then it returns a false value. If os.Stat returns any other error then it raises an error. The structured value returned if name exists contains the fields name, size, mode, perm, modTime, isDir, and type.
stat is not hermetic: its return value depends on the state of the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
Example
{{ if stat (joinPath .chezmoi.homeDir \".pyenv\") }}\n# ~/.pyenv exists\n{{ end }}\n
toPrettyJson returns the JSON representation of value. The optional indent specifies how much nested elements are indented relative to their parent. indent defaults to two spaces.
The gitHub* template functions return data from the GitHub API.
By default, chezmoi makes anonymous GitHub API requests, which are subject to GitHub's rate limits (currently 60 requests per hour per source IP address). chezmoi caches results from identical GitHub API requests for the period defined in gitHub.refreshPeriod (default one minute).
If any of the environment variables $CHEZMOI_GITHUB_ACCESS_TOKEN, $GITHUB_ACCESS_TOKEN, or $GITHUB_TOKEN are found, then the first one found will be used to authenticate the GitHub API requests which have a higher rate limit (currently 5,000 requests per hour per user).
In practice, GitHub API rate limits are high enough chezmoi's caching of results mean that you should rarely need to set a token, unless you are sharing a source IP address with many other GitHub users. If needed, the GitHub documentation describes how to create a personal access token.
gitHubKeys returns user's public SSH keys from GitHub using the GitHub API. The returned value is a slice of structs with .ID and .Key fields.
Warning
If you use this function to populate your ~/.ssh/authorized_keys file then you potentially open SSH access to anyone who is able to modify or add to your GitHub public SSH keys, possibly including certain GitHub employees. You should not use this function on publicly-accessible machines and should always verify that no unwanted keys have been added, for example by using the -v / --verbose option when running chezmoi apply or chezmoi update.
Additionally, GitHub automatically removes keys which haven't been used in the last year. This may cause your keys to be removed from ~/.ssh/authorized_keys suddenly, and without any warning or indication of the removal. You should provide one or more keys in plain text alongside this function to avoid unknowingly losing remote access to your machine.
Example
{{ range gitHubKeys \"user\" }}\n{{- .Key }}\n{{ end }}\n
gitHubLatestRelease calls the GitHub API to retrieve the latest release about the given owner-repo, returning structured data as defined by the GitHub Go API bindings.
Calls to gitHubLatestRelease are cached so calling gitHubLatestRelease with the same owner-repo will only result in one call to the GitHub API.
gitHubLatestReleaseAssetURL calls the GitHub API to retrieve the latest release about the given owner-repo, returning structured data as defined by the GitHub Go API bindings. It then iterates through all the release's assets, returning the first one that matches pattern. pattern is a shell pattern as described in path.Match.
Calls to gitHubLatestReleaseAssetURL are cached so calling gitHubLatestReleaseAssetURL with the same owner-repo will only result in one call to the GitHub API.
gitHubLatestTag calls the GitHub API to retrieve the latest tag for the given owner-repo, returning structured data as defined by the GitHub Go API bindings.
Calls to gitHubLatestTag are cached the same as githubTags, so calling gitHubLatestTag with the same owner-repo will only result in one call to the GitHub API.
Example
{{ (gitHubLatestTag \"docker/compose\").Name }}\n
Warning
The gitHubLatestTag returns the first tag returned by the list repository tags GitHub API endpoint. Although this seems to be the most recent tag, the GitHub API documentation does not specify the order of the returned tags.
gitHubRelease calls the GitHub API to retrieve the latest releases about the given owner-repo, It iterates through all the versions of the release, fetching the first entry equal to version.
It then returns structured data as defined by the GitHub Go API bindings.
Calls to gitHubRelease are cached so calling gitHubRelease with the same owner-repo version will only result in one call to the GitHub API.
"},{"location":"reference/templates/github-functions/gitHubReleaseAssetURL/","title":"gitHubReleaseAssetURL owner-repo version pattern","text":"
gitHubReleaseAssetURL calls the GitHub API to retrieve the latest releases about the given owner-repo, returning structured data as defined by the GitHub Go API bindings. It iterates through all the versions of the release, returning the first entry equal to version. It then iterates through all the release's assets, returning the first one that matches pattern. pattern is a shell pattern as described in path.Match.
Calls to gitHubReleaseAssetURL are cached so calling gitHubReleaseAssetURL with the same owner-repo will only result in one call to the GitHub API.
gitHubReleases calls the GitHub API to retrieve the first page of releases for the given owner-repo, returning structured data as defined by the GitHub Go API bindings.
Calls to gitHubReleases are cached so calling gitHubReleases with the same owner-repo will only result in one call to the GitHub API.
gitHubTags calls the GitHub API to retrieve the first page of tags for the given owner-repo, returning structured data as defined by the GitHub Go API bindings.
Calls to gitHubTags are cached so calling gitHubTags with the same owner-repo will only result in one call to the GitHub API.
The gopass* template functions return data stored in gopass using the gopass CLI (gopass) or builtin code.
By default, chezmoi will use the gopass CLI (gopass). Depending on your gopass configuration, you may have to enter your passphrase once for each secret.
When setting gopass.mode to builtin, chezmoi use builtin code to access the goapass database and caches your passphrase in plaintext in memory until chezmoi terminates.
Warning
Using the builtin code is experimental and may be removed.
gopass returns passwords stored in gopass using the gopass CLI (gopass). gopass-name is passed to gopass show --password $GOPASS_NAME and the first line of the output of gopass is returned with the trailing newline stripped. The output from gopass is cached so calling gopass multiple times with the same gopass-name will only invoke gopass once.
gopass returns raw passwords stored in gopass using the gopass CLI (gopass). gopass-name is passed to gopass show --noparsing $GOPASS_NAME and the output is returned. The output from gopassRaw is cached so calling gopassRaw multiple times with the same gopass-name will only invoke gopass once.
hcpVaultSecret returns the plaintext secret from HCP Vault Secrets using vlt secrets get --plaintext.
If any of application-name, project-id, or organization-id are empty or omitted, then chezmoi will use the value from the hcpVaultSecret.applicationName, hcpVaultSecret.projectId, and hcpVaultSecret.organizationId config variables if they are set and not empty.
hcpVaultSecretJson returns structured data from HCP Vault Secrets using vlt secrets get --format=json.
If any of application-name, project-id, or organization-id are empty or omitted, then chezmoi will use the value from the hcpVaultSecret.applicationName, hcpVaultSecret.projectId, and hcpVaultSecret.organizationId config variables if they are set and not empty.
These template functions are only available when generating a config file with chezmoi init. For testing with chezmoi execute-template, pass the --init flag to enable them.
promptBool prompts the user with prompt and returns the user's response interpreted as a boolean. If default is passed and the user's response is empty then it returns default. The user's response is interpreted as follows (case insensitive):
Response Result 1, on, t, true, y, yes true 0, off, f, false, n, no false"},{"location":"reference/templates/init-functions/promptBoolOnce/","title":"promptBoolOnce map path prompt [default]","text":"
promptBoolOnce returns the value of map at path if it exists and is a boolean value, otherwise it prompts the user for a boolean value with prompt and an optional default using promptBool.
Example
{{ $hasGUI := promptBoolOnce . \"hasGUI\" \"Does this machine have a GUI\" }}\n
promptChoice prompts the user with prompt and choices and returns the user's response. choices must be a list of strings. If default is passed and the user's response is empty then it returns default.
Example
{{- $choices := list \"desktop\" \"server\" -}}\n{{- $hosttype := promptChoice \"What type of host are you on\" $choices -}}\n[data]\n hosttype = {{- $hosttype | quote -}}\n
promptChoiceOnce returns the value of map at path if it exists and is a string, otherwise it prompts the user for one of choices with prompt and an optional default using promptChoice.
Example
{{- $choices := list \"desktop\" \"laptop\" \"server\" \"termux\" -}}\n{{- $hosttype := promptChoiceOnce . \"hosttype\" \"What type of host are you on\" $choices -}}\n[data]\n hosttype = {{- $hosttype | quote -}}\n
promptInt prompts the user with prompt and returns the user's response interpreted as an integer. If default is passed and the user's response is empty then it returns default.
promptIntOnce returns the value of map at path if it exists and is an integer value, otherwise it prompts the user for a integer value with prompt and an optional default using promptInt.
Example
{{ $monitors := promptIntOnce . \"monitors\" \"How many monitors does this machine have\" }}\n
promptString prompts the user with prompt and returns the user's response with all leading and trailing spaces stripped. If default is passed and the user's response is empty then it returns default.
promptStringOnce returns the value of map at path if it exists and is a string value, otherwise it prompts the user for a string value with prompt and an optional default using promptString.
Example
{{ $email := promptStringOnce . \"email\" \"What is your email address\" }}\n
stdinIsATTY returns true if chezmoi's standard input is a TTY. It is primarily useful for determining whether prompt* functions should be called or default values be used.
The keepassxc* template functions return structured data retrieved from a KeePassXC database using the KeePassXC CLI (keepassxc-cli)
The database is configured by setting keepassxc.database in the configuration file. You will be prompted for the database password the first time keepassxc-cli is run, and the password is cached, in plain text, in memory until chezmoi terminates.
The command used can be changed by setting the keepassxc.command configuration variable, and extra arguments can be added by setting keepassxc.args. The password prompt can be disabled by setting keepassxc.prompt to false.
By default, chezmoi will prompt for the KeePassXC password when required and cache it for the duration of chezmoi's execution. Setting keepassxc.mode to open will tell chezmoi to instead open KeePassXC's console with keepassxc-cli open followed by keepassxc.args. chezmoi will use this console to request values from KeePassXC.
When setting keepassxc.mode to builtin, chezmoi uses a builtin library to access a keepassxc database, which can be handy if keepassxc-cli is not available. Some KeePassXC features (such as Yubikey-enhanced encryption) may not be available with builtin support.
keepassxc returns structured data for entry using keepassxc-cli.
The output from keepassxc-cli is parsed into key-value pairs and cached so calling keepassxc multiple times with the same entry will only invoke keepassxc-cli once.
keeper returns structured data retrieved from Keeper using the Commander CLI. uid is passed to keeper get --format=json and the output is parsed as JSON.
On FreeBSD, the keyring template function is only available if chezmoi was compiled with cgo enabled. The official release binaries of chezmoi are not compiled with cgo enabled, and keyring will always return an empty string.
lastpass returns structured data from LastPass using the LastPass CLI (lpass). id is passed to lpass show --json $ID and the output from lpass is parsed as JSON. In addition, the note field, if present, is further parsed as colon-separated key-value pairs. The structured data is an array so typically the index function is used to extract the first item. The output from lastpass is cached so calling lastpass multiple times with the same id will only invoke lpass once.
lastpassRaw returns structured data from LastPass using the LastPass CLI (lpass). It behaves identically to the lastpass function, except that no further parsing is done on the note field.
The pass template functions return passwords stored in pass using the pass CLI (pass).
Hint
To use a pass-compatible password manager like passage, set pass.command to the name of the binary and use chezmoi's pass* template functions as if you were using pass.
pass returns passwords stored in pass using the pass CLI (pass). pass-name is passed to pass show $PASS_NAME and the first line of the output of pass is returned with the trailing newline stripped. The output from pass is cached so calling pass multiple times with the same pass-name will only invoke pass once.
passFields returns structured data stored in pass using the pass CLI (pass). pass-name is passed to pass show $PASS_NAME and the output is parsed as colon-separated key-value pairs, one per line. The return value is a map of keys to values.
passRaw returns passwords stored in pass using the pass CLI (pass). pass-name is passed to pass show $PASS_NAME and the output is returned. The output from pass is cached so calling passRaw multiple times with the same pass-name will only invoke pass once.
secret returns the output of the generic secret command defined by the secret.command configuration variable with secret.args and args with leading and trailing whitespace removed. The output is cached so multiple calls to secret with the same args will only invoke the generic secret command once.
secretJSON returns structured data from the generic secret command defined by the secret.command configuration variable with secret.args and args. The output is parsed as JSON. The output is cached so multiple calls to secret with the same args will only invoke the generic secret command once.
vault returns structured data from Vault using the Vault CLI (vault). key is passed to vault kv get -format=json $KEY and the output from vault is parsed as JSON. The output from vault is cached so calling vault multiple times with the same key will only invoke vault once.
chezmoi add $FILE adds $FILEfrom your home directory to the source directory.
chezmoi edit $FILE opens your editor with the file in the source directory that corresponds to $FILE.
chezmoi status gives a quick summary of what files would change if you ran chezmoi apply.
chezmoi diff shows the changes that chezmoi apply would make to your home directory.
chezmoi apply updates your dotfiles from the source directory.
chezmoi edit --apply $FILE is like chezmoi edit $FILE but also runs chezmoi apply $FILE afterwards.
chezmoi cd opens a subshell in the source directory.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo H->>W: chezmoi add <file> W->>W: chezmoi edit <file> W-->>H: chezmoi status W-->>H: chezmoi diff W->>H: chezmoi apply W->>H: chezmoi edit --apply <file> H-->>W: chezmoi cd"},{"location":"user-guide/command-overview/#using-chezmoi-across-multiple-machines","title":"Using chezmoi across multiple machines","text":"
chezmoi init $GITHUB_USERNAME clones your dotfiles from GitHub into the source directory.
chezmoi init --apply $GITHUB_USERNAME clones your dotfiles from GitHub into the source directory and runs chezmoi apply.
chezmoi update pulls the latest changes from your remote repo and runs chezmoi apply.
Use normal git commands to add, commit, and push changes to your remote repo.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi init <github-username> R->>H: chezmoi init --apply <github-username> R->>H: chezmoi update <github-username> W->>L: git commit L->>R: git push"},{"location":"user-guide/command-overview/#working-with-templates","title":"Working with templates","text":"
chezmoi data prints the available template data.
chezmoi add --template $FILE adds $FILE as a template.
chezmoi chattr +template $FILE makes an existing file a template.
chezmoi cat $FILE prints the target contents of $FILE, without changing $FILE.
chezmoi execute-template is useful for testing and debugging templates.
"},{"location":"user-guide/daily-operations/","title":"Daily operations","text":""},{"location":"user-guide/daily-operations/#edit-your-dotfiles","title":"Edit your dotfiles","text":"
Edit a dotfile with:
chezmoi edit $FILENAME\n
This will edit $FILENAME's source file in your source directory. chezmoi will not make any changes to the actual dotfile until you run chezmoi apply.
To automatically run chezmoi apply when you quit your editor, run:
chezmoi edit --apply $FILENAME\n
To automatically run chezmoi apply whenever you save the file in your editor, run:
chezmoi edit --watch $FILENAME\n
You don't have to use chezmoi edit to edit your dotfiles. For more information, see Do I have to use chezmoi edit to edit my dotfiles?
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo W->>W: chezmoi edit W->>H: chezmoi apply W->>H: chezmoi edit --apply W->>H: chezmoi edit --watch"},{"location":"user-guide/daily-operations/#pull-the-latest-changes-from-your-repo-and-apply-them","title":"Pull the latest changes from your repo and apply them","text":"
You can pull the changes from your repo and apply them in a single command:
chezmoi update\n
This runs git pull --autostash --rebase in your source directory and then chezmoi apply.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>H: chezmoi update"},{"location":"user-guide/daily-operations/#pull-the-latest-changes-from-your-repo-and-see-what-would-change-without-actually-applying-the-changes","title":"Pull the latest changes from your repo and see what would change, without actually applying the changes","text":"
This runs git pull --autostash --rebase in your source directory and chezmoi diff then shows the difference between the target state computed from your source directory and the actual state.
If you're happy with the changes, then you can run
chezmoi apply\n
to apply them.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi git pull W-->>H: chezmoi diff W->>H: chezmoi apply"},{"location":"user-guide/daily-operations/#automatically-commit-and-push-changes-to-your-repo","title":"Automatically commit and push changes to your repo","text":"
chezmoi can automatically commit and push changes to your source directory to your repo. This feature is disabled by default. To enable it, add the following to your config file:
~/.config/chezmoi/chezmoi.toml
[git]\n autoCommit = true\n autoPush = true\n
Whenever a change is made to your source directory, chezmoi will commit the changes with an automatically-generated commit message (if autoCommit is true) and push them to your repo (if autoPush is true). autoPush implies autoCommit, i.e. if autoPush is true then chezmoi will auto-commit your changes. If you only set autoCommit to true then changes will be committed but not pushed.
By default, autoCommit will generate a commit message based on the files changed. You can override this by setting the git.commitMessageTemplate configuration variable. For example, to have chezmoi prompt you for a commit message each time, use:
If your commit message is longer than fits in a string then you can set git.commitMessageTemplateFile to specify a path to the commit message template relative to the source directory, for example:
Be careful when using autoPush. If your dotfiles repo is public and you accidentally add a secret in plain text, that secret will be pushed to your public repo.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo W->>L: autoCommit W->>R: autoPush"},{"location":"user-guide/daily-operations/#install-chezmoi-and-your-dotfiles-on-a-new-machine-with-a-single-command","title":"Install chezmoi and your dotfiles on a new machine with a single command","text":"
chezmoi's install script can run chezmoi init for you by passing extra arguments to the newly installed chezmoi binary. If your dotfiles repo is github.com/$GITHUB_USERNAME/dotfiles then installing chezmoi, running chezmoi init, and running chezmoi apply can be done in a single line of shell:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --apply $GITHUB_USERNAME\n
If your dotfiles repo has a different name to dotfiles, or if you host your dotfiles on a different service, then see the reference manual for chezmoi init.
For setting up transitory environments (e.g. short-lived Linux containers) you can install chezmoi, install your dotfiles, and then remove all traces of chezmoi, including the source directory and chezmoi's configuration directory, with a single command:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --one-shot $GITHUB_USERNAME\n
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi init $GITHUB_USERNAME R->>H: chezmoi init --apply $GITHUB_USERNAME R->>H: chezmoi init --one-shot $GITHUB_USERNAME"},{"location":"user-guide/include-files-from-elsewhere/","title":"Include dotfiles from elsewhere","text":"
The sections below contain examples of how to use .chezmoiexternal.toml to include files from external sources. For more details, check the reference manual .
"},{"location":"user-guide/include-files-from-elsewhere/#include-a-subdirectory-from-a-url","title":"Include a subdirectory from a URL","text":"
To include a subdirectory from another repository, e.g. Oh My Zsh, you cannot use git submodules because chezmoi uses its own format for the source state and Oh My Zsh is not distributed in this format. Instead, you can use the .chezmoiexternal.$FORMAT to tell chezmoi to import dotfiles from an external source.
For example, to import Oh My Zsh, the zsh-syntax-highlighting plugin, and powerlevel10k, put the following in ~/.local/share/chezmoi/.chezmoiexternal.toml:
chezmoi will download the archives and unpack them as if they were part of the source state. chezmoi caches downloaded archives locally to avoid re-downloading them every time you run a chezmoi command, and will only re-download them at most every refreshPeriod (default never).
In the above example refreshPeriod is set to 168h (one week) for .oh-my-zsh and .oh-my-zsh/custom/plugins/zsh-syntax-highlighting because the URL point to tarballs of the master branch, which changes over time. No refresh period is set for .oh-my-zsh/custom/themes/powerlevel10k because the URL points to the a tarball of a tagged version, which does not change over time. To bump the version of powerlevel10k, change the version in the URL.
To force a refresh the downloaded archives, use the --refresh-externals flag to chezmoi apply:
chezmoi --refresh-externals apply\n
--refresh-externals can be shortened to -R:
chezmoi -R apply\n
When using Oh My Zsh, make sure you disable auto-updates by setting DISABLE_AUTO_UPDATE=\"true\" in ~/.zshrc. Auto updates will cause the ~/.oh-my-zsh directory to drift out of sync with chezmoi's source state. To update Oh My Zsh and its plugins, refresh the downloaded archives.
Note
If your external dependency target directory can contain cache files that are added during normal use, chezmoi will report that files have changed on chezmoi apply. To avoid this, add the cache directory to your .chezmoiignore file.
For example, Oh My Zsh may cache completions in .oh-my-zsh/cache/completions/, which should be added to your .chezmoiignore file.
Warning
Do not use externals for large files or archives. chezmoi validates the exact contents of externals every time you run chezmoi diff, chezmoi apply, or chezmoi verify. For large externals, use a run_once_ or run_onchange_ script to unpack the archive or file once instead.
"},{"location":"user-guide/include-files-from-elsewhere/#include-a-subdirectory-with-selected-files-from-a-url","title":"Include a subdirectory with selected files from a URL","text":"
Use include pattern filters to include only selected files from an archive URL.
For example, to import just the required source files of the zsh-syntax-highlighting plugin in the example above, add in include filter to the zsh-syntax-highlighting section as shown below:
"},{"location":"user-guide/include-files-from-elsewhere/#include-a-single-file-from-a-url","title":"Include a single file from a URL","text":"
Including single files uses the same mechanism as including a subdirectory above, except with the external type file instead of archive. For example, to include plug.vim from github.com/junegunn/vim-plug in ~/.vim/autoload/plug.vim put the following in ~/.local/share/chezmoi/.chezmoiexternal.toml:
~/.local/share/chezmoi/.chezmoiexternal.toml
[\".vim/autoload/plug.vim\"]\n type = \"file\"\n url = \"https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim\"\n refreshPeriod = \"168h\"\n
"},{"location":"user-guide/include-files-from-elsewhere/#extract-a-single-file-from-an-archive","title":"Extract a single file from an archive","text":"
You can extract a single file from an archive using the archive-file type in .chezmoiexternal.$FORMAT, for example:
This will extract the single archive member age/age from the given URL (which is computed for the current OS and architecture) to the target ./local/bin/age.
It is occasionally useful to import entire archives of configuration into your source state. The import command does this. For example, to import the latest version github.com/ohmyzsh/ohmyzsh to ~/.oh-my-zsh run:
This only updates the source state. You will need to run:
chezmoi apply\n
to update your destination directory.
"},{"location":"user-guide/include-files-from-elsewhere/#handle-tar-archives-in-an-unsupported-compression-format","title":"Handle tar archives in an unsupported compression format","text":"
chezmoi natively understands tar archives. tar archives can be uncompressed or compressed in the bzip2, gzip, xz, or zstd formats.
If you have a tar archive in an unsupported compression format then you can use a filter to decompress it. For example, before chezmoi natively supported the zstd compression format, you could handle .tar.zst external archives with, for example:
~/.local/share/chezmoi/.chezmoiexternal.toml
[\".Software/anki/2.1.54-qt6\"]\n type = \"archive\"\n url = \"https://github.com/ankitects/anki/releases/download/2.1.54/anki-2.1.54-linux-qt6.tar.zst\"\n filter.command = \"zstd\"\n filter.args = [\"-d\"]\n format = \"tar\"\n
Here filter.command and filter.args together tell chezmoi to filter the downloaded data through zstd -d. The format = \"tar\" line tells chezmoi that output of the filter is an uncompressed tar archive.
"},{"location":"user-guide/include-files-from-elsewhere/#include-a-subdirectory-from-a-git-repository","title":"Include a subdirectory from a git repository","text":"
You can configure chezmoi to keep a git repository up to date in a subdirectory by using the external type git-repo, for example:
~/.local/share/chezmoi/.chezmoiexternal.toml
[\".vim/pack/alker0/chezmoi.vim\"]\n type = \"git-repo\"\n url = \"https://github.com/alker0/chezmoi.vim.git\"\n refreshPeriod = \"168h\"\n
If the directory does not exist then chezmoi will run git clone to clone it. If the directory does exist then chezmoi will run git pull to pull the latest changes, but not more often than every refreshPeriod. In the above example the refreshPeriod is 168h which is one week. The default refreshPeriod is zero, which disables refreshes. You can force a refresh (i.e. force a git pull) by passing the --refresh-externals/-R flag to chezmoi apply.
Warning
chezmoi's support for git-repo externals is limited to running git clone and/or git pull in a directory. You must have a git binary in your $PATH.
Using a git-repo external delegates management of the directory to git. chezmoi cannot manage any other files in that directory.
The contents of git-repo externals will not be manifested in commands like chezmoi diff or chezmoi dump, and will be listed by chezmoi unmanaged.
Hint
If you need to manage extra files in a git-repo external, use an archive external instead with the URL pointing to an archive of the git repo's master or main branch.
You can customize the arguments to git clone and git pull by setting the $DIR.clone.args and $DIR.pull.args variables in .chezmoiexternal.$FORMAT, for example:
"},{"location":"user-guide/include-files-from-elsewhere/#use-git-submodules-in-your-source-directory","title":"Use git submodules in your source directory","text":"
Important
If you use git submodules, then you should set the external_ attribute on the subdirectory containing the submodule.
You can include git repos from elsewhere as git submodules in your source directory. chezmoi init and chezmoi update are aware of git submodules and will run git with the --recurse-submodules flag by default.
chezmoi assumes that all files and directories in its source state are in chezmoi's format, i.e. their filenames include attributes like private_ and run_. Most git submodules are not in chezmoi's format and so files like run_test.sh will be interpreted by chezmoi as a run_ script. To avoid this problem, set the external_ attribute on all subdirectories that contain submodules.
You can stop chezmoi from handling git submodules by passing the --recurse-submodules=false flag or setting the update.recurseSubmodules configuration variable to false.
"},{"location":"user-guide/manage-different-types-of-file/","title":"Manage different types of file","text":""},{"location":"user-guide/manage-different-types-of-file/#have-chezmoi-create-a-directory-but-ignore-its-contents","title":"Have chezmoi create a directory, but ignore its contents","text":"
If you want chezmoi to create a directory, but ignore its contents, say ~/src, first run:
mkdir -p $(chezmoi source-path)/src\n
This creates the directory in the source state, which means that chezmoi will create it (if it does not already exist) when you run chezmoi apply.
However, as this is an empty directory it will be ignored by git. So, create a file in the directory in the source state that will be seen by git (so git does not ignore the directory) but ignored by chezmoi (so chezmoi does not include it in the target state):
touch $(chezmoi source-path)/src/.keep\n
chezmoi automatically creates .keep files when you add an empty directory with chezmoi add.
"},{"location":"user-guide/manage-different-types-of-file/#ensure-that-a-target-is-removed","title":"Ensure that a target is removed","text":"
Create a file called .chezmoiremove in the source directory containing a list of patterns of files to remove. chezmoi will remove anything in the target directory that matches the pattern. As this command is potentially dangerous, you should run chezmoi in verbose, dry-run mode beforehand to see what would be removed:
chezmoi apply --dry-run --verbose\n
.chezmoiremove is interpreted as a template, so you can remove different files on different machines. Negative matches (patterns prefixed with a !) or targets listed in .chezmoiignore will never be removed.
"},{"location":"user-guide/manage-different-types-of-file/#manage-part-but-not-all-of-a-file","title":"Manage part, but not all, of a file","text":"
chezmoi, by default, manages whole files, but there are two ways to manage just parts of a file.
Firstly, a modify_ script receives the current contents of the file on the standard input and chezmoi reads the target contents of the file from the script's standard output. This can be used to change parts of a file, for example using sed.
Hint
If you need random access to the file to modify it, then you can write standard input to a temporary file, modify the temporary file, and then write the temporary file to the standard output, for example:
If the file does not exist then the standard input to the modify_ script will be empty and it is the script's responsibility to write a complete file to the standard output.
modify_ scripts that contain the string chezmoi:modify-template are executed as templates with the current contents of the file passed as .chezmoi.stdin and the result of the template execution used as the new contents of the file.
Example
To replace the string old with new in a file while leaving the rest of the file unchanged, use the modify script:
Secondly, if only a small part of the file changes then consider using a template to re-generate the full contents of the file from the current state. For example, Kubernetes configurations include a current context that can be substituted with:
~/.local/share/chezmoi/dot_kube/config.tmpl
current-context: {{ output \"kubectl\" \"config\" \"current-context\" | trim }}\n
Hint
For managing ini files with a mix of settings and state (such as recently used files or window positions), there is a third party tool called chezmoi_modify_manager that builds upon modify_ scripts. See related software for more information.
"},{"location":"user-guide/manage-different-types-of-file/#manage-a-files-permissions-but-not-its-contents","title":"Manage a file's permissions, but not its contents","text":"
chezmoi's create_ attributes allows you to tell chezmoi to create a file if it does not already exist. chezmoi, however, will apply any permission changes from the executable_, private_, and readonly_ attributes. This can be used to control a file's permissions without altering its contents.
For example, if you want to ensure that ~/.kube/config always has permissions 600 then if you create an empty file called dot_kube/private_config in your source state, chezmoi will ensure ~/.kube/config's permissions are 0600 when you run chezmoi apply without changing its contents.
This approach does have the downside that chezmoi will create the file if it does not already exist. If you only want chezmoi apply to set a file's permissions if it already exists and not create the file otherwise, you can use a run_ script. For example, create a file in your source state called run_set_kube_config_permissions.sh containing:
"},{"location":"user-guide/manage-different-types-of-file/#handle-configuration-files-which-are-externally-modified","title":"Handle configuration files which are externally modified","text":"
Some programs modify their configuration files. When you next run chezmoi apply, any modifications made by the program will be lost.
You can track changes to these files by replacing with a symlink back to a file in your source directory, which is under version control. Here is a worked example for VSCode's settings.json on Linux:
Copy the configuration file to your source directory:
The prefix private_ is used because the ~/.config and ~/.config/Code directories are private by default.
Apply the changes:
chezmoi apply -v\n
Now, when the program modifies its configuration file it will modify the file in the source state instead.
"},{"location":"user-guide/manage-different-types-of-file/#populate-sshauthorized_keys-with-your-public-ssh-keys-from-github","title":"Populate ~/.ssh/authorized_keys with your public SSH keys from GitHub","text":"
chezmoi can retrieve your public SSH keys from GitHub, which can be useful for populating your ~/.ssh/authorized_keys. Put the following in your ~/.local/share/chezmoi/dot_ssh/authorized_keys.tmpl:
{{ range gitHubKeys \"$GITHUB_USERNAME\" -}}\n{{ .Key }}\n{{ end -}}\n
The primary goal of chezmoi is to manage configuration files across multiple machines, for example your personal macOS laptop, your work Ubuntu desktop, and your work Linux laptop. You will want to keep much configuration the same across these, but also need machine-specific configurations for email addresses, credentials, etc. chezmoi achieves this functionality by using text/template for the source state where needed.
For example, your home ~/.gitconfig on your personal machine might look like:
To handle this, on each machine create a configuration file called ~/.config/chezmoi/chezmoi.toml defining variables that might vary from machine to machine. For example, for your home machine:
~/.config/chezmoi/chezmoi.toml
[data]\n email = \"me@home.org\"\n
If you intend to store private data (e.g. access tokens) in ~/.config/chezmoi/chezmoi.toml, make sure it has permissions 0600.
If you prefer, you can use JSON, JSONC, or YAML for your configuration file. Variable names must start with a letter and be followed by zero or more letters or digits.
Then, add ~/.gitconfig to chezmoi using the --template flag to turn it into a template:
chezmoi add --template ~/.gitconfig\n
You can then open the template (which will be saved in the file ~/.local/share/chezmoi/dot_gitconfig.tmpl):
chezmoi edit ~/.gitconfig\n
Edit the file so it looks something like:
~/.local/share/chezmoi/dot_gitconfig.tmpl
[user]\n email = {{ .email | quote }}\n
Templates are often used to capture machine-specific differences. For example, in your ~/.local/share/chezmoi/dot_bashrc.tmpl you might have:
~/.local/share/chezmoi/dot_bashrc.tmpl
# common config\nexport EDITOR=vi\n\n# machine-specific configuration\n{{- if eq .chezmoi.hostname \"work-laptop\" }}\n# this will only be included in ~/.bashrc on work-laptop\n{{- end }}\n
For a full list of variables, run:
chezmoi data\n
For more advanced usage, you can use the full power of the text/template language. chezmoi includes all of the text functions from sprig and its own functions for interacting with password managers.
Templates can be executed directly from the command line, without the need to create a file on disk, with the execute-template command, for example:
This is useful when developing or debugging templates.
Some password managers allow you to store complete files. The files can be retrieved with chezmoi's template functions. For example, if you have a file stored in 1Password with the UUID uuid then you can retrieve it with the template:
{{- onepasswordDocument \"uuid\" -}}\n
The -s inside the brackets remove any whitespace before or after the template expression, which is useful if your editor has added any newlines.
If, after executing the template, the file contents are empty, the target file will be removed. This can be used to ensure that files are only present on certain machines. If you want an empty file to be created anyway, you will need to give it an empty_ prefix.
"},{"location":"user-guide/manage-machine-to-machine-differences/#ignore-files-or-a-directory-on-different-machines","title":"Ignore files or a directory on different machines","text":"
For coarser-grained control of files and entire directories managed on different machines, or to exclude certain files completely, you can create .chezmoiignore files in the source directory. These specify a list of patterns that chezmoi should ignore, and are interpreted as templates. An example .chezmoiignore file might look like:
~/.local/share/chezmoi/.chezmoiignore
README.md\n{{- if ne .chezmoi.hostname \"work-laptop\" }}\n.work # only manage .work on work-laptop\n{{- end }}\n
The use of ne (not equal) is deliberate. What we want to achieve is \"only install .work if hostname is work-laptop\" but chezmoi installs everything by default, so we have to turn the logic around and instead write \"ignore .work unless the hostname is work-laptop\".
Patterns can be excluded by starting the line with a !, for example:
~/.local/share/chezmoi/.chezmoiignore
dir/f*\n!dir/foo\n
will ignore all files beginning with an f in dir except for dir/foo.
You can see what files chezmoi ignores with the command
chezmoi ignored\n
"},{"location":"user-guide/manage-machine-to-machine-differences/#handle-different-file-locations-on-different-systems-with-the-same-contents","title":"Handle different file locations on different systems with the same contents","text":"
If you want to have the same file contents in different locations on different systems, but maintain only a single file in your source state, you can use a shared template.
Create the common file in the .chezmoitemplates directory in the source state. For example, create .chezmoitemplates/file.conf. The contents of this file are available in templates with the template $NAME . function where $NAME is the name of the file (. passes the current data to the template code in file.conf; see template action for details).
Then create files for each system, for example Library/Application Support/App/file.conf.tmpl for macOS and dot_config/app/file.conf.tmpl for Linux. Both template files should contain {{- template \"file.conf\" . -}}.
Finally, tell chezmoi to ignore files where they are not needed by adding lines to your .chezmoiignore file, for example:
~/.local/share/chezmoi/.chezmoiignore
{{ if ne .chezmoi.os \"darwin\" }}\nLibrary/Application Support/App/file.conf\n{{ end }}\n{{ if ne .chezmoi.os \"linux\" }}\n.config/app/file.conf\n{{ end }}\n
"},{"location":"user-guide/manage-machine-to-machine-differences/#use-completely-different-dotfiles-on-different-machines","title":"Use completely different dotfiles on different machines","text":"
chezmoi's template functionality allows you to change a file's contents based on any variable. For example, if you want ~/.bashrc to be different on Linux and macOS you would create a file in the source state called dot_bashrc.tmpl containing:
~/.local/share/chezmoi/dot_bashrc.tmpl
{{ if eq .chezmoi.os \"darwin\" -}}\n# macOS .bashrc contents\n{{ else if eq .chezmoi.os \"linux\" -}}\n# Linux .bashrc contents\n{{ end -}}\n
However, if the differences between the two versions are so large that you'd prefer to use completely separate files in the source state, you can achieve this with the include template function.
Create the following files:
~/.local/share/chezmoi/.bashrc_darwin
# macOS .bashrc contents\n
~/.local/share/chezmoi/.bashrc_linux
# Linux .bashrc contents\n
~/.local/share/chezmoi/dot_bashrc.tmpl
{{- if eq .chezmoi.os \"darwin\" -}}\n{{- include \".bashrc_darwin\" -}}\n{{- else if eq .chezmoi.os \"linux\" -}}\n{{- include \".bashrc_linux\" -}}\n{{- end -}}\n
This will cause ~/.bashrc to contain ~/.local/share/chezmoi/.bashrc_darwin on macOS and ~/.local/share/chezmoi/.bashrc_linux on Linux.
If you want to use templates within your templates, then, instead, create:
{{- if eq .chezmoi.os \"darwin\" -}}\n{{- template \"bashrc_darwin.tmpl\" . -}}\n{{- else if eq .chezmoi.os \"linux\" -}}\n{{- template \"bashrc_linux.tmpl\" . -}}\n{{- end -}}\n
"},{"location":"user-guide/setup/","title":"Setup","text":""},{"location":"user-guide/setup/#understand-chezmois-files-and-directories","title":"Understand chezmoi's files and directories","text":"
chezmoi generates your dotfiles for your local machine. It combines two main sources of data:
The source directory, ~/.local/share/chezmoi, is common to all your machines, and is a clone of your dotfiles repo. Each file that chezmoi manages has a corresponding file in the source directory.
The config file, typically ~/.config/chezmoi/chezmoi.toml (although you can use JSON or YAML if you prefer), is specific to the local machine.
Files whose contents are the same on all of your machines are copied verbatim from the source directory. Files which vary from machine to machine are executed as templates, typically using data from the local machine's config file to tune the final contents specific to the local machine.
"},{"location":"user-guide/setup/#use-a-hosted-repo-to-manage-your-dotfiles-across-multiple-machines","title":"Use a hosted repo to manage your dotfiles across multiple machines","text":"
chezmoi relies on your version control system and hosted repo to share changes across multiple machines. You should create a repo on the source code repository of your choice (e.g. Bitbucket, GitHub, or GitLab, many people call their repo dotfiles) and push the repo in the source directory here. For example:
These commands are summarized this sequence diagram:
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi init <repo> W-->>H: chezmoi diff W->>H: chezmoi apply R->>H: chezmoi init --apply <repo>"},{"location":"user-guide/setup/#use-a-private-repo-to-store-your-dotfiles","title":"Use a private repo to store your dotfiles","text":"
chezmoi supports storing your dotfiles in both public and private repos.
chezmoi is designed so that your dotfiles repo can be public by making it easy for you to store your secrets either in your password manager, in encrypted files, or in private configuration files. Your dotfiles repo can still be private, if you choose.
If you use a private repo for your dotfiles then you will typically need to enter your credentials (e.g. your username and password) each time you interact with the repo, for example when pulling or pushing changes. chezmoi itself does not store any credentials, but instead relies on your local git configuration for these operations.
When using a private repo on GitHub without --ssh, when prompted for a password you will need to enter a GitHub personal access token. For more information on these changes, read the GitHub blog post on Token authentication requirements for Git operations
"},{"location":"user-guide/setup/#create-a-config-file-on-a-new-machine-automatically","title":"Create a config file on a new machine automatically","text":"
chezmoi init can also create a config file automatically, if one does not already exist. If your repo contains a file called .chezmoi.$FORMAT.tmpl where $FORMAT is one of the supported config file formats (e.g. json, jsonc, toml, or yaml) then chezmoi init will execute that template to generate your initial config file.
Specifically, if you have .chezmoi.toml.tmpl that looks like this:
Then chezmoi init will create an initial chezmoi.toml using this template. promptStringOnce is a special function that prompts the user (you) for a value if it is not already set in your data.
To test this template, use chezmoi execute-template with the --init and --promptString flags, for example:
"},{"location":"user-guide/setup/#re-create-your-config-file","title":"Re-create your config file","text":"
If you change your config file template, chezmoi will warn you if your current config file was not generated from that template. You can re-generate your config file by running:
chezmoi init\n
If you are using any prompt* template functions in your config file template you will be prompted again. However, you can avoid this with the following example template logic:
Templates are used to change the contents of a file depending on the environment. For example, you can use the hostname of the machine to create different configurations on different machines.
chezmoi uses the text/template syntax from Go extended with text template functions from sprig.
When reading files from the source state, chezmoi interprets them as a template if either of the following is true:
The file name has a .tmpl suffix.
The file is in the .chezmoitemplates directory, or a subdirectory of .chezmoitemplates.
chezmoi provides a variety of template variables. For a full list, run
chezmoi data\n
These come from a variety of sources (later data overwrite earlier ones):
Variables populated by chezmoi are in .chezmoi, for example .chezmoi.os.
Variables created by you in the .chezmoidata.$FORMAT configuration file. The various supported formats (json, jsonc, toml and yaml) are read in alphabetical order.
Variables created by you in the data section of the configuration file.
Furthermore, chezmoi provides a variety of functions to retrieve data at runtime from password managers, environment variables, and the filesystem.
"},{"location":"user-guide/templating/#creating-a-template-file","title":"Creating a template file","text":"
There are several ways to create a template:
When adding a file for the first time, pass the --template argument, for example:
chezmoi add --template ~/.zshrc\n
If a file is already managed by chezmoi, but is not a template, you can make it a template by running, for example:
chezmoi chattr +template ~/.zshrc\n
You can create a template manually in the source directory by giving it a .tmpl extension, for example:
chezmoi cd\n$EDITOR dot_zshrc.tmpl\n
Templates in .chezmoitemplates must be created manually, for example:
Templates can be tested and debugged with chezmoi execute-template, which treats each of its arguments as a template and executes it. The templates are interpreted and the results are output to standard output, making it useful for testing small template fragments:
Template actions are written inside double curly brackets, {{ and }}. Actions can be variables, pipelines, or control statements. Text outside actions is copied literally.
Variables are written literally, for example:
{{ .chezmoi.hostname }}\n
Conditional expressions can be written using if, else if, else, and end, for example:
{{ if eq .chezmoi.os \"darwin\" }}\n# darwin\n{{ else if eq .chezmoi.os \"linux\" }}\n# linux\n{{ else }}\n# other operating system\n{{ end }}\n
For a full description of the template syntax, see the text/template documentation.
For formatting reasons you might want to leave some whitespace after or before the template code. This whitespace will remain in the final file, which you might not want.
A solution for this is to place a minus sign and a space next to the brackets. So {{- for the left brackets and -}} for the right brackets. Here's an example:
HOSTNAME={{- .chezmoi.hostname }}\n
This will result in
HOSTNAME=myhostname\n
Notice that this will remove any number of tabs, spaces and even newlines and carriage returns.
A very useful feature of chezmoi templates is the ability to perform logical operations.
# common config\nexport EDITOR=vi\n\n# machine-specific configuration\n{{- if eq .chezmoi.hostname \"work-laptop\" }}\n# this will only be included in ~/.bashrc on work-laptop\n{{- end }}\n
In this example chezmoi will look at the hostname of the machine and if that is equal to \"work-laptop\", the text between the if and the end will be included in the result.
"},{"location":"user-guide/templating/#boolean-functions","title":"Boolean functions","text":"Function Return value eq Returns true if the first argument is equal to any of the other arguments not Returns the boolean negation of its single argument and Returns the boolean AND of its arguments by returning the first empty argument or the last argument, that is, and x y behaves as if x then y else x. All the arguments are evaluated or Returns the boolean OR of its arguments by returning the first non-empty argument or the last argument, that is, or x y behaves as if x then x else y All the arguments are evaluated"},{"location":"user-guide/templating/#integer-functions","title":"Integer functions","text":"Function Return value len Returns the integer length of its argument eq Returns the boolean truth of arg1 == arg2 ne Returns the boolean truth of arg1 != arg2 lt Returns the boolean truth of arg1 < arg2 le Returns the boolean truth of arg1 <= arg2 gt Returns the boolean truth of arg1 > arg2 ge Returns the boolean truth of arg1 >= arg2"},{"location":"user-guide/templating/#more-complicated-logic","title":"More complicated logic","text":"
Up until now, we have only seen if statements that can handle at most two variables. In this part we will see how to create more complicated expressions.
You can also create more complicated expressions. The eq command can accept multiple arguments. It will check if the first argument is equal to any of the other arguments.
{{ if eq \"foo\" \"foo\" \"bar\" }}hello{{end}}\n{{ if eq \"foo\" \"bar\" \"foo\" }}hello{{end}}\n{{ if eq \"foo\" \"bar\" \"bar\" }}hello{{end}}\n
The first two examples will output hello and the last example will output nothing.
The operators or and and can also accept multiple arguments.
You can perform multiple checks in one if statement.
{{ if (and (eq .chezmoi.os \"linux\") (ne .email \"me@home.org\")) }}\n...\n{{ end }}\n
This will check if the operating system is Linux and the configured email is not the home email. The brackets are needed here, because otherwise all the arguments will be give to the and command.
This way you can chain as many operators together as you like.
chezmoi defines a few useful templates variables that depend on the system you are currently on. A list of the variables defined by chezmoi can be found here.
There are, however more variables than that. To view the variables available on your system, execute:
chezmoi data\n
This outputs the variables in JSON format by default. To access the variable chezmoi.kernel.osrelease in a template, use
{{ .chezmoi.kernel.osrelease }}\n
This way you can also access the variables you defined yourself.
Files in the .chezmoitemplates subdirectory are parsed as templates and are available to be included in other templates using the template action with a name equal to their relative path to the .chezmoitemplates directory.
By default, such templates will be executed with nil data. If you want to access template variables (e.g. .chezmoi.os) in the template you must pass the data explicitly.
For example:
.chezmoitemplates/part.tmpl:\n{{ if eq .chezmoi.os \"linux\" }}\n# linux config\n{{ else }}\n# non-linux config\n{{ end }}\n\ndot_file.tmpl:\n{{ template \"part.tmpl\" . }}\n
"},{"location":"user-guide/templating/#using-chezmoitemplates-for-creating-similar-files","title":"Using .chezmoitemplates for creating similar files","text":"
When you have multiple similar files, but they aren't quite the same, you can create a template file in the directory .chezmoitemplates. This template can be inserted in other template files, for example:
In the example above only one arguments is passed to the template. To pass more arguments to the template, you can do it in two ways.
"},{"location":"user-guide/templating/#via-the-config-file","title":"Via the config file","text":"
This method is useful if you want to use the same template arguments multiple times, because you don't specify the arguments every time. Instead you specify them in the file ~/.config/chezmoi/chezmoi.toml:
~/.config/chezmoi/chezmoi.toml
[data.alacritty.big]\n fontsize = 18\n font = \"DejaVu Serif\"\n[data.alacritty.small]\n fontsize = 12\n font = \"DejaVu Sans Mono\"\n
Use the variables in ~/.local/share/chezmoi/.chezmoitemplates/alacritty:
And connect them with ~/.local/share/chezmoi/small-font.yml.tmpl:
~/.local/share/chezmoi/small-font.yml.tmpl
{{- template \"alacritty\" .alacritty.small -}}\n
At the moment, this means that you'll have to duplicate the alacritty data in the config file on every machine, but a feature will be added to avoid this.
"},{"location":"user-guide/templating/#by-passing-a-dictionary","title":"By passing a dictionary","text":"
Using the same alacritty configuration as above, you can pass the arguments to it with a dictionary, for example ~/.local/share/chezmoi/small-font.yml.tmpl:
"},{"location":"user-guide/use-scripts-to-perform-actions/","title":"Use scripts to perform actions","text":""},{"location":"user-guide/use-scripts-to-perform-actions/#understand-how-scripts-work","title":"Understand how scripts work","text":"
chezmoi supports scripts that are executed when you run chezmoi apply. These scripts can be configured to run every time, only when their contents have changed, or only if they haven't been run before.
Scripts are any file in the source directory with the prefix run_, and they are executed in alphabetical order.
run_ scripts: These scripts are executed every time you run chezmoi apply.
run_onchange_ scripts: These scripts are only executed if their content has changed since the last time they were run.
run_once_ scripts: These scripts are executed once for each unique version of the content. If the script is a template, the content is hashed after template execution. chezmoi tracks the content's SHA256 hash and stores it in a database. If the content has been run before (even under a different filename), the script will not run again unless the content itself changes.
Scripts break chezmoi's declarative approach and should be used sparingly. All scripts should be idempotent, including run_onchange_ and run_once_ scripts.
Scripts are normally run while chezmoi updates your dotfiles. For example, run_b.sh will be run after updating a.txt and before updating c.txt. To run scripts before or after the updates, use the before_ or after_ attributes, respectively, e.g., run_once_before_install-password-manager.sh.
Scripts must be created manually in the source directory, typically by running chezmoi cd and then creating a file with a run_ prefix. There is no need to set the executable bit on the script.
Scripts with the .tmpl suffix are treated as templates, with the usual template variables available. If the template resolves to only whitespace or an empty string, the script will not be executed, which is useful for disabling scripts dynamically.
When executing a script, chezmoi generates the script contents in a file in a temporary directory with the executable bit set and then executes it using exec(3). As a result, the script must either include a #! line or be an executable binary. Script working directory is set to the first existing parent directory in the destination tree.
If a .chezmoiscripts directory exists at the root of the source directory, scripts in this directory are executed as normal scripts, without creating a corresponding directory in the target state.
In verbose mode, the scripts' contents are printed before execution. In dry-run mode, scripts are not executed.
You can set extra environment variables for your scripts in the scriptEnv section of your config file. For example, to set the MY_VAR environment variable to my_value, specify:
~/.config/chezmoi/chezmoi.toml
[scriptEnv]\n MY_VAR = \"my_value\"\n
chezmoi sets a number of environment variables when running scripts, including CHEZMOI=1 and common template data like CHEZMOI_OS and CHEZMOI_ARCH.
Note
By default, chezmoi diff will print the contents of scripts that would be run by chezmoi apply. To exclude scripts from the output of chezmoi diff, set diff.exclude in your configuration file, for example:
~/.config/chezmoi/chezmoi.toml
[diff]\n exclude = [\"scripts\"]\n
Similarly, chezmoi status will print the names of the scripts that it will execute with the status R. This can similarly disabled by setting status.exclude to [\"scripts\"] in your configuration file.
"},{"location":"user-guide/use-scripts-to-perform-actions/#install-packages-with-scripts","title":"Install packages with scripts","text":"
Change to the source directory and create a file called run_onchange_install-packages.sh. In this file create your package installation script, e.g.
#!/bin/sh\nsudo apt install ripgrep\n
The next time you run chezmoi apply or chezmoi update this script will be run. As it has the run_onchange_ prefix, it will not be run again unless its contents change, for example if you add more packages to be installed.
This script can also be a template. For example, if you create run_onchange_install-packages.sh.tmpl with the contents:
{{ if eq .chezmoi.os \"linux\" -}}\n#!/bin/sh\nsudo apt install ripgrep\n{{ else if eq .chezmoi.os \"darwin\" -}}\n#!/bin/sh\nbrew install ripgrep\n{{ end -}}\n
This will install ripgrep on both Debian/Ubuntu Linux systems and macOS.
"},{"location":"user-guide/use-scripts-to-perform-actions/#run-a-script-when-the-contents-of-another-file-changes","title":"Run a script when the contents of another file changes","text":"
chezmoi's run_ scripts are run every time you run chezmoi apply, whereas run_onchange_ scripts are run only when their contents have changed, after executing them as templates. You can use this to cause a run_onchange_ script to run when the contents of another file has changed by including a checksum of the other file's contents in the script.
For example, if your dconf settings are stored in dconf.ini in your source directory then you can make chezmoi apply only load them when the contents of dconf.ini has changed by adding the following script as run_onchange_dconf-load.sh.tmpl:
As the SHA256 sum of dconf.ini is included in a comment in the script, the contents of the script will change whenever the contents of dconf.ini are changed, so chezmoi will re-run the script whenever the contents of dconf.ini change.
In this example you should also add dconf.ini to .chezmoiignore so chezmoi does not create dconf.ini in your home directory.
"},{"location":"user-guide/use-scripts-to-perform-actions/#clear-the-state-of-all-run_onchange_-and-run_once_-scripts","title":"Clear the state of all run_onchange_ and run_once_ scripts","text":"
chezmoi stores whether and when run_onchange_ and run_once_ scripts have been run in its persistent state.
To clear the state of run_onchange_ scripts, run:
chezmoi state delete-bucket --bucket=entryState\n
To clear the state of run_once_ scripts, run:
chezmoi state delete-bucket --bucket=scriptState\n
"},{"location":"user-guide/advanced/customize-your-source-directory/","title":"Customize your source directory","text":""},{"location":"user-guide/advanced/customize-your-source-directory/#use-a-subdirectory-of-your-dotfiles-repo-as-the-root-of-the-source-state","title":"Use a subdirectory of your dotfiles repo as the root of the source state","text":"
By default, chezmoi uses the root of your dotfiles repo as the root of the source state. If your source state contains many entries in its root, then your target directory (usually your home directory) will in turn be filled with many entries in its root as well. You can reduce the number of entries by keeping .chezmoiignore up to date, but this can become tiresome.
Instead, you can specify that chezmoi should read the source state from a subdirectory of the source directory instead by creating a file called .chezmoiroot containing the relative path to this subdirectory.
For example, given:
~/.local/share/chezmoi/.chezmoiroot
home\n
Then chezmoi will read the source state from the home subdirectory of your source directory, for example the desired state of ~/.gitconfig will be read from ~/.local/share/chezmoi/home/dot_gitconfig (instead of ~/.local/share/chezmoi/dot_gitconfig).
When migrating an existing chezmoi dotfiles repo to use .chezmoiroot you will need to move the relevant files in to the new root subdirectory manually. You do not need to move files that are ignored by chezmoi in all cases (i.e. are listed in .chezmoiignore when executed as a template on all machines), and you can afterwards remove their entries from home/.chezmoiignore.
"},{"location":"user-guide/advanced/customize-your-source-directory/#use-a-different-version-control-system-to-git","title":"Use a different version control system to git","text":"
Although chezmoi is primarily designed to use a git repo for the source state, it does not require git and can be used with other version control systems, such as fossil or pijul.
The version control system is used in only three places:
chezmoi init will use git clone to clone the source repo if it does not already exist.
chezmoi update will use git pull by default to pull the latest changes.
chezmoi's auto add, commit, and push functionality use git status, git add, git commit and git push.
Using a different version control system (VCS) to git can be achieved in two ways.
Firstly, if your VCS is compatible with git's CLI, then you can set the git.command configuration variable to your VCS command and set useBuiltinGit to false.
Otherwise, you can use your VCS to create the source directory before running chezmoi init, for example:
The creation of an empty .git directory in the source directory is required for chezmoi to be able to identify the work tree.
For updates, you can set the update.command and update.args configuration variables and chezmoi update will use these instead of git pull, for example:
Currently, it is not possible to override the auto add, commit, and push behavior for non-git VCSs, so you will have to commit changes manually, for example:
chezmoi uses a declarative approach for the contents of dotfiles, but package installation requires running imperative commands. However, you can simulate declarative package installation with a combination of a .chezmoidata file and a run_onchange_ script.
The following example uses homebrew on macOS, but should be adaptable to other operating systems and package managers.
First, create .chezmoidata/packages.yaml declaring the packages that you want installed, for example:
{{ if eq .chezmoi.os \"darwin\" -}}\n#!/bin/bash\n\nbrew bundle --no-lock --file=/dev/stdin <<EOF\n{{ range .packages.darwin.brews -}}\nbrew {{ . | quote }}\n{{ end -}}\n{{ range .packages.darwin.casks -}}\ncask {{ . | quote }}\n{{ end -}}\nEOF\n{{ end -}}\n
Now, when you run chezmoi apply, chezmoi will execute the install-packages.sh script with when the list of packages defined in .chezmoidata/packages.yaml changes.
"},{"location":"user-guide/advanced/install-your-password-manager-on-init/","title":"Install your password manager on init","text":"
If you use a password manager to store your secrets then you may need to install your password manager after you have run chezmoi init on a new machine but before chezmoi init --apply or chezmoi apply executes your run_before_ scripts.
chezmoi provides a hooks.read-source-state.pre hook that allows you to modify your system after chezmoi init has cloned your dotfile repo but before chezmoi has read the source state. This is the perfect time to install your password manager as you can assume that ~/.local/share/chezmoi is populated but has not yet been read.
First, write your password manager install hook. chezmoi executes this hook every time any command reads the source state so the hook should terminate as quickly as possible if there is no work to do.
This hook is not a template so you cannot use template variables and must instead detect the system you are running on yourself.
#!/bin/sh\n\n# exit immediately if password-manager-binary is already in $PATH\ntype password-manager-binary >/dev/null 2>&1 && exit\n\ncase \"$(uname -s)\" in\nDarwin)\n # commands to install password-manager-binary on Darwin\n ;;\nLinux)\n # commands to install password-manager-binary on Linux\n ;;\n*)\n echo \"unsupported OS\"\n exit 1\n ;;\nesac\n
Note
The leading . in .install-password-manager.sh is important because it tells chezmoi to ignore .install-password-manager.sh when declaring the state of files in your home directory.
Finally, tell chezmoi to run your password manager install hook before reading the source state:
"},{"location":"user-guide/advanced/migrate-away-from-chezmoi/","title":"Migrate away from chezmoi","text":"
chezmoi provides several mechanisms to help you move to an alternative dotfile manager (or even no dotfile manager at all) in the future:
chezmoi creates your dotfiles just as if you were not using a dotfile manager at all. Your dotfiles are regular files, directories, and symlinks. You can run chezmoi purge to delete all traces of chezmoi and then, if you're migrating to a new dotfile manager, then you can use whatever mechanism it provides to add your dotfiles to your new system.
chezmoi has a chezmoi archive command that generates a tarball of your dotfiles. You can replace the contents of your dotfiles repo with the contents of the archive and you've effectively immediately migrated away from chezmoi.
chezmoi has a chezmoi dump command that dumps the interpreted (target) state in a machine-readable form, so you can write scripts around chezmoi.
"},{"location":"user-guide/advanced/use-chezmoi-with-watchman/","title":"Use chezmoi with Watchman","text":"
chezmoi can be used with Watchman to automatically run chezmoi apply whenever your source state changes, but there are some limitations because Watchman runs actions in the background without a terminal.
Firstly, Watchman spawns a server which runs actions when filesystems change. This server reads its environment variables when it is started, typically on the first invocation of the watchman command. If you use a password manager that uses environment variables to persist login sessions, then you must login to your password manager before you run the first watchman command, and your session might eventually time out.
Secondly, Watchman runs processes without a terminal, and so cannot run interactive processes. For chezmoi apply, you can use the --force flag to suppress prompts to overwrite files that have been modified since chezmoi last wrote them. However, if any other part of chezmoi apply is interactive, for example if your password manager prompts for a password, then it will not work with Watchman.
"},{"location":"user-guide/encryption/age/#symmetric-encryption-with-a-passphrase","title":"Symmetric encryption with a passphrase","text":"
To use age's symmetric encryption with a passphrase, set age.passphrase to true in your config file, for example:
~/.config/chezmoi/chezmoi.toml
encryption = \"age\"\n[age]\n passphrase = true\n
You will be prompted for the passphrase whenever you run chezmoi add --encrypt and whenever chezmoi needs to decrypt the file, for example when you run chezmoi apply, chezmoi diff, or chezmoi status.
"},{"location":"user-guide/encryption/age/#builtin-age-encryption","title":"Builtin age encryption","text":"
chezmoi has builtin support for age encryption which is automatically used if the age command is not found in $PATH.
Info
The builtin age encryption does not support passphrases, symmetric encryption, or SSH keys.
Passphrases are not supported because chezmoi needs to decrypt files regularly, e.g. when running a chezmoi diff or a chezmoi status command, not just when running chezmoi apply. Prompting for a passphrase each time would quickly become tiresome.
Symmetric encryption may be supported in the future. Please open an issue if you want this.
SSH keys are not supported as the age documentation explicitly recommends not using them:
When integrating age into a new system, it's recommended that you only support X25519 keys, and not SSH keys. The latter are supported for manual encryption operations.
chezmoi supports encrypting files with gpg. Encrypted files are stored in the source state and automatically be decrypted when generating the target state or editing a file contents with chezmoi edit.
Specify symmetric encryption in your configuration file:
~/.config/chezmoi/chezmoi.toml
encryption = \"gpg\"\n[gpg]\n symmetric = true\n
chezmoi will encrypt files:
gpg --armor --symmetric\n
"},{"location":"user-guide/encryption/gpg/#encrypting-files-with-a-passphrase","title":"Encrypting files with a passphrase","text":"
If you want to encrypt your files with a passphrase, but don't mind the passphrase being stored in plaintext on your machines, then you can use the following configuration:
This will prompt you for the passphrase the first time you run chezmoi init on a new machine, and then remember the passphrase in your configuration file.
Make sure encryption is added to the top level section at the beginning of the config, before any other sections.
Then, configure chezmoi as you would for age.
"},{"location":"user-guide/frequently-asked-questions/design/","title":"Design","text":""},{"location":"user-guide/frequently-asked-questions/design/#do-i-have-to-use-chezmoi-edit-to-edit-my-dotfiles","title":"Do I have to use chezmoi edit to edit my dotfiles?","text":"
No. chezmoi edit is a convenience command that has a couple of useful features, but you don't have to use it.
You can also run chezmoi cd and then just edit the files in the source state directly. After saving an edited file you can run chezmoi diff to check what effect the changes would have, and run chezmoi apply if you're happy with them. If there are inconsistencies that you want to keep, then chezmoi merge-all will help you resolve any differences.
chezmoi edit provides the following useful features:
The arguments to chezmoi edit are the files in their target location, so you don't have to think about source state attributes and your editor's syntax highlighting will work.
If the dotfile is encrypted in the source state, then chezmoi edit will decrypt it to a private directory, open that file in your $EDITOR, and then re-encrypt the file when you quit your editor. This makes encryption transparent.
With the --diff and --apply options you can see what would change and apply those changes without having to run chezmoi diff or chezmoi apply.
If you have configured git auto commits or git auto pushes then chezmoi edit will create commits and push them for you.
If you chose to edit files in the source state and you're using VIM then github.com/alker0/chezmoi.vim gives you syntax highlighting, however you edit your files. Besides using the plugin, you can use modeline to tell VIM the correct filetype. For example, put # vim: filetype=zsh at the top of dot_zshrc, and VIM will treat dot_zshrc as zsh file.
"},{"location":"user-guide/frequently-asked-questions/design/#why-doesnt-chezmoi-use-symlinks-like-gnu-stow","title":"Why doesn't chezmoi use symlinks like GNU Stow?","text":"
Symlinks are first class citizens in chezmoi: chezmoi supports creating them, updating them, removing them, and even more advanced features not found in other dotfile managers like having the same symlink point to different targets on different machines by using a template.
With chezmoi, you only use a symlink where you really need a symlink, in contrast to some other dotfile managers (e.g. GNU Stow) which require the use of symlinks as a layer of indirection between a dotfile's location (which can be anywhere in your home directory) and a dotfile's content (which needs to be in a centralized directory that you manage with version control). chezmoi solves this problem in a different way.
Instead of using a symlink to redirect from the dotfile's location to the centralized directory, chezmoi generates the dotfile as a regular file in its final location from the contents of the centralized directory. This approach allows chezmoi to provide features that are not possible when using symlinks, for example having files that are encrypted, executable, private, or templates.
There is nothing special about dotfiles managed by chezmoi whereas dotfiles managed with GNU Stow are special because they're actually symlinks to somewhere else.
The only advantage to using GNU Stow-style symlinks is that changes that you make to the dotfile's contents in the centralized directory are immediately visible whenever you save them, whereas chezmoi currently requires you to pass the --watch flag to chezmoi edit or set edit.watch to true in your configuration file.
If you really want to use symlinks, then chezmoi provides a symlink mode which uses symlinks where possible. This configures chezmoi to work like GNU Stow and have it create a set of symlinks back to a central directory, but this currently requires a bit of manual work (as described in #167). chezmoi might get some automation to help (see #886 for example) but it does need some convincing use cases that demonstrate that a symlink from a dotfile's location to its contents in a central directory is better than just having the correct dotfile contents.
"},{"location":"user-guide/frequently-asked-questions/design/#what-are-the-limitations-of-chezmois-symlink-mode","title":"What are the limitations of chezmoi's symlink mode?","text":"
In symlink mode chezmoi replaces targets with symlinks to the source directory if the target is a regular file and is not encrypted, executable, private, or a template.
Symlinks cannot be used for encrypted files because the source state contains the ciphertext, not the plaintext.
Symlinks cannot be used for executable files as the executable bit would need to be set on the file in the source directory and chezmoi uses only regular files and directories in its source state for portability across operating systems. This may change in the future.
Symlinks cannot be used for private files because git does not persist group and world permission bits.
Symlinks cannot be used for templated files because the source state contains the template, not the result of executing the template.
Symlinks cannot be used for entire directories because of chezmoi's use of attributes in the filename mangles entries in the directory, directories might have the exact_ attribute and contain empty files, and the directory's entries might not be usable with symlinks.
In symlink mode, running chezmoi add does not immediately replace the targets with a symlink. You must run chezmoi apply to create the symlinks.
"},{"location":"user-guide/frequently-asked-questions/design/#why-does-chezmoi-use-weird-filenames","title":"Why does chezmoi use weird filenames?","text":"
There are a number of criticisms of how chezmoi uses filenames:
The long source file names are weird and verbose.
Not all possible file permissions can be represented.
Everything is in a single directory, which can end up containing many entries.
chezmoi's decision to store metadata in filenames is a deliberate, practical, compromise.
Firstly, almost all programs store metadata in filenames: the filename's extension. chezmoi extends the filename to storing metadata in attributes in the filename's prefix as well.
The dot_ attribute makes it transparent which dotfiles are managed by chezmoi and which files are ignored by chezmoi. chezmoi ignores all files and directories that start with . so no special whitelists are needed for version control systems and their control files (e.g. .git and .gitignore).
chezmoi needs per-file metadata to know how to interpret the source file's contents, for example to know when the source file is a template or if the file's contents are encrypted. By storing this metadata in the filename, the metadata is unambiguously associated with a single file and adding, updating, or removing a single file touches only a single file in the source state. Changes to the metadata (e.g. chezmoi chattr +template $TARGET) are simple file renames and isolated to the affected file.
If chezmoi were to, say, use a common configuration file listing which files were templates and/or encrypted, then changes to any file would require updates to the common configuration file. Automating updates to configuration files requires a round trip (read config file, update config, write config) and it is not always possible preserve comments and formatting.
chezmoi's attributes of executable_, private_, and readonly_ allow the file permissions 0o644, 0o755, 0o600, 0o700, 0o444, 0o555, 0o400, and 0o500 to be represented. Directories can only have permissions 0o755, 0o700, or 0o500. In practice, these cover all permissions typically used for dotfiles. If this does cause a genuine problem for you, please open an issue on GitHub.
File permissions and modes like executable_, private_, readonly_, and symlink_ could also be stored in the filesystem, rather than in the filename. However, this requires the permissions to be preserved and handled by the underlying version control system and filesystem. chezmoi provides first-class support for Windows, where the executable_ and private_ attributes have no direct equivalents and symbolic links are not always permitted. By using regular files and directories, chezmoi avoids variations in the operating system, version control system, and filesystem making it both more robust and more portable.
chezmoi uses a 1:1 mapping between entries in the source state and entries in the target state. This mapping is bi-directional and unambiguous.
However, this also means that dotfiles that in the same directory in the target state must be in the same directory in the source state. In particular, every entry managed by chezmoi in the root of your home directory has a corresponding entry in the root of your source directory, which can mean that you end up with a lot of entries in the root of your source directory. This can be mitigated by using .chezmoiroot file.
If chezmoi were to permit, say, multiple separate source directories (so you could, say, put dot_bashrc in a bash/ subdirectory, and dot_vimrc in a vim/ subdirectory, but have chezmoi apply map these to ~/.bashrc and ~/.vimrc in the root of your home directory) then the mapping between source and target states is no longer bidirectional nor unambiguous, which significantly increases complexity and requires more user interaction. For example, if both bash/dot_bashrc and vim/dot_bashrc exist, what should be the contents of ~/.bashrc? If you run chezmoi add ~/.zshrc, should dot_zshrc be stored in the source bash/ directory, the source vim/ directory, or somewhere else? How does the user communicate their preferences?
chezmoi has many users and any changes to the source state representation must be backwards-compatible.
In summary, chezmoi's source state representation is a compromise with both advantages and disadvantages. Changes to the representation will be considered, but must meet the following criteria, in order of importance:
Be fully backwards-compatible for existing users.
Fix a genuine problem encountered in practice.
Be independent of the underlying operating system, version control system, and filesystem.
Not add significant extra complexity to the user interface or underlying implementation.
"},{"location":"user-guide/frequently-asked-questions/design/#can-chezmoi-support-multiple-sources-or-multiple-source-states","title":"Can chezmoi support multiple sources or multiple source states?","text":"
With some dotfile managers, dotfiles can be distributed across multiple directories or even multiple repos. For example, the user might have one directory per application, or separate repos for home and work configurations, or even separate git submodules for different applications. These can be considered multiple sources of truth for the target state. This, however, comes with complications:
Multiple sources of truth complicate the user interface. When running chezmoi add $FILE, which source should $FILE be added to?
Multiple sources of truth do not compose easily if target files overlap. For example, if you have two sources, both of which need to set an environment variable in .bashrc, how do you handle this when both, only one, or neither source might be activated? What if the sources are mutually exclusive, e.g. if the VIM source and the Emacs source both want to set the $EDITOR environment variable?
Multiple sources of truth are not always independent. Related to the previous point, consider a source that adds an applications's configuration files and shell completions. Should the shell completions be part of the applications's source or of the shell's source?
chezmoi instead makes the opinionated choice to use a single source of truth, i.e. a single branch in a single git repo. Using a single source of truth avoids the inherent complexity and ambiguity of multiple sources.
chezmoi provides mechanisms like templates (for minor differences), .chezmoiignore (for controlling the presence or otherwise of complete files and directories), and password manager integration (so secrets never need to be stored in a repo) handle machine-to-machine differences. Externals make it easy to pull in dotfiles from third-party sources.
That said, if you are keen to use multiple sources of truth with chezmoi, you have a number of options with some scripting around chezmoi.
Firstly, you can run chezmoi apply with different arguments to the --config and --source flags which will apply to the same destination. So that you only have to type one command you can wrap this in a shell function, for example:
If you want to generate multiple configuration files with chezmoi init then you will need the --config-path flag. For more advanced use, use the --destination, --cache, and --persistent-state flags.
Secondly, you can assemble a single source state from multiple sources and then use chezmoi apply. For example, if you have multiple source states in subdirectories of ~/.dotfiles:
#!/bin/bash\n\n# create a combined source state in a temporary directory\ncombined_source=\"$(mktemp -d)\"\n\n# remove the temporary source state on exit\ntrap 'rm -rf -- \"${combined_source}\"' INT TERM\n\n# copy files from multiple sources into the temporary source state\nfor source in $HOME/.dotfiles/*; do\n cp -r \"${source}\"/* \"${combined_source}\"\ndone\n\n# apply the temporary source state\nchezmoi apply --source \"${combined_source}\"\n
Thirdly, you can use a run_ script to invoke a second instance of chezmoi, as used by @felipecrs.
"},{"location":"user-guide/frequently-asked-questions/design/#why-does-chezmoi-cd-spawn-a-shell-instead-of-just-changing-directory","title":"Why does chezmoi cd spawn a shell instead of just changing directory?","text":"
chezmoi cd spawns a shell because it is not possible for a program to change the working directory of its parent process. You can add a shell function instead:
chezmoi-cd() {\n cd $(chezmoi source-path)\n}\n
Typing chezmoi-cd will then change the directory of your current shell to chezmoi's source directory.
"},{"location":"user-guide/frequently-asked-questions/design/#why-are-the-prompt-functions-only-available-in-config-file-templates","title":"Why are the prompt* functions only available in config file templates?","text":"
chezmoi regularly needs to execute templates to determine the target contents of files. For example, templates are executed for the apply, diff, and status commands, amongst many others. Having to interactively respond each time would quickly become tiresome. Therefore, chezmoi only provides these functions when generating a config file from a config file template (e.g. when you run chezmoi init or chezmoi --init apply).
"},{"location":"user-guide/frequently-asked-questions/design/#why-not-use-ansiblechefpuppetsalt-or-similar-to-manage-my-dotfiles-instead","title":"Why not use Ansible/Chef/Puppet/Salt, or similar to manage my dotfiles instead?","text":"
Whole system management tools are more than capable of managing your dotfiles, but they are large systems that entail several disadvantages. Compared to whole system management tools, chezmoi offers:
Small, focused feature set designed for dotfiles. There's simply less to learn with chezmoi compared to whole system management tools.
Easy installation and execution on every platform, without root access. Installing chezmoi requires only copying a single binary file with no external dependencies. Executing chezmoi just involves running the binary. In contrast, installing and running a whole system management tool typically requires installing a scripting language runtime, several packages, and running a system service, all typically requiring root access.
chezmoi's focus and simple installation means that it runs almost everywhere: from tiny ARM-based Linux systems to Windows desktops, from inside lightweight containers to FreeBSD-based virtual machines in the cloud.
"},{"location":"user-guide/frequently-asked-questions/design/#can-i-use-chezmoi-to-manage-files-outside-my-home-directory","title":"Can I use chezmoi to manage files outside my home directory?","text":"
In practice, yes, you can, but this usage is strongly discouraged beyond using your system's package manager to install the packages you need.
chezmoi is designed to operate on your home directory, and is explicitly not a full system configuration management tool. That said, there are some ways to have chezmoi manage a few files outside your home directory.
chezmoi's scripts can execute arbitrary commands, so you can use a run_ script that is run every time you run chezmoi apply, to, for example:
Make the target file outside your home directory a symlink to a file managed by chezmoi in your home directory.
Copy a file managed by chezmoi inside your home directory to the target file.
Execute a template with chezmoi execute-template --output=$FILENAME template where $FILENAME is outside the target directory.
chezmoi executes all scripts as the user executing chezmoi, so you may need to add extra privilege elevation commands like sudo or PowerShell start -verb runas -wait to your script.
chezmoi, by default, operates on your home directory but this can be overridden with the --destination command line flag or by specifying destDir in your config file, and could even be the root directory (/ or C:\\). This allows you, in theory, to use chezmoi to manage any file in your filesystem, but this usage is extremely strongly discouraged.
If your needs extend beyond modifying a handful of files outside your target system, then existing configuration management tools like Puppet, Chef, Ansible, and Salt are much better suited - and of course can be called from a chezmoi run_ script. Put your Puppet Manifests, Chef Recipes, Ansible Modules, and Salt Modules in a directory ignored by .chezmoiignore so they do not pollute your home directory.
chezmoi was inspired by Puppet, but was created because Puppet is an 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.
"},{"location":"user-guide/frequently-asked-questions/design/#where-does-the-name-chezmoi-come-from","title":"Where does the name \"chezmoi\" come from?","text":"
\"chezmoi\" splits to \"chez moi\" and pronounced /\u0283e\u026a mwa/ (shay-mwa) meaning \"at my house\" in French. It's seven letters long, which is an appropriate length for a command that is only run occasionally. If you prefer a shorter command, add an alias to your shell configuration, for example:
alias cz=chezmoi\n
"},{"location":"user-guide/frequently-asked-questions/encryption/","title":"Encryption","text":""},{"location":"user-guide/frequently-asked-questions/encryption/#how-do-i-configure-chezmoi-to-encrypt-files-but-only-request-a-passphrase-the-first-time-chezmoi-init-is-run","title":"How do I configure chezmoi to encrypt files but only request a passphrase the first time chezmoi init is run?","text":"
The following steps use age for encryption.
This can be achieved with the following process:
Generate an age private key.
Encrypt the private key with a passphrase.
Configure chezmoi to decrypt the private key if needed.
Configure chezmoi to use the private key.
Add encrypted files.
First, change to chezmoi's root directory:
chezmoi cd ~\n
Generate an age private key encrypted with a passphrase in the file key.txt.age with the command:
$ age-keygen | age --armor --passphrase > key.txt.age\nPublic key: age193wd0hfuhtjfsunlq3c83s8m93pde442dkcn7lmj3lspeekm9g7stwutrl\nEnter passphrase (leave empty to autogenerate a secure one):\nConfirm passphrase:\n
Use a strong passphrase and make a note of the public key (age193wd0hfuhtjfsunlq3c83s8m93pde442dkcn7lmj3lspeekm9g7stwutrl in this case).
Add key.txt.age to .chezmoiignore so that chezmoi does not try to create it:
echo key.txt.age >> .chezmoiignore\n
Configure chezmoi to decrypt the passphrase-encrypted private key if needed:
Specify the public and private keys for encryption. age.recipient must be your public key from above. Make sure encryption is added at the beginning, before any other sections.
Run chezmoi init --apply to generate the chezmoi's config file and decrypt the private key:
$ chezmoi init --apply\nEnter passphrase:\n
At this stage everything is configured and git status should report:
$ git status\nOn branch main\nUntracked files:\n (use \"git add <file>...\" to include in what will be committed)\n .chezmoi.toml.tmpl\n .chezmoiignore\n key.txt.age\n run_once_before_decrypt-private-key.sh.tmpl\n\nnothing added to commit but untracked files present (use \"git add\" to track)\n
If you're happy with the changes you can commit them. All four files should be committed.
Add files that you want to encrypt using the --encrypt argument to chezmoi add, for example:
chezmoi add --encrypt ~/.ssh/id_rsa\n
When you run chezmoi init on a new machine you will be prompted to enter your passphrase once to decrypt key.txt.age. Your decrypted private key will be stored in ~/.config/chezmoi/key.txt.
"},{"location":"user-guide/frequently-asked-questions/encryption/#how-to-re-encrypt-encrypted-files","title":"How to re-encrypt encrypted files","text":"
To rotate from an expired GPG key to its replacement, or change from GPG to age encryption, the following steps can be used:
Make sure you have applied all encrypted files (e.g. chezmoi apply decrypts files and places them in their destinations).
Update chezmoi configuration to use the new encryption method (examples: gpg, age, age with one-time passphrase).
Remove all encrypted files from the state via chezmoi forget or chezmoi unmanage.
Add them back with chezmoi add --encrypt.
"},{"location":"user-guide/frequently-asked-questions/encryption/#example-migrate-from-gpg-to-age","title":"Example: Migrate from GPG to age","text":"
Update chezmoi configuration to use age encryption (with chezmoi edit-config or manually editing the corresponding template):
for encrypted_file in $(chezmoi managed --include encrypted --path-style absolute)\ndo\n # optionally, add --force to avoid prompts\n chezmoi forget \"$encrypted_file\"\n\n # strip the .asc extension\n decrypted_file=\"${encrypted_file%.asc}\"\n\n chezmoi add --encrypt \"$decrypted_file\"\ndone\n
"},{"location":"user-guide/frequently-asked-questions/general/","title":"General","text":""},{"location":"user-guide/frequently-asked-questions/general/#what-other-questions-have-been-asked-about-chezmoi","title":"What other questions have been asked about chezmoi?","text":"
See the issues and discussions.
"},{"location":"user-guide/frequently-asked-questions/general/#where-do-i-ask-a-question-that-isnt-answered-here","title":"Where do I ask a question that isn't answered here?","text":"
Please open an issue on GitHub or start a discussion.
"},{"location":"user-guide/frequently-asked-questions/general/#i-like-chezmoi-how-do-i-say-thanks","title":"I like chezmoi. How do I say thanks?","text":"
Thank you! chezmoi was written to scratch a personal itch, and I'm very happy that it's useful to you. Please give chezmoi a star on GitHub, and if you're happy to share your public dotfile repo then tag it with chezmoi.
If you write an article or give a talk on chezmoi please inform the author (e.g. by opening an issue) so it can be added to chezmoi's articles, podcasts, and videos pages.
Contributions are very welcome and every bug report, support request, and feature request helps make chezmoi better. Thank you :)
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/","title":"Troubleshooting","text":""},{"location":"user-guide/frequently-asked-questions/troubleshooting/#how-can-i-quickly-check-for-problems-with-chezmoi-on-my-machine","title":"How can I quickly check for problems with chezmoi on my machine?","text":"
Run:
chezmoi doctor\n
Anything ok is fine, anything warning is only a problem if you want to use the related feature, and anything error indicates a definite problem.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#a-specific-command-is-not-behaving-as-i-expect-how-can-i-debug-it","title":"A specific command is not behaving as I expect. How can I debug it?","text":"
The --verbose flag makes chezmoi to print extra information about what it is doing.
The --debug flag makes chezmoi print very detailed step by step information.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#the-output-of-chezmoi-diff-is-broken-and-does-not-contain-color-what-could-be-wrong","title":"The output of chezmoi diff is broken and does not contain color. What could be wrong?","text":"
By default, chezmoi's diff output includes ANSI color escape sequences (e.g. ESC[37m) and is piped into your pager (by default less). chezmoi assumes that your pager passes through the ANSI color escape sequences, as configured on many systems, but not all. If your pager does not pass through ANSI color escape sequences then you will see monochrome diff output with uninterpreted ANSI color escape sequences.
This can typically by fixed by setting the environment variable
export LESS=-R\n
which instructs less to display \"raw\" control characters via the -R / --RAW-CONTROL-CHARS option.
You can also set the pager configuration variable in your config file, for example:
~/.config/chezmoi/chezmoi.toml
pager = \"less -R\"\n
If you have set a different pager (via the pager configuration variable or PAGER environment variable) then you must ensure that it passes through raw control characters. Alternatively, you can use the --color=false option to chezmoi to disable colors or the --no-pager option to chezmoi to disable the pager.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#why-do-i-get-a-blank-buffer-or-empty-file-when-running-chezmoi-edit","title":"Why do I get a blank buffer or empty file when running chezmoi edit?","text":"
In this case, chezmoi edit typically prints a warning like:
chezmoi: warning: $EDITOR $TMPDIR/$FILENAME: returned in less than 1s\n
chezmoi edit performs a bit of magic to improve the experience of editing files in the source state by invoking your editor with filenames in a temporary directory that look like filenames in your home directory. What's happening here is that your editor command is exiting immediately, so chezmoi thinks you've finished editing and so removes the temporary directory, but actually your editor command has forked a edit process in the background, and that edit process opens a now non-existent file.
To fix this you have to configure your editor command to remain in the foreground until you have finished editing the file, so chezmoi knows when to remove the temporary directory.
VIMVSCode
Pass the -f flag, e.g. by setting the edit.flags configuration variable to [\"-f\"], or by setting the EDITOR environment variable to include the -f flag, e.g. export EDITOR=\"vim -f\".
Pass the --wait flag, e.g. by setting the edit.flags configuration variable to [\"--wait\"] or by setting the EDITOR environment variable to include the --wait flag, e.g. export EDITOR=\"code --wait\".
The \"bit of magic\" that chezmoi edit performs includes:
chezmoi edit makes the filename opened by your editor more closely match the target filename, which can help your editor choose the correct syntax highlighting. For example, if you run chezmoi edit ~/.zshrc, your editor is be opened with $TMPDIR/.zshrc but you'll actually be editing ~/.local/share/chezmoi/dot_zshrc. Under the hood, chezmoi creates a hardlink in a temporary directory to the file in your source directory, so even though your editor thinks it's editing .zshrc, it is really editing dot_zshrc in your source directory.
If the source file is encrypted then chezmoi edit transparently decrypts and re-encrypts the file for you. Specifically, chezmoi decrypts the file into a private temporary directory and open your editor with the decrypted file, and re-encrypts the file when you exit your editor.
If the source file is a template, then chezmoi edit preserves the .tmpl extension.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-makes-sshconfig-group-writeable-how-do-i-stop-this","title":"chezmoi makes ~/.ssh/config group writeable. How do I stop this?","text":"
By default, chezmoi uses your system's umask when creating files. On most systems the default umask is 022 but some systems use 002, which means that files and directories are group writeable by default.
You can override this for chezmoi by setting the umask configuration variable in your configuration file, for example:
~/.config/chezmoi/chezmoi.toml
umask = 0o022\n
Note
This will apply to all files and directories that chezmoi manages and will ensure that none of them are group writeable. It is not currently possible to control group write permissions for individual files or directories. Please open an issue on GitHub if you need this.
This is likely because the chezmoi binary you are using was statically compiled with musl and the machine you are running on uses LDAP or NIS.
The immediate fix is to use a package built for your distribution (e.g a .deb or .rpm) which is linked against glibc and includes LDAP/NIS support instead of the statically-compiled binary.
If the problem still persists, then please open an issue on GitHub.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-chezmoi-timeout-or-chezmoi-timeout-obtaining-persistent-state-lock","title":"chezmoi reports chezmoi: timeout or chezmoi: timeout obtaining persistent state lock","text":"
chezmoi will report this when it is unable to lock its persistent state (~/.config/chezmoi/chezmoistate.boltdb), typically because another instance of chezmoi is currently running and holding the lock.
This can happen, for example, if you have a run_ script that invokes chezmoi, or are running chezmoi in another window.
Under the hood, chezmoi uses bbolt which permits multiple simultaneous readers, but only one writer (with no readers).
Commands that take a write lock include add, apply, edit, forget, import, init, state, unmanage, and update. Commands that take a read lock include diff, status, and verify.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-chezmoi-forkexec-tmpxxxxxxxxxxxx-exec-format-error-when-executing-a-template-script","title":"chezmoi reports chezmoi: fork/exec /tmp/XXXXXXXXXX.XX: exec format error when executing a template script","text":"
This error occurs when you have a newline before the #! in your script. Suppress the newline by including a - before the closing }} on the first line.
For example, if your template script begins with
{{ if eq .chezmoi.os \"linux\" }}\n#!/bin/sh\n
change this to
{{ if eq .chezmoi.os \"linux\" -}}\n#!/bin/sh\n
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-chezmoi-forkexec-tmpxxxxxxxxxxxx-permission-denied-when-executing-a-script","title":"chezmoi reports chezmoi: fork/exec /tmp/XXXXXXXXXX.XX: permission denied when executing a script","text":"
This error occurs when your temporary directory is mounted with the noexec option.
As chezmoi scripts can be templates, encrypted, or both, chezmoi needs to write the final script's contents to a file so that it can be executed by the operating system. By default, chezmoi will use $TMPDIR for this.
You can change the temporary directory into which chezmoi writes and executes scripts with the scriptTempDir configuration variable. For example, to use a subdirectory of your home directory you can use:
~/.config/chezmoi/chezmoi.toml
scriptTempDir = \"~/tmp\"\n
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-chezmoi-mkdir-xxxxx-no-such-file-or-directory-when-trying-to-manage-file-or-directory","title":"chezmoi reports chezmoi: mkdir xxxxx: no such file or directory when trying to manage file or directory","text":"
This error occurs when you try to add directory/file to be managed via chezmoi but the same directory is only listed in .chezmoiexternal.$FORMAT.
A workaround can be applied in a such case via manually creating import directory in chezmoi source directory (typically ~/.local/share/chezmoi) and create .keep file.
For example, if .chezmoiexternal.toml has the configuration:
Now once that done chezmoi add ~/.config/direnv/direnvrc should work. For reference see this issue
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-read-devstdin-permission-denied-or-write-devstdout-permission-denied-when-i-redirect-standard-input-or-standard-output","title":"chezmoi reports read /dev/stdin: permission denied or write /dev/stdout: permission denied when I redirect standard input or standard output","text":"
This error occurs when you installed chezmoi with snap and is caused by a long-standing bug in snap.
This is not a bug in chezmoi and there is nothing that chezmoi can do about this. However, there are two workarounds:
Firstly, you can use alternatives to shell redirection. For standard input:
Secondly, you can install chezmoi with any of the many supported install methods instead of snap.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-forkexec-no-such-file-or-directory-when-running-scripts-on-nix-or-termux","title":"chezmoi reports fork/exec ...: no such file or directory when running scripts on Nix or Termux","text":"
You are likely using a hardcoded script interpreter in the shebang line of your scripts, e.g.
#!/bin/bash\n
/bin/bash does not exist on Nix or Termux. You must update the shebang line to point to the actual bash interpreter. The easiest way to do this is make the script a template and use the lookPath template function, for example:
#!{{ lookPath \"bash\" }}\n
Alternatively, you can use the actual path to bash on your system, for example:
NixTermux
#!/usr/bin/env bash\n
#!/data/data/com.termux/files/usr/bin/bash\n
"},{"location":"user-guide/frequently-asked-questions/usage/","title":"Usage","text":""},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-edit-my-dotfiles-with-chezmoi","title":"How do I edit my dotfiles with chezmoi?","text":"
There are five popular approaches:
Use chezmoi edit $FILE. This will open the source file for $FILE in your editor, including opening the template if the file is templated and transparently decrypting and re-encrypting it if it is encrypted. For extra ease, use chezmoi edit --apply $FILE to apply the changes when you quit your editor, and chezmoi edit --watch $FILE to apply the changes whenever you save the file.
Use chezmoi cd and edit the files in the source directory directly. Run chezmoi diff to see what changes would be made, and chezmoi apply to make the changes.
If your editor supports opening directories, run chezmoi edit with no arguments to open the source directory.
Edit the file in your home directory, and then either re-add it by running chezmoi add $FILE or chezmoi re-add.
Edit the file in your home directory, and then merge your changes with source state by running chezmoi merge $FILE.
Note
re-add doesn't work with templates.
"},{"location":"user-guide/frequently-asked-questions/usage/#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","title":"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?","text":"
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.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-can-i-tell-what-dotfiles-in-my-home-directory-arent-managed-by-chezmoi-is-there-an-easy-way-to-have-chezmoi-manage-a-subset-of-them","title":"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?","text":"
chezmoi unmanaged will list everything not managed by chezmoi. You can add entire directories with chezmoi add.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-can-i-tell-what-dotfiles-in-my-home-directory-are-currently-managed-by-chezmoi","title":"How can I tell what dotfiles in my home directory are currently managed by chezmoi?","text":"
chezmoi managed will list everything managed by chezmoi.
"},{"location":"user-guide/frequently-asked-questions/usage/#if-theres-a-mechanism-in-place-for-the-above-is-there-also-a-way-to-tell-chezmoi-to-ignore-specific-files-or-groups-of-files-eg-by-directory-name-or-by-glob","title":"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)?","text":"
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 called .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.
"},{"location":"user-guide/frequently-asked-questions/usage/#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","title":"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?","text":"
Yes. Running chezmoi add will update the source state with the target. To see diffs of what would change, without actually changing anything, use chezmoi diff.
"},{"location":"user-guide/frequently-asked-questions/usage/#once-ive-made-a-change-to-the-source-directory-how-do-i-commit-it","title":"Once I've made a change to the source directory, how do I commit it?","text":"
You have several options:
chezmoi cd opens a shell in the source directory, where you can run your usual version control commands, like git add and git commit.
chezmoi git runs git in 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.
"},{"location":"user-guide/frequently-asked-questions/usage/#ive-made-changes-to-both-the-destination-state-and-the-source-state-that-i-want-to-keep-how-can-i-keep-them-both","title":"I've made changes to both the destination state and the source state that I want to keep. How can I keep them both?","text":"
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.
"},{"location":"user-guide/frequently-asked-questions/usage/#can-i-use-chezmoi-to-manage-my-shell-history-across-multiple-machines","title":"Can I use chezmoi to manage my shell history across multiple machines?","text":"
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. chezmoi 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 shell histories.
Instead, consider using a dedicated tool for sharing shell history across multiple machines, like atuin. You can use chezmoi to install and configure atuin.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-install-pre-requisites-for-templates","title":"How do I install pre-requisites for templates?","text":"
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:
chezmoi will make sure to execute it before templating other files.
Tip
You can use scriptEnv to inject data into your scripts through environment variables.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-write-a-literal-or-in-a-template","title":"How do I write a literal {{ or }} in a template?","text":"
{{ and }} are chezmoi's default template delimiters, and so need escaping, for example:
{{ \"{{\" }}\n{{ \"}}\" }}\n
results in
{{\n}}\n
For longer tokens containing a {{ and a }} you can use a longer literal, for example:
{{ \"{{ .Target }}\" }}\n
results in
{{ .Target }}\n
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-run-a-script-when-a-git-repo-external-changes","title":"How do I run a script when a git-repo external changes?","text":"
Use a run_onchange_after_*.tmpl script that includes the HEAD commit. For example, if ~/.emacs.d is a git-repo external, then create:
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-run-a-script-periodically","title":"How do I run a script periodically?","text":"
Use a run_once_*.tmpl script that includes the current time truncated to a suitable unit. For example, to run a script daily:
~/.local/share/chezmoi/run_once_daily.tmpl
#!/bin/sh\n\n# {{ now | date \"2006-01-02\" }}\necho \"new day\"\n
For weekly, use the week number from the output of date, for example:
~/.local/share/chezmoi/run_once_weekly.tmpl
#!/bin/sh\n\n# {{ output \"date\" \"+%V\" | trim }}\necho \"new week\"\n
Or, approximate the week number with template functions:
~/.local/share/chezmoi/run_once_weekly.tmpl
#!/bin/sh\n\n# {{ div now.YearDay 7 }}\necho \"new week\"\n
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-enable-shell-completions","title":"How do I enable shell completions?","text":"
chezmoi includes shell completions for bash, fish, powershell, and zsh. If you have installed chezmoi via your package manager then the shell completion should already be installed. For PowerShell, you need to manually add the completion script to your profile. 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.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-use-tools-that-i-installed-with-flatpak","title":"How do I use tools that I installed with Flatpak?","text":"
Command line programs installed with Flatpak cannot be run directly. Instead, they must be run with flatpak run. This can either be added by using a wrapper script or by configuring chezmoi to invoke flatpak run with the correct arguments directly. Wrapper scripts are recommended, as they work with the doctor command.
"},{"location":"user-guide/frequently-asked-questions/usage/#use-a-wrapper-script","title":"Use a wrapper script","text":"
Create a wrapper script with the exact same name as the command that invokes flatpak run and passes all arguments to the wrapped command.
For example, to wrap KeePassXC installed with Flatpak, create the script:
keepassxc-cli
#!/bin/bash\n\nflatpak run --command=keepassxc-cli org.keepassxc.KeePassXC -- \"$@\"\n
Note that the script is called keepassxc-cli without any .sh extension, so it has the exact same name as the keepassxc-cli command that chezmoi invokes by default. Ensure that this script is in your path and is executable.
"},{"location":"user-guide/frequently-asked-questions/usage/#configure-chezmoi-to-invoke-flatpak-run","title":"Configure chezmoi to invoke flatpak run","text":"
For tools that chezmoi invokes with .command and .args configuration variables, you can configure chezmoi to invoke flatpak directly with the correct arguments.
For example, to use VSCodium installed with Flatpak as your diff command, add the following to your config file:
Note that the command is flatpak, the first two arguments are run and the name of app, and any further arguments are passed to the app.
"},{"location":"user-guide/machines/containers-and-vms/","title":"Containers and VMs","text":"
You can use chezmoi to manage your dotfiles in GitHub Codespaces, Visual Studio Codespaces, and Visual Studio Code Remote - Containers.
For a quick start, you can clone the chezmoi/dotfiles repository which supports Codespaces out of the box.
The workflow is different to using chezmoi on a new machine, notably:
These systems will automatically clone your dotfiles repo to ~/dotfiles, so there is no need to clone your repo yourself.
The installation script must be non-interactive.
When running in a Codespace, the environment variable CODESPACES will be set to true. You can read its value with the env template function.
First, if you are using a chezmoi configuration file template, ensure that it is non-interactive when running in Codespaces, for example, .chezmoi.toml.tmpl might contain:
{{- $codespaces:= env \"CODESPACES\" | not | not -}}\nsourceDir = {{ .chezmoi.sourceDir | quote }}\n\n[data]\n name = \"Your name\"\n codespaces = {{ $codespaces }}\n{{- if $codespaces }}{{/* Codespaces dotfiles setup is non-interactive, so set an email address */}}\n email = \"your@email.com\"\n{{- else }}{{/* Interactive setup, so prompt for an email address */}}\n email = {{ promptString \"email\" | quote }}\n{{- end }}\n
Info
Setting the sourceDir configuration variable to .chezmoi.sourceDir is required because Codespaces clones your dotfiles repo to a different one to chezmoi's default.
This sets the codespaces template variable, so you don't have to repeat (env \"CODESPACES\") in your templates. It also sets the sourceDir configuration to the --source argument passed in chezmoi init.
Second, create an install.sh script that installs chezmoi and your dotfiles and add it to .chezmoiignore and your dotfiles repo:
The generated script installs the latest version of chezmoi in ~/.local/bin if needed, and then chezmoi init ... invokes chezmoi to create its configuration file and initialize your dotfiles. --apply tells chezmoi to apply the changes immediately, and --source=... tells chezmoi where to find the cloned dotfiles repo, which in this case is the same folder in which the script is running from.
Finally, modify any of your templates to use the codespaces variable if needed. For example, to install vim-gtk on Linux but not in Codespaces, your run_once_install-packages.sh.tmpl might contain:
{{- if (and (eq .chezmoi.os \"linux\") (not .codespaces)) -}}\n#!/bin/sh\nsudo apt install -y vim-gtk\n{{- end -}}\n
"},{"location":"user-guide/machines/general/","title":"General","text":""},{"location":"user-guide/machines/general/#determine-whether-the-current-machine-is-a-laptop-or-desktop","title":"Determine whether the current machine is a laptop or desktop","text":"
The following template sets the $chassisType variable to \"desktop\" or \"laptop\" on macOS, Linux, and Windows.
"},{"location":"user-guide/machines/general/#determine-how-many-cpu-cores-and-threads-the-current-machine-has","title":"Determine how many CPU cores and threads the current machine has","text":"
The following template sets the $cpuCores and $cpuThreads variables to the number of CPU cores and threads on the current machine respectively on macOS, Linux and Windows.
{{- if gt .cpu.threads .cpu.cores -}}\nHyperthreaded!\n{{- else -}}\nNot hyperthreaded!\n{{- end -}}\n
"},{"location":"user-guide/machines/linux/","title":"Linux","text":""},{"location":"user-guide/machines/linux/#combine-operating-system-and-linux-distribution-conditionals","title":"Combine operating system and Linux distribution conditionals","text":"
There can be as much variation between Linux distributions as there is between operating systems. Due to text/template's eager evaluation of conditionals, this means you often have to write templates with nested conditionals:
{{ if eq .chezmoi.os \"darwin\" }}\n# macOS-specific code\n{{ else if eq .chezmoi.os \"linux\" }}\n{{ if eq .chezmoi.osRelease.id \"debian\" }}\n# Debian-specific code\n{{ else if eq .chezmoi.osRelease.id \"fedora\" }}\n# Fedora-specific code\n{{ end }}\n{{ end }}\n
This can be simplified by combining the operating system and distribution into a single custom template variable. Put the following in your configuration file template:
This defines the .osid template variable to be {{ .chezmoi.os }} on machines without an os-release file, or to be {{ .chezmoi.os }}-{{ .chezmoi.osRelease.id }} on machines with an os-release file.
You can then simplify your conditionals to be:
{{ if eq .osid \"darwin\" }}\n# macOS-specific code\n{{ else if eq .osid \"linux-debian\" }}\n# Debian-specific code\n{{ else if eq .osid \"linux-fedora\" }}\n# Fedora-specific code\n{{ end }}\n
"},{"location":"user-guide/machines/macos/","title":"macOS","text":""},{"location":"user-guide/machines/macos/#use-brew-bundle-to-manage-your-brews-and-casks","title":"Use brew bundle to manage your brews and casks","text":"
Homebrew's brew bundle subcommand allows you to specify a list of brews and casks to be installed. You can integrate this with chezmoi by creating a run_once_ script. For example, create a file in your source directory called run_once_before_install-packages-darwin.sh.tmpl containing:
{{- if eq .chezmoi.os \"darwin\" -}}\n#!/bin/bash\n\nbrew bundle --no-lock --file=/dev/stdin <<EOF\nbrew \"git\"\ncask \"google-chrome\"\nEOF\n{{ end -}}\n
Note
The Brewfile is embedded directly in the script with a bash here document. chezmoi will run this script whenever its contents change, i.e. when you add or remove brews or casks.
"},{"location":"user-guide/machines/macos/#determine-the-hostname","title":"Determine the hostname","text":"
The result of the hostname command on macOS depends on the network that the machine is connected to. For a stable result, use the scutil command:
{{ $computerName := output \"scutil\" \"--get\" \"ComputerName\" | trim }}\n
"},{"location":"user-guide/machines/macos/#run-script-after-every-macos-update","title":"Run script after every macOS update","text":"
You can automate a script to run after each macOS update by creating a run_onchange_ script and using the output template function to run sw_vers:
"},{"location":"user-guide/machines/windows/","title":"Windows","text":""},{"location":"user-guide/machines/windows/#detect-windows-subsystem-for-linux-wsl","title":"Detect Windows Subsystem for Linux (WSL)","text":"
WSL can be detected by looking for the string Microsoft or microsoft in /proc/sys/kernel/osrelease, which is available in the template variable .chezmoi.kernel.osrelease, for example:
{{ if eq .chezmoi.os \"linux\" }}\n{{ if (.chezmoi.kernel.osrelease | lower | contains \"microsoft\") }}\n# WSL-specific code\n{{ end }}\n{{ end }}\n
"},{"location":"user-guide/machines/windows/#run-a-powershell-script-as-admin-on-windows","title":"Run a PowerShell script as admin on Windows","text":"
If you use gsudo, it has tips on writing self-elevating scripts.
"},{"location":"user-guide/machines/windows/#notes-on-running-elevated-scripts","title":"Notes on running elevated scripts","text":"
However you decide to run a script in an elevated prompt, as soon as the non-elevated script returns, chezmoi will move to the next step in its processing (running more scripts, creating files, etc.). Ensure that the elevated script completes before the non-elevated script exits, or subsequent steps may not run as expected. In the example above, this is accomplished by passing -Wait to PowerShell's Start-Process cmdlet.
Note that by including -NoExit in $CommandLine, the new (elevated) PowerShell process/window will not exit automatically on completion. This means you'll need to close the new window by hand for chezmoi to continue its steps. If this manual intervention is desired, it would be convenient to print a message as the script's last command to indicate completion for you to safely close the elevated window. If you want no manual intervention, you can remove -NoExit from $CommandLine, but then you likely won\u2019t see the output of the elevated script, which will make it more difficult to determine if something went wrong during its execution.
Template functions allow you to retrieve secrets from many popular password managers. Using a password manager allows you to keep all your secrets in one place, make your dotfiles repo public, and synchronize changes to secrets across multiple machines.
The output of op item get $UUID --format json is available as the onepassword template function. chezmoi parses the JSON output and returns it as structured data. For example, if the output is:
chezmoi will verify the availability and validity of a session token in the current environment. If it is missing or expired, you will be interactively prompted to sign-in again.
In the past chezmoi used to exit with an error when no valid session was available. If you'd like to restore this behavior, set the onepassword.prompt configuration variable to false, for example:
~/.config/chezmoi/chezmoi.toml
[onepassword]\n prompt = false\n
Danger
Do not use prompt on shared machines. A session token verified or acquired interactively will be passed to the 1Password CLI through a command line parameter, which is visible to other users of the same system.
chezmoi has experimental support for secrets automation with 1Password Connect and 1Password Service Accounts. These might be used on restricted machines where you cannot or do not wish to install a full 1Password desktop application.
When these features are used, the behavior of the 1Password CLI changes, so chezmoi requires explicit configuration for either connect or service account modes using the onepassword.mode configuration option. The default, if not specified, is account:
~/.config/chezmoi/chezmoi.toml
[onepassword]\n mode = \"account\"\n
In account mode, chezmoi will stop with an error if the environment variable OP_SERVICE_ACCOUNT_TOKEN is set, or if both environment variables OP_CONNECT_HOST and OP_CONNECT_TOKEN are set.
Info
Both 1Password Connect and Service Accounts prevent the CLI from working with multiple accounts. If you need access to secrets from more than one 1Password account, do not use these features with chezmoi.
The AWS shared profile name and region can be specified in chezmoi's config file with awsSecretsManager.profile and awsSecretsManager.region respectively. By default, these values will be picked up from the standard environment variables and config files used by the standard AWS tooling.
~/.config/chezmoi/chezmoi.toml
[awsSecretsManager]\n profile = myWorkProfile\n region = us-east-2\n
chezmoi includes support for Bitwarden using the Bitwarden CLI (bw), Bitwarden Secrets CLI (bws), and rbw commands to expose data as a template function.
If required, unlock your Bitwarden vault (API key and SSO logins always require an explicit unlock step):
bw unlock\n
Set the BW_SESSION environment variable, as instructed.
Bitwarden Session One-liner
The BW_SESSION value can be set directly. The exact combination differs based on whether you are currently logged into Bitwarden and how you log into Bitwarden.
export BW_SESSION=$(bw unlock --raw) # You are already logged in with any method\nexport BW_SESSION=$(bw login $BITWARDEN_EMAIL --raw) # You are not logged in and log in with an email\nexport BW_SESSION=$(bw login --sso && bw unlock --raw) # You are not logged in and login with SSO or API key\n
The structured data from bw get is available as the bitwarden template function in your config files, for example:
Custom fields can be accessed with the bitwardenFields template function. For example, if you have a custom field named token you can retrieve its value with:
Attachments can be accessed with the bitwardenAttachment and bitwardenAttachmentByRef template function. For example, if you have an attachment named id_rsa, you can retrieve its value with:
You can use any command line tool that outputs secrets either as a string or in JSON format. Choose the binary by setting secret.command in your configuration file. You can then invoke this command with the secret and secretJSON template functions which return the raw output and JSON-decoded output respectively. All of the above secret managers can be supported in this way:
chezmoi includes support for Doppler using the doppler CLI to expose data through the doppler and dopplerProjectJson template functions.
Log in using:
doppler login\n
It is now possible to interact with the doppler CLI in two different, but similar, ways. Both make use of the command doppler secrets download --json --no-file behind the scenes but present a different experience.
The doppler function is used in the following way:
All secrets from the specified project/config combination are cached for subsequent access and will not requery the doppler CLI for another secret in the same project/config. This caching mechanism enhances performance and reduces unnecessary CLI calls.
The dopplerProjectJson presents the secrets as json structured data and is used in the following way:
It is important to note that neither of the above parse any individual secret as json. This can be achieved by using the fromJson function, for example:
If you want to specify the private key to use for the decryption, structured data can be retrieved with the ejsonDecryptWithKey template function, for example:
Additional attributes are available through the keepassxcAttribute function. For example, if you have an entry called SSH Key with an additional attribute called private-key, its value is available as:
chezmoi includes an experimental mode to support using KeePassXC with YubiKeys. Set keepassxc.mode to open and keepassxc.args to the arguments required to set your YubiKey, for example:
For retrieving more complex data, use the keeper template function with a UID to retrieve structured data from keeper get or the keeperDataFields template function which restructures the output of keeper get in to a more convenient form, for example:
"},{"location":"user-guide/password-managers/keychain-and-windows-credentials-manager/","title":"Keychain and Windows Credentials Manager","text":"
chezmoi includes support for Keychain (on macOS), GNOME Keyring (on Linux and FreeBSD), and Windows Credentials Manager (on Windows) via the zalando/go-keyring library.
Set values with:
$ chezmoi secret keyring set --service=$SERVICE --user=$USER\nValue: xxxxxxxx\n
The value can then be used in templates using the keyring function which takes the service and user as arguments.
For example, save a GitHub access token in keyring with:
$ chezmoi secret keyring set --service=github --user=$GITHUB_USERNAME\nValue: xxxxxxxx\n
and then include it in your ~/.gitconfig file with:
chezmoi includes support for LastPass using the LastPass CLI to expose data as a template function.
Log in to LastPass using:
lpass login $LASTPASS_USERNAME\n
Check that lpass is working correctly by showing password data:
lpass show --json $LASTPASS_ENTRY_ID\n
where $LASTPASS_ENTRY_ID is a LastPass Entry Specification.
The structured data from lpass show --json id is available as the lastpass template function. The value will be an array of objects. You can use the index function and .Field syntax of the text/template language to extract the field you want. For example, to extract the password field from first the \"GitHub\" entry, use:
chezmoi automatically parses the note value of the LastPass entry as colon-separated key-value pairs, so, for example, you can extract a private SSH key like this:
chezmoi includes support for Vault using the Vault CLI to expose data as a template function.
The vault CLI needs to be correctly configured on your machine, e.g. the VAULT_ADDR and VAULT_TOKEN environment variables must be set correctly. Verify that this is the case by running:
vault kv get -format=json $KEY\n
The structured data from vault kv get -format=json is available as the vault template function. You can use the .Field syntax of the text/template language to extract the data you want. For example:
{{ (vault \"$KEY\").data.data.password }}\n
"},{"location":"user-guide/tools/diff/","title":"Diff","text":""},{"location":"user-guide/tools/diff/#use-a-custom-diff-tool","title":"Use a custom diff tool","text":"
By default, chezmoi uses a built-in diff. You can use a custom tool by setting the diff.command and diff.args configuration variables. The elements of diff.args are interpreted as templates with the variables .Destination and .Target containing filenames of the file in the destination state and the target state respectively. For example, to use meld, specify:
If you generate your config file from a config file template, then you'll need to escape the {{ and }} as {{ \"{{\" }} and {{ \"}}\" }}. That way your generated config file contains the {{ and }} you expect.
"},{"location":"user-guide/tools/diff/#use-vscode-as-the-diff-tool","title":"Use VSCode as the diff tool","text":"
To use VSCode as the diff tool, add the following to your config:
"},{"location":"user-guide/tools/diff/#use-delta-as-the-diff-tool","title":"Use delta as the diff tool","text":"
To use delta as the diff tool you must set both diff.command and diff.pager to delta, for example:
TOMLYAML ~/.config/chezmoi/chezmoi.toml
[diff]\ncommand = \"delta\"\npager = \"delta\"\n
~/.config/chezmoi/chezmoi.yaml
diff:\n command: \"delta\"\n pager: \"delta\"\n
"},{"location":"user-guide/tools/diff/#dont-show-scripts-in-the-diff-output","title":"Don't show scripts in the diff output","text":"
By default, chezmoi diff will show all changes, including the contents of scripts that will be run. You can exclude scripts from the diff output by setting the diff.exclude configuration variable in your configuration file, for example:
~/.config/chezmoi/chezmoi.toml
[diff]\n exclude = [\"scripts\"]\n
"},{"location":"user-guide/tools/diff/#dont-show-externals-in-the-diff-output","title":"Don't show externals in the diff output","text":"
To exclude diffs from externals, either pass the --exclude=externals flag or set diff.exclude to [\"externals\"] in your config file.
"},{"location":"user-guide/tools/diff/#customize-the-diff-pager","title":"Customize the diff pager","text":"
You can change the diff format, and/or pipe the output into a pager of your choice by setting diff.pager configuration variable. For example, to use diff-so-fancy specify:
~/.config/chezmoi/chezmoi.toml
[diff]\n pager = \"diff-so-fancy\"\n
The pager can be disabled using the --no-pager flag or by setting diff.pager to an empty string.
"},{"location":"user-guide/tools/diff/#show-human-friendly-diffs-for-binary-files","title":"Show human-friendly diffs for binary files","text":"
Similar to git, chezmoi includes a \"textconv\" feature that can transform file contents before passing them to the diff program. This is primarily useful for generating human-readable diffs of binary files.
For example, to show diffs of macOS .plist files, add the following to your configuration file:
This will pipe all .plist files through plutil -convert xml1 -o - - before showing differences.
"},{"location":"user-guide/tools/editor/","title":"Editor","text":""},{"location":"user-guide/tools/editor/#use-your-preferred-editor-with-chezmoi-edit-and-chezmoi-edit-config","title":"Use your preferred editor with chezmoi edit and chezmoi edit-config","text":"
By default, chezmoi will use your preferred editor as defined by the $VISUAL or $EDITOR environment variables, falling back to a default editor depending on your operating system (vi on UNIX-like operating systems, notepad.exe on Windows).
You can configure chezmoi to use your preferred editor by either setting the $EDITOR environment variable or setting the edit.command variable in your configuration file.
The editor command must only return when you have finished editing the files. chezmoi will emit a warning if your editor command returns too quickly.
In the specific case of using VSCode or Codium as your editor, you must pass the --wait flag, for example, in your shell config:
"},{"location":"user-guide/tools/editor/#use-chezmoi-with-emacs","title":"Use chezmoi with emacs","text":"
github.com/tuh8888/chezmoi.el provides convenience functions for interacting with chezmoi from emacs, and is available in MELPA.
"},{"location":"user-guide/tools/http-or-socks5-proxy/","title":"HTTP or SOCKS5 proxy","text":"
chezmoi supports HTTP, HTTPS, and SOCKS5 proxies. Set the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables, or their lowercase equivalents, for example:
"},{"location":"user-guide/tools/merge/","title":"Merge","text":""},{"location":"user-guide/tools/merge/#use-a-custom-merge-command","title":"Use a custom merge command","text":"
By default, chezmoi uses vimdiff. You can use a custom command by setting the merge.command and merge.args configuration variables. The elements of merge.args are interpreted as templates with the variables .Destination, .Source, and .Target containing filenames of the file in the destination state, source state, and target state respectively. For example, to use neovim's diff mode, specify:
If you generate your config file from a config file template, then you'll need to escape the {{ and }} as {{ \"{{\" }} and {{ \"}}\" }}. That way your generated config file contains the {{ and }} you expect.
"},{"location":"user-guide/tools/merge/#use-vscode-as-the-merge-tool","title":"Use VSCode as the merge tool","text":"
To use VSCode as the merge tool, add the following to your config:
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"chezmoi","text":"
Manage your dotfiles across multiple diverse machines, securely.
The latest version of chezmoi is 2.59.0 (release notes, release history).
"},{"location":"#what-does-chezmoi-do","title":"What does chezmoi do?","text":"
chezmoi helps you manage your personal configuration files (dotfiles, like ~/.gitconfig) across multiple machines.
chezmoi provides many features beyond symlinking or using a bare git repo including:
templates (to handle small differences between machines)
password manager support (to store your secrets securely)
importing files from archives (great for shell and editor plugins)
full file encryption (using gpg or age)
running scripts (to handle everything else)
With chezmoi, pronounced /\u0283e\u026a mwa/ (shay-mwa), you can install chezmoi and your dotfiles from your GitHub dotfiles repo on a new, empty machine with a single command:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --apply $GITHUB_USERNAME\n
As well as the curl | sh installation, you can install chezmoi with your favorite package manager.
Updating your dotfiles on any machine is a single command:
chezmoi update\n
chezmoi runs on all popular operating systems, is distributed as a single statically-linked binary with no dependencies, and does not require root access.
"},{"location":"#how-do-i-start-with-chezmoi","title":"How do I start with chezmoi?","text":"
Install chezmoi then read the quick start guide. The user guide covers most common tasks. For a full description, consult the reference.
"},{"location":"#should-i-use-chezmoi","title":"Should I use chezmoi?","text":"
See what other people think about chezmoi by reading articles, listening to podcasts, and watching videos about chezmoi. Read how chezmoi compares to other dotfile managers. Explore other people's dotfile repos that use chezmoi.
"},{"location":"#how-do-i-get-help-using-chezmoi","title":"How do I get help using chezmoi?","text":"
chezmoi has extensive documentation. First, use the search bar at the top of this page using a few, short, and specific keywords related to your problem.
chezmoi is an open source project with tens of thousands of users, so it is very likely that someone else has already encountered and solved your problem. Search chezmoi's GitHub repo for issues and discussions with keywords related to your problem.
If your question is still unanswered, please open a GitHub issue for support.
"},{"location":"#i-like-chezmoi-how-do-i-say-thanks","title":"I like chezmoi. How do I say thanks?","text":"
Please give chezmoi a star on GitHub.
Share chezmoi and, if you're happy to share your public dotfiles repo, then tag your repo with chezmoi.
Contributions are very welcome and every bug report, support request, and feature request helps make chezmoi better. Thank you :)
chezmoi does not accept financial contributions. Instead, please make a donation to a charity or cause of your choice.
"},{"location":"comparison-table/","title":"Comparison table","text":"chezmoi dotbot rcm vcsh yadm bare git Distribution Single binary Python package Multiple files Single script or package Single script - Install method Many git submodule Many Many Many Manual Non-root install on bare system \u2705 \u2049\ufe0f \u2705 \u2705 \u2705 \u2705 Windows support \u2705 \u2705 \u274c \u274c \u2705 \u2705 Bootstrap requirements None Python, git Perl sh, git git git Source repos Single Single Multiple Multiple Single Single dotfiles are... Files Symlinks Files Files Files Files Config file Optional Required Optional None Optional Optional Private files \u2705 \u274c \u274c \u274c \u2705 \u274c Show differences without applying \u2705 \u274c \u274c \u2705 \u2705 \u2705 Whole file encryption \u2705 \u274c \u274c \u274c \u2705 \u274c Password manager integration \u2705 \u274c \u274c \u274c \u274c \u274c Machine-to-machine file differences Templates Alternative files Alternative files Branches Alternative files, templates \u2049\ufe0f Custom variables in templates \u2705 \u274c \u274c \u274c \u274c \u274c Executable files \u2705 \u2705 \u2705 \u2705 \u2705 \u2705 File creation with initial contents \u2705 \u274c \u274c \u2705 \u274c \u274c Externals \u2705 \u274c \u274c \u274c \u274c \u274c Manage partial files \u2705 \u274c \u274c \u2049\ufe0f \u2705 \u2049\ufe0f File removal \u2705 \u274c \u274c \u2705 \u2705 \u274c Directory creation \u2705 \u2705 \u2705 \u2705 \u2705 \u2705 Run scripts \u2705 \u2705 \u2705 \u2705 \u2705 \u274c Run once scripts \u2705 \u274c \u274c \u2705 \u2705 \u274c Machine-to-machine symlink differences \u2705 \u274c \u274c \u2049\ufe0f \u2705 \u2049\ufe0f Shell completion \u2705 \u274c \u274c \u2705 \u2705 \u2705 Archive import \u2705 \u274c \u274c \u2705 \u274c \u2705 Archive export \u2705 \u274c \u274c \u2705 \u274c \u2705 Implementation language Go Python Perl POSIX Shell Bash C
\u2705 Supported, \u2049\ufe0f Possible with significant manual effort, \u274c Not supported
For more comparisons, visit dotfiles.github.io/utilities.
If you already have a dotfiles repo using chezmoi on GitHub at https://github.com/$GITHUB_USERNAME/dotfiles then you can install chezmoi and your dotfiles with the single command:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --apply $GITHUB_USERNAME\n
Private GitHub repos require other authentication methods:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --apply git@github.com:$GITHUB_USERNAME/dotfiles.git\n
Hint
If you want to install chezmoi in ./.local/bin instead of ./bin you can use get.chezmoi.io/lb or chezmoi.io/getlb instead.
Hint
To install the chezmoi binary in a different directory, use the -b option, for example:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- -b $HOME/.local/bin\n
"},{"location":"install/#download-a-pre-built-linux-package","title":"Download a pre-built Linux package","text":"
Download a package for your distribution and architecture.
Verify the that the SHA256 sum of your downloads matches the SHA256 sum in the verified checksum file. All the downloaded files must be in the current directory.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
"},{"location":"migrating-from-another-dotfile-manager/","title":"Migrating from another dotfile manager","text":""},{"location":"migrating-from-another-dotfile-manager/#migrate-from-a-dotfile-manager-that-uses-symlinks","title":"Migrate from a dotfile manager that uses symlinks","text":"
Many dotfile managers replace dotfiles with symbolic links to files in a common directory. If you chezmoi add such a symlink, chezmoi will add the symlink, not the file. To assist with migrating from symlink-based systems, use the --follow option to chezmoi add, for example:
chezmoi add --follow ~/.bashrc\n
This will tell chezmoi add that the target state of ~/.bashrc is the target of the ~/.bashrc symlink, rather than the symlink itself. When you run chezmoi apply, chezmoi will replace the ~/.bashrc symlink with the file contents.
Roughly speaking, chezmoi stores the desired state of your dotfiles in the directory ~/.local/share/chezmoi. When you run chezmoi apply, chezmoi calculates the desired contents for each of your dotfiles and then makes the minimum changes required to make your dotfiles match your desired state. chezmoi's concepts are described more accurately in the reference manual.
"},{"location":"quick-start/#start-using-chezmoi-on-your-current-machine","title":"Start using chezmoi on your current machine","text":"
Assuming that you have already installed chezmoi, initialize chezmoi with:
chezmoi init\n
This will create a new git local repository in ~/.local/share/chezmoi where chezmoi will store its source state. By default, chezmoi only modifies files in the working copy.
Manage your first file with chezmoi:
chezmoi add ~/.bashrc\n
This will copy ~/.bashrc to ~/.local/share/chezmoi/dot_bashrc.
Edit the source state:
chezmoi edit ~/.bashrc\n
This will open ~/.local/share/chezmoi/dot_bashrc in your $EDITOR. Make some changes and save the file.
Hint
You don't have to use chezmoi edit to edit your dotfiles. See this FAQ entry for more details.
See what changes chezmoi would make:
chezmoi diff\n
Apply the changes:
chezmoi -v apply\n
All chezmoi commands accept the -v (verbose) flag to print out exactly what changes they will make to the file system, and the -n (dry run) flag to not make any actual changes. The combination -n-v is very useful if you want to see exactly what changes would be made.
Next, open a shell in the source directory, to commit your changes:
chezmoi can be configured to automatically add, commit, and push changes to your repo.
chezmoi can also be used with GitLab, or BitBucket, Source Hut, or any other git hosting service.
Finally, exit the shell in the source directory to return to where you were:
exit\n
These commands are summarized in this sequence diagram:
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo H->>L: chezmoi init H->>W: chezmoi add <file> W->>W: chezmoi edit <file> W-->>H: chezmoi diff W->>H: chezmoi apply H-->>W: chezmoi cd W->>L: git add W->>L: git commit L->>R: git push W-->>H: exit"},{"location":"quick-start/#using-chezmoi-across-multiple-machines","title":"Using chezmoi across multiple machines","text":"
On a second machine, initialize chezmoi with your dotfiles repo:
This will check out the repo and any submodules and optionally create a chezmoi config file for you.
Check what changes that chezmoi will make to your home directory by running:
chezmoi diff\n
If you are happy with the changes that chezmoi will make then run:
chezmoi apply -v\n
If you are not happy with the changes to a file then either edit it with:
chezmoi edit $FILE\n
Or, invoke a merge tool (by default vimdiff) to merge changes between the current contents of the file, the file in your working copy, and the computed contents of the file:
chezmoi merge $FILE\n
On any machine, you can pull and apply the latest changes from your repo with:
chezmoi update -v\n
These commands are summarized in this sequence diagram:
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi init <repo> W-->>H: chezmoi diff W->>H: chezmoi apply W->>W: chezmoi edit <file> W->>W: chezmoi merge <file> R->>H: chezmoi update"},{"location":"quick-start/#set-up-a-new-machine-with-a-single-command","title":"Set up a new machine with a single command","text":"
You can install your dotfiles on new machine with a single command:
This command is summarized in this sequence diagram:
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>H: chezmoi init --apply <repo>"},{"location":"quick-start/#next-steps","title":"Next steps","text":"
For a full list of commands run:
chezmoi help\n
chezmoi has much more functionality. Good starting points are reading what other people say about chezmoi, adding more dotfiles, and using templates to manage files that vary from machine to machine and retrieve secrets from your password manager. Read the user guide to explore and see how people use chezmoi for inspiration.
"},{"location":"what-does-chezmoi-do/","title":"What does chezmoi do?","text":"
chezmoi helps you manage your personal configuration files (dotfiles, like ~/.gitconfig) across multiple machines.
chezmoi is helpful if you have spent time customizing the tools you use (e.g. shells, editors, and version control systems) and want to keep machines running different accounts (e.g. home and work) and/or different operating systems (e.g. Linux, macOS, and Windows) in sync, while still being able to easily cope with differences from machine to machine.
chezmoi scales from the trivial (e.g. copying a few dotfiles onto a Raspberry Pi, development container, or virtual machine) to complex long-lived multi-machine development environments (e.g. keeping any number of home and work, Linux, macOS, and Windows machines in sync). In all cases you only need to maintain a single source of truth (a single branch in git) and getting started only requires adding a single binary to your machine (which you can do with curl, wget, or scp).
chezmoi has strong support for security, allowing you to manage secrets (e.g. passwords, access tokens, and private keys) securely and seamlessly using a password manager and/or encrypt whole files with your favorite encryption tool.
If you do not personalize your configuration or only ever use a single operating system with a single account and none of your dotfiles contain secrets then you don't need chezmoi. Otherwise, read on...
"},{"location":"what-does-chezmoi-do/#what-are-chezmois-key-features","title":"What are chezmoi's key features?","text":""},{"location":"what-does-chezmoi-do/#flexible","title":"Flexible","text":"
You can share as much configuration across machines as you want, while still being able to control machine-specific details.Your dotfiles can be templates (using text/template syntax). Predefined variables allow you to change behavior depending on operating system, architecture, and hostname. chezmoi runs on all commonly-used platforms, like Linux, macOS, and Windows. It also runs on less commonly-used platforms, like FreeBSD, OpenBSD, and Termux.
"},{"location":"what-does-chezmoi-do/#personal-and-secure","title":"Personal and secure","text":"
Nothing leaves your machine, unless you want it to. Your configuration remains in a git repo under your control. You can write the configuration file in the format of your choice. chezmoi can retrieve secrets from 1Password, AWS Secrets Manager, Azure Key Vault, Bitwarden, Dashlane, Doppler, gopass, HCP Vault Secrets, KeePassXC, Keeper, LastPass, pass, passage, passhole, Vault, Keychain, Keyring, or any command-line utility of your choice. You can encrypt individual files with GnuPG or age. You can checkout your dotfiles repo on as many machines as you want without revealing any secrets to anyone.
chezmoi includes verbose and dry run modes so you can review exactly what changes it will make to your home directory before making them. chezmoi's source format uses only regular files and directories that map one-to-one with the files, directories, and symlinks in your home directory that you choose to manage. If you decide not to use chezmoi in the future, it is easy to move your data elsewhere.
"},{"location":"what-does-chezmoi-do/#declarative-and-robust","title":"Declarative and robust","text":"
You declare the desired state of files, directories, and symbolic links in your source of truth and chezmoi updates your home directory to match that state. What you want is what you get. chezmoi updates all files and symbolic links atomically. You will never be left with incomplete files that could lock you out, even if the update process is interrupted.
"},{"location":"what-does-chezmoi-do/#fast-and-easy-to-use","title":"Fast and easy to use","text":"
Using chezmoi feels like using git: the commands are similar and chezmoi runs in fractions of a second. chezmoi makes most day-to-day operations one line commands, including installation, initialization, and keeping your machines up-to-date. chezmoi can pull and apply changes from your dotfiles repo in a single command, and automatically commit and push changes.
"},{"location":"why-use-chezmoi/","title":"Why use chezmoi?","text":""},{"location":"why-use-chezmoi/#why-should-i-use-a-dotfile-manager","title":"Why should I use a dotfile manager?","text":"
Dotfile managers give you the combined benefit of a consistent environment everywhere with an undo command and a restore from backup.
As the core of our development environments become increasingly standardized (e.g. using git at both home and work), and we further customize them, at the same time we increasingly work in ephemeral environments like Docker containers, virtual machines, and GitHub Codespaces.
In the same way that nobody would use an editor without an undo command, or develop software without a version control system, chezmoi brings the investment that you have made in mastering your tools to every environment that you work in.
"},{"location":"why-use-chezmoi/#i-already-have-a-system-to-manage-my-dotfiles-why-should-i-use-chezmoi","title":"I already have a system to manage my dotfiles, why should I use chezmoi?","text":"
Quote
I\u2019ve been using Chezmoi for more than a year now, across at least 3 computers simultaneously, and I really love it. Most of all, I love how fast I can configure a new machine when I use it. In just a couple minutes of work, I can kick off a process on a brand-new computer that will set up my dotfiles and install all my usual software so it feels like a computer I\u2019ve been using for years. I also appreciate features like secrets management, which allow me to share my dotfiles while keeping my secrets safe. Overall, I love the way Chezmoi fits so perfectly into the niche of managing dotfiles.
\u2014 @mike_kasberg
Quote
I had initially been turned off when I first encountered [chezmoi], because [chezmoi] seemed overkill for (what appeared to me) a simple task.
But the problem of managing a relatively small number of dotfiles across a relatively small number of machines with small differences between them and keeping them up to date proved to be MUCH more complex than I imagined. Copy things around by hand, and then later distributing them via source control got hairy very quickly.
I finally realized all those features were absolutely necessary to manage things sanely, and once I took some time to learn how to do things with chezmoi, I have never looked back.
\u2014 njt
Quote
Regular reminder that chezmoi is the best dotfile manager utility I've used and you can too
\u2014 @mbbroberg
If you're using any of the following methods:
A custom shell script.
An existing dotfile manager like dotbot, rcm, homesick, vcsh, yadm, or GNU Stow.
A bare git repo.
Then you've probably run into at least one of the following problems.
"},{"location":"why-use-chezmoi/#if-coping-with-differences-between-machines-requires-extra-effort","title":"...if coping with differences between machines requires extra effort","text":"
If you want to synchronize your dotfiles across multiple operating systems or distributions, then you may need to manually perform extra steps to cope with differences from machine to machine. You might need to run different commands on different machines, maintain separate per-machine files or branches (with the associated hassle of merging, rebasing, or copying each change), or hope that your custom logic handles the differences correctly.
chezmoi uses a single source of truth (a single branch) and a single command that works on every machine. Individual files can be templates to handle machine to machine differences, if needed.
"},{"location":"why-use-chezmoi/#if-you-have-to-keep-your-dotfiles-repo-private","title":"...if you have to keep your dotfiles repo private","text":"
Quote
And regarding dotfiles, I saw that. It's only public dotfiles repos so I have to evaluate my dotfiles history to be sure. I have secrets scanning and more, but it was easier to keep it private for security, I'm ok mostly though. I'm using chezmoi and it's easier now
\u2014 @sheldon_hull
If your system stores secrets in plain text, then you must be very careful about where you clone your dotfiles. If you clone them on your work machine then anyone with access to your work machine (e.g. your IT department) will have access to your home secrets. If you clone it on your home machine then you risk leaking work secrets.
With chezmoi you can store secrets in your password manager or encrypt them, and even store passwords in different ways on different machines. You can clone your dotfiles repository anywhere, and even make your dotfiles repo public, without leaving personal secrets on your work machine or work secrets on your personal machine.
"},{"location":"why-use-chezmoi/#if-you-have-to-maintain-your-own-tool","title":"...if you have to maintain your own tool","text":"
Quote
I've offloaded my dotfiles deployment from a homespun shell script to chezmoi. I'm quite happy with this decision.
\u2014 @gotgenes
Quote
I discovered chezmoi and it's pretty cool, just migrated my old custom multi-machine sync dotfile setup and it's so much simpler now
in case you're wondering I have written 0 code
\u2014 @buritica
Quote
Chezmoi is like what you might get if you re-wrote my bash script in Go, came up with better solutions than diff for managing config on multiple machines, added in secrets management and other useful dotfile tools, and tweaked and perfected it over years.
@mike_kasberg
If your system was written by you for your personal use, then it probably has the functionality that you needed when you wrote it. If you need more functionality then you have to implement it yourself.
chezmoi includes a huge range of battle-tested functionality out-of-the-box, including dry-run and diff modes, script execution, conflict resolution, Windows support, and much, much more. chezmoi is used by thousands of people and has a rich suite of both unit and integration tests. When you hit the limits of your existing dotfile management system, chezmoi already has a tried-and-tested solution ready for you to use.
"},{"location":"why-use-chezmoi/#if-setting-up-your-dotfiles-requires-more-than-one-short-command","title":"...if setting up your dotfiles requires more than one short command","text":"
If your system is written in a scripting language like Python, Perl, or Ruby, then you also need to install a compatible version of that language's runtime before you can use your system.
chezmoi is distributed as a single stand-alone statically-linked binary with no dependencies that you can simply copy onto your machine and run. You don't even need git installed. chezmoi provides one-line installs, pre-built binaries, packages for Linux and BSD distributions, Homebrew formulae, Scoop and Chocolatey support on Windows, and a initial config file generation mechanism to make installing your dotfiles on a new machine as painless as possible.
If you use an LLM (Large Language Model, like ChatGPT, Claude, Gemini, GitHub Copilot, or Llama) to make a contribution then you must say so in your contribution and you must carefully review your contribution for correctness before sharing it. If you share un-reviewed LLM-generated content then you will be immediately banned. See CODE_OF_CONDUCT.md for more information.
chezmoi is written in Go and development happens on GitHub. chezmoi is a standard Go project, using standard Go tooling. chezmoi requires Go 1.23 or later.
chezmoi's tests include integration tests with other software. If the other software is not found in $PATH the tests will be skipped. Running the full set of tests requires age, base64, bash, bzip2, git, gpg, gzip, perl, python3, rage, ruby, sed, sha256sum, tr, true, unzip, xz, zip, and zstd.
Run chezmoi:
go run .\n
Run a set of smoke tests, including cross-compilation, tests, and linting:
make smoke-test\n
Test building chezmoi for all architectures:
make test-release\n
Hint
If you use fish as your primary shell, you may get warnings from Fish during tests:
error: can not save history\nwarning-path: Unable to locate data directory derived from $HOME: '/home/user/.local/share/fish'.\nwarning-path: The error was 'Operation not supported'.\nwarning-path: Please set $HOME to a directory where you have write access.\n
These can be avoided with by running tests with SHELL=bash or SHELL=zsh:
SHELL=bash make test\nSHELL=zsh make smoke-test\nSHELL=bash go test ./...\n
Directory Contents assets/chezmoi.io/docs/ The documentation single source of truth. Help text, examples, and the chezmoi.io website are generated from the files in this directory internal/chezmoi/ chezmoi's core functionality internal/cmd/ Code for the chezmoi command internal/cmd/testdata/scripts/ High-level tests of chezmoi's commands using testscript"},{"location":"developer-guide/architecture/#key-concepts","title":"Key concepts","text":"
As described in the reference manual, chezmoi evaluates the source state to compute a target state for the destination directory (typically your home directory). It then compares the target state to the actual state of the destination directory and performs any changes necessary to update the destination directory to match the target state. These concepts are represented directly in chezmoi's code.
chezmoi uses the generic term entry to describe something that it manages. Entries can be files, directories, symlinks, scripts, amongst other things.
All of chezmoi's interaction with the operating system is abstracted through the System interface. A System includes functionality to read and write files and directories and execute commands. chezmoi makes a distinction between idempotent commands that can be run multiple times without modifying the underlying system and arbitrary commands that may modify the underlying system.
The real underlying system is implemented via a RealSystem struct. Other Systems are composed on top of this to provide further functionality. For example, the --debug flag is implemented by wrapping the RealSystem with a DebugSystem that logs all calls to the underlying RealSystem. --dry-run is implemented by wrapping the RealSystem with a DryRunSystem that allows reads to pass through but silently discards all writes.
The SourceState struct represents a source state, including reading a source state from the source directory, executing templates, applying the source state (i.e. updating a System to match the desired source state), and adding more entries to the source state.
Entries in the source state are abstracted by the SourceStateEntry interface implemented by the SourceStateFile and SourceStateDir structs, as the source state only consists of regular files and directories.
A SourceStateFile includes a FileAttr struct describing the attributes parsed from its file name. Similarly, a SourceStateDir includes a DirAttr struct describing the directory attributes parsed from a directory name.
SourceStateEntrys can compute their target state entries, i.e. what the equivalent entry should be in the target state, abstracted by the TargetStateEntry interface.
Actual target state entries include TargetStateFile structs, representing a file with contents and permissions, TargetStateDir structs, representing a directory, TargetStateSymlink for symlinks, TargetStateRemove for entries that should be removed, and TargetStateScript for scripts that should be run.
The actual state of an entry in the target state is abstracted via the ActualStateEntry interface, with ActualStateAbsent, ActualStateDir, ActualStateFile, ActualStateSymlink structs implementing this interface.
Finally, an EntryState struct represents a serialization of an ActualEntryState for storage in and retrieval from chezmoi's persistent state. It stores a SHA256 of the entry's contents, rather than the full contents, to avoid storing secrets in the persistent state.
With these concepts, chezmoi's apply command is effectively:
Read the source state from the source directory.
For each entry in the source state (SourceStateEntry), compute its TargetStateEntry and read its actual state in the destination state (ActualStateEntry).
If the ActualStateEntry is not equivalent to the TargetStateEntry then apply the minimal set of changes to the ActualStateEntry so that they are equivalent.
Furthermore, chezmoi stores the EntryState of each entry that it writes in its persistent state. chezmoi can then detect if a third party has updated a target since chezmoi last wrote it by comparing the actual state entry in the target state with the entry state in the persistent state.
internal/cmd/*cmd.go files contain the code for each individual command. internal/cmd/*templatefuncs.go files contain the template functions.
Commands are defined as methods on the Config struct. The Config struct is large, containing all configuration values read from the config file, command line arguments, and computed and cached values.
The Config.persistentPreRunRootE and Config.persistentPostRunRootE methods set up and tear down state for individual commands based on the command's Annotations field, which defines how the command interacts with the file system and persistent state.
chezmoi uses separate types for absolute paths (AbsPath) and relative paths (RelPath) to avoid errors where paths are combined (e.g. joining two absolute paths is an error). The type SourceRelPath is a relative path within the source directory and handles file and directory attributes.
Internally, chezmoi normalizes all paths to use forward slashes with an optional upper-cased Windows volume so they can be compared with string comparisons. Paths read from the user may include tilde (~) to represent the user's home directory, use forward or backward slashes, and are treated as external paths (ExtPath). These are normalized to absolute paths. chezmoi is case-sensitive internally and makes no attempt to handle case-insensitive or case-preserving filesystems.
Persistent state is treated as a two-level key-value store with the pseudo-structure map[Bucket]map[Key]Value, where Bucket, Key, and Value are all []bytes. The PersistentState interface defines interaction with them. Sometimes temporary persistent states are used. For example, in dry run mode (--dry-run) the actual persistent state is copied into a temporary persistent state in memory which remembers writes but does not persist them to disk.
Encryption tools are abstracted by the Encryption interface that contains methods of encrypting and decrypting files and []bytes. Implementations are the AGEEncryption and GPGEncryption structs. A DebugEncryption struct wraps an Encryption interface and logs the methods called.
"},{"location":"developer-guide/architecture/#run_once_-and-run_onchange_-scripts","title":"run_once_ and run_onchange_ scripts","text":"
The execution of a run_once_ script is recorded by storing the SHA256 of its contents in the scriptState bucket in the persistent state. On future invocations the script is only run if no matching contents SHA256 is found in the persistent state.
The execution of a run_onchange_ script is recorded by storing its target name in the entryState bucket along with its contents SHA256 sum. On future invocations the script is only run if its contents SHA256 sum has changed, and its contents SHA256 sum is then updated in the persistent state.
chezmoi has a mix of, unit, integration, and end-to-end tests. Unit and integration tests use the github.com/alecthomas/assert/v2 framework. End-to-end tests use github.com/rogpeppe/go-internal/testscript with the test scripts themselves in internal/cmd/testdata/scripts/$TEST_NAME.txtar.
You can run individual end-to-end tests with
go test ./internal/cmd -run=TestScript/$TEST_NAME\n
Tests should, if at all possible, run unmodified on all operating systems tested in CI (Linux, macOS, Windows, and FreeBSD). Windows will sometimes need special handling due to its path separator and lack of POSIX-style file permissions.
"},{"location":"developer-guide/building-on-top-of-chezmoi/","title":"Building on top of chezmoi","text":"
chezmoi is designed with UNIX-style composability in mind, and the command line tool is semantically versioned. Building on top of chezmoi should primarily be done by executing the chezmoi binary with arguments and the standard input and output configured appropriately. The chezmoi dump and chezmoi state commands allows the inspection of chezmoi's internal state.
Bug reports, bug fixes, and documentation improvements are always welcome. Please open an issue or create a pull request with your report, fix, or improvement.
If you want to make a more significant change, please first open an issue to discuss the change that you want to make. Dave Cheney gives a good rationale as to why this is important.
All changes are made via pull requests. In your pull request, please make sure that:
All existing tests pass. You can ensure this by running make test.
There are appropriate additional tests that demonstrate that your PR works as intended.
The documentation is updated, if necessary. For new features you should add an entry in assets/chezmoi.io/docs/user-guide/ and a complete description in assets/chezmoi.io/docs/reference/. See website for instructions on how to build and view a local version of the documentation.
All generated files are up to date. You can ensure this by running make generate and including any modified files in your commit.
The code is correctly formatted, according to gofumpt. You can ensure this by running make format.
The code passes golangci-lint. You can ensure this by running make lint.
The commit messages follow the conventional commits specification. chezmoi's release notes are generated directly from the commit messages. For trivial or user-invisible changes, please use the prefix chore:.
Commits are logically separate, with no merge or \"fixup\" commits.
chezmoi generates the install script from a single source of truth. You must run
go generate\n
if your change includes any of the following:
Modifications to the install script template.
Additions or modifications to the list of supported OSs and architectures.
chezmoi's continuous integration verifies that all generated files are up to date. Changes to generated files should be included in the commit that modifies the source of truth.
If you're packaging chezmoi for an operating system or distribution:
chezmoi has no build dependencies other than the standard Go toolchain.
chezmoi has no runtime dependencies, but is usually used with git, so many packagers choose to make git an install dependency or recommended package.
Please set the version number, git commit, and build time in the binary. This greatly assists debugging when end users report problems or ask for help. You can do this by passing the following flags to go build:
$VERSION should be the chezmoi version, e.g. 1.7.3. Any v prefix is optional and will be stripped, so you can pass the git tag in directly.
Hint
The command git describe --abbrev=0 --tags will return a suitable value for $VERSION.
$COMMIT should be the full git commit hash at which chezmoi is built, e.g. 4d678ce6850c9d81c7ab2fe0d8f20c1547688b91.
Hint
The assets/scripts/generate-commit.go script will return a suitable value for $COMMIT. You can run it with go run assets/scripts/generate-commit.go.
Hint
The source archive contains a file called COMMIT containing the commit hash.
$DATE should be the date of the build as a UNIX timestamp or in RFC3339 format.
Hint
The command git show -s --format=%ct HEAD returns the UNIX timestamp of the last commit, e.g. 1636668628.
The command date -u +%Y-%m-%dT%H:%M:%SZ returns the current time in RFC3339 format, e.g. 2019-11-23T18:29:25Z.
$BUILT_BY should be a string indicating what system was used to build the binary. Typically it should be the name of your packaging system, e.g. homebrew.
Please enable cgo, if possible. chezmoi can be built and run without cgo, but the .chezmoi.username and .chezmoi.group template variables may not be set correctly on some systems.
chezmoi includes an upgrade command which attempts to self-upgrade. You can remove this command completely by building chezmoi with the noupgrade build tag.
chezmoi includes shell completions in the completions directory. Please include these in the package and install them in the shell-appropriate directory, if possible.
If the instructions for installing chezmoi in chezmoi's install guide are absent or incorrect, please open an issue or submit a PR to correct them.
brew automation will automatically detect new releases of chezmoi within a few hours and open a pull request in github.com/Homebrew/homebrew-core to bump the version.
If needed, the pull request can be created with:
brew bump-formula-pr --tag=v1.2.3 chezmoi\n
Note
chezmoi is in Scoop's Main bucket. Scoop's automation will automatically detect new releases within a few hours.
chezmoi uses GoReleaser's support for signing to sign the checksums of its release assets with cosign.
Details:
The cosign private key was generated with cosign v1.12.1 on a private recently-installed Ubuntu 22.04.1 system with a single user and all available updates applied.
The private key uses a long (more than 32 character) password generated locally by a password manager.
The password-protected private key is stored in chezmoi's public GitHub repo.
The private key's password is stored as a GitHub Actions secret and only available to the release step of release job of the main workflow.
The cosign public key is included in the release assets and also uploaded to https://chezmoi.io/cosign.pub. Since https://chezmoi.io is served by GitHub pages, it probably has equivalent security to chezmoi's GitHub Releases page, which is also managed by GitHub.
Virus scanning software, especially on Windows machines, occasionally report viruses or trojans in the chezmoi binary. This is almost certainly a false positive.
For more information see Why does my virus-scanning software think my Go distribution or compiled binary is infected? in the Go FAQ.
"},{"location":"developer-guide/security/#reporting-a-vulnerability","title":"Reporting a vulnerability","text":"
Please report vulnerabilities by opening a GitHub issue or sending an email to twpayne+chezmoi-security@gmail.com.
Unit testing, using testing, and github.com/alecthomas/assert/v2, tests that functions and small components behave as expected for a wide range of inputs, especially edge cases. These are generally found in internal/chezmoi/*_test.go.
Filesystem integration tests, using testing and github.com/twpayne/go-vfs/v5, test chezmoi's effects on the filesystem. This include some tests in internal/chezmoi/*_test.go, and higher level command tests in internal/cmd/*cmd_test.go.
High-level integration tests using github.com/rogpeppe/go-internal/testscript are in internal/cmd/testdata/scripts/*.txtar and are run by internal/cmd/main_test.go.
Linux distribution and OS tests run the full test suite using Docker for different Linux distributions (in assets/docker) and Vagrant for different OSes (in assets/vagrant). Windows tests are run in GitHub Actions.
"},{"location":"developer-guide/using-make/","title":"Building and installing with make","text":"
chezmoi can be built with GNU make, assuming you have the Go toolchain installed.
Running make will build a chezmoi binary in the current directory for the host OS and architecture. To embed version information in the binary and control installation the following variables are available:
Variable Example Purpose $VERSIONv2.0.0 Set version $COMMIT3895680a... Set the git commit at which the code was built $DATE2019-11-23T18:29:25Z The time of the build $BUILT_BYhomebrew The packaging system performing the build $PREFIX/usr Installation prefix $DESTDIRinstall-root Fake installation root
Running make install will install the chezmoi binary in ${DESTDIR}${PREFIX}/bin.
The website is generated with Material for MkDocs from the contents of the assets/chezmoi.io/docs/ directory. It is hosted by GitHub pages from the gh-pages branch.
To build the website locally, Go 1.23 (or later) and uv 0.4.15 (or later) must be installed. Python 3.10 (or later) is required, but may be installed with uv:
If Python 3.10 (or later) is not currently installed, install it with uv:
uv python install 3.10\n
Install the dependencies (the --frozen is optional but recommended):
The website is automatically deployed when new releases are created, but manual deployments can be triggered by maintainers with appropriate access using:
Recommended article: Fedora Magazine: Take back your dotfiles with Chezmoi
Date Version Language Title 2025-01-26 2.58.0 JP chezmoi \u3067 macOS \u306e user defaults \u3082\u7ba1\u7406\u3059\u308b 2025-01-19 2.58.0 EN Managing dotfiles with chezmoi 2025-01-03 2.57.0 EN Frictionless Dotfile Management With Chezmoi 2024-12-19 2.56.0 JP chezmoi\u3067dotfiles\u3092\u7ba1\u7406\u3059\u308b 2024-12-18 2.56.0 EN Exploring Tools For Managing Your Dotfiles 2024-12-02 2.55.0 JP chezmoi\u3092\u4f7f\u3063\u305f\u30ed\u30fc\u30ab\u30eb\u74b0\u5883\u7206\u901f\u69cb\u7bc9 2024-11-19 2.54.0 AR \u0634\u064a\u0645\u0648\u0627 (chezmoi) \u0628\u0628\u0633\u0627\u0637\u0629 2024-11-16 2.54.0 EN Swapping to Chezmoi 2024-11-07 2.53.1 EN dotfiles management: chezmoi 2024-01-07 2.52.3 EN How I manage Neovim configuration with Chezmoi 2024-09-15 2.52.2 EN Cross-Platform Dotfiles with Chezmoi, Nix, Brew, and Devpod 2024-09-09 2.52.2 EN Keeping your Dotfiles in Sync and your Secrets in Gopass 2024-09-08 2.52.1 EN Managing dotfiles with chezmoi 2024-08-30 2.52.1 JP dotfiles\u7ba1\u7406\u3092chezmoi\u306b\u79fb\u884c\u3059\u308b 2024-07-31 2.51.0 EN Managing dotfiles with chezmoi 2024-07-28 2.51.0 EN Development Environment Setup with Chezmoi 2024-06-26 2.49.1 EN Automate Your Dotfiles with Chezmoi 2024-05-27 2.48.1 EN Managing Dotfiles with Chezmoi 2024-05-01 2.48.0 TH \u0e08\u0e31\u0e14\u0e01\u0e32\u0e23 dotfiles \u0e14\u0e49\u0e27\u0e22 chezmoi 2024-04-27 2.48.0 CN \u4f7f\u7528 chezmoi & vscode, \u7ba1\u7406\u4f60\u7684 dotfiles 2024-04-24 2.47.4 EN Chezmoi: Manage Your Dotfiles Across Multiple Linux Systems 2024-03-25 2.47.2 EN Whatever happened to dotfiles? 2024-03-23 2.47.2 EN A tour around chezmoi 2024-03-23 2.47.2 CN \u4f7f\u7528 chezmoi & vscode, \u7ba1\u7406\u4f60\u7684 dotfiles 2024-03-11 2.47.1 CN Chezmoi\uff1a\u512a\u96c5\u7ba1\u7406Linux\u7684dotfile\uff0c\u4f7f\u7528Git\u5132\u5b58\u5eab\u5099\u4efd\uff0c\u985e\u4f3cGNU Stow 2024-03-02 2.47.0 EN The Ultimate Dotfiles Management Tool 2024-02-25 2.47.0 EN Atuin and chezmoi are the dog's bollocks 2024-01-07 2.43.0 EN Chezmore Chezmoi 2023-12-23 2.42.3 DE Lokale Kofigurationsdateien sicher mit chezmoi und Git synchronisieren 2023-12-18 2.42.3 JP chezmoi \u7ba1\u7406\u306edotfiles \u3067\u30de\u30b7\u30f3\u6bce\u306b\u8a2d\u5b9a\u3092\u5909\u3048\u305f\u3044 2023-12-17 2.42.3 JP chezmoi \u3092 \u30b5\u30d6\u30de\u30b7\u30f3\u306b\u3082\u5c0e\u5165\u3059\u308b 2023-12-16 2.42.3 JP chezmoi \u3092\u4f7f\u3063\u305f dotfiles \u306e\u7ba1\u7406\u65b9\u6cd5 2023-12-10 2.42.2 JP chezmoi \u3067 dotfiles \u3092\u7ba1\u7406\u3059\u308b\u3068\u304d\u306b\u4fbf\u5229\u306a\u6a5f\u80fd\u306b\u3064\u3044\u3066\u307e\u3068\u3081\u308b 2023-10-29 2.40.4 CN \u7528 chezmoi \u7ba1\u7406 dotfiles 2023-09-13 2.39.1 JP \u8907\u6570OS\u306b\u5bfe\u5fdc\u3057\u3066\u3044\u308bchezmoi\u3092\u4f7f\u3063\u3066dotfiles\u3092\u52b9\u7387\u7684\u306b\u7ba1\u7406\u3059\u308b 2023-09-07 2.39.1 JP \u3010chezmoi\u3011dotfile\u306e\u30bb\u30ad\u30e5\u30a2\u306a\u5024\u3092dashlane\u304b\u3089\u53c2\u7167\u3067\u304d\u308b\u3088\u3046\u306b\u3059\u308b 2023-08-05 2.36.1 EN Dotfiles with chezmoi 2023-06-14 2.34.1 RU chezmoi 2023-05-16 2.33.6 JP chezmoi 2023-04-29 2.33.1 JP chezmoi \u306e\u30c6\u30f3\u30d7\u30ec\u30fc\u30c8\u6a5f\u80fd\u3092\u4f7f\u3063\u3066\u30b7\u30a7\u30eb\u306e\u8d77\u52d5\u3092\u9ad8\u901f\u5316\u3059\u308b 2023-04-26 2.33.1 EN Managing my /home directory 2023-04-15 2.33.1 JP dotfiles \u306e\u7ba1\u7406\u306b chezmoi \u3092\u5c0e\u5165\u3057\u3066 fswatch \u3067\u81ea\u52d5 apply \u3067\u304d\u308b\u3088\u3046\u306b\u3057\u305fg 2023-04-08 2.33.1 KR chezmoi, \ubcf8\uaca9\uc801\uc73c\ub85c \ud65c\uc6a9\ud558\uae30 2023-03-25 2.33.0 KR chezmoi, \uc138\uc0c1 \ud3b8\ub9ac\ud558\uac8c dotfile \uad00\ub9ac\ud558\uae30 2023-03-17 2.32.0 EN Automating the Setup of a New Mac With All Your Apps, Preferences, and Development Tools 2023-03-21 2.32.0 JP AWS CLI \u306e\u30d7\u30ed\u30d5\u30a1\u30a4\u30eb\u3092 chezmoi \u3068Bitwarden \u3067\u7ba1\u7406\u3059\u308b 2023-02-26 2.31.0 EN Managing dotfiles with chezmoi 2023-01-22 2.29.3 EN Managing dotfiles 2023-01-22 2.29.3 JP dotfile manager \u306e chezmoi \u306b\u79fb\u884c\u3057\u3066\u307f\u308b 2023-01-13 2.29.1 EN Making the most out of distrobox and toolbx 2023-01-12 2.29.1 JP Chezmoi\u3067\u304b\u3093\u305f\u3093\u30af\u30ed\u30b9\u30d7\u30e9\u30c3\u30c8\u30d5\u30a9\u30fc\u30e0dotfiles\u7ba1\u7406\u306e\u30b9\u30b9\u30e1 2023-01-05 2.29.1 JP \u65e2\u5b58\u306e dotfiles \u3092 chezmoi \u3067\u7ba1\u7406\u3059\u308b 2022-09-28 2.24.0 EN Shit Hot Dotfiles 2022-09-13 2.22.1 IT Come installare Chezmoi: gestisci in modo sicuro i dotfile su pi\u00f9 macchine 2022-08-11 2.20.0 EN Chezmoi - a very cool tool to manage your dotfiles 2022-08-05 2.20.0 CN \u4f7f\u7528chezmoi\u7ba1\u7406dotfiles 2022-06-11 2.17.1 JP chezmoi \u3067 Linux \u3068 macOS \u4e21\u65b9\u3067\u4f7f\u3048\u308b dotfiles \u3092\u4f5c\u308b 2022-06-02 2.17.1 EN Local Env as Code: Is it possible yet 2022-05-16 2.16.0 EN Chezmoi for DotFiles 2022-04-25 2.15.1 EN Easily moving Linux installs 2022-03-13 2.14.0 EN Tools I love: Chezmoi 2022-03-03 2.13.0 EN Local Environment-as-Code: Is It Possible Yet? 2022-02-22 2.12.1 JP chezmoi \u3092\u4f7f\u3063\u3066 VSCode devcontainer \u5bfe\u5fdc dotfiles \u3092\u4f5c\u308b 2022-02-17 2.12.0 ES Qu\u00e9 son y c\u00f3mo gestionar archivos dotfiles con chezmoi 2022-02-12 2.11.2 EN How To Manage Dotfiles With Chezmoi 2022-02-02 2.11.0 FR Controler ses dotfiles en environnement \u00e9ph\u00e9m\u00e8re 2022-02-01 2.10.1 JP chezmoi \u3067 dotfiles \u3092\u624b\u8efd\u306b\u67d4\u8edf\u306b\u30bb\u30ad\u30e5\u30a2\u306b\u7ba1\u7406\u3059\u308b 2022-01-26 2.10.1 JP chezmoi \u3067 dotfiles \u3092\u7ba1\u7406\u3059\u308b 2022-01-12 2.9.5 IT Come funzionano i miei Mac 2021-12-23 2.9.3 EN Use Chezmoi to guarantee idempotency of terminal 2021-12-20 2.9.3 EN How chezmoi Implements Cross-Platform CI 2021-12-13 2.9.3 EN Managing Dotfiles With Chezmoi 2021-12-04 2.9.2 EN Advanced features of Chezmoi 2021-12-01 2.9.1 EN Chezmoi 2 2021-11-26 2.8.0 EN Weekly Journal 47 - chezmoi, neovim 2021-10-26 2.7.3 RU \u0421\u0438\u043d\u0445\u0440\u043e\u043d\u0438\u0437\u0430\u0446\u0438\u044f \u0441\u0438\u0441\u0442\u0435\u043c\u043d\u044b\u0445 \u043d\u0430\u0441\u0442\u0440\u043e\u0435\u043a 2021-10-25 2.7.3 EN Share credentials across machines using chezmoi and bitwarden 2021-09-18 2.1.2 EN PBS 125 of X \u2014 Chezmoi on Multiple Computers 2021-09-14 2.2.0 EN Managing preference plists under Chezmoi 2021-09-06 2.2.0 EN chezmoi dotfile management 2021-09-04 2.2.0 EN Configuration Management 2021-09-04 2.1.2 EN PBS 124 of X \u2014 Chezmoi Templates 2021-08-22 2.1.2 EN PBS 123 of X \u2014 Backing up and Syncing Dot Files with Chezmoi 2021-08-08 2.1.2 EN PBS 122 of X \u2014 Managing Dot Files with Chezmoi 2021-08-04 2.1.2 PT Como instalar o Chezmoi, um gerenciador de dotfiles, no Ubuntu, Linux Mint, Fedora, Debian 2021-07-23 2.1.2 EN PBS 121 of X \u2014 Managing Dot Files and an Introduction to Chezmoi 2021-07-15 2.1.2 CN \u4f7f\u7528Chezmoi\u7ba1\u7406\u914d\u7f6e\u6587\u4ef6 2021-05-14 2.0.12 EN A brief history of my dotfile management 2021-05-12 2.0.12 EN My Dotfiles Story: A Journey to Chezmoi 2021-05-10 2.0.11 EN Development Environment (2021) 2021-04-08 2.0.9 FR Bienvenue chez moi 2021-04-01 2.0.7 EN ChezMoi 2021-02-17 1.8.11 JP chezmoi \u3067 dotfiles \u3092\u624b\u8efd\u306b\u67d4\u8edf\u306b\u30bb\u30ad\u30e5\u30a2\u306b\u7ba1\u7406\u3059\u308b 2021-02-07 1.8.10 JP chezmoi\u59cb\u3081\u305f 2021-01-29 1.8.10 CN \u7528 Chezmoi \u7ba1\u7406\u914d\u7f6e\u6587\u4ef6 2021-01-12 1.8.10 EN Automating the Setup of a New Mac With All Your Apps, Preferences, and Development Tools 2020-11-06 1.8.8 EN Chezmoi \u2013 Securely Manage dotfiles across multiple machines 2020-11-05 1.8.8 EN Using chezmoi to manage dotfiles 2020-10-05 1.8.6 EN Dotfiles with Chezmoi 2020-10-03 1.8.6 EN Chezmoi Merging 2020-08-13 1.8.3 EN Using BitWarden and Chezmoi to manage SSH keys 2020-08-09 1.8.3 EN Automating and testing dotfiles 2020-08-03 1.8.3 EN Automating a Linux in Windows Dev Setup 2020-07-03 1.8.3 EN Feeling at home in a LXD container 2020-06-15 1.8.2 EN Dotfiles management using chezmoi - How I Use Linux Desktop at Work Part5 2020-04-27 1.8.0 EN Managing my dotfiles with chezmoi 2020-04-20 1.8.0 FR Gestion des dotfiles et des secrets avec chezmoi 2020-04-19 1.7.19 FR Git & dotfiles : versionner ses fichiers de configuration 2020-04-16 1.7.19 FR Chezmoi, visite guid\u00e9e 2020-04-17 1.7.17 CN \u7528 Chezmoi \u53d6\u56de\u4f60\u7684\u70b9\u6587\u4ef6 2020-04-03 1.7.17 EN Fedora Magazine: Take back your dotfiles with Chezmoi 2020-04-01 1.7.17 EN Managing dotfiles and secret with chezmoi 2019-01-10 0.0.11 EN Linux Fu: The kitchen sync"},{"location":"links/dotfile-repos/","title":"Dotfile repos","text":"
Recommended podcast: Managing Dot Files and an Introduction to Chezmoi
Date Version Language Title 2024-10-17 2.52.4 EN Releasing more BSDs 2023-05-22 2.33.6 ES 491 - Tres herramientas que han revolucionado mi terminal Linux 2023-01-30 2.29.3 ES 459 - Soy un zoquete, otra vez hice un rm -rf 2022-05-27 2.17.0 EN F\u00e9d\u00e9rer une communaut\u00e9 technique autour d'un projet Open Source 2022-03-11 2.14.0 EN The Real Python Podcast: Episode 101: Tools for Setting Up Python on a New Machine 2021-09-18 2.1.2 EN CCATP #699 \u2013 Bart Busschots on PBS 125 of X \u2013 Chezmoi on Multiple Computers 2021-09-04 2.1.2 EN CCATP #698 \u2013 Bart Busschots on PBS 124 of X \u2013 Chezmoi Templates 2021-08-22 2.1.2 EN CCATP #696 \u2013 Bart Busschots on PBS 123 of X \u2014 Backing up and Syncing Dot Files with Chezmoi 2021-08-08 2.1.2 EN CCATP #695 \u2013 Bart Busschots on PBS 122 \u2013 Managing Dot Files with Chezmoi 2021-07-23 2.1.2 EN CCATP #693 \u2013 Bart Busschots on PBS 121 of X \u2014 Managing Dot Files and an Introduction to Chezmoi 2019-11-20 1.7.2 EN FLOSS weekly episode 556: chezmoi"},{"location":"links/related-software/","title":"Related software","text":""},{"location":"links/related-software/#editor-integration","title":"Editor integration","text":""},{"location":"links/related-software/#githubcomandre-kotakenvim-chezmoi","title":"github.com/andre-kotake/nvim-chezmoi","text":"
An add-on to deal with config files that contain a mix of settings and transient state, such as with GUI program settings files also containing recently used files and window positions.
Recommended video: chezmoi: manage your dotfiles across multiple, diverse machines, securely
Date Version Language Title 2024-11-18 2.54.0 AR Chezmoi, Dotfiles, Workflow, Templates and Encryption Arabic \u0634\u0631\u062d 2024-06-22 2.47.1 EN Automating Development Environments with Ansible & Chezmoi 2024-02-17 2.47.0 EN 12 GREAT command line programs YOU recommended! 2024-01-14 2.24.0 EN managing dotfiles: a guided tour through my own setup 2023-12-03 2.42.2 EN The ultimate dotfiles setup 2022-12-15 2.27.3 ES Archivos de configuraci\u00f3n f\u00e1cil con chezmoi 2022-09-13 2.22.1 EN Using chezmoi to automate dotfiles / config files (+ my bashrc) 2022-04-27 2.15.1 EN Easily moving Linux installs 2021-12-08 2.9.3 EN How Go makes chezmoi possible 2021-11-27 2.8.0 TH Command \u0e44\u0e23 2021-11-27 : \u0e22\u0e49\u0e32\u0e22 dotfiles \u0e44\u0e1b chezmoi 2021-09-06 2.2.0 EN chezmoi: Organize your dotfiles across multiple computers 2021-02-06 1.8.10 EN chezmoi: manage your dotfiles across multiple, diverse machines, securely 2020-07-06 1.8.3 EN Conf42: chezmoi: Manage your dotfiles across multiple machines, securely 2020-03-12 1.7.16 EN Managing Dotfiles with ChezMoi 2019-11-20 1.7.2 EN FLOSS weekly episode 556: chezmoi"},{"location":"reference/","title":"Reference","text":"
Welcome to the reference section of the chezmoi documentation.
chezmoi is deterministic in its order of application. The order is:
Read the source state.
Read the destination state.
Compute the target state.
Run run_before_ scripts in alphabetical order.
Update entries in the target state (files, directories, externals, scripts, symlinks, etc.) in alphabetical order of their target name. Directories (including those created by externals) are updated before the files they contain.
Run run_after_ scripts in alphabetical order.
Target names are considered after all attributes are stripped.
Example
Given create_alpha and modify_dot_beta in the source state, .beta will be updated before alpha because .beta sorts before alpha.
chezmoi assumes that the source or destination states are not modified while chezmoi is being executed. This assumption permits significant performance improvements, including allowing chezmoi to only read files from the source and destination states if they are needed to compute the target state.
chezmoi's behavior when the above assumptions are violated is undefined. For example, using a run_before_ script to update files in the source or destination states violates the assumption that the source and destination states do not change while chezmoi is running.
Note
External sources are updated during the update phase; it is inadvisable for a run_before_ script to depend on an external applied during the update phase. run_after_ scripts may freely depend on externals.
chezmoi computes the target state for the current machine and then updates the destination directory, where:
The destination directory is the directory that chezmoi manages, usually your home directory, ~.
A target is a file, directory, or symlink in the destination directory.
The destination state is the current state of all the targets in the destination directory.
The source state declares the desired state of your home directory, including templates that use machine-specific data. It contains only regular files and directories.
The source directory is where chezmoi stores the source state. By default it is ~/.local/share/chezmoi.
The config file contains machine-specific data. By default it is ~/.config/chezmoi/chezmoi.toml.
The target state is the desired state of the destination directory. It is computed from the source state, the config file, and the destination state. The target state includes regular files and directories, and may also include symbolic links, scripts to be run, and targets to be removed.
The working tree is the git working tree. Normally it is the same as the source directory, but can be a parent of the source directory.
If you run chezmoi command where command is not a builtin chezmoi command then chezmoi will look for a binary called chezmoi-command in your $PATH. If such a binary is found then chezmoi will execute it. Otherwise, chezmoi will report an unknown command error.
chore: Bump golangci-lint to v1.51.2 by @twpayne in #2782
docs: Improve documentation on git-repo externals by @twpayne in #2785
chore: Update dependencies by @twpayne in #2788
chore: Enable most govet linters by @twpayne in #2794
chore: Update dependencies by @twpayne in #2795
feat: Add Dashlane password manager support by @twpayne in #2792
fix: Detect absolute paths in externals on Windows by @twpayne in #2796
feat: Add Dashlane secure notes support by @XaF in #2797
chore(deps): bump cpina/github-action-push-to-another-repository from 9e487f29582587eeb4837c0552c886bb0644b6b9 to 0a14457bb28b04dfa1652e0ffdfda866d2845c73 by @dependabot in #2802
chore(deps): bump github/codeql-action from 2.2.1 to 2.2.5 by @dependabot in #2803
chore(deps): bump actions/cache from 3.2.4 to 3.2.6 by @dependabot in #2804
feat: Improve handling of include and exclude for externals and encrypted files by @twpayne in #2451
feat: Extend --include and --exclude flags to include templates by @twpayne in #2455
feat: Add per-template configurable delimiters by @twpayne in #2457
chore: Fix user guide link in support issue template by @bradenhilton in #2464
chore(deps): bump github/codeql-action from 2.1.26 to 2.1.27 by @dependabot in #2459
docs: Update homepage by @twpayne in #2458
chore(deps): bump dorny/paths-filter from 2.10.2 to 2.11.1 by @dependabot in #2460
chore(deps): bump actions/cache from 3.0.9 to 3.0.11 by @dependabot in #2461
chore(deps): bump sigstore/cosign-installer from 2.7.0 to 2.8.0 by @dependabot in #2462
chore(deps): bump cpina/github-action-push-to-another-repository from 9e487f29582587eeb4837c0552c886bb0644b6b9 to 940a2857e598a6392bd336330b07416c1ae8ea1f by @dependabot in #2466
chore: Update dependencies by @twpayne in #2465
chore(deps): bump actions/checkout from 3.0.2 to 3.1.0 by @dependabot in #2463
chore: Tweak template directive implementation by @twpayne in #2467
chore: Miscellaneous fixes by @twpayne in #2469
feat: Add option to exclude scripts that are always run by @twpayne in #2473
fix: Extend template directives functionality by @halostatue in #2471
chore: Update dependencies by @twpayne in #2474
docs: Add faq entry for templates pre-requisites by @felipecrs in #2476
docs: Add release notes and release history by @twpayne in #2477
docs: Add note on setting .ps1 interpreter to pwsh by @bradenhilton in #2478
chore: Fix comments that start from an incorrect name by @alexandear in #2481
chore: Add package descriptions by @twpayne in #2485
fix: Include git repo external state in state dump output by @twpayne in #2487
docs: Add FAQ entry on snap stdin/stdout redirect bug by @twpayne in #2488
chore: Use fs.ModePerm instead of 0o777 for all permissions by @twpayne in #2489
chore: GitHub Actions fixes by @twpayne in #2492
docs(bitwarden): Correct bitwardenFields example by @choznerol in #2493
feat: Populate VERSIONINFO on Windows builds by @bradenhilton in #2479
chore: Update dependencies by @twpayne in #2494
docs: Remove duplicate words by @bradenhilton in #2497
chore: Improve error messages from git-repo externals by @twpayne in #2501
fix: Construct templateDataMap manually by @halostatue in #2503
feat: Add --recurse-submodules flag to init command by @twpayne in #2511
feat: Add --recurse-submodules flag to update command by @twpayne in #2512
chore: Reorder eqFold template function reference page by @bradenhilton in #2513
chore: Fix refactored --include and --exclude flags by @twpayne in #2514
chore: Add test for .chezmoiignore and scripts by @twpayne in #2515
chore: Update dependencies by @twpayne in #2516
chore: Minor documentation tweaks by @twpayne in #2518
chore: Release improvements by @twpayne in #2517
chore(deps): bump goreleaser/goreleaser-action from 3.1.0 to 3.2.0 by @dependabot in #2519
chore(deps): bump actions/upload-artifact from 3.1.0 to 3.1.1 by @dependabot in #2520
chore(deps): bump actions/setup-go from 3.3.0 to 3.3.1 by @dependabot in #2522
chore(deps): bump github/codeql-action from 2.1.27 to 2.1.29 by @dependabot in #2523
chore(deps): bump sigstore/cosign-installer from 2.8.0 to 2.8.1 by @dependabot in #2521
817d3e7 feat: Stop building snaps\\n ab6bc8d feat: Make add command add empty files, remove --empty flag\\n 755e02f fix: Don't return an error when the user chooses quit from a prompt\\n b554329 feat: Implement documented add --prompt flag\\n b95449f docs: Remove stray whitespace\\n ebeebcb docs: Add extra documentation to autotemplate\\n 991a630 docs: Clarify what 'source state' means\\n 2421da8 fix: Check .chezmoiversion in init command\\n 25b32fb feat: Give more context in Windows errors\\n 9605e40 feat: Make --autotemplate escape template markers\\n 2c89541 feat: Support determining FQDN via /etc/myname\\n 281e770 feat: Support multiple GPG recipients\\n cbed719 feat: Include git working tree state in doctor output\\n 87c1a91 docs: Use modeline to set filetype in VIM\\n 1af0576 feat: Include last modified time of config file in doctor output\\n 44762fd feat: Add quoteList template function\\n 2bf1210 feat: Add textconv configuration for friendlier binary diffs\\n 814f1f2 docs: Refactor Windows chassisType template\\n 7199cb2 docs: Add link to blog\\n d29344f fix: Improve quality of POSIX shell scripts\\n f2f8d87 docs: Add link to blog post\\n
"},{"location":"reference/source-state-attributes/","title":"Source state attributes","text":"
chezmoi stores the source state of files, symbolic links, and directories in regular files and directories in the source directory (~/.local/share/chezmoi by default). This location can be overridden with the -S flag or by giving a value for sourceDir in the configuration file. Directory targets are represented as directories in the source state. All other target types are represented as files in the source state. Some state is encoded in the source names.
The following prefixes and suffixes are special, and are collectively referred to as \"attributes\":
Prefix Effect after_ Run script after updating the destination before_ Run script before updating the destination create_ Ensure that the file exists, and create it with contents if it does not dot_ Rename to use a leading dot, e.g. dot_foo becomes .fooempty_ Ensure the file exists, even if is empty. By default, empty files are removed encrypted_ Encrypt the file in the source state external_ Ignore attributes in child entries exact_ Remove anything not managed by chezmoi executable_ Add executable permissions to the target file literal_ Stop parsing prefix attributes modify_ Treat the contents as a script that modifies an existing file once_ Only run the script if its contents have not been run before onchange_ Only run the script if its contents have not been run before with the same filename private_ Remove all group and world permissions from the target file or directory readonly_ Remove all write permissions from the target file or directory remove_ Remove the file or symlink if it exists or the directory if it is empty run_ Treat the contents as a script to run symlink_ Create a symlink instead of a regular file Suffix Effect .literal Stop parsing suffix attributes .tmpl Treat the contents of the source file as a template
Different target types allow different prefixes and suffixes. The order of prefixes is important.
Target type Source type Allowed prefixes in order Allowed suffixes Directory Directory remove_, external_, exact_, private_, readonly_, dot_ none Regular file File encrypted_, private_, readonly_, empty_, executable_, dot_.tmpl Create file File create_, encrypted_, private_, readonly_, empty_, executable_, dot_.tmpl Modify file File modify_, encrypted_, private_, readonly_, executable_, dot_.tmpl Remove file File remove_, dot_ none Script File run_, once_ or onchange_, before_ or after_.tmpl Symbolic link File symlink_, dot_.tmpl
The literal_ prefix and .literal suffix can appear anywhere and stop attribute parsing. This permits filenames that would otherwise conflict with chezmoi's attributes to be represented.
In addition, if the source file is encrypted, the suffix .age (when age encryption is used) or .asc (when gpg encryption is used) is stripped. These suffixes can be overridden with the age.suffix and gpg.suffix configuration variables.
chezmoi ignores all files and directories in the source directory that begin with a . with the exception of files and directories that begin with .chezmoi.
chezmoi will create, update, and delete files, directories, and symbolic links in the destination directory, and run scripts. chezmoi deterministically performs actions in ASCII order of their target name.
Example
Given a file dot_a, a script run_z, and a directory exact_dot_c, chezmoi will first create .a, create .c, and then execute run_z.
Files are represented by regular files in the source state. The encrypted_ attribute determines whether the file in the source state is encrypted. The executable_ attribute will set the executable bits in the target state, and the private_ attribute will clear all group and world permissions. The readonly_ attribute will clear all write permission bits in the target state. Files with the .tmpl suffix will be interpreted as templates. If the target contents are empty then the file will be removed, unless it has an empty_ prefix.
Files with the create_ prefix will be created in the target state with the contents of the file in the source state if they do not already exist. If the file in the destination state already exists then its contents will be left unchanged.
Files with the modify_ prefix are treated as scripts that modify an existing file.
If the file contains a line with the text chezmoi:modify-template then that line is removed and the rest of the script is executed template with the existing file's contents passed as a string in .chezmoi.stdin. The result of executing the template are the new contents of the file.
Otherwise, the contents of the existing file (which maybe empty if the existing file does not exist or is empty) are passed to the script's standard input, and the new contents are read from the script's standard output.
Directories are represented by regular directories in the source state. The exact_ attribute causes chezmoi to remove any entries in the target state that are not explicitly specified in the source state, and the private_ attribute causes chezmoi to clear all group and world permissions. The readonly_ attribute will clear all write permission bits.
Symbolic links are represented by regular files in the source state with the prefix symlink_. The contents of the file will have a trailing newline stripped, and the result be interpreted as the target of the symbolic link. Symbolic links with the .tmpl suffix in the source state are interpreted as templates. If the target of the symbolic link is empty or consists only of whitespace, then the target is removed.
Scripts are represented as regular files in the source state with prefix run_. The file's contents (after being interpreted as a template if it has a .tmpl suffix) are executed.
Scripts are executed on every chezmoi apply, unless they have the once_ or onchange_ attribute. run_once_ scripts are only executed if a script with the same contents has not been run before, i.e. if the script is new or if its contents have changed. run_onchange_ scripts are executed whenever their contents change, even if a script with the same contents has run before.
Scripts with the before_ attribute are executed before any files, directories, or symlinks are updated. Scripts with the after_ attribute are executed after all files, directories, and symlinks have been updated. Scripts without an before_ or after_ attribute are executed in ASCII order of their target names with respect to files, directories, and symlinks.
Scripts will normally run with their working directory set to their equivalent location in the destination directory. If the equivalent location in the destination directory either does not exist or is not a directory, then chezmoi will walk up the script's directory hierarchy and run the script in the first directory that exists and is a directory.
Example
A script in ~/.local/share/chezmoi/dir/run_script will be run with a working directory of ~/dir.
chezmoi sets a number of CHEZMOI* environment variables when running scripts, corresponding to commonly-used template data variables. Extra environment variables can be set in the env or scriptEnv configuration variables.
Scripts are executed using an interpreter, if configured. See the section on interpreters.
By default, chezmoi will create regular files and directories. Setting mode = \"symlink\" will make chezmoi behave more like a dotfile manager that uses symlinks by default, i.e. chezmoi apply will make dotfiles symlinks to files in the source directory if the target is a regular file and is not encrypted, executable, private, or a template.
"},{"location":"reference/command-line-flags/","title":"Command line flags","text":"
Command line flags override any values set in the configuration file.
"},{"location":"reference/command-line-flags/common/","title":"Common command line flags","text":"
The following flags apply to multiple commands where they are relevant.
Print paths in the given style. The default is relative.
Style Description absolute Absolute paths in the destination directory relative Relative paths to the destination directory source-absolute Absolute paths in the source tree directory source-relative Relative paths to the source tree directory all All path styles, indexed by relative"},{"location":"reference/command-line-flags/common/#-r-recursive","title":"-r, --recursive","text":"
You can provide a list of entry types, separated by commas. Types can be preceded with no to remove them, e.g. scripts,noalways.
Type Description all All entries none No entries dirs Directories files Files remove Removes scripts Scripts symlinks Symbolic links always Scripts that are always run encrypted Encrypted entries externals External entries templates Templates"},{"location":"reference/command-line-flags/developer/","title":"Developer command line flags","text":"
The following flags are global but only relevant for developers and debugging.
Colorize diffs, value can be on, off, auto, or any boolean-like value recognized by promptBool. The default is auto which will colorize diffs only if the environment variable $NO_COLOR is not set and stdout is a terminal.
Assume the configuration file is in the given format. This is only needed if the config filename does not have an extension, for example when it is /dev/stdin. Supported formats: json, jsonc, toml, yaml.
Set dry run mode. In dry run mode, the destination directory is never modified. This is most useful in combination with the -v (verbose) flag to print changes that would be made without making them.
Read and write the persistent state from filename. By default, chezmoi stores its persistent state in chezmoistate.boltdb in the same directory as its configuration file.
Control the refresh of the externals cache. value can be any of always, auto, or never and defaults to always if no value is specified. If no --refresh-externals flag is specified then chezmoi defaults to auto.
always (or any truthy value as accepted by parseBool) causes chezmoi to re-download externals.
auto means only re-download externals that have not been downloaded within their refresh periods.
never (or any other falsey value accepted by parseBool) means only download if no cached external is available.
Use chezmoi's builtin age encryption instead of an external age command. value can be on, off, auto, or any boolean-like value recognized by promptBool. The default is auto which will only use the builtin age if age.command cannot be found in $PATH.
The builtin age command does not support passphrases, symmetric encryption, or the use of SSH keys.
Use chezmoi's builtin git instead of git.command for the init and update commands. value can be on, off, auto, or any boolean-like value recognized by promptBool. The default is auto which will only use the builtin git if git.command cannot be found in $PATH.
Info
chezmoi's builtin git has only supports the HTTP and HTTPS transports and does not support git-repo externals.
Set verbose mode. In verbose mode, chezmoi prints the changes that it is making as approximate shell commands, and any differences in files between the target state and the destination set are printed as unified diffs.
Use directory as the git working tree directory. By default, chezmoi searches the source directory and then its ancestors for the first directory that contains a .git directory.
Add targets to the source state. If any target is already in the source state, then its source state is replaced with its current state in the destination directory.
Automatically generate a template by replacing strings that match variable values from the data section of the config file with their respective config names as a template string. Longer substitutions occur before shorter ones. This implies the --template option.
Warning
--autotemplate uses a greedy algorithm which occasionally generates templates with unwanted variable substitutions. Carefully review any templates it generates.
When adding symlink to an absolute path in the source directory or destination directory, create a symlink template with .chezmoi.sourceDir or .chezmoi.homeDir. This is useful for creating portable absolute symlinks.
Ensure that target... are in the target state, updating them if necessary. If no targets are specified, the state of all targets are ensured. If a target has been modified since chezmoi last wrote it then the user will be prompted if they want to overwrite the file.
Write the target contents of targets to stdout. targets must be files, scripts, or symlinks. For files, the target file contents are written. For scripts, the script's contents are written. For symlinks, the target is written.
Launch a shell in the working tree (typically the source directory). chezmoi will launch the command set by the cd.command configuration variable with any extra arguments specified by cd.args. If this is not set, chezmoi will attempt to detect your shell and finally fall back to an OS-specific default.
If the optional argument path is present, the shell will be launched in the source directory corresponding to path.
The shell will have various CHEZMOI* environment variables set, as for scripts.
Hint
This does not change the current directory of the current shell. To do that, instead use:
Change the attributes and/or type of targets. modifier specifies what to modify.
Add attributes by specifying them or their abbreviations directly, optionally prefixed with a plus sign (+). Remove attributes by prefixing them or their attributes with the string no or a minus sign (-). The available attribute modifiers and their abbreviations are:
The type of a target can be changed using a type modifier:
Type modifier createmodifyscriptsymlink
The negative form of type modifiers, e.g. nocreate, changes the target to be a regular file if it is of that type, otherwise the type is left unchanged.
Multiple modifications may be specified by separating them with a comma (,). If you use the -modifier form then you must put modifier after a -- to prevent chezmoi from interpreting -modifier as an option.
Decrypt files using chezmoi's configured encryption. If no files are given, decrypt the standard input. The decrypted result is written to the standard output or a file if the --output flag is set.
Print the difference between the target state and the destination state for targets. If no targets are specified, print the differences for all targets.
If a diff.pager command is set in the configuration file then the output will be piped into it.
If diff.command is set then it will be invoked to show individual file differences with diff.args passed as arguments. Each element of diff.args is interpreted as a template with the variables .Destination and .Target available corresponding to the path of the file in the source and target state respectively. The default value of diff.args is [\"{{ .Destination }}\", \"{{ .Target }}\"]. If diff.args does not contain any template arguments then {{ .Destination }} and {{ .Target }} will be appended automatically.
Edit the configuration file template. If no configuration file template exists, then a new one is created with the contents of the current config file.
Edit the source state of targets, which must be files or symlinks. If no targets are given then the working tree of the source directory is opened.
Encrypted files are decrypted to a private temporary directory and the editor is invoked with the decrypted file. When the editor exits the edited decrypted file is re-encrypted and replaces the original file in the source state.
If the operating system supports hard links, then the edit command invokes the editor with filenames which match the target filename, unless the edit.hardlink configuration variable is set to false or the --hardlink=false command line flag is set.
Invoke the editor with a hard link to the source file with a name matching the target filename. This can help the editor determine the type of the file correctly. This is the default.
Encrypt files using chezmoi's configured encryption. If no files are given, encrypt the standard input. The encrypted result is written to the standard output or a file if the --output flag is set.
Execute templates. This is useful for testing templates or for calling chezmoi from other scripts. templates are interpreted as literal templates, with no whitespace added to the output between arguments. If no templates are specified, the template is read from stdin.
Simulate the promptBool template function with a function that returns values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptBool is called with a prompt that does not match any of pairs, then it returns false.
Simulate the promptChoice template function with a function that returns values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptChoice is called with a prompt that does not match any of pairs, then it returns false.
Simulate the promptInt template function with a function that returns values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptInt is called with a prompt that does not match any of pairs, then it returns zero.
Simulate the promptString template function with a function that returns values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptString is called with a prompt that does not match any of pairs, then it returns prompt unchanged.
Generates output for use with chezmoi. The currently supported outputs are:
Output Description git-commit-message A git commit message, describing the changes to the source directory. install.sh An install script, suitable for use with GitHub Codespaces"},{"location":"reference/commands/generate/#examples","title":"Examples","text":"
Import the source state from an archive file in to a directory in the source state. This is primarily used to make subdirectories of your home directory exactly match the contents of a downloaded archive. You will generally always want to set the --destination, --exact, and --remove-destination flags.
The supported archive formats are tar, tar.gz, tgz, tar.bz2, tbz2, txz, tar.zst, and zip.
Setup the source directory, generate the config file, and optionally update the destination directory to match the target state.
By default, if repo is given, chezmoi will guess the full git repo URL, using HTTPS by default, or SSH if the --ssh option is specified, according to the following patterns:
To disable git repo URL guessing, pass the --guess-repo-url=false option.
First, if the source directory does not already contain a repository, then if repo is given, it is checked out into the source directory; otherwise a new repository is initialized in the source directory.
Second, if a file called .chezmoi.$FORMAT.tmpl exists, where $FORMAT is one of the supported file formats (e.g. json, jsonc, toml, or yaml) then a new configuration file is created using that file as a template.
Then, if the --apply flag is passed, chezmoi apply is run.
Then, if the --purge flag is passed, chezmoi will remove its source, config, and cache directories.
Finally, if the --purge-binary is passed, chezmoi will attempt to remove its own binary.
Include existing template data when creating the config file. This defaults to true. Set this to false to simulate creating the config file with no existing template data.
--one-shot is the equivalent of --apply, --depth=1, --force, --purge, and --purge-binary. It attempts to install your dotfiles with chezmoi and then remove all traces of chezmoi from the system. This is useful for setting up temporary environments (e.g. Docker containers).
Populate the promptBool template function with values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptBool is called with a prompt that does not match any of pairs, then it prompts the user for a value.
Populate the promptChoice template function with values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptChoice is called with a prompt that does not match any of pairs, then it prompts the user for a value.
Populate the promptInt template function with values from pairs. pairs is a comma-separated list of prompt=value pairs. If prompInt is called with a prompt that does not match any of pairs, then it prompts the user for a value.
Populate the promptString template function with values from pairs. pairs is a comma-separated list of prompt=value pairs. If promptString is called with a prompt that does not match any of pairs, then it prompts the user for a value.
List all managed entries in the destination directory under all paths in alphabetical order. When no paths are supplied, list all managed entries in the destination directory in alphabetical order.
Print paths in the given style. The default is relative.
Style Description absolute Absolute paths in the destination directory relative Relative paths to the destination directory source-absolute Absolute paths in the source tree directory source-relative Relative paths to the source tree directory all All path styles, indexed by relative"},{"location":"reference/commands/managed/#-t-tree","title":"-t, --tree","text":"
Perform a three-way merge between the destination state, the target state, and the source state for each target. The merge tool is defined by the merge.command configuration variable, and defaults to vimdiff. If multiple targets are specified the merge tool is invoked separately and sequentially for each target. If the target state cannot be computed (for example if source is a template containing errors or an encrypted file that cannot be decrypted) a two-way merge is performed instead.
The order of arguments to merge.command is set by merge.args. Each argument is interpreted as a template with the variables .Destination, .Source, and .Target available corresponding to the path of the file in the destination state, the source state, and the target state respectively. The default value of merge.args is [\"{{ .Destination }}\", \"{{ .Source }}\", \"{{ .Target }}\"]. If merge.args does not contain any template arguments then {{ .Destination }}, {{ .Source }}, and {{ .Target }} will be appended automatically.
Re-add modified files in the target state, preserving any encrypted_ attributes. chezmoi will not overwrite templates, and all entries that are not files are ignored. Directories are recursed into by default.
If no targets are specified then all modified files are re-added. If one or more targets are given then only those targets are re-added.
Run a secret manager's CLI, passing any extra arguments to the secret manager's CLI. This is primarily for verifying chezmoi's integration with a custom secret manager. Normally you would use chezmoi's existing template functions to retrieve secrets.
Note
If you need to pass flags to the secret manager's CLI you must separate them with -- to prevent chezmoi from interpreting them.
On FreeBSD, the secret keyring command is only available if chezmoi was compiled with cgo enabled. The official release binaries of chezmoi are not compiled with cgo enabled, and secret keyring command is not available.
chezmoi state data\nchezmoi state delete --bucket=$BUCKET --key=$KEY\nchezmoi state delete-bucket --bucket=$BUCKET\nchezmoi state dump\nchezmoi state get --bucket=$BUCKET --key=$KEY\nchezmoi state get-bucket --bucket=$BUCKET\nchezmoi state set --bucket=$BUCKET --key=$KEY --value=$VALUE\nchezmoi state reset\n
Print the status of the files and scripts managed by chezmoi in a format similar to git status.
The first column of output indicates the difference between the last state written by chezmoi and the actual state. The second column indicates the difference between the actual state and the target state, and what effect running chezmoi apply will have.
Character Meaning First column Second column Space No change No change No change A Added Entry was created Entry will be created D Deleted Entry was deleted Entry will be deleted M Modified Entry was modified Entry will be modified R Run Not applicable Script will be run"},{"location":"reference/commands/status/#common-flags","title":"Common flags","text":""},{"location":"reference/commands/status/#-x-exclude-types","title":"-x, --exclude types","text":"
Exclude target state entries of specific types. The default is none.
Types can be explicitly included with the --include flag.
Example
--exclude=scripts will cause the command to not run scripts and --exclude=encrypted will exclude encrypted files.
Print paths in the given style. The default is relative.
Style Description absolute Absolute paths in the destination directory relative Relative paths to the destination directory source-absolute Absolute paths in the source tree directory source-relative Relative paths to the source tree directory all All path styles, indexed by relative"},{"location":"reference/commands/status/#-r-recursive","title":"-r, --recursive","text":"
Recurse into subdirectories. Enabled by default. Can be disabled with --recursive=false.
Print paths in the given style. The default is relative.
Style Description absolute Absolute paths in the destination directory relative Relative paths to the destination directory"},{"location":"reference/commands/unmanaged/#-t-tree","title":"-t, --tree","text":"
Pull changes from the source repo and apply any changes.
If update.command is set then chezmoi will run update.command with update.args in the working tree. Otherwise, chezmoi will run git pull --autostash --rebase [--recurse-submodules] , using chezmoi's builtin git if useBuiltinGit is true or if git.command cannot be found in $PATH.
Upgrade chezmoi by downloading and installing the latest released version. This will call the GitHub API to determine if there is a new version of chezmoi available, and if so, download and attempt to install it in the same way as chezmoi was previously installed.
If the any of the $CHEZMOI_GITHUB_ACCESS_TOKEN, $CHEZMOI_GITHUB_TOKEN, $GITHUB_ACCESS_TOKEN, or $GITHUB_TOKEN environment variables are set, then the first value found will be used to authenticate requests to the GitHub API, otherwise unauthenticated requests are used which are subject to stricter rate limiting. Unauthenticated requests should be sufficient for most cases.
Warning
If you installed chezmoi using a package manager, the upgrade command might have been removed by the package maintainer.
Override the upgrade method that was automatically detected by chezmoi.
Danger
This flag should only be used when recommended by chezmoi developers.
Methods Description brew-upgrade Run brew upgrade chezmoi. replace-executable Download the latest released executable from Github. snap-refresh Run snap refresh chezmoi. sudo-upgrade-package Same as upgrade-package but use sudo. upgrade-package Download and install .apk, .deb or .rpm package. Run pacman on Arch Linux."},{"location":"reference/commands/verify/","title":"verify [target...]","text":"
Verify that all targets match their target state. chezmoi exits with code 0 (success) if all targets match their target state, or 1 (failure) otherwise. If no targets are specified then all targets are checked.
chezmoi searches for its configuration file according to the XDG Base Directory Specification and supports JSON, JSONC, TOML, and YAML. The basename of the config file is chezmoi. If multiple configuration file formats are present, chezmoi will report an error.
In most installations, the config file will be read from $HOME/.config/chezmoi/chezmoi.$FORMAT (%USERPROFILE%/.config/chezmoi/chezmoi.$FORMAT), where $FORMAT is one of json, jsonc, toml, or yaml. The config file can be set explicitly with the --config command line option. By default, the format is detected based on the extension of the config file name, but can be overridden with the --config-format command line option.
The editor used is the first non-empty string of the edit.command configuration variable, the $VISUAL environment variable, the $EDITOR environment variable. If none are set then chezmoi falls back to notepad.exe on Windows systems and vi on non-Windows systems.
When the edit.command configuration variable is used, extra arguments can be passed to the editor with the edit.args configuration variable.
chezmoi will emit a warning if the editor returns in less than edit.minDuration (default 1s). To disable this warning, set edit.minDuration to 0.
Hook commands are executed before and after events. Unlike scripts, hooks are always run, even if --dry-run is specified. Hooks should be fast and idempotent.
The following events are defined:
Event Trigger command, e.g. add Running chezmoi command, e.g. chezmoi addgit-auto-commit Generating an automatic git commit git-auto-push Running an automatic git push read-source-state Reading the source state
Each event can have a .pre and/or a .post command. The event.pre command is executed before event occurs and the event.post command is executed after event has occurred.
A command contains a command or script and an optional array of strings args. commands are executed directly. scripts are executed with configured interpreter for the script's extension, see the section on interpreters.
When running hooks, the CHEZMOI=1 and CHEZMOI_* environment variables will be set. CHEZMOI_COMMAND is set to the chezmoi command being run, CHEZMOI_COMMAND_DIR is set to the directory where chezmoi was run from, and CHEZMOI_ARGS contains the full arguments to chezmoi, starting with the path to chezmoi's executable.
The execution of scripts and hooks on Windows depends on the file extension. Windows will natively execute scripts with a .bat, .cmd, .com, and .exe extensions. Other extensions require an interpreter, which must be in your %PATH%.
Script interpreters can be added or overridden by adding the corresponding extension (without the leading dot) as a key under the interpreters section of the configuration file.
Note
The leading . is dropped from extension, for example to specify the interpreter for .pl files you configure interpreters.pl (where . in this case just means \"a child of\" in the configuration file, however that is specified in your preferred format).
Example
To change the Python interpreter to C:\\Python39\\python3.exe and add a Tcl/Tk interpreter, include the following in your config file:
Note that the TOML version can also be written like this, which resembles the YAML version more and makes it clear that the key for each file extension should not have a leading .:
If the script in the source state is a template (with a .tmpl extension), then chezmoi will strip the .tmpl extension and use the next remaining extension to determine the interpreter to use.
By default, chezmoi will request passwords from the terminal.
If the --no-tty option is passed, then chezmoi will instead read passwords from the standard input.
Otherwise, if the configuration variable pinentry.command is set then chezmoi will instead used the given command to read passwords, assuming that it follows the Assuan protocol like GnuPG's pinentry. The configuration variable pinentry.args specifies extra arguments to be passed to pinentry.command and the configuration variable pinentry.options specifies extra options to be set. The default pinentry.options is [\"allow-external-password-cache\"].
A section called textconv in the configuration file controls how file contents are modified before being passed to diff.
The textconv must contain an array of objects where each object has the following properties:
Name Type Description pattern string Target path pattern to match command string Command to transform contents args []string Extra arguments to command
Files whose target path matches pattern are transformed by passing them to the standard input of command with args, and new contents are read from the command's standard output.
If a target path does not match any patterns then the file contents are passed unchanged to diff. If a target path matches multiple patterns then element with the longest pattern is used.
By default, chezmoi uses your current umask as set by your operating system and shell. chezmoi only stores crude permissions in its source state, namely in the executable and private attributes, corresponding to the umasks of 0o111 and 0o077 respectively.
For machine-specific control of umask, set the umask configuration variable in chezmoi's configuration file.
The following configuration variables are available:
Section Variable Type Default value Description Top level cacheDir string $XDG_CACHE_HOME/chezmoi$HOME/.cache/chezmoi%USERPROFILE%/.cache/chezmoi Cache directory color string auto Colorize output data object none Template data destDir string $HOME%USERPROFILE% Destination directory encryption string none Encryption type, either age or gpgenv object none Extra environment variables for scripts and commands format string json Format for data output, either json or yamlinteractive string false Prompt for all changes mode string file Mode in target dir, either file or symlinkpager string $PAGER Default pager CLI command persistentState string $XDG_CONFIG_HOME/chezmoi/chezmoi.boltdb$HOME/.config/chezmoi/chezmoi.boltdb%USERPROFILE%/.config/chezmoi/chezmoi.boltdb Location of the persistent state file progress bool false Display progress bars scriptEnv object none Extra environment variables for scripts and commands scriptTempDir string none Temporary directory for scripts sourceDir string $XDG_SHARE_HOME/chezmoi$HOME/.local/share/chezmoi%USERPROFILE%/.local/share/chezmoi Source directory tempDir string from system Temporary directory umask int from system Umask useBuiltinAge string auto Use builtin age if age command is not found in $PATHuseBuiltinGit string auto Use builtin git if git command is not found in $PATHverbose bool false Make output more verbose workingTree string source directory git working tree directory addencrypt bool false Encrypt by default secrets string warning Action when secrets are found when adding files templateSymlinks bool false Template symlinks to source and home dirs ageargs []string none Extra args to age CLI command command string age age CLI command identities []string none age identity files identity string none age identity file passphrase bool false Use age passphrase instead of identity recipient string none age recipient recipients []string none age recipients recipientsFile string none age recipients file recipientsFiles []string none age recipients files suffix string .age Suffix appended to age-encrypted files symmetric bool false Use age symmetric encryption awsSecretsManagerprofile string none AWS shared profile name region string none AWS region azureKeyVaultdefaultVault string none Default Azure Key Vault name bitwardencommand string bw Bitwarden CLI command bitwardenSecretscommand string bws Bitwarden Secrets CLI command cdargs []string none Extra args to shell in cd command command string none Shell to run in cd command completioncustom bool false Enable custom shell completions dashlaneargs []string none Extra args to Dashlane CLI command command string dcli Dashlane CLI command diffargs []string see diff Extra args to external diff command command string none External diff command exclude []string none Entry types to exclude from diffs pager string none Diff-specific pager reverse bool false Reverse order of arguments to diff scriptContents bool true Show script contents dopplerargs []string none Extra args to Doppler CLI command command string doppler Doppler CLI command config string none Default config (aka environment) if none is specified project string none Default project name if none is specified editapply bool false Apply changes on exit args []string none Extra args to edit command command string $EDITOR / $VISUAL Edit command hardlink bool true Invoke editor with a hardlink to the source file minDuration duration 1s Minimum duration for edit command watch bool false Automatically apply changes when files are saved ejsonkey string none The private key to use for decryption, will supersede using the keyDir if set. keyDir string none Path to directory containing private keys. Defaults to /opt/ejson/keys. Setting the EJSON_KEYDIR environment will also set this value, with lower precedence. gitautoAdd bool false Add changes to the source state after any change autoCommit bool false Commit changes to the source state after any change autoPush bool false Push changes to the source state after any change command string git git CLI command commitMessageTemplate string none Commit message template commitMessageTemplateFile string none Commit message template file (relative to source directory) lfs bool false Run git lfs pull after cloning gitHubrefreshPeriod duration 1m Minimum duration between identical GitHub API requests gopasscommand string gopass gopass CLI command mode string none See gopass functions gpgargs []string none Extra args to GPG CLI command command string gpg GPG CLI command recipient string none GPG recipient recipients []string none GPG recipients suffix string .asc Suffix appended to GPG-encrypted files symmetric bool false Use symmetric GPG encryption hcpVaultSecretsapplicationName string none Default application name if none is specified args []string none Extra args to HCP Vault Secrets CLI command command string vlt HCP Vault Secrets CLI command organizationId string none Default organization ID if none is specified projectId string none Default project ID if none is specified hooks command.post.args []string none Extra arguments to command to run after command command.post.command []string none Command to run after command command.pre.args []string none Extra arguments to command to run before command command.pre.command []string none Command to run before command interpreters extension.args []string none See Interpreters extension.command string special See Interpreters keepassxcargs []string none Extra args to KeePassXC CLI command command string keepassxc-cli KeePassXC CLI command database string none KeePassXC database mode string cache-password See KeePassXC functions prompt bool true Prompt for password keeperargs []string none Extra args to Keeper CLI command command string keeper Keeper CLI command lastpasscommand string lpass LastPass CLI command mergeargs []string See merge Extra args to three-way merge CLI command command string none Three-way merge CLI command onepasswordcache bool true Enable optional caching provided by opcommand string op 1Password CLI command mode string account See 1Password Secrets Automation prompt bool true Prompt for sign-in when no valid session is available onepasswordSDKtoken string none See 1Password SDK functions tokenEnvVar string none See 1Password SDK functions passcommand string pass Pass CLI command passholeargs []string none Extra args to Passhole CLI command command string ph Passhole CLI command prompt bool true Prompt for password pinentryargs []string none Extra args to pinentry CLI command command string none pinentry CLI command options []string See pinentry Extra options for pinentry rbwcommand string rbw Unofficial Bitwarden CLI command secretargs []string none Extra args to secret CLI command command string none Generic secret CLI command statusexclude []string none Entry types to exclude from status pathStyle string relative How to present the path to files in status output templateoptions []string [\"missingkey=error\"] Template options textconv []object none See textconv updateapply bool true Apply after pulling args []string none Extra args to update command command string none Update command recurseSubmodules bool true Update submodules recursively vaultcommand string vault Vault CLI command verifyexclude []string none Entry types to exclude from verify warnings object none See Warnings"},{"location":"reference/configuration-file/warnings/","title":"Warnings","text":"
By default, chezmoi will warn you when it encounters potential problems. Some of these warnings can be suppressed by setting values in configuration file.
Variable Type Default Description configFileTemplateHasChanged bool true Warn when the config file template has changed
All directories in the source state whose name begins with . are ignored by default, unless they are one of the special directories listed here. .chezmoitemplates is read before all other files so that they can be used in templates.
If a directory called .chezmoidata exists in the source state, then all files in it are interpreted as template data in the format given by their extension.
If a directory called .chezmoiscripts exists in the root of the source directory then any scripts in it are executed as normal scripts without creating a corresponding directory in the target state.
If a directory called .chezmoitemplates exists, then all files in this directory are available as templates with a name equal to the relative path to the .chezmoitemplates directory.
The template action can be used to include these templates in another template. The value of . must be set explicitly if needed, otherwise the template will be executed with nil data.
All files in the source state whose name begins with . are ignored by default, unless they are one of the special files listed here. .chezmoidata.$FORMAT is read before all other files so that it can be used in templates.
If a file called .chezmoi.$FORMAT.tmpl exists then chezmoi init will use it to create an initial config file. $FORMAT must be one of the supported config file formats, e.g. json, jsonc, toml, or yaml. Templates defined in .chezmoitemplates are not available because the template is executed before the source state is read.
If a file called .chezmoiexternal.$FORMAT (with an optional .tmpl extension) exists anywhere in the source state (either ~/.local/share/chezmoi or directory defined inside .chezmoiroot), it is interpreted as a list of external files and archives to be included as if they were in the source state.
$FORMAT must be one of chezmoi's supported configuration file formats, e.g. json, jsonc, toml, or yaml.
.chezmoiexternal.$FORMAT is interpreted as a template. This allows different externals to be included on different machines.
If a .chezmoiexternal.$FORMAT file is located in an ignored directory (one listed in .chezmoiignore), all entries within the file are also ignored.
Entries are indexed by target name relative to the directory of the .chezmoiexternal.$FORMAT file, and must have a type and a url and/or a urls field. type can be either file, archive, archive-file, or git-repo. If the entry's parent directories do not already exist in the source state then chezmoi will create them as regular directories.
Entries may have the following fields:
Variable Type Default value Description type string none External type (file, archive, archive-file, or git-repo) decompress string none Decompression for file encrypted bool false Whether the external is encrypted exact bool false Add exact_ attribute to directories in archive exclude []string none Patterns to exclude from archive executable bool false Add executable_ attribute to file private bool false Add private_ attribute to file readonly bool false Add readonly_ attribute to file format string autodetect Format of archive path string none Path to file in archive include []string none Patterns to include from archive refreshPeriod duration 0 Refresh period stripComponents int 0 Number of leading directory components to strip from archives url string none URL urls []string none Extra URLs to try, in order checksum.sha256 string none Expected SHA256 checksum of data checksum.sha384 string none Expected SHA384 checksum of data checksum.sha512 string none Expected SHA512 checksum of data checksum.size int none Expected size of data clone.args []string none Extra args to git clonefilter.command string none Command to filter contents filter.args []string none Extra args to command to filter contents pull.args []string none Extra args to git pullarchive.extractAppleDouble bool false If true, AppleDouble files are extracted
url must be an https://, http://, or file:// URL. If urls is specified then they are tried in order and the first URL that succeeds is used.
If any of the optional checksum.sha256, checksum.sha384, or checksum.sha512 fields are set, chezmoi will verify that the downloaded data has the given checksum.
The optional boolean encrypted field specifies whether the file or archive is encrypted.
The optional string decompress specifies how the file should be decompressed. Supported compression formats are bzip2, gzip, xz, and zstd. Note the .zip files are archives and you must use the archive-file type to extract a single file from a .zip archive.
If optional string filter.command and array of strings filter.args are specified, the file or archive is filtered by piping it into the command's standard input and reading the command's standard output.
If type is file then the target is a file with the contents of url. The optional boolean field executable may be set, in which case the target file will be executable.
If type is archive then the target is a directory with the contents of the archive at url. The optional boolean field exact may be set, in which case the directory and all subdirectories will be treated as exact directories, i.e. chezmoi apply will remove entries not present in the archive. The optional integer field stripComponents will remove leading path components from the members of archive. The optional string field format sets the archive format. The supported archive formats are tar, tar.gz, tgz, tar.bz2, tbz2, xz, .tar.zst, and zip. If format is not specified then chezmoi will guess the format using firstly the path of the URL and secondly its contents.
When type is archive or archive-file, the optional setting archive.extractAppleDouble controls whether AppleDouble files are extracted. It is false by default, so AppleDouble files will not be extracted.
The optional include and exclude fields are lists of patterns specify which archive members to include or exclude respectively. Patterns match paths in the archive, not the target state. chezmoi uses the following algorithm to determine whether an archive member is included:
If the archive member name matches any exclude pattern, then the archive member is excluded. In addition, if the archive member is a directory, then all contained files and sub-directories will be excluded, too (recursively).
Otherwise, if the archive member name matches any include pattern, then the archive member is included.
Otherwise, if only include patterns were specified then the archive member is excluded.
Otherwise, if only exclude patterns were specified then the archive member is included.
Otherwise, the archive member is included.
Excluded archive members do not generate source state entries, and, if they are directories, all of their children are also excluded.
If type is archive-file then the target is a file or symlink with the contents of the entry path in the archive at url. The optional integer field stripComponents will remove leading path components from the members of the archive before comparing them with path. The behavior of format is the same as for archive. If executable is true then chezmoi will set the executable bits on the target file, even if they are not set in the archive.
If type is git-repo then chezmoi will run git clone $URL $TARGET_NAME with the optional clone.args if the target does not exist. If the target exists, then chezmoi will run git pull with the optional pull.args to update the target.
For file and archive externals, chezmoi will cache downloaded URLs. The optional duration refreshPeriod field specifies how often chezmoi will re-download the URL. The default is zero meaning that chezmoi will never re-download unless forced. To force chezmoi to re-download URLs, pass the -R/--refresh-externals flag. Suitable refresh periods include one day (24h), one week (168h), or four weeks (672h).
If a file called .chezmoiignore (with an optional .tmpl extension) exists in the source state then it is interpreted as a set of patterns to ignore. Patterns are matched using doublestar.Match and match against the target path, not the source path.
Patterns can be excluded by prefixing them with a ! character. All excludes take priority over all includes.
Comments are introduced with the # character and run until the end of the line.
.chezmoiignore is interpreted as a template, whether or not it has a .tmpl extension. This allows different files to be ignored on different machines.
.chezmoiignore files in subdirectories apply only to that subdirectory.
Example
~/.local/share/chezmoi/.chezmoiignore
README.md\n\n*.txt # ignore *.txt in the target directory\n*/*.txt # ignore *.txt in subdirectories of the target directory\n # but not in subdirectories of subdirectories;\n # so a/b/c.txt would *not* be ignored\n\nbackups/ # ignore the backups folder, but not its contents\nbackups/** # ignore the contents of backups folder but not the folder itself\n\n{{- if ne .email \"firstname.lastname@company.com\" }}\n# Ignore .company-directory unless configured with a company email\n.company-directory # note that the pattern is not dot_company-directory\n{{- end }}\n\n{{- if ne .email \"me@home.org\" }}\n.personal-file\n{{- end }}\n
If a file called .chezmoiremove (with an optional .tmpl extension) exists in the source state then it is interpreted as a list of targets to remove. .chezmoiremove is interpreted as a template, whether or not it has a .tmpl extension.
If a file called .chezmoiroot exists in the root of the source directory then the source state is read from the directory specified in .chezmoiroot interpreted as a relative path to the source directory. .chezmoiroot is read before all other files in the source directory.
If a file called .chezmoiversion exists, then its contents are interpreted as a semantic version defining the minimum version of chezmoi required to interpret the source state correctly. chezmoi will refuse to interpret the source state if the current version is too old.
chezmoi executes templates using text/template. The result is treated differently depending on whether the target is a file or a symlink.
If target is a file, then:
If the result is an empty string, then the file is removed.
Otherwise, the target file contents are result.
If the target is a symlink, then:
Leading and trailing whitespace are stripped from the result.
If the result is an empty string, then the symlink is removed.
Otherwise, the target symlink target is the result.
chezmoi executes templates using text/template's missingkey=error option, which means that misspelled or missing keys will raise an error. This can be overridden by setting a list of options in the configuration file.
Hint
For a full list of template options, see Template.Option.
File-specific template options can be set using template directives in the template of the form:
chezmoi:template:$KEY=$VALUE\n
which sets the template option $KEY to $VALUE. $VALUE must be quoted if it contains spaces or double quotes. Multiple key/value pairs may be specified on a single line.
Lines containing template directives are removed to avoid parse errors from any delimiters. If multiple directives are present in a file, later directives override earlier ones.
Then the delimiters $LEFT and $RIGHT are used instead. Either or both of left-delimiter=$LEFT and right-delimiter=$RIGHT may be omitted. If either $LEFT or $RIGHT is empty then the default delimiter ({{ and }} respectively) is set instead.
The delimiters are specific to the file in which they appear and are not inherited by templates called from the file.
Many of the template functions available in chezmoi primarily use UNIX-style line endings (lf/\\n), which may result in unexpected output when running chezmoi diff on a modify_ template. These line endings can be overridden with a template directive:
chezmoi:template:line-endings=$VALUE\n
$VALUE can be an arbitrary string or one of:
Value Effect crlf Use Windows line endings (\\r\\n) lf Use UNIX-style line endings (\\n) native Use platform-native line endings (crlf on Windows, lf elsewhere)"},{"location":"reference/templates/directives/#missing-keys","title":"Missing keys","text":"
By default, chezmoi will return an error if a template indexes a map with a key that is not present in the map. This behavior can be changed globally with the template.options configuration variable or with a template directive:
chezmoi:template:missing-key=$VALUE\n
$VALUE can be one of:
Value Effect error Return an error on any missing key (default) invalid Ignore missing keys. If printed, the result of the index operation is the string <no value>zero Ignore missing keys. If printed, the result of the index operation is the zero value"},{"location":"reference/templates/variables/","title":"Variables","text":"
chezmoi provides the following automatically-populated variables:
Variable Type Value .chezmoi.arch string Architecture, e.g. amd64, arm, etc. as returned by runtime.GOARCH .chezmoi.args []string The arguments passed to the chezmoi command, starting with the program command .chezmoi.cacheDir string The cache directory .chezmoi.config object The configuration, as read from the config file .chezmoi.configFile string The path to the configuration file used by chezmoi .chezmoi.destDir string The destination directory .chezmoi.executable string The path to the chezmoi executable, if available .chezmoi.fqdnHostname string The fully-qualified domain name hostname of the machine chezmoi is running on .chezmoi.gid string The primary group ID .chezmoi.group string The group of the user running chezmoi .chezmoi.homeDir string The home directory of the user running chezmoi .chezmoi.hostname string The hostname of the machine chezmoi is running on, up to the first ..chezmoi.kernel object Contains information from /proc/sys/kernel. Linux only, useful for detecting specific kernels (e.g. Microsoft's WSL kernel) .chezmoi.os string Operating system, e.g. darwin, linux, etc. as returned by runtime.GOOS .chezmoi.osRelease object The information from /etc/os-release, Linux only, run chezmoi data to see its output .chezmoi.pathListSeparator string The path list separator, typically ; on Windows and : on other systems. Used to separate paths in environment variables. ie /bin:/sbin:/usr/bin.chezmoi.pathSeparator string The path separator, typically \\ on windows and / on unix. Used to separate files and directories in a path. ie c:\\see\\dos\\run.chezmoi.sourceDir string The source directory .chezmoi.sourceFile string The path of the template relative to the source directory .chezmoi.targetFile string The absolute path of the target file for the template .chezmoi.uid string The user ID .chezmoi.username string The username of the user running chezmoi .chezmoi.version.builtBy string The program that built the chezmoi executable, if set .chezmoi.version.commit string The git commit at which the chezmoi executable was built, if set .chezmoi.version.date string The timestamp at which the chezmoi executable was built, if set .chezmoi.version.version string The version of chezmoi .chezmoi.windowsVersion object Windows version information, if running on Windows .chezmoi.workingTree string The working tree of the source directory
.chezmoi.windowsVersion contains the following keys populated from the registry key Computer\\HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion.
Additional variables can be defined in the config file in the data section. Variable names must consist of a letter and be followed by zero or more letters and/or digits.
The onepassword* template functions return structured data from 1Password using the 1Password CLI (op).
Info
When using the 1Password CLI with biometric authentication, chezmoi derives values from op account list that can resolves into the appropriate 1Password account-uuid.
As an example, if op account list --format=json returns the following structure:
The following values can be used in the account parameter and the value some-account-uuid will be passed as the --account parameter to op.
some-account-uuid
some-user-uuid
account1.1password.ca
account1
my@email.com
my
my@account1.1password.ca
my@account1
If there are multiple accounts and any value exists more than once, that value will be removed from the account mapping. That is, if you are signed into my@email.com and your@email.com for account1.1password.ca, then account1.1password.ca will not be a valid lookup value, but my@account1, my@account1.1password.ca, your@account1, and your@account1.1password.ca would all be valid lookups.
Warning
chezmoi has experimental support for 1Password secrets automation modes. These modes change how the 1Password CLI works and affect all functions. Most notably, account parameters are not allowed on all 1Password template functions.
onepassword returns structured data from 1Password using the 1Password CLI (op). uuid is passed to op item get $UUID --format json and the output from op is parsed as JSON. The output from op is cached so calling onepassword multiple times with the same uuid will only invoke op once. If the optional vault is supplied, it will be passed along to the op item get call, which can significantly improve performance. If the optional account is supplied, it will be passed along to the op item get call, which will help it look in the right account, in case you have multiple accounts (e.g., personal and work accounts).
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
The 1password CLI command can be set with the onePassword.command config variable, and extra arguments can be specified with the onePassword.args config variable.
onepasswordDetailsFields returns structured data from 1Password using the 1Password CLI (op). uuid is passed to op get item $UUID, the output from op is parsed as JSON, and elements of details.fields are returned as a map indexed by each field's id (if set) or label (if set and id is not present).
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
The output from op is cached so calling onepasswordDetailsFields multiple times with the same uuid will only invoke op once. If the optional vault is supplied, it will be passed along to the op get call, which can significantly improve performance. If the optional account is supplied, it will be passed along to the op get call, which will help it look in the right account, in case you have multiple accounts (e.g. personal and work accounts).
onepasswordDocument returns a document from 1Password using the 1Password CLI (op). uuid is passed to op get document $UUID and the output from op is returned. The output from op is cached so calling onepasswordDocument multiple times with the same uuid will only invoke op once. If the optional vault is supplied, it will be passed along to the op get call, which can significantly improve performance. If the optional account is supplied, it will be passed along to the op get call, which will help it look in the right account, in case you have multiple accounts (e.g., personal and work accounts).
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
onepasswordItemFields returns structured data from 1Password using the 1Password CLI (op). uuid is passed to op item get $UUID --format json, the output from op is parsed as JSON, and each element of details.sections are iterated over and any fields are returned as a map indexed by each field's n.
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
onepasswordRead returns data from 1Password using the 1Password CLI (op). url is passed to the op read --no-newline command. If account is specified, the extra arguments --account $ACCOUNT are passed to op.
If there is no valid session in the environment, by default you will be interactively prompted to sign in.
Example
The result of
{{ onepasswordRead \"op://vault/item/field\" }}\n
is equivalent to calling
$ op read --no-newline op://vault/item/field\n
Warning
When using 1Password secrets automation, the account parameter is not allowed.
1Password SDK template functions are experimental and may change.
The onepasswordSDK* template functions return structured data from 1Password using the 1Password SDK.
By default, the 1Password service account token is taken from the $OP_SERVICE_ACCOUNT_TOKEN environment variable. The name of the environment variable can be set with onepasswordSDK.tokenEnvVar configuration variable, or the token can be set explicitly by setting the onepasswordSDK.token configuration variable.
onepasswordSDKItemsGet is an experimental function and may change.
onepasswordSDKItemsGet returns an item from 1Password using the 1Password SDK.
The output of onepasswordSDKItemsGet is cached so multiple calls to onepasswordSDKItemsGet with the same vault-id and item-id will return the same value.
The awsSecretsManager* functions return data from AWS Secrets Manager using the GetSecretValue API.
The profile and region are pulled from the standard environment variables and shared config files but can be overridden by setting awsSecretsManager.profile and awsSecretsManager.region configuration variables respectively.
awsSecretsManager returns structured data retrieved from AWS Secrets Manager. arn specifies the SecretId passed to GetSecretValue. This can either be the full ARN or the simpler name if applicable.
awsSecretsManager returns the raw string value retrieved from AWS Secrets Manager. arn specifies the SecretId passed to GetSecretValue. This can either be the full ARN or the simpler name if applicable.
"},{"location":"reference/templates/azure-key-vault-functions/azureKeyVault/","title":"azureKeyVault secret name [vault-name]","text":"
azureKeyVault returns a secret value retrieved from an Azure Key Vault.
The mandatory secret name argument specifies the name of the secret to retrieve.
The optional vault name argument specifies the name of the vault, if not set, the default vault name will be used.
Warning
The current implementation will always return the latest version of the secret. Retrieving a specific version of a secret is not supported.
bitwarden returns structured data retrieved from Bitwarden using the Bitwarden CLI (bw). args are passed to bw get unchanged and the output from bw get is parsed as JSON.
The output from bw get is cached so calling bitwarden multiple times with the same arguments will only invoke bw once.
bitwardenAttachment returns a document from Bitwarden using the Bitwarden CLI (bw). filename and itemid are passed to bw get attachment $FILENAME --itemid $ITEMID and the output is returned.
The output from bw is cached so calling bitwardenAttachment multiple times with the same filename and itemid will only invoke bw once.
bitwardenFields returns structured data retrieved from Bitwarden using the Bitwarden CLI (bw). args are passed to bw get unchanged, the output from bw get is parsed as JSON, and the elements of fields are returned as a dict indexed by each field's name.
The output from bw get is cached so calling bitwardenFields multiple times with the same arguments will only invoke bw get once.
bitwardenSecrets returns structured data from Bitwarden using the Bitwarden Secrets CLI (bws). secret-id is passed to bws secret get and the output from bws secret get is parsed as JSON and returned.
If the additional access-token argument is given, it is passed to bws secret get with the --access-token flag.
The output from bws secret get is cached so calling bitwardenSecrets multiple times with the same secret-id and access-token will only invoke bws secret get once.
"},{"location":"reference/templates/bitwarden-functions/rbw/","title":"rbw name [arg...]","text":"
rbw returns structured data retrieved from Bitwarden using rbw. name is passed to rbw get --raw, along with any extra args, and the output is parsed as JSON.
The output from rbw get --raw is cached so calling rbw multiple times with the same arguments will only invoke rbw once.
"},{"location":"reference/templates/bitwarden-functions/rbwFields/","title":"rbwFields name [arg...]","text":"
rbw returns structured data retrieved from Bitwarden using rbw. name is passed to rbw get --raw, along with any extra args, the output is parsed as JSON, and the elements of fields are returned as a dict indexed by each field's name.
The output from rbw get --raw is cached so calling rbwFields multiple times with the same arguments will only invoke rbwFields once.
dashlaneNote returns the content of a secure note from Dashlane using the Dashlane CLI (dcli). filter is passed to dcli note, and the output from dcli note is just read as a multiline string.
The output from dcli note is cached so calling dashlaneNote multiple times with the same filter will only invoke dcli note once.
dashlanePassword returns structured data from Dashlane using the Dashlane CLI (dcli). filter is passed to dcli password --output json, and the output from dcli password is parsed as JSON.
The output from dcli password cached so calling dashlanePassword multiple times with the same filter will only invoke dcli password once.
doppler returns the secret for the specified project and configuration from Doppler using doppler secrets download --json --no-file.
If either of project or config are empty or omitted, then chezmoi will use the value from the doppler.project and doppler.config config variables if they are set and not empty.
dopplerProjectJson returns the secret for the specified project and configuration from Doppler using doppler secrets download --json --no-file as json structured data.
If either of project or config are empty or omitted, then chezmoi will use the value from the doppler.project and doppler.config config variables if they are set and not empty.
ejsonDecrypt returns the decrypted content of an ejson-encrypted file.
filePath indicates where the encrypted file is located.
The decrypted file is cached so calling ejsonDecrypt multiple times with the same filePath will only run through the decryption process once. The cache is shared with ejsonDecryptWithKey.
ejsonDecryptWithKey returns the decrypted content of an ejson-encrypted file.
filePath indicates where the encrypted file is located, and key is used to decrypt the file.
The decrypted file is cached so calling ejsonDecryptWithKey multiple times with the same filePath will only run through the decryption process once. The cache is shared with ejsonDecrypt.
deleteValueAtPath modifies dict to delete the value at path and returns dict. path can be either a string containing a .-separated list of keys or a list of keys.
If path does not exist in dict then deleteValueAtPath returns dict unchanged.
eqFold returns the boolean truth of comparing string1 with string2 and any number of extraStrings under Unicode case-folding.
Example
{{ $commandOutput := output \"path/to/output-FOO.sh\" }}\n{{ if eqFold \"foo\" $commandOutput }}\n# $commandOutput is \"foo\"/\"Foo\"/\"FOO\"...\n{{ else if eqFold \"bar\" $commandOutput }}\n# $commandOutput is \"bar\"/\"Bar\"/\"BAR\"...\n{{ end }}\n
findExecutable searches for an executable named file in directories identified by path-list. The result will be the executable file concatenated with the matching path. If an executable file cannot be found in path-list, findExecutable returns an empty string.
findExecutable is provided as an alternative to lookPath so that you can interrogate the system PATH as it would be configured after chezmoi apply. Like lookPath, findExecutable is not hermetic: its return value depends on the state of the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
The return value of the first successful call to findExecutable is cached, and future calls to findExecutable with the same parameters will return this path.
Info
On Windows, the resulting path will contain the first found executable extension as identified by the environment variable %PathExt%.
Example
{{ if findExecutable \"rtx\" (list \"bin\" \"go/bin\" \".cargo/bin\" \".local/bin\") }}\n# $HOME/.cargo/bin/rtx exists and will probably be in $PATH after apply\n{{ end }}\n
findOneExecutable searches for an executable from file-list in directories identified by path-list, finding the first matching executable in the first matching directory (each directory is searched for matching executables in turn). The result will be the executable file concatenated with the matching path. If an executable from file-list cannot be found in path-list, findOneExecutable returns an empty string.
findOneExecutable is provided as an alternative to lookPath so that you can interrogate the system PATH as it would be configured after chezmoi apply. Like lookPath, findOneExecutable is not hermetic: its return value depends on the state of the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
The return value of the first successful call to findOneExecutable is cached, and future calls to findOneExecutable with the same parameters will return this path.
Info
On Windows, the resulting path will contain the first found executable extension as identified by the environment variable %PathExt%.
Example
{{ if findOneExecutable (list \"eza\" \"exa\") (list \"bin\" \"go/bin\" \".cargo/bin\" \".local/bin\") }}\n# $HOME/.cargo/bin/exa exists and will probably be in $PATH after apply\n{{ end }}\n
fromJson parses jsontext as JSON and returns the parsed value.
JSON numbers that can be represented exactly as 64-bit signed integers are returned as such. Otherwise, if the number is in the range of 64-bit IEEE floating point values, it is returned as such. Otherwise, the number is returned as a string. See RFC7159 Section 6.
includeTemplate returns the result of executing the contents of filename with the optional data. Relative paths are first searched for in .chezmoitemplates and, if not found, are interpreted relative to the source directory.
joinPath joins any number of path elements into a single path, separating them with the OS-specific path separator. Empty elements are ignored. The result is cleaned. If the argument list is empty or all its elements are empty, joinPath returns an empty string. On Windows, the result will only be a UNC path if the first non-empty element is a UNC path.
lookPath searches for an executable named file in the directories named by the PATH environment variable. If file contains a slash, it is tried directly and the PATH is not consulted. The result may be an absolute path or a path relative to the current directory. If file is not found, lookPath returns an empty string.
lookPath is not hermetic: its return value depends on the state of the environment and the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
The return value of the first successful call to lookPath is cached, and future calls to lookPath for the same file will return this path.
Example
{{ if lookPath \"diff-so-fancy\" }}\n# diff-so-fancy is in $PATH\n{{ end }}\n
lstat runs os.Lstat on name. If name exists it returns structured data. If name does not exist then it returns a false value. If os.Lstat returns any other error then it raises an error. The structured value returned if name exists contains the fields name, size, mode, perm, modTime, isDir, and type.
lstat is not hermetic: its return value depends on the state of the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
Example
{{ if eq (joinPath .chezmoi.homeDir \".xinitrc\" | lstat).type \"symlink\" }}\n# ~/.xinitrc exists and is a symlink\n{{ end }}\n
mozillaInstallHash returns the Mozilla install hash for path. This is a convenience function to assist the management of Firefox profiles.
"},{"location":"reference/templates/functions/output/","title":"output name [arg...]","text":"
output returns the output of executing the command name with args. If executing the command returns an error then template execution exits with an error. The execution occurs every time that the template is executed. It is the user's responsibility to ensure that executing the command is both idempotent and fast.
Example
current-context: {{ output \"kubectl\" \"config\" \"current-context\" | trim }}\n
pruneEmptyDicts modifies dict to remove nested empty dicts. Properties are pruned from the bottom up, so any nested dicts that themselves only contain empty dicts are pruned.
replaceAllRegex returns text with all substrings matching the regular expression expr replaced with repl. It is an alternative to sprig's regexpReplaceAll function with a different argument order that supports pipelining.
"},{"location":"reference/templates/functions/setValueAtPath/","title":"setValueAtPath path value dict","text":"
setValueAtPath modifies dict to set the value at path to value and returns dict. path can be either a string containing a .-separated list of keys or a list of keys. The function will create new key/value pairs in dict if needed.
This is an alternative to sprig's set function with a different argument order that supports pipelining.
stat runs os.Stat on name. If name exists it returns structured data. If name does not exist then it returns a false value. If os.Stat returns any other error then it raises an error. The structured value returned if name exists contains the fields name, size, mode, perm, modTime, isDir, and type.
stat is not hermetic: its return value depends on the state of the filesystem at the moment the template is executed. Exercise caution when using it in your templates.
Example
{{ if stat (joinPath .chezmoi.homeDir \".pyenv\") }}\n# ~/.pyenv exists\n{{ end }}\n
toPrettyJson returns the JSON representation of value. The optional indent specifies how much nested elements are indented relative to their parent. indent defaults to two spaces.
"},{"location":"reference/templates/functions/warnf/","title":"warnf format [arg...]","text":"
warnf prints a message to stderr prefixed by chezmoi: warning: and returns the empty string. format is interpreted as a printf-style format string with the given args.
The gitHub* template functions return data from the GitHub API.
By default, chezmoi makes anonymous GitHub API requests, which are subject to GitHub's rate limits (currently 60 requests per hour per source IP address). chezmoi caches results from identical GitHub API requests for the period defined in gitHub.refreshPeriod (default one minute).
If any of the environment variables $CHEZMOI_GITHUB_ACCESS_TOKEN, $GITHUB_ACCESS_TOKEN, or $GITHUB_TOKEN are found, then the first one found will be used to authenticate the GitHub API requests which have a higher rate limit (currently 5,000 requests per hour per user).
In practice, GitHub API rate limits are high enough chezmoi's caching of results mean that you should rarely need to set a token, unless you are sharing a source IP address with many other GitHub users. If needed, the GitHub documentation describes how to create a personal access token.
gitHubKeys returns user's public SSH keys from GitHub using the GitHub API. The returned value is a slice of structs with .ID and .Key fields.
Warning
If you use this function to populate your ~/.ssh/authorized_keys file then you potentially open SSH access to anyone who is able to modify or add to your GitHub public SSH keys, possibly including certain GitHub employees. You should not use this function on publicly-accessible machines and should always verify that no unwanted keys have been added, for example by using the -v / --verbose option when running chezmoi apply or chezmoi update.
Additionally, GitHub automatically removes keys which haven't been used in the last year. This may cause your keys to be removed from ~/.ssh/authorized_keys suddenly, and without any warning or indication of the removal. You should provide one or more keys in plain text alongside this function to avoid unknowingly losing remote access to your machine.
Example
{{ range gitHubKeys \"user\" }}\n{{- .Key }}\n{{ end }}\n
gitHubLatestRelease calls the GitHub API to retrieve the latest release about the given owner-repo, returning structured data as defined by the GitHub Go API bindings.
Calls to gitHubLatestRelease are cached so calling gitHubLatestRelease with the same owner-repo will only result in one call to the GitHub API.
gitHubLatestReleaseAssetURL calls the GitHub API to retrieve the latest release about the given owner-repo, returning structured data as defined by the GitHub Go API bindings. It then iterates through all the release's assets, returning the first one that matches pattern. pattern is a shell pattern as described in path.Match.
Calls to gitHubLatestReleaseAssetURL are cached so calling gitHubLatestReleaseAssetURL with the same owner-repo will only result in one call to the GitHub API.
gitHubLatestTag calls the GitHub API to retrieve the latest tag for the given owner-repo, returning structured data as defined by the GitHub Go API bindings.
Calls to gitHubLatestTag are cached the same as githubTags, so calling gitHubLatestTag with the same owner-repo will only result in one call to the GitHub API.
Example
{{ (gitHubLatestTag \"docker/compose\").Name }}\n
Warning
The gitHubLatestTag returns the first tag returned by the list repository tags GitHub API endpoint. Although this seems to be the most recent tag, the GitHub API documentation does not specify the order of the returned tags.
gitHubRelease calls the GitHub API to retrieve the latest releases about the given owner-repo, It iterates through all the versions of the release, fetching the first entry equal to version.
It then returns structured data as defined by the GitHub Go API bindings.
Calls to gitHubRelease are cached so calling gitHubRelease with the same owner-repo version will only result in one call to the GitHub API.
"},{"location":"reference/templates/github-functions/gitHubReleaseAssetURL/","title":"gitHubReleaseAssetURL owner-repo version pattern","text":"
gitHubReleaseAssetURL calls the GitHub API to retrieve the latest releases about the given owner-repo, returning structured data as defined by the GitHub Go API bindings. It iterates through all the versions of the release, returning the first entry equal to version. It then iterates through all the release's assets, returning the first one that matches pattern. pattern is a shell pattern as described in path.Match.
Calls to gitHubReleaseAssetURL are cached so calling gitHubReleaseAssetURL with the same owner-repo will only result in one call to the GitHub API.
gitHubReleases calls the GitHub API to retrieve the first page of releases for the given owner-repo, returning structured data as defined by the GitHub Go API bindings.
Calls to gitHubReleases are cached so calling gitHubReleases with the same owner-repo will only result in one call to the GitHub API.
gitHubTags calls the GitHub API to retrieve the first page of tags for the given owner-repo, returning structured data as defined by the GitHub Go API bindings.
Calls to gitHubTags are cached so calling gitHubTags with the same owner-repo will only result in one call to the GitHub API.
The gopass* template functions return data stored in gopass using the gopass CLI (gopass) or builtin code.
By default, chezmoi will use the gopass CLI (gopass). Depending on your gopass configuration, you may have to enter your passphrase once for each secret.
When setting gopass.mode to builtin, chezmoi use builtin code to access the goapass database and caches your passphrase in plaintext in memory until chezmoi terminates.
Warning
Using the builtin code is experimental and may be removed.
gopass returns passwords stored in gopass using the gopass CLI (gopass). gopass-name is passed to gopass show --password $GOPASS_NAME and the first line of the output of gopass is returned with the trailing newline stripped. The output from gopass is cached so calling gopass multiple times with the same gopass-name will only invoke gopass once.
gopass returns raw passwords stored in gopass using the gopass CLI (gopass). gopass-name is passed to gopass show --noparsing $GOPASS_NAME and the output is returned. The output from gopassRaw is cached so calling gopassRaw multiple times with the same gopass-name will only invoke gopass once.
hcpVaultSecret returns the plaintext secret from HCP Vault Secrets using vlt secrets get --plaintext.
If any of application-name, project-id, or organization-id are empty or omitted, then chezmoi will use the value from the hcpVaultSecret.applicationName, hcpVaultSecret.projectId, and hcpVaultSecret.organizationId config variables if they are set and not empty.
hcpVaultSecretJson returns structured data from HCP Vault Secrets using vlt secrets get --format=json.
If any of application-name, project-id, or organization-id are empty or omitted, then chezmoi will use the value from the hcpVaultSecret.applicationName, hcpVaultSecret.projectId, and hcpVaultSecret.organizationId config variables if they are set and not empty.
These template functions are only available when generating a config file with chezmoi init. For testing with chezmoi execute-template, pass the --init flag to enable them.
promptBool prompts the user with prompt and returns the user's response interpreted as a boolean. If default is passed and the user's response is empty then it returns default. The user's response is interpreted as follows (case insensitive):
Response Result 1, on, t, true, y, yes true 0, off, f, false, n, no false"},{"location":"reference/templates/init-functions/promptBoolOnce/","title":"promptBoolOnce map path prompt [default]","text":"
promptBoolOnce returns the value of map at path if it exists and is a boolean value, otherwise it prompts the user for a boolean value with prompt and an optional default using promptBool.
Example
{{ $hasGUI := promptBoolOnce . \"hasGUI\" \"Does this machine have a GUI\" }}\n
promptChoice prompts the user with prompt and choices and returns the user's response. choices must be a list of strings. If default is passed and the user's response is empty then it returns default.
Example
{{- $choices := list \"desktop\" \"server\" -}}\n{{- $hosttype := promptChoice \"What type of host are you on\" $choices -}}\n[data]\n hosttype = {{- $hosttype | quote -}}\n
promptChoiceOnce returns the value of map at path if it exists and is a string, otherwise it prompts the user for one of choices with prompt and an optional default using promptChoice.
Example
{{- $choices := list \"desktop\" \"laptop\" \"server\" \"termux\" -}}\n{{- $hosttype := promptChoiceOnce . \"hosttype\" \"What type of host are you on\" $choices -}}\n[data]\n hosttype = {{- $hosttype | quote -}}\n
promptInt prompts the user with prompt and returns the user's response interpreted as an integer. If default is passed and the user's response is empty then it returns default.
promptIntOnce returns the value of map at path if it exists and is an integer value, otherwise it prompts the user for a integer value with prompt and an optional default using promptInt.
Example
{{ $monitors := promptIntOnce . \"monitors\" \"How many monitors does this machine have\" }}\n
promptString prompts the user with prompt and returns the user's response with all leading and trailing spaces stripped. If default is passed and the user's response is empty then it returns default.
promptStringOnce returns the value of map at path if it exists and is a string value, otherwise it prompts the user for a string value with prompt and an optional default using promptString.
Example
{{ $email := promptStringOnce . \"email\" \"What is your email address\" }}\n
stdinIsATTY returns true if chezmoi's standard input is a TTY. It is primarily useful for determining whether prompt* functions should be called or default values be used.
The keepassxc* template functions return structured data retrieved from a KeePassXC database using the KeePassXC CLI (keepassxc-cli)
The database is configured by setting keepassxc.database in the configuration file. You will be prompted for the database password the first time keepassxc-cli is run, and the password is cached, in plain text, in memory until chezmoi terminates.
The command used can be changed by setting the keepassxc.command configuration variable, and extra arguments can be added by setting keepassxc.args. The password prompt can be disabled by setting keepassxc.prompt to false.
By default, chezmoi will prompt for the KeePassXC password when required and cache it for the duration of chezmoi's execution. Setting keepassxc.mode to open will tell chezmoi to instead open KeePassXC's console with keepassxc-cli open followed by keepassxc.args. chezmoi will use this console to request values from KeePassXC.
When setting keepassxc.mode to builtin, chezmoi uses a builtin library to access a keepassxc database, which can be handy if keepassxc-cli is not available. Some KeePassXC features (such as Yubikey-enhanced encryption) may not be available with builtin support.
keepassxc returns structured data for entry using keepassxc-cli.
The output from keepassxc-cli is parsed into key-value pairs and cached so calling keepassxc multiple times with the same entry will only invoke keepassxc-cli once.
keeper returns structured data retrieved from Keeper using the Commander CLI. uid is passed to keeper get --format=json and the output is parsed as JSON.
On FreeBSD, the keyring template function is only available if chezmoi was compiled with cgo enabled. The official release binaries of chezmoi are not compiled with cgo enabled, and keyring will always return an empty string.
lastpass returns structured data from LastPass using the LastPass CLI (lpass). id is passed to lpass show --json $ID and the output from lpass is parsed as JSON. In addition, the note field, if present, is further parsed as colon-separated key-value pairs. The structured data is an array so typically the index function is used to extract the first item. The output from lastpass is cached so calling lastpass multiple times with the same id will only invoke lpass once.
lastpassRaw returns structured data from LastPass using the LastPass CLI (lpass). It behaves identically to the lastpass function, except that no further parsing is done on the note field.
The pass template functions return passwords stored in pass using the pass CLI (pass).
Hint
To use a pass-compatible password manager like passage, set pass.command to the name of the binary and use chezmoi's pass* template functions as if you were using pass.
pass returns passwords stored in pass using the pass CLI (pass). pass-name is passed to pass show $PASS_NAME and the first line of the output of pass is returned with the trailing newline stripped. The output from pass is cached so calling pass multiple times with the same pass-name will only invoke pass once.
passFields returns structured data stored in pass using the pass CLI (pass). pass-name is passed to pass show $PASS_NAME and the output is parsed as colon-separated key-value pairs, one per line. The return value is a map of keys to values.
passRaw returns passwords stored in pass using the pass CLI (pass). pass-name is passed to pass show $PASS_NAME and the output is returned. The output from pass is cached so calling passRaw multiple times with the same pass-name will only invoke pass once.
secret returns the output of the generic secret command defined by the secret.command configuration variable with secret.args and args with leading and trailing whitespace removed. The output is cached so multiple calls to secret with the same args will only invoke the generic secret command once.
secretJSON returns structured data from the generic secret command defined by the secret.command configuration variable with secret.args and args. The output is parsed as JSON. The output is cached so multiple calls to secret with the same args will only invoke the generic secret command once.
vault returns structured data from Vault using the Vault CLI (vault). key is passed to vault kv get -format=json $KEY and the output from vault is parsed as JSON. The output from vault is cached so calling vault multiple times with the same key will only invoke vault once.
chezmoi add $FILE adds $FILEfrom your home directory to the source directory.
chezmoi edit $FILE opens your editor with the file in the source directory that corresponds to $FILE.
chezmoi status gives a quick summary of what files would change if you ran chezmoi apply.
chezmoi diff shows the changes that chezmoi apply would make to your home directory.
chezmoi apply updates your dotfiles from the source directory.
chezmoi edit --apply $FILE is like chezmoi edit $FILE but also runs chezmoi apply $FILE afterwards.
chezmoi cd opens a subshell in the source directory.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo H->>W: chezmoi add <file> W->>W: chezmoi edit <file> W-->>H: chezmoi status W-->>H: chezmoi diff W->>H: chezmoi apply W->>H: chezmoi edit --apply <file> H-->>W: chezmoi cd"},{"location":"user-guide/command-overview/#using-chezmoi-across-multiple-machines","title":"Using chezmoi across multiple machines","text":"
chezmoi init $GITHUB_USERNAME clones your dotfiles from GitHub into the source directory.
chezmoi init --apply $GITHUB_USERNAME clones your dotfiles from GitHub into the source directory and runs chezmoi apply.
chezmoi update pulls the latest changes from your remote repo and runs chezmoi apply.
Use normal git commands to add, commit, and push changes to your remote repo.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi init <github-username> R->>H: chezmoi init --apply <github-username> R->>H: chezmoi update <github-username> W->>L: git commit L->>R: git push"},{"location":"user-guide/command-overview/#working-with-templates","title":"Working with templates","text":"
chezmoi data prints the available template data.
chezmoi add --template $FILE adds $FILE as a template.
chezmoi chattr +template $FILE makes an existing file a template.
chezmoi cat $FILE prints the target contents of $FILE, without changing $FILE.
chezmoi execute-template is useful for testing and debugging templates.
"},{"location":"user-guide/daily-operations/","title":"Daily operations","text":""},{"location":"user-guide/daily-operations/#edit-your-dotfiles","title":"Edit your dotfiles","text":"
Edit a dotfile with:
chezmoi edit $FILENAME\n
This will edit $FILENAME's source file in your source directory. chezmoi will not make any changes to the actual dotfile until you run chezmoi apply.
To automatically run chezmoi apply when you quit your editor, run:
chezmoi edit --apply $FILENAME\n
To automatically run chezmoi apply whenever you save the file in your editor, run:
chezmoi edit --watch $FILENAME\n
You don't have to use chezmoi edit to edit your dotfiles. For more information, see Do I have to use chezmoi edit to edit my dotfiles?
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo W->>W: chezmoi edit W->>H: chezmoi apply W->>H: chezmoi edit --apply W->>H: chezmoi edit --watch"},{"location":"user-guide/daily-operations/#pull-the-latest-changes-from-your-repo-and-apply-them","title":"Pull the latest changes from your repo and apply them","text":"
You can pull the changes from your repo and apply them in a single command:
chezmoi update\n
This runs git pull --autostash --rebase in your source directory and then chezmoi apply.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>H: chezmoi update"},{"location":"user-guide/daily-operations/#pull-the-latest-changes-from-your-repo-and-see-what-would-change-without-actually-applying-the-changes","title":"Pull the latest changes from your repo and see what would change, without actually applying the changes","text":"
This runs git pull --autostash --rebase in your source directory and chezmoi diff then shows the difference between the target state computed from your source directory and the actual state.
If you're happy with the changes, then you can run
chezmoi apply\n
to apply them.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi git pull W-->>H: chezmoi diff W->>H: chezmoi apply"},{"location":"user-guide/daily-operations/#automatically-commit-and-push-changes-to-your-repo","title":"Automatically commit and push changes to your repo","text":"
chezmoi can automatically commit and push changes to your source directory to your repo. This feature is disabled by default. To enable it, add the following to your config file:
~/.config/chezmoi/chezmoi.toml
[git]\n autoCommit = true\n autoPush = true\n
Whenever a change is made to your source directory, chezmoi will commit the changes with an automatically-generated commit message (if autoCommit is true) and push them to your repo (if autoPush is true). autoPush implies autoCommit, i.e. if autoPush is true then chezmoi will auto-commit your changes. If you only set autoCommit to true then changes will be committed but not pushed.
By default, autoCommit will generate a commit message based on the files changed. You can override this by setting the git.commitMessageTemplate configuration variable. For example, to have chezmoi prompt you for a commit message each time, use:
If your commit message is longer than fits in a string then you can set git.commitMessageTemplateFile to specify a path to the commit message template relative to the source directory, for example:
Be careful when using autoPush. If your dotfiles repo is public and you accidentally add a secret in plain text, that secret will be pushed to your public repo.
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo W->>L: autoCommit W->>R: autoPush"},{"location":"user-guide/daily-operations/#install-chezmoi-and-your-dotfiles-on-a-new-machine-with-a-single-command","title":"Install chezmoi and your dotfiles on a new machine with a single command","text":"
chezmoi's install script can run chezmoi init for you by passing extra arguments to the newly installed chezmoi binary. If your dotfiles repo is github.com/$GITHUB_USERNAME/dotfiles then installing chezmoi, running chezmoi init, and running chezmoi apply can be done in a single line of shell:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --apply $GITHUB_USERNAME\n
If your dotfiles repo has a different name to dotfiles, or if you host your dotfiles on a different service, then see the reference manual for chezmoi init.
For setting up transitory environments (e.g. short-lived Linux containers) you can install chezmoi, install your dotfiles, and then remove all traces of chezmoi, including the source directory and chezmoi's configuration directory, with a single command:
sh -c \"$(curl -fsLS get.chezmoi.io)\" -- init --one-shot $GITHUB_USERNAME\n
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi init $GITHUB_USERNAME R->>H: chezmoi init --apply $GITHUB_USERNAME R->>H: chezmoi init --one-shot $GITHUB_USERNAME"},{"location":"user-guide/include-files-from-elsewhere/","title":"Include dotfiles from elsewhere","text":"
The sections below contain examples of how to use .chezmoiexternal.toml to include files from external sources. For more details, check the reference manual .
"},{"location":"user-guide/include-files-from-elsewhere/#include-a-subdirectory-from-a-url","title":"Include a subdirectory from a URL","text":"
To include a subdirectory from another repository, e.g. Oh My Zsh, you cannot use git submodules because chezmoi uses its own format for the source state and Oh My Zsh is not distributed in this format. Instead, you can use the .chezmoiexternal.$FORMAT to tell chezmoi to import dotfiles from an external source.
For example, to import Oh My Zsh, the zsh-syntax-highlighting plugin, and powerlevel10k, put the following in ~/.local/share/chezmoi/.chezmoiexternal.toml:
chezmoi will download the archives and unpack them as if they were part of the source state. chezmoi caches downloaded archives locally to avoid re-downloading them every time you run a chezmoi command, and will only re-download them at most every refreshPeriod (default never).
In the above example refreshPeriod is set to 168h (one week) for .oh-my-zsh and .oh-my-zsh/custom/plugins/zsh-syntax-highlighting because the URL point to tarballs of the master branch, which changes over time. No refresh period is set for .oh-my-zsh/custom/themes/powerlevel10k because the URL points to the a tarball of a tagged version, which does not change over time. To bump the version of powerlevel10k, change the version in the URL.
To force a refresh the downloaded archives, use the --refresh-externals flag to chezmoi apply:
chezmoi --refresh-externals apply\n
--refresh-externals can be shortened to -R:
chezmoi -R apply\n
When using Oh My Zsh, make sure you disable auto-updates by setting DISABLE_AUTO_UPDATE=\"true\" in ~/.zshrc. Auto updates will cause the ~/.oh-my-zsh directory to drift out of sync with chezmoi's source state. To update Oh My Zsh and its plugins, refresh the downloaded archives.
Note
If your external dependency target directory can contain cache files that are added during normal use, chezmoi will report that files have changed on chezmoi apply. To avoid this, add the cache directory to your .chezmoiignore file.
For example, Oh My Zsh may cache completions in .oh-my-zsh/cache/completions/, which should be added to your .chezmoiignore file.
Warning
Do not use externals for large files or archives. chezmoi validates the exact contents of externals every time you run chezmoi diff, chezmoi apply, or chezmoi verify. For large externals, use a run_once_ or run_onchange_ script to unpack the archive or file once instead.
"},{"location":"user-guide/include-files-from-elsewhere/#include-a-subdirectory-with-selected-files-from-a-url","title":"Include a subdirectory with selected files from a URL","text":"
Use include pattern filters to include only selected files from an archive URL.
For example, to import just the required source files of the zsh-syntax-highlighting plugin in the example above, add in include filter to the zsh-syntax-highlighting section as shown below:
"},{"location":"user-guide/include-files-from-elsewhere/#include-a-single-file-from-a-url","title":"Include a single file from a URL","text":"
Including single files uses the same mechanism as including a subdirectory above, except with the external type file instead of archive. For example, to include plug.vim from github.com/junegunn/vim-plug in ~/.vim/autoload/plug.vim put the following in ~/.local/share/chezmoi/.chezmoiexternal.toml:
~/.local/share/chezmoi/.chezmoiexternal.toml
[\".vim/autoload/plug.vim\"]\n type = \"file\"\n url = \"https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim\"\n refreshPeriod = \"168h\"\n
"},{"location":"user-guide/include-files-from-elsewhere/#extract-a-single-file-from-an-archive","title":"Extract a single file from an archive","text":"
You can extract a single file from an archive using the archive-file type in .chezmoiexternal.$FORMAT, for example:
This will extract the single archive member age/age from the given URL (which is computed for the current OS and architecture) to the target ./local/bin/age.
It is occasionally useful to import entire archives of configuration into your source state. The import command does this. For example, to import the latest version github.com/ohmyzsh/ohmyzsh to ~/.oh-my-zsh run:
This only updates the source state. You will need to run:
chezmoi apply\n
to update your destination directory.
"},{"location":"user-guide/include-files-from-elsewhere/#handle-tar-archives-in-an-unsupported-compression-format","title":"Handle tar archives in an unsupported compression format","text":"
chezmoi natively understands tar archives. tar archives can be uncompressed or compressed in the bzip2, gzip, xz, or zstd formats.
If you have a tar archive in an unsupported compression format then you can use a filter to decompress it. For example, before chezmoi natively supported the zstd compression format, you could handle .tar.zst external archives with, for example:
~/.local/share/chezmoi/.chezmoiexternal.toml
[\".Software/anki/2.1.54-qt6\"]\n type = \"archive\"\n url = \"https://github.com/ankitects/anki/releases/download/2.1.54/anki-2.1.54-linux-qt6.tar.zst\"\n filter.command = \"zstd\"\n filter.args = [\"-d\"]\n format = \"tar\"\n
Here filter.command and filter.args together tell chezmoi to filter the downloaded data through zstd -d. The format = \"tar\" line tells chezmoi that output of the filter is an uncompressed tar archive.
"},{"location":"user-guide/include-files-from-elsewhere/#include-a-subdirectory-from-a-git-repository","title":"Include a subdirectory from a git repository","text":"
You can configure chezmoi to keep a git repository up to date in a subdirectory by using the external type git-repo, for example:
~/.local/share/chezmoi/.chezmoiexternal.toml
[\".vim/pack/alker0/chezmoi.vim\"]\n type = \"git-repo\"\n url = \"https://github.com/alker0/chezmoi.vim.git\"\n refreshPeriod = \"168h\"\n
If the directory does not exist then chezmoi will run git clone to clone it. If the directory does exist then chezmoi will run git pull to pull the latest changes, but not more often than every refreshPeriod. In the above example the refreshPeriod is 168h which is one week. The default refreshPeriod is zero, which disables refreshes. You can force a refresh (i.e. force a git pull) by passing the --refresh-externals/-R flag to chezmoi apply.
Warning
chezmoi's support for git-repo externals is limited to running git clone and/or git pull in a directory. You must have a git binary in your $PATH.
Using a git-repo external delegates management of the directory to git. chezmoi cannot manage any other files in that directory.
The contents of git-repo externals will not be manifested in commands like chezmoi diff or chezmoi dump, and will be listed by chezmoi unmanaged.
Hint
If you need to manage extra files in a git-repo external, use an archive external instead with the URL pointing to an archive of the git repo's master or main branch.
You can customize the arguments to git clone and git pull by setting the $DIR.clone.args and $DIR.pull.args variables in .chezmoiexternal.$FORMAT, for example:
"},{"location":"user-guide/include-files-from-elsewhere/#use-git-submodules-in-your-source-directory","title":"Use git submodules in your source directory","text":"
Important
If you use git submodules, then you should set the external_ attribute on the subdirectory containing the submodule.
You can include git repos from elsewhere as git submodules in your source directory. chezmoi init and chezmoi update are aware of git submodules and will run git with the --recurse-submodules flag by default.
chezmoi assumes that all files and directories in its source state are in chezmoi's format, i.e. their filenames include attributes like private_ and run_. Most git submodules are not in chezmoi's format and so files like run_test.sh will be interpreted by chezmoi as a run_ script. To avoid this problem, set the external_ attribute on all subdirectories that contain submodules.
You can stop chezmoi from handling git submodules by passing the --recurse-submodules=false flag or setting the update.recurseSubmodules configuration variable to false.
"},{"location":"user-guide/manage-different-types-of-file/","title":"Manage different types of file","text":""},{"location":"user-guide/manage-different-types-of-file/#have-chezmoi-create-a-directory-but-ignore-its-contents","title":"Have chezmoi create a directory, but ignore its contents","text":"
If you want chezmoi to create a directory, but ignore its contents, say ~/src, first run:
mkdir -p $(chezmoi source-path)/src\n
This creates the directory in the source state, which means that chezmoi will create it (if it does not already exist) when you run chezmoi apply.
However, as this is an empty directory it will be ignored by git. So, create a file in the directory in the source state that will be seen by git (so git does not ignore the directory) but ignored by chezmoi (so chezmoi does not include it in the target state):
touch $(chezmoi source-path)/src/.keep\n
chezmoi automatically creates .keep files when you add an empty directory with chezmoi add.
"},{"location":"user-guide/manage-different-types-of-file/#ensure-that-a-target-is-removed","title":"Ensure that a target is removed","text":"
Create a file called .chezmoiremove in the source directory containing a list of patterns of files to remove. chezmoi will remove anything in the target directory that matches the pattern. As this command is potentially dangerous, you should run chezmoi in verbose, dry-run mode beforehand to see what would be removed:
chezmoi apply --dry-run --verbose\n
.chezmoiremove is interpreted as a template, so you can remove different files on different machines. Negative matches (patterns prefixed with a !) or targets listed in .chezmoiignore will never be removed.
"},{"location":"user-guide/manage-different-types-of-file/#manage-part-but-not-all-of-a-file","title":"Manage part, but not all, of a file","text":"
chezmoi, by default, manages whole files, but there are two ways to manage just parts of a file.
Firstly, a modify_ script receives the current contents of the file on the standard input and chezmoi reads the target contents of the file from the script's standard output. This can be used to change parts of a file, for example using sed.
Hint
If you need random access to the file to modify it, then you can write standard input to a temporary file, modify the temporary file, and then write the temporary file to the standard output, for example:
If the file does not exist then the standard input to the modify_ script will be empty and it is the script's responsibility to write a complete file to the standard output.
modify_ scripts that contain the string chezmoi:modify-template are executed as templates with the current contents of the file passed as .chezmoi.stdin and the result of the template execution used as the new contents of the file.
Example
To replace the string old with new in a file while leaving the rest of the file unchanged, use the modify script:
Secondly, if only a small part of the file changes then consider using a template to re-generate the full contents of the file from the current state. For example, Kubernetes configurations include a current context that can be substituted with:
~/.local/share/chezmoi/dot_kube/config.tmpl
current-context: {{ output \"kubectl\" \"config\" \"current-context\" | trim }}\n
Hint
For managing ini files with a mix of settings and state (such as recently used files or window positions), there is a third party tool called chezmoi_modify_manager that builds upon modify_ scripts. See related software for more information.
"},{"location":"user-guide/manage-different-types-of-file/#manage-a-files-permissions-but-not-its-contents","title":"Manage a file's permissions, but not its contents","text":"
chezmoi's create_ attributes allows you to tell chezmoi to create a file if it does not already exist. chezmoi, however, will apply any permission changes from the executable_, private_, and readonly_ attributes. This can be used to control a file's permissions without altering its contents.
For example, if you want to ensure that ~/.kube/config always has permissions 600 then if you create an empty file called dot_kube/private_config in your source state, chezmoi will ensure ~/.kube/config's permissions are 0600 when you run chezmoi apply without changing its contents.
This approach does have the downside that chezmoi will create the file if it does not already exist. If you only want chezmoi apply to set a file's permissions if it already exists and not create the file otherwise, you can use a run_ script. For example, create a file in your source state called run_set_kube_config_permissions.sh containing:
"},{"location":"user-guide/manage-different-types-of-file/#handle-configuration-files-which-are-externally-modified","title":"Handle configuration files which are externally modified","text":"
Some programs modify their configuration files. When you next run chezmoi apply, any modifications made by the program will be lost.
You can track changes to these files by replacing with a symlink back to a file in your source directory, which is under version control. Here is a worked example for VSCode's settings.json on Linux:
Copy the configuration file to your source directory:
The prefix private_ is used because the ~/.config and ~/.config/Code directories are private by default.
Apply the changes:
chezmoi apply -v\n
Now, when the program modifies its configuration file it will modify the file in the source state instead.
"},{"location":"user-guide/manage-different-types-of-file/#populate-sshauthorized_keys-with-your-public-ssh-keys-from-github","title":"Populate ~/.ssh/authorized_keys with your public SSH keys from GitHub","text":"
chezmoi can retrieve your public SSH keys from GitHub, which can be useful for populating your ~/.ssh/authorized_keys. Put the following in your ~/.local/share/chezmoi/dot_ssh/authorized_keys.tmpl:
{{ range gitHubKeys \"$GITHUB_USERNAME\" -}}\n{{ .Key }}\n{{ end -}}\n
The primary goal of chezmoi is to manage configuration files across multiple machines, for example your personal macOS laptop, your work Ubuntu desktop, and your work Linux laptop. You will want to keep much configuration the same across these, but also need machine-specific configurations for email addresses, credentials, etc. chezmoi achieves this functionality by using text/template for the source state where needed.
For example, your home ~/.gitconfig on your personal machine might look like:
To handle this, on each machine create a configuration file called ~/.config/chezmoi/chezmoi.toml defining variables that might vary from machine to machine. For example, for your home machine:
~/.config/chezmoi/chezmoi.toml
[data]\n email = \"me@home.org\"\n
If you intend to store private data (e.g. access tokens) in ~/.config/chezmoi/chezmoi.toml, make sure it has permissions 0600.
If you prefer, you can use JSON, JSONC, or YAML for your configuration file. Variable names must start with a letter and be followed by zero or more letters or digits.
Then, add ~/.gitconfig to chezmoi using the --template flag to turn it into a template:
chezmoi add --template ~/.gitconfig\n
You can then open the template (which will be saved in the file ~/.local/share/chezmoi/dot_gitconfig.tmpl):
chezmoi edit ~/.gitconfig\n
Edit the file so it looks something like:
~/.local/share/chezmoi/dot_gitconfig.tmpl
[user]\n email = {{ .email | quote }}\n
Templates are often used to capture machine-specific differences. For example, in your ~/.local/share/chezmoi/dot_bashrc.tmpl you might have:
~/.local/share/chezmoi/dot_bashrc.tmpl
# common config\nexport EDITOR=vi\n\n# machine-specific configuration\n{{- if eq .chezmoi.hostname \"work-laptop\" }}\n# this will only be included in ~/.bashrc on work-laptop\n{{- end }}\n
For a full list of variables, run:
chezmoi data\n
For more advanced usage, you can use the full power of the text/template language. chezmoi includes all of the text functions from sprig and its own functions for interacting with password managers.
Templates can be executed directly from the command line, without the need to create a file on disk, with the execute-template command, for example:
This is useful when developing or debugging templates.
Some password managers allow you to store complete files. The files can be retrieved with chezmoi's template functions. For example, if you have a file stored in 1Password with the UUID uuid then you can retrieve it with the template:
{{- onepasswordDocument \"uuid\" -}}\n
The -s inside the brackets remove any whitespace before or after the template expression, which is useful if your editor has added any newlines.
If, after executing the template, the file contents are empty, the target file will be removed. This can be used to ensure that files are only present on certain machines. If you want an empty file to be created anyway, you will need to give it an empty_ prefix.
"},{"location":"user-guide/manage-machine-to-machine-differences/#ignore-files-or-a-directory-on-different-machines","title":"Ignore files or a directory on different machines","text":"
For coarser-grained control of files and entire directories managed on different machines, or to exclude certain files completely, you can create .chezmoiignore files in the source directory. These specify a list of patterns that chezmoi should ignore, and are interpreted as templates. An example .chezmoiignore file might look like:
~/.local/share/chezmoi/.chezmoiignore
README.md\n{{- if ne .chezmoi.hostname \"work-laptop\" }}\n.work # only manage .work on work-laptop\n{{- end }}\n
The use of ne (not equal) is deliberate. What we want to achieve is \"only install .work if hostname is work-laptop\" but chezmoi installs everything by default, so we have to turn the logic around and instead write \"ignore .work unless the hostname is work-laptop\".
Patterns can be excluded by starting the line with a !, for example:
~/.local/share/chezmoi/.chezmoiignore
dir/f*\n!dir/foo\n
will ignore all files beginning with an f in dir except for dir/foo.
You can see what files chezmoi ignores with the command
chezmoi ignored\n
"},{"location":"user-guide/manage-machine-to-machine-differences/#handle-different-file-locations-on-different-systems-with-the-same-contents","title":"Handle different file locations on different systems with the same contents","text":"
If you want to have the same file contents in different locations on different systems, but maintain only a single file in your source state, you can use a shared template.
Create the common file in the .chezmoitemplates directory in the source state. For example, create .chezmoitemplates/file.conf. The contents of this file are available in templates with the template $NAME . function where $NAME is the name of the file (. passes the current data to the template code in file.conf; see template action for details).
Then create files for each system, for example Library/Application Support/App/file.conf.tmpl for macOS and dot_config/app/file.conf.tmpl for Linux. Both template files should contain {{- template \"file.conf\" . -}}.
Finally, tell chezmoi to ignore files where they are not needed by adding lines to your .chezmoiignore file, for example:
~/.local/share/chezmoi/.chezmoiignore
{{ if ne .chezmoi.os \"darwin\" }}\nLibrary/Application Support/App/file.conf\n{{ end }}\n{{ if ne .chezmoi.os \"linux\" }}\n.config/app/file.conf\n{{ end }}\n
"},{"location":"user-guide/manage-machine-to-machine-differences/#use-completely-different-dotfiles-on-different-machines","title":"Use completely different dotfiles on different machines","text":"
chezmoi's template functionality allows you to change a file's contents based on any variable. For example, if you want ~/.bashrc to be different on Linux and macOS you would create a file in the source state called dot_bashrc.tmpl containing:
~/.local/share/chezmoi/dot_bashrc.tmpl
{{ if eq .chezmoi.os \"darwin\" -}}\n# macOS .bashrc contents\n{{ else if eq .chezmoi.os \"linux\" -}}\n# Linux .bashrc contents\n{{ end -}}\n
However, if the differences between the two versions are so large that you'd prefer to use completely separate files in the source state, you can achieve this with the include template function.
Create the following files:
~/.local/share/chezmoi/.bashrc_darwin
# macOS .bashrc contents\n
~/.local/share/chezmoi/.bashrc_linux
# Linux .bashrc contents\n
~/.local/share/chezmoi/dot_bashrc.tmpl
{{- if eq .chezmoi.os \"darwin\" -}}\n{{- include \".bashrc_darwin\" -}}\n{{- else if eq .chezmoi.os \"linux\" -}}\n{{- include \".bashrc_linux\" -}}\n{{- end -}}\n
This will cause ~/.bashrc to contain ~/.local/share/chezmoi/.bashrc_darwin on macOS and ~/.local/share/chezmoi/.bashrc_linux on Linux.
If you want to use templates within your templates, then, instead, create:
{{- if eq .chezmoi.os \"darwin\" -}}\n{{- template \"bashrc_darwin.tmpl\" . -}}\n{{- else if eq .chezmoi.os \"linux\" -}}\n{{- template \"bashrc_linux.tmpl\" . -}}\n{{- end -}}\n
"},{"location":"user-guide/setup/","title":"Setup","text":""},{"location":"user-guide/setup/#understand-chezmois-files-and-directories","title":"Understand chezmoi's files and directories","text":"
chezmoi generates your dotfiles for your local machine. It combines two main sources of data:
The source directory, ~/.local/share/chezmoi, is common to all your machines, and is a clone of your dotfiles repo. Each file that chezmoi manages has a corresponding file in the source directory.
The config file, typically ~/.config/chezmoi/chezmoi.toml (although you can use JSON or YAML if you prefer), is specific to the local machine.
Files whose contents are the same on all of your machines are copied verbatim from the source directory. Files which vary from machine to machine are executed as templates, typically using data from the local machine's config file to tune the final contents specific to the local machine.
"},{"location":"user-guide/setup/#use-a-hosted-repo-to-manage-your-dotfiles-across-multiple-machines","title":"Use a hosted repo to manage your dotfiles across multiple machines","text":"
chezmoi relies on your version control system and hosted repo to share changes across multiple machines. You should create a repo on the source code repository of your choice (e.g. Bitbucket, GitHub, or GitLab, many people call their repo dotfiles) and push the repo in the source directory here. For example:
These commands are summarized this sequence diagram:
sequenceDiagram participant H as home directory participant W as working copy participant L as local repo participant R as remote repo R->>W: chezmoi init <repo> W-->>H: chezmoi diff W->>H: chezmoi apply R->>H: chezmoi init --apply <repo>"},{"location":"user-guide/setup/#use-a-private-repo-to-store-your-dotfiles","title":"Use a private repo to store your dotfiles","text":"
chezmoi supports storing your dotfiles in both public and private repos.
chezmoi is designed so that your dotfiles repo can be public by making it easy for you to store your secrets either in your password manager, in encrypted files, or in private configuration files. Your dotfiles repo can still be private, if you choose.
If you use a private repo for your dotfiles then you will typically need to enter your credentials (e.g. your username and password) each time you interact with the repo, for example when pulling or pushing changes. chezmoi itself does not store any credentials, but instead relies on your local git configuration for these operations.
When using a private repo on GitHub without --ssh, when prompted for a password you will need to enter a GitHub personal access token. For more information on these changes, read the GitHub blog post on Token authentication requirements for Git operations
"},{"location":"user-guide/setup/#create-a-config-file-on-a-new-machine-automatically","title":"Create a config file on a new machine automatically","text":"
chezmoi init can also create a config file automatically, if one does not already exist. If your repo contains a file called .chezmoi.$FORMAT.tmpl where $FORMAT is one of the supported config file formats (e.g. json, jsonc, toml, or yaml) then chezmoi init will execute that template to generate your initial config file.
Specifically, if you have .chezmoi.toml.tmpl that looks like this:
Then chezmoi init will create an initial chezmoi.toml using this template. promptStringOnce is a special function that prompts the user (you) for a value if it is not already set in your data.
To test this template, use chezmoi execute-template with the --init and --promptString flags, for example:
"},{"location":"user-guide/setup/#re-create-your-config-file","title":"Re-create your config file","text":"
If you change your config file template, chezmoi will warn you if your current config file was not generated from that template. You can re-generate your config file by running:
chezmoi init\n
If you are using any prompt* template functions in your config file template you will be prompted again. However, you can avoid this with the following example template logic:
Templates are used to change the contents of a file depending on the environment. For example, you can use the hostname of the machine to create different configurations on different machines.
chezmoi uses the text/template syntax from Go extended with text template functions from sprig.
When reading files from the source state, chezmoi interprets them as a template if either of the following is true:
The file name has a .tmpl suffix.
The file is in the .chezmoitemplates directory, or a subdirectory of .chezmoitemplates.
chezmoi provides a variety of template variables. For a full list, run
chezmoi data\n
These come from a variety of sources (later data overwrite earlier ones):
Variables populated by chezmoi are in .chezmoi, for example .chezmoi.os.
Variables created by you in the .chezmoidata.$FORMAT configuration file. The various supported formats (json, jsonc, toml and yaml) are read in alphabetical order.
Variables created by you in the data section of the configuration file.
Furthermore, chezmoi provides a variety of functions to retrieve data at runtime from password managers, environment variables, and the filesystem.
"},{"location":"user-guide/templating/#creating-a-template-file","title":"Creating a template file","text":"
There are several ways to create a template:
When adding a file for the first time, pass the --template argument, for example:
chezmoi add --template ~/.zshrc\n
If a file is already managed by chezmoi, but is not a template, you can make it a template by running, for example:
chezmoi chattr +template ~/.zshrc\n
You can create a template manually in the source directory by giving it a .tmpl extension, for example:
chezmoi cd\n$EDITOR dot_zshrc.tmpl\n
Templates in .chezmoitemplates must be created manually, for example:
Templates can be tested and debugged with chezmoi execute-template, which treats each of its arguments as a template and executes it. The templates are interpreted and the results are output to standard output, making it useful for testing small template fragments:
Template actions are written inside double curly brackets, {{ and }}. Actions can be variables, pipelines, or control statements. Text outside actions is copied literally.
Variables are written literally, for example:
{{ .chezmoi.hostname }}\n
Conditional expressions can be written using if, else if, else, and end, for example:
{{ if eq .chezmoi.os \"darwin\" }}\n# darwin\n{{ else if eq .chezmoi.os \"linux\" }}\n# linux\n{{ else }}\n# other operating system\n{{ end }}\n
For a full description of the template syntax, see the text/template documentation.
For formatting reasons you might want to leave some whitespace after or before the template code. This whitespace will remain in the final file, which you might not want.
A solution for this is to place a minus sign and a space next to the brackets. So {{- for the left brackets and -}} for the right brackets. Here's an example:
HOSTNAME={{- .chezmoi.hostname }}\n
This will result in
HOSTNAME=myhostname\n
Notice that this will remove any number of tabs, spaces and even newlines and carriage returns.
A very useful feature of chezmoi templates is the ability to perform logical operations.
# common config\nexport EDITOR=vi\n\n# machine-specific configuration\n{{- if eq .chezmoi.hostname \"work-laptop\" }}\n# this will only be included in ~/.bashrc on work-laptop\n{{- end }}\n
In this example chezmoi will look at the hostname of the machine and if that is equal to \"work-laptop\", the text between the if and the end will be included in the result.
"},{"location":"user-guide/templating/#boolean-functions","title":"Boolean functions","text":"Function Return value eq Returns true if the first argument is equal to any of the other arguments not Returns the boolean negation of its single argument and Returns the boolean AND of its arguments by returning the first empty argument or the last argument, that is, and x y behaves as if x then y else x. All the arguments are evaluated or Returns the boolean OR of its arguments by returning the first non-empty argument or the last argument, that is, or x y behaves as if x then x else y All the arguments are evaluated"},{"location":"user-guide/templating/#integer-functions","title":"Integer functions","text":"Function Return value len Returns the integer length of its argument eq Returns the boolean truth of arg1 == arg2 ne Returns the boolean truth of arg1 != arg2 lt Returns the boolean truth of arg1 < arg2 le Returns the boolean truth of arg1 <= arg2 gt Returns the boolean truth of arg1 > arg2 ge Returns the boolean truth of arg1 >= arg2"},{"location":"user-guide/templating/#more-complicated-logic","title":"More complicated logic","text":"
Up until now, we have only seen if statements that can handle at most two variables. In this part we will see how to create more complicated expressions.
You can also create more complicated expressions. The eq command can accept multiple arguments. It will check if the first argument is equal to any of the other arguments.
{{ if eq \"foo\" \"foo\" \"bar\" }}hello{{end}}\n{{ if eq \"foo\" \"bar\" \"foo\" }}hello{{end}}\n{{ if eq \"foo\" \"bar\" \"bar\" }}hello{{end}}\n
The first two examples will output hello and the last example will output nothing.
The operators or and and can also accept multiple arguments.
You can perform multiple checks in one if statement.
{{ if (and (eq .chezmoi.os \"linux\") (ne .email \"me@home.org\")) }}\n...\n{{ end }}\n
This will check if the operating system is Linux and the configured email is not the home email. The brackets are needed here, because otherwise all the arguments will be give to the and command.
This way you can chain as many operators together as you like.
chezmoi defines a few useful templates variables that depend on the system you are currently on. A list of the variables defined by chezmoi can be found here.
There are, however more variables than that. To view the variables available on your system, execute:
chezmoi data\n
This outputs the variables in JSON format by default. To access the variable chezmoi.kernel.osrelease in a template, use
{{ .chezmoi.kernel.osrelease }}\n
This way you can also access the variables you defined yourself.
Files in the .chezmoitemplates subdirectory are parsed as templates and are available to be included in other templates using the template action with a name equal to their relative path to the .chezmoitemplates directory.
By default, such templates will be executed with nil data. If you want to access template variables (e.g. .chezmoi.os) in the template you must pass the data explicitly.
For example:
.chezmoitemplates/part.tmpl:\n{{ if eq .chezmoi.os \"linux\" }}\n# linux config\n{{ else }}\n# non-linux config\n{{ end }}\n\ndot_file.tmpl:\n{{ template \"part.tmpl\" . }}\n
"},{"location":"user-guide/templating/#using-chezmoitemplates-for-creating-similar-files","title":"Using .chezmoitemplates for creating similar files","text":"
When you have multiple similar files, but they aren't quite the same, you can create a template file in the directory .chezmoitemplates. This template can be inserted in other template files, for example:
In the example above only one arguments is passed to the template. To pass more arguments to the template, you can do it in two ways.
"},{"location":"user-guide/templating/#via-the-config-file","title":"Via the config file","text":"
This method is useful if you want to use the same template arguments multiple times, because you don't specify the arguments every time. Instead you specify them in the file ~/.config/chezmoi/chezmoi.toml:
~/.config/chezmoi/chezmoi.toml
[data.alacritty.big]\n fontsize = 18\n font = \"DejaVu Serif\"\n[data.alacritty.small]\n fontsize = 12\n font = \"DejaVu Sans Mono\"\n
Use the variables in ~/.local/share/chezmoi/.chezmoitemplates/alacritty:
And connect them with ~/.local/share/chezmoi/small-font.yml.tmpl:
~/.local/share/chezmoi/small-font.yml.tmpl
{{- template \"alacritty\" .alacritty.small -}}\n
At the moment, this means that you'll have to duplicate the alacritty data in the config file on every machine, but a feature will be added to avoid this.
"},{"location":"user-guide/templating/#by-passing-a-dictionary","title":"By passing a dictionary","text":"
Using the same alacritty configuration as above, you can pass the arguments to it with a dictionary, for example ~/.local/share/chezmoi/small-font.yml.tmpl:
"},{"location":"user-guide/use-scripts-to-perform-actions/","title":"Use scripts to perform actions","text":""},{"location":"user-guide/use-scripts-to-perform-actions/#understand-how-scripts-work","title":"Understand how scripts work","text":"
chezmoi supports scripts that are executed when you run chezmoi apply. These scripts can be configured to run every time, only when their contents have changed, or only if they haven't been run before.
Scripts are any file in the source directory with the prefix run_, and they are executed in alphabetical order.
run_ scripts: These scripts are executed every time you run chezmoi apply.
run_onchange_ scripts: These scripts are only executed if their content has changed since the last time they were run.
run_once_ scripts: These scripts are executed once for each unique version of the content. If the script is a template, the content is hashed after template execution. chezmoi tracks the content's SHA256 hash and stores it in a database. If the content has been run before (even under a different filename), the script will not run again unless the content itself changes.
Scripts break chezmoi's declarative approach and should be used sparingly. All scripts should be idempotent, including run_onchange_ and run_once_ scripts.
Scripts are normally run while chezmoi updates your dotfiles. For example, run_b.sh will be run after updating a.txt and before updating c.txt. To run scripts before or after the updates, use the before_ or after_ attributes, respectively, e.g., run_once_before_install-password-manager.sh.
Scripts must be created manually in the source directory, typically by running chezmoi cd and then creating a file with a run_ prefix. There is no need to set the executable bit on the script.
Scripts with the .tmpl suffix are treated as templates, with the usual template variables available. If the template resolves to only whitespace or an empty string, the script will not be executed, which is useful for disabling scripts dynamically.
When executing a script, chezmoi generates the script contents in a file in a temporary directory with the executable bit set and then executes it using exec(3). As a result, the script must either include a #! line or be an executable binary. Script working directory is set to the first existing parent directory in the destination tree.
If a .chezmoiscripts directory exists at the root of the source directory, scripts in this directory are executed as normal scripts, without creating a corresponding directory in the target state.
In verbose mode, the scripts' contents are printed before execution. In dry-run mode, scripts are not executed.
You can set extra environment variables for your scripts in the scriptEnv section of your config file. For example, to set the MY_VAR environment variable to my_value, specify:
~/.config/chezmoi/chezmoi.toml
[scriptEnv]\n MY_VAR = \"my_value\"\n
chezmoi sets a number of environment variables when running scripts, including CHEZMOI=1 and common template data like CHEZMOI_OS and CHEZMOI_ARCH.
Note
By default, chezmoi diff will print the contents of scripts that would be run by chezmoi apply. To exclude scripts from the output of chezmoi diff, set diff.exclude in your configuration file, for example:
~/.config/chezmoi/chezmoi.toml
[diff]\n exclude = [\"scripts\"]\n
Similarly, chezmoi status will print the names of the scripts that it will execute with the status R. This can similarly disabled by setting status.exclude to [\"scripts\"] in your configuration file.
"},{"location":"user-guide/use-scripts-to-perform-actions/#install-packages-with-scripts","title":"Install packages with scripts","text":"
Change to the source directory and create a file called run_onchange_install-packages.sh. In this file create your package installation script, e.g.
#!/bin/sh\nsudo apt install ripgrep\n
The next time you run chezmoi apply or chezmoi update this script will be run. As it has the run_onchange_ prefix, it will not be run again unless its contents change, for example if you add more packages to be installed.
This script can also be a template. For example, if you create run_onchange_install-packages.sh.tmpl with the contents:
{{ if eq .chezmoi.os \"linux\" -}}\n#!/bin/sh\nsudo apt install ripgrep\n{{ else if eq .chezmoi.os \"darwin\" -}}\n#!/bin/sh\nbrew install ripgrep\n{{ end -}}\n
This will install ripgrep on both Debian/Ubuntu Linux systems and macOS.
"},{"location":"user-guide/use-scripts-to-perform-actions/#run-a-script-when-the-contents-of-another-file-changes","title":"Run a script when the contents of another file changes","text":"
chezmoi's run_ scripts are run every time you run chezmoi apply, whereas run_onchange_ scripts are run only when their contents have changed, after executing them as templates. You can use this to cause a run_onchange_ script to run when the contents of another file has changed by including a checksum of the other file's contents in the script.
For example, if your dconf settings are stored in dconf.ini in your source directory then you can make chezmoi apply only load them when the contents of dconf.ini has changed by adding the following script as run_onchange_dconf-load.sh.tmpl:
As the SHA256 sum of dconf.ini is included in a comment in the script, the contents of the script will change whenever the contents of dconf.ini are changed, so chezmoi will re-run the script whenever the contents of dconf.ini change.
In this example you should also add dconf.ini to .chezmoiignore so chezmoi does not create dconf.ini in your home directory.
"},{"location":"user-guide/use-scripts-to-perform-actions/#clear-the-state-of-all-run_onchange_-and-run_once_-scripts","title":"Clear the state of all run_onchange_ and run_once_ scripts","text":"
chezmoi stores whether and when run_onchange_ and run_once_ scripts have been run in its persistent state.
To clear the state of run_onchange_ scripts, run:
chezmoi state delete-bucket --bucket=entryState\n
To clear the state of run_once_ scripts, run:
chezmoi state delete-bucket --bucket=scriptState\n
"},{"location":"user-guide/advanced/customize-your-source-directory/","title":"Customize your source directory","text":""},{"location":"user-guide/advanced/customize-your-source-directory/#use-a-subdirectory-of-your-dotfiles-repo-as-the-root-of-the-source-state","title":"Use a subdirectory of your dotfiles repo as the root of the source state","text":"
By default, chezmoi uses the root of your dotfiles repo as the root of the source state. If your source state contains many entries in its root, then your target directory (usually your home directory) will in turn be filled with many entries in its root as well. You can reduce the number of entries by keeping .chezmoiignore up to date, but this can become tiresome.
Instead, you can specify that chezmoi should read the source state from a subdirectory of the source directory instead by creating a file called .chezmoiroot containing the relative path to this subdirectory.
For example, given:
~/.local/share/chezmoi/.chezmoiroot
home\n
Then chezmoi will read the source state from the home subdirectory of your source directory, for example the desired state of ~/.gitconfig will be read from ~/.local/share/chezmoi/home/dot_gitconfig (instead of ~/.local/share/chezmoi/dot_gitconfig).
When migrating an existing chezmoi dotfiles repo to use .chezmoiroot you will need to move the relevant files in to the new root subdirectory manually. You do not need to move files that are ignored by chezmoi in all cases (i.e. are listed in .chezmoiignore when executed as a template on all machines), and you can afterwards remove their entries from home/.chezmoiignore.
"},{"location":"user-guide/advanced/customize-your-source-directory/#use-a-different-version-control-system-to-git","title":"Use a different version control system to git","text":"
Although chezmoi is primarily designed to use a git repo for the source state, it does not require git and can be used with other version control systems, such as fossil or pijul.
The version control system is used in only three places:
chezmoi init will use git clone to clone the source repo if it does not already exist.
chezmoi update will use git pull by default to pull the latest changes.
chezmoi's auto add, commit, and push functionality use git status, git add, git commit and git push.
Using a different version control system (VCS) to git can be achieved in two ways.
Firstly, if your VCS is compatible with git's CLI, then you can set the git.command configuration variable to your VCS command and set useBuiltinGit to false.
Otherwise, you can use your VCS to create the source directory before running chezmoi init, for example:
The creation of an empty .git directory in the source directory is required for chezmoi to be able to identify the work tree.
For updates, you can set the update.command and update.args configuration variables and chezmoi update will use these instead of git pull, for example:
Currently, it is not possible to override the auto add, commit, and push behavior for non-git VCSs, so you will have to commit changes manually, for example:
chezmoi uses a declarative approach for the contents of dotfiles, but package installation requires running imperative commands. However, you can simulate declarative package installation with a combination of a .chezmoidata file and a run_onchange_ script.
The following example uses homebrew on macOS, but should be adaptable to other operating systems and package managers.
First, create .chezmoidata/packages.yaml declaring the packages that you want installed, for example:
{{ if eq .chezmoi.os \"darwin\" -}}\n#!/bin/bash\n\nbrew bundle --no-lock --file=/dev/stdin <<EOF\n{{ range .packages.darwin.brews -}}\nbrew {{ . | quote }}\n{{ end -}}\n{{ range .packages.darwin.casks -}}\ncask {{ . | quote }}\n{{ end -}}\nEOF\n{{ end -}}\n
Now, when you run chezmoi apply, chezmoi will execute the install-packages.sh script with when the list of packages defined in .chezmoidata/packages.yaml changes.
"},{"location":"user-guide/advanced/install-your-password-manager-on-init/","title":"Install your password manager on init","text":"
If you use a password manager to store your secrets then you may need to install your password manager after you have run chezmoi init on a new machine but before chezmoi init --apply or chezmoi apply executes your run_before_ scripts.
chezmoi provides a hooks.read-source-state.pre hook that allows you to modify your system after chezmoi init has cloned your dotfile repo but before chezmoi has read the source state. This is the perfect time to install your password manager as you can assume that ~/.local/share/chezmoi is populated but has not yet been read.
First, write your password manager install hook. chezmoi executes this hook every time any command reads the source state so the hook should terminate as quickly as possible if there is no work to do.
This hook is not a template so you cannot use template variables and must instead detect the system you are running on yourself.
#!/bin/sh\n\n# exit immediately if password-manager-binary is already in $PATH\ntype password-manager-binary >/dev/null 2>&1 && exit\n\ncase \"$(uname -s)\" in\nDarwin)\n # commands to install password-manager-binary on Darwin\n ;;\nLinux)\n # commands to install password-manager-binary on Linux\n ;;\n*)\n echo \"unsupported OS\"\n exit 1\n ;;\nesac\n
Note
The leading . in .install-password-manager.sh is important because it tells chezmoi to ignore .install-password-manager.sh when declaring the state of files in your home directory.
Finally, tell chezmoi to run your password manager install hook before reading the source state:
"},{"location":"user-guide/advanced/migrate-away-from-chezmoi/","title":"Migrate away from chezmoi","text":"
chezmoi provides several mechanisms to help you move to an alternative dotfile manager (or even no dotfile manager at all) in the future:
chezmoi creates your dotfiles just as if you were not using a dotfile manager at all. Your dotfiles are regular files, directories, and symlinks. You can run chezmoi purge to delete all traces of chezmoi and then, if you're migrating to a new dotfile manager, then you can use whatever mechanism it provides to add your dotfiles to your new system.
chezmoi has a chezmoi archive command that generates a tarball of your dotfiles. You can replace the contents of your dotfiles repo with the contents of the archive and you've effectively immediately migrated away from chezmoi.
chezmoi has a chezmoi dump command that dumps the interpreted (target) state in a machine-readable form, so you can write scripts around chezmoi.
"},{"location":"user-guide/advanced/use-chezmoi-with-watchman/","title":"Use chezmoi with Watchman","text":"
chezmoi can be used with Watchman to automatically run chezmoi apply whenever your source state changes, but there are some limitations because Watchman runs actions in the background without a terminal.
Firstly, Watchman spawns a server which runs actions when filesystems change. This server reads its environment variables when it is started, typically on the first invocation of the watchman command. If you use a password manager that uses environment variables to persist login sessions, then you must login to your password manager before you run the first watchman command, and your session might eventually time out.
Secondly, Watchman runs processes without a terminal, and so cannot run interactive processes. For chezmoi apply, you can use the --force flag to suppress prompts to overwrite files that have been modified since chezmoi last wrote them. However, if any other part of chezmoi apply is interactive, for example if your password manager prompts for a password, then it will not work with Watchman.
"},{"location":"user-guide/encryption/age/#symmetric-encryption-with-a-passphrase","title":"Symmetric encryption with a passphrase","text":"
To use age's symmetric encryption with a passphrase, set age.passphrase to true in your config file, for example:
~/.config/chezmoi/chezmoi.toml
encryption = \"age\"\n[age]\n passphrase = true\n
You will be prompted for the passphrase whenever you run chezmoi add --encrypt and whenever chezmoi needs to decrypt the file, for example when you run chezmoi apply, chezmoi diff, or chezmoi status.
"},{"location":"user-guide/encryption/age/#builtin-age-encryption","title":"Builtin age encryption","text":"
chezmoi has builtin support for age encryption which is automatically used if the age command is not found in $PATH.
Info
The builtin age encryption does not support passphrases, symmetric encryption, or SSH keys.
Passphrases are not supported because chezmoi needs to decrypt files regularly, e.g. when running a chezmoi diff or a chezmoi status command, not just when running chezmoi apply. Prompting for a passphrase each time would quickly become tiresome.
Symmetric encryption may be supported in the future. Please open an issue if you want this.
SSH keys are not supported as the age documentation explicitly recommends not using them:
When integrating age into a new system, it's recommended that you only support X25519 keys, and not SSH keys. The latter are supported for manual encryption operations.
chezmoi supports encrypting files with gpg. Encrypted files are stored in the source state and automatically be decrypted when generating the target state or editing a file contents with chezmoi edit.
Specify symmetric encryption in your configuration file:
~/.config/chezmoi/chezmoi.toml
encryption = \"gpg\"\n[gpg]\n symmetric = true\n
chezmoi will encrypt files:
gpg --armor --symmetric\n
"},{"location":"user-guide/encryption/gpg/#encrypting-files-with-a-passphrase","title":"Encrypting files with a passphrase","text":"
If you want to encrypt your files with a passphrase, but don't mind the passphrase being stored in plaintext on your machines, then you can use the following configuration:
This will prompt you for the passphrase the first time you run chezmoi init on a new machine, and then remember the passphrase in your configuration file.
Make sure encryption is added to the top level section at the beginning of the config, before any other sections.
Then, configure chezmoi as you would for age.
"},{"location":"user-guide/frequently-asked-questions/design/","title":"Design","text":""},{"location":"user-guide/frequently-asked-questions/design/#do-i-have-to-use-chezmoi-edit-to-edit-my-dotfiles","title":"Do I have to use chezmoi edit to edit my dotfiles?","text":"
No. chezmoi edit is a convenience command that has a couple of useful features, but you don't have to use it.
You can also run chezmoi cd and then just edit the files in the source state directly. After saving an edited file you can run chezmoi diff to check what effect the changes would have, and run chezmoi apply if you're happy with them. If there are inconsistencies that you want to keep, then chezmoi merge-all will help you resolve any differences.
chezmoi edit provides the following useful features:
The arguments to chezmoi edit are the files in their target location, so you don't have to think about source state attributes and your editor's syntax highlighting will work.
If the dotfile is encrypted in the source state, then chezmoi edit will decrypt it to a private directory, open that file in your $EDITOR, and then re-encrypt the file when you quit your editor. This makes encryption transparent.
With the --diff and --apply options you can see what would change and apply those changes without having to run chezmoi diff or chezmoi apply.
If you have configured git auto commits or git auto pushes then chezmoi edit will create commits and push them for you.
If you chose to edit files in the source state and you're using VIM then github.com/alker0/chezmoi.vim gives you syntax highlighting, however you edit your files. Besides using the plugin, you can use modeline to tell VIM the correct filetype. For example, put # vim: filetype=zsh at the top of dot_zshrc, and VIM will treat dot_zshrc as zsh file.
"},{"location":"user-guide/frequently-asked-questions/design/#why-doesnt-chezmoi-use-symlinks-like-gnu-stow","title":"Why doesn't chezmoi use symlinks like GNU Stow?","text":"
Symlinks are first class citizens in chezmoi: chezmoi supports creating them, updating them, removing them, and even more advanced features not found in other dotfile managers like having the same symlink point to different targets on different machines by using a template.
With chezmoi, you only use a symlink where you really need a symlink, in contrast to some other dotfile managers (e.g. GNU Stow) which require the use of symlinks as a layer of indirection between a dotfile's location (which can be anywhere in your home directory) and a dotfile's content (which needs to be in a centralized directory that you manage with version control). chezmoi solves this problem in a different way.
Instead of using a symlink to redirect from the dotfile's location to the centralized directory, chezmoi generates the dotfile as a regular file in its final location from the contents of the centralized directory. This approach allows chezmoi to provide features that are not possible when using symlinks, for example having files that are encrypted, executable, private, or templates.
There is nothing special about dotfiles managed by chezmoi whereas dotfiles managed with GNU Stow are special because they're actually symlinks to somewhere else.
The only advantage to using GNU Stow-style symlinks is that changes that you make to the dotfile's contents in the centralized directory are immediately visible whenever you save them, whereas chezmoi currently requires you to pass the --watch flag to chezmoi edit or set edit.watch to true in your configuration file.
If you really want to use symlinks, then chezmoi provides a symlink mode which uses symlinks where possible. This configures chezmoi to work like GNU Stow and have it create a set of symlinks back to a central directory, but this currently requires a bit of manual work (as described in #167). chezmoi might get some automation to help (see #886 for example) but it does need some convincing use cases that demonstrate that a symlink from a dotfile's location to its contents in a central directory is better than just having the correct dotfile contents.
"},{"location":"user-guide/frequently-asked-questions/design/#what-are-the-limitations-of-chezmois-symlink-mode","title":"What are the limitations of chezmoi's symlink mode?","text":"
In symlink mode chezmoi replaces targets with symlinks to the source directory if the target is a regular file and is not encrypted, executable, private, or a template.
Symlinks cannot be used for encrypted files because the source state contains the ciphertext, not the plaintext.
Symlinks cannot be used for executable files as the executable bit would need to be set on the file in the source directory and chezmoi uses only regular files and directories in its source state for portability across operating systems. This may change in the future.
Symlinks cannot be used for private files because git does not persist group and world permission bits.
Symlinks cannot be used for templated files because the source state contains the template, not the result of executing the template.
Symlinks cannot be used for entire directories because of chezmoi's use of attributes in the filename mangles entries in the directory, directories might have the exact_ attribute and contain empty files, and the directory's entries might not be usable with symlinks.
In symlink mode, running chezmoi add does not immediately replace the targets with a symlink. You must run chezmoi apply to create the symlinks.
"},{"location":"user-guide/frequently-asked-questions/design/#why-does-chezmoi-use-weird-filenames","title":"Why does chezmoi use weird filenames?","text":"
There are a number of criticisms of how chezmoi uses filenames:
The long source file names are weird and verbose.
Not all possible file permissions can be represented.
Everything is in a single directory, which can end up containing many entries.
chezmoi's decision to store metadata in filenames is a deliberate, practical, compromise.
Firstly, almost all programs store metadata in filenames: the filename's extension. chezmoi extends the filename to storing metadata in attributes in the filename's prefix as well.
The dot_ attribute makes it transparent which dotfiles are managed by chezmoi and which files are ignored by chezmoi. chezmoi ignores all files and directories that start with . so no special whitelists are needed for version control systems and their control files (e.g. .git and .gitignore).
chezmoi needs per-file metadata to know how to interpret the source file's contents, for example to know when the source file is a template or if the file's contents are encrypted. By storing this metadata in the filename, the metadata is unambiguously associated with a single file and adding, updating, or removing a single file touches only a single file in the source state. Changes to the metadata (e.g. chezmoi chattr +template $TARGET) are simple file renames and isolated to the affected file.
If chezmoi were to, say, use a common configuration file listing which files were templates and/or encrypted, then changes to any file would require updates to the common configuration file. Automating updates to configuration files requires a round trip (read config file, update config, write config) and it is not always possible preserve comments and formatting.
chezmoi's attributes of executable_, private_, and readonly_ allow the file permissions 0o644, 0o755, 0o600, 0o700, 0o444, 0o555, 0o400, and 0o500 to be represented. Directories can only have permissions 0o755, 0o700, or 0o500. In practice, these cover all permissions typically used for dotfiles. If this does cause a genuine problem for you, please open an issue on GitHub.
File permissions and modes like executable_, private_, readonly_, and symlink_ could also be stored in the filesystem, rather than in the filename. However, this requires the permissions to be preserved and handled by the underlying version control system and filesystem. chezmoi provides first-class support for Windows, where the executable_ and private_ attributes have no direct equivalents and symbolic links are not always permitted. By using regular files and directories, chezmoi avoids variations in the operating system, version control system, and filesystem making it both more robust and more portable.
chezmoi uses a 1:1 mapping between entries in the source state and entries in the target state. This mapping is bi-directional and unambiguous.
However, this also means that dotfiles that in the same directory in the target state must be in the same directory in the source state. In particular, every entry managed by chezmoi in the root of your home directory has a corresponding entry in the root of your source directory, which can mean that you end up with a lot of entries in the root of your source directory. This can be mitigated by using .chezmoiroot file.
If chezmoi were to permit, say, multiple separate source directories (so you could, say, put dot_bashrc in a bash/ subdirectory, and dot_vimrc in a vim/ subdirectory, but have chezmoi apply map these to ~/.bashrc and ~/.vimrc in the root of your home directory) then the mapping between source and target states is no longer bidirectional nor unambiguous, which significantly increases complexity and requires more user interaction. For example, if both bash/dot_bashrc and vim/dot_bashrc exist, what should be the contents of ~/.bashrc? If you run chezmoi add ~/.zshrc, should dot_zshrc be stored in the source bash/ directory, the source vim/ directory, or somewhere else? How does the user communicate their preferences?
chezmoi has many users and any changes to the source state representation must be backwards-compatible.
In summary, chezmoi's source state representation is a compromise with both advantages and disadvantages. Changes to the representation will be considered, but must meet the following criteria, in order of importance:
Be fully backwards-compatible for existing users.
Fix a genuine problem encountered in practice.
Be independent of the underlying operating system, version control system, and filesystem.
Not add significant extra complexity to the user interface or underlying implementation.
"},{"location":"user-guide/frequently-asked-questions/design/#can-chezmoi-support-multiple-sources-or-multiple-source-states","title":"Can chezmoi support multiple sources or multiple source states?","text":"
With some dotfile managers, dotfiles can be distributed across multiple directories or even multiple repos. For example, the user might have one directory per application, or separate repos for home and work configurations, or even separate git submodules for different applications. These can be considered multiple sources of truth for the target state. This, however, comes with complications:
Multiple sources of truth complicate the user interface. When running chezmoi add $FILE, which source should $FILE be added to?
Multiple sources of truth do not compose easily if target files overlap. For example, if you have two sources, both of which need to set an environment variable in .bashrc, how do you handle this when both, only one, or neither source might be activated? What if the sources are mutually exclusive, e.g. if the VIM source and the Emacs source both want to set the $EDITOR environment variable?
Multiple sources of truth are not always independent. Related to the previous point, consider a source that adds an applications's configuration files and shell completions. Should the shell completions be part of the applications's source or of the shell's source?
chezmoi instead makes the opinionated choice to use a single source of truth, i.e. a single branch in a single git repo. Using a single source of truth avoids the inherent complexity and ambiguity of multiple sources.
chezmoi provides mechanisms like templates (for minor differences), .chezmoiignore (for controlling the presence or otherwise of complete files and directories), and password manager integration (so secrets never need to be stored in a repo) handle machine-to-machine differences. Externals make it easy to pull in dotfiles from third-party sources.
That said, if you are keen to use multiple sources of truth with chezmoi, you have a number of options with some scripting around chezmoi.
Firstly, you can run chezmoi apply with different arguments to the --config and --source flags which will apply to the same destination. So that you only have to type one command you can wrap this in a shell function, for example:
If you want to generate multiple configuration files with chezmoi init then you will need the --config-path flag. For more advanced use, use the --destination, --cache, and --persistent-state flags.
Secondly, you can assemble a single source state from multiple sources and then use chezmoi apply. For example, if you have multiple source states in subdirectories of ~/.dotfiles:
#!/bin/bash\n\n# create a combined source state in a temporary directory\ncombined_source=\"$(mktemp -d)\"\n\n# remove the temporary source state on exit\ntrap 'rm -rf -- \"${combined_source}\"' INT TERM\n\n# copy files from multiple sources into the temporary source state\nfor source in $HOME/.dotfiles/*; do\n cp -r \"${source}\"/* \"${combined_source}\"\ndone\n\n# apply the temporary source state\nchezmoi apply --source \"${combined_source}\"\n
Thirdly, you can use a run_ script to invoke a second instance of chezmoi, as used by @felipecrs.
"},{"location":"user-guide/frequently-asked-questions/design/#why-does-chezmoi-cd-spawn-a-shell-instead-of-just-changing-directory","title":"Why does chezmoi cd spawn a shell instead of just changing directory?","text":"
chezmoi cd spawns a shell because it is not possible for a program to change the working directory of its parent process. You can add a shell function instead:
chezmoi-cd() {\n cd $(chezmoi source-path)\n}\n
Typing chezmoi-cd will then change the directory of your current shell to chezmoi's source directory.
"},{"location":"user-guide/frequently-asked-questions/design/#why-are-the-prompt-functions-only-available-in-config-file-templates","title":"Why are the prompt* functions only available in config file templates?","text":"
chezmoi regularly needs to execute templates to determine the target contents of files. For example, templates are executed for the apply, diff, and status commands, amongst many others. Having to interactively respond each time would quickly become tiresome. Therefore, chezmoi only provides these functions when generating a config file from a config file template (e.g. when you run chezmoi init or chezmoi --init apply).
"},{"location":"user-guide/frequently-asked-questions/design/#why-not-use-ansiblechefpuppetsalt-or-similar-to-manage-my-dotfiles-instead","title":"Why not use Ansible/Chef/Puppet/Salt, or similar to manage my dotfiles instead?","text":"
Whole system management tools are more than capable of managing your dotfiles, but they are large systems that entail several disadvantages. Compared to whole system management tools, chezmoi offers:
Small, focused feature set designed for dotfiles. There's simply less to learn with chezmoi compared to whole system management tools.
Easy installation and execution on every platform, without root access. Installing chezmoi requires only copying a single binary file with no external dependencies. Executing chezmoi just involves running the binary. In contrast, installing and running a whole system management tool typically requires installing a scripting language runtime, several packages, and running a system service, all typically requiring root access.
chezmoi's focus and simple installation means that it runs almost everywhere: from tiny ARM-based Linux systems to Windows desktops, from inside lightweight containers to FreeBSD-based virtual machines in the cloud.
"},{"location":"user-guide/frequently-asked-questions/design/#can-i-use-chezmoi-to-manage-files-outside-my-home-directory","title":"Can I use chezmoi to manage files outside my home directory?","text":"
In practice, yes, you can, but this usage is strongly discouraged beyond using your system's package manager to install the packages you need.
chezmoi is designed to operate on your home directory, and is explicitly not a full system configuration management tool. That said, there are some ways to have chezmoi manage a few files outside your home directory.
chezmoi's scripts can execute arbitrary commands, so you can use a run_ script that is run every time you run chezmoi apply, to, for example:
Make the target file outside your home directory a symlink to a file managed by chezmoi in your home directory.
Copy a file managed by chezmoi inside your home directory to the target file.
Execute a template with chezmoi execute-template --output=$FILENAME template where $FILENAME is outside the target directory.
chezmoi executes all scripts as the user executing chezmoi, so you may need to add extra privilege elevation commands like sudo or PowerShell start -verb runas -wait to your script.
chezmoi, by default, operates on your home directory but this can be overridden with the --destination command line flag or by specifying destDir in your config file, and could even be the root directory (/ or C:\\). This allows you, in theory, to use chezmoi to manage any file in your filesystem, but this usage is extremely strongly discouraged.
If your needs extend beyond modifying a handful of files outside your target system, then existing configuration management tools like Puppet, Chef, Ansible, and Salt are much better suited - and of course can be called from a chezmoi run_ script. Put your Puppet Manifests, Chef Recipes, Ansible Modules, and Salt Modules in a directory ignored by .chezmoiignore so they do not pollute your home directory.
chezmoi was inspired by Puppet, but was created because Puppet is an 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.
"},{"location":"user-guide/frequently-asked-questions/design/#where-does-the-name-chezmoi-come-from","title":"Where does the name \"chezmoi\" come from?","text":"
\"chezmoi\" splits to \"chez moi\" and pronounced /\u0283e\u026a mwa/ (shay-mwa) meaning \"at my house\" in French. It's seven letters long, which is an appropriate length for a command that is only run occasionally. If you prefer a shorter command, add an alias to your shell configuration, for example:
alias cz=chezmoi\n
"},{"location":"user-guide/frequently-asked-questions/encryption/","title":"Encryption","text":""},{"location":"user-guide/frequently-asked-questions/encryption/#how-do-i-configure-chezmoi-to-encrypt-files-but-only-request-a-passphrase-the-first-time-chezmoi-init-is-run","title":"How do I configure chezmoi to encrypt files but only request a passphrase the first time chezmoi init is run?","text":"
The following steps use age for encryption.
This can be achieved with the following process:
Generate an age private key.
Encrypt the private key with a passphrase.
Configure chezmoi to decrypt the private key if needed.
Configure chezmoi to use the private key.
Add encrypted files.
First, change to chezmoi's root directory:
chezmoi cd ~\n
Generate an age private key encrypted with a passphrase in the file key.txt.age with the command:
$ age-keygen | age --armor --passphrase > key.txt.age\nPublic key: age193wd0hfuhtjfsunlq3c83s8m93pde442dkcn7lmj3lspeekm9g7stwutrl\nEnter passphrase (leave empty to autogenerate a secure one):\nConfirm passphrase:\n
Use a strong passphrase and make a note of the public key (age193wd0hfuhtjfsunlq3c83s8m93pde442dkcn7lmj3lspeekm9g7stwutrl in this case).
Add key.txt.age to .chezmoiignore so that chezmoi does not try to create it:
echo key.txt.age >> .chezmoiignore\n
Configure chezmoi to decrypt the passphrase-encrypted private key if needed:
Specify the public and private keys for encryption. age.recipient must be your public key from above. Make sure encryption is added at the beginning, before any other sections.
Run chezmoi init --apply to generate the chezmoi's config file and decrypt the private key:
$ chezmoi init --apply\nEnter passphrase:\n
At this stage everything is configured and git status should report:
$ git status\nOn branch main\nUntracked files:\n (use \"git add <file>...\" to include in what will be committed)\n .chezmoi.toml.tmpl\n .chezmoiignore\n key.txt.age\n run_once_before_decrypt-private-key.sh.tmpl\n\nnothing added to commit but untracked files present (use \"git add\" to track)\n
If you're happy with the changes you can commit them. All four files should be committed.
Add files that you want to encrypt using the --encrypt argument to chezmoi add, for example:
chezmoi add --encrypt ~/.ssh/id_rsa\n
When you run chezmoi init on a new machine you will be prompted to enter your passphrase once to decrypt key.txt.age. Your decrypted private key will be stored in ~/.config/chezmoi/key.txt.
"},{"location":"user-guide/frequently-asked-questions/encryption/#how-to-re-encrypt-encrypted-files","title":"How to re-encrypt encrypted files","text":"
To rotate from an expired GPG key to its replacement, or change from GPG to age encryption, the following steps can be used:
Make sure you have applied all encrypted files (e.g. chezmoi apply decrypts files and places them in their destinations).
Update chezmoi configuration to use the new encryption method (examples: gpg, age, age with one-time passphrase).
Remove all encrypted files from the state via chezmoi forget or chezmoi unmanage.
Add them back with chezmoi add --encrypt.
"},{"location":"user-guide/frequently-asked-questions/encryption/#example-migrate-from-gpg-to-age","title":"Example: Migrate from GPG to age","text":"
Update chezmoi configuration to use age encryption (with chezmoi edit-config or manually editing the corresponding template):
for encrypted_file in $(chezmoi managed --include encrypted --path-style absolute)\ndo\n # optionally, add --force to avoid prompts\n chezmoi forget \"$encrypted_file\"\n\n # strip the .asc extension\n decrypted_file=\"${encrypted_file%.asc}\"\n\n chezmoi add --encrypt \"$decrypted_file\"\ndone\n
"},{"location":"user-guide/frequently-asked-questions/general/","title":"General","text":""},{"location":"user-guide/frequently-asked-questions/general/#what-other-questions-have-been-asked-about-chezmoi","title":"What other questions have been asked about chezmoi?","text":"
See the issues and discussions.
"},{"location":"user-guide/frequently-asked-questions/general/#where-do-i-ask-a-question-that-isnt-answered-here","title":"Where do I ask a question that isn't answered here?","text":"
Please open an issue on GitHub or start a discussion.
"},{"location":"user-guide/frequently-asked-questions/general/#i-like-chezmoi-how-do-i-say-thanks","title":"I like chezmoi. How do I say thanks?","text":"
Thank you! chezmoi was written to scratch a personal itch, and I'm very happy that it's useful to you. Please give chezmoi a star on GitHub, and if you're happy to share your public dotfile repo then tag it with chezmoi.
If you write an article or give a talk on chezmoi please inform the author (e.g. by opening an issue) so it can be added to chezmoi's articles, podcasts, and videos pages.
Contributions are very welcome and every bug report, support request, and feature request helps make chezmoi better. Thank you :)
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/","title":"Troubleshooting","text":""},{"location":"user-guide/frequently-asked-questions/troubleshooting/#how-can-i-quickly-check-for-problems-with-chezmoi-on-my-machine","title":"How can I quickly check for problems with chezmoi on my machine?","text":"
Run:
chezmoi doctor\n
Anything ok is fine, anything warning is only a problem if you want to use the related feature, and anything error indicates a definite problem.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#a-specific-command-is-not-behaving-as-i-expect-how-can-i-debug-it","title":"A specific command is not behaving as I expect. How can I debug it?","text":"
The --verbose flag makes chezmoi to print extra information about what it is doing.
The --debug flag makes chezmoi print very detailed step by step information.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#the-output-of-chezmoi-diff-is-broken-and-does-not-contain-color-what-could-be-wrong","title":"The output of chezmoi diff is broken and does not contain color. What could be wrong?","text":"
By default, chezmoi's diff output includes ANSI color escape sequences (e.g. ESC[37m) and is piped into your pager (by default less). chezmoi assumes that your pager passes through the ANSI color escape sequences, as configured on many systems, but not all. If your pager does not pass through ANSI color escape sequences then you will see monochrome diff output with uninterpreted ANSI color escape sequences.
This can typically by fixed by setting the environment variable
export LESS=-R\n
which instructs less to display \"raw\" control characters via the -R / --RAW-CONTROL-CHARS option.
You can also set the pager configuration variable in your config file, for example:
~/.config/chezmoi/chezmoi.toml
pager = \"less -R\"\n
If you have set a different pager (via the pager configuration variable or PAGER environment variable) then you must ensure that it passes through raw control characters. Alternatively, you can use the --color=false option to chezmoi to disable colors or the --no-pager option to chezmoi to disable the pager.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#why-do-i-get-a-blank-buffer-or-empty-file-when-running-chezmoi-edit","title":"Why do I get a blank buffer or empty file when running chezmoi edit?","text":"
In this case, chezmoi edit typically prints a warning like:
chezmoi: warning: $EDITOR $TMPDIR/$FILENAME: returned in less than 1s\n
chezmoi edit performs a bit of magic to improve the experience of editing files in the source state by invoking your editor with filenames in a temporary directory that look like filenames in your home directory. What's happening here is that your editor command is exiting immediately, so chezmoi thinks you've finished editing and so removes the temporary directory, but actually your editor command has forked a edit process in the background, and that edit process opens a now non-existent file.
To fix this you have to configure your editor command to remain in the foreground until you have finished editing the file, so chezmoi knows when to remove the temporary directory.
VIMVSCode
Pass the -f flag, e.g. by setting the edit.flags configuration variable to [\"-f\"], or by setting the EDITOR environment variable to include the -f flag, e.g. export EDITOR=\"vim -f\".
Pass the --wait flag, e.g. by setting the edit.flags configuration variable to [\"--wait\"] or by setting the EDITOR environment variable to include the --wait flag, e.g. export EDITOR=\"code --wait\".
The \"bit of magic\" that chezmoi edit performs includes:
chezmoi edit makes the filename opened by your editor more closely match the target filename, which can help your editor choose the correct syntax highlighting. For example, if you run chezmoi edit ~/.zshrc, your editor is be opened with $TMPDIR/.zshrc but you'll actually be editing ~/.local/share/chezmoi/dot_zshrc. Under the hood, chezmoi creates a hardlink in a temporary directory to the file in your source directory, so even though your editor thinks it's editing .zshrc, it is really editing dot_zshrc in your source directory.
If the source file is encrypted then chezmoi edit transparently decrypts and re-encrypts the file for you. Specifically, chezmoi decrypts the file into a private temporary directory and open your editor with the decrypted file, and re-encrypts the file when you exit your editor.
If the source file is a template, then chezmoi edit preserves the .tmpl extension.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-makes-sshconfig-group-writeable-how-do-i-stop-this","title":"chezmoi makes ~/.ssh/config group writeable. How do I stop this?","text":"
By default, chezmoi uses your system's umask when creating files. On most systems the default umask is 022 but some systems use 002, which means that files and directories are group writeable by default.
You can override this for chezmoi by setting the umask configuration variable in your configuration file, for example:
~/.config/chezmoi/chezmoi.toml
umask = 0o022\n
Note
This will apply to all files and directories that chezmoi manages and will ensure that none of them are group writeable. It is not currently possible to control group write permissions for individual files or directories. Please open an issue on GitHub if you need this.
This is likely because the chezmoi binary you are using was statically compiled with musl and the machine you are running on uses LDAP or NIS.
The immediate fix is to use a package built for your distribution (e.g a .deb or .rpm) which is linked against glibc and includes LDAP/NIS support instead of the statically-compiled binary.
If the problem still persists, then please open an issue on GitHub.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-chezmoi-timeout-or-chezmoi-timeout-obtaining-persistent-state-lock","title":"chezmoi reports chezmoi: timeout or chezmoi: timeout obtaining persistent state lock","text":"
chezmoi will report this when it is unable to lock its persistent state (~/.config/chezmoi/chezmoistate.boltdb), typically because another instance of chezmoi is currently running and holding the lock.
This can happen, for example, if you have a run_ script that invokes chezmoi, or are running chezmoi in another window.
Under the hood, chezmoi uses bbolt which permits multiple simultaneous readers, but only one writer (with no readers).
Commands that take a write lock include add, apply, edit, forget, import, init, state, unmanage, and update. Commands that take a read lock include diff, status, and verify.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-chezmoi-forkexec-tmpxxxxxxxxxxxx-exec-format-error-when-executing-a-template-script","title":"chezmoi reports chezmoi: fork/exec /tmp/XXXXXXXXXX.XX: exec format error when executing a template script","text":"
This error occurs when you have a newline before the #! in your script. Suppress the newline by including a - before the closing }} on the first line.
For example, if your template script begins with
{{ if eq .chezmoi.os \"linux\" }}\n#!/bin/sh\n
change this to
{{ if eq .chezmoi.os \"linux\" -}}\n#!/bin/sh\n
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-chezmoi-forkexec-tmpxxxxxxxxxxxx-permission-denied-when-executing-a-script","title":"chezmoi reports chezmoi: fork/exec /tmp/XXXXXXXXXX.XX: permission denied when executing a script","text":"
This error occurs when your temporary directory is mounted with the noexec option.
As chezmoi scripts can be templates, encrypted, or both, chezmoi needs to write the final script's contents to a file so that it can be executed by the operating system. By default, chezmoi will use $TMPDIR for this.
You can change the temporary directory into which chezmoi writes and executes scripts with the scriptTempDir configuration variable. For example, to use a subdirectory of your home directory you can use:
~/.config/chezmoi/chezmoi.toml
scriptTempDir = \"~/tmp\"\n
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-chezmoi-mkdir-xxxxx-no-such-file-or-directory-when-trying-to-manage-file-or-directory","title":"chezmoi reports chezmoi: mkdir xxxxx: no such file or directory when trying to manage file or directory","text":"
This error occurs when you try to add directory/file to be managed via chezmoi but the same directory is only listed in .chezmoiexternal.$FORMAT.
A workaround can be applied in a such case via manually creating import directory in chezmoi source directory (typically ~/.local/share/chezmoi) and create .keep file.
For example, if .chezmoiexternal.toml has the configuration:
Now once that done chezmoi add ~/.config/direnv/direnvrc should work. For reference see this issue
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-read-devstdin-permission-denied-or-write-devstdout-permission-denied-when-i-redirect-standard-input-or-standard-output","title":"chezmoi reports read /dev/stdin: permission denied or write /dev/stdout: permission denied when I redirect standard input or standard output","text":"
This error occurs when you installed chezmoi with snap and is caused by a long-standing bug in snap.
This is not a bug in chezmoi and there is nothing that chezmoi can do about this. However, there are two workarounds:
Firstly, you can use alternatives to shell redirection. For standard input:
Secondly, you can install chezmoi with any of the many supported install methods instead of snap.
"},{"location":"user-guide/frequently-asked-questions/troubleshooting/#chezmoi-reports-forkexec-no-such-file-or-directory-when-running-scripts-on-nix-or-termux","title":"chezmoi reports fork/exec ...: no such file or directory when running scripts on Nix or Termux","text":"
You are likely using a hardcoded script interpreter in the shebang line of your scripts, e.g.
#!/bin/bash\n
/bin/bash does not exist on Nix or Termux. You must update the shebang line to point to the actual bash interpreter. The easiest way to do this is make the script a template and use the lookPath template function, for example:
#!{{ lookPath \"bash\" }}\n
Alternatively, you can use the actual path to bash on your system, for example:
NixTermux
#!/usr/bin/env bash\n
#!/data/data/com.termux/files/usr/bin/bash\n
"},{"location":"user-guide/frequently-asked-questions/usage/","title":"Usage","text":""},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-edit-my-dotfiles-with-chezmoi","title":"How do I edit my dotfiles with chezmoi?","text":"
There are five popular approaches:
Use chezmoi edit $FILE. This will open the source file for $FILE in your editor, including opening the template if the file is templated and transparently decrypting and re-encrypting it if it is encrypted. For extra ease, use chezmoi edit --apply $FILE to apply the changes when you quit your editor, and chezmoi edit --watch $FILE to apply the changes whenever you save the file.
Use chezmoi cd and edit the files in the source directory directly. Run chezmoi diff to see what changes would be made, and chezmoi apply to make the changes.
If your editor supports opening directories, run chezmoi edit with no arguments to open the source directory.
Edit the file in your home directory, and then either re-add it by running chezmoi add $FILE or chezmoi re-add.
Edit the file in your home directory, and then merge your changes with source state by running chezmoi merge $FILE.
Note
re-add doesn't work with templates.
"},{"location":"user-guide/frequently-asked-questions/usage/#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","title":"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?","text":"
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.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-can-i-tell-what-dotfiles-in-my-home-directory-arent-managed-by-chezmoi-is-there-an-easy-way-to-have-chezmoi-manage-a-subset-of-them","title":"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?","text":"
chezmoi unmanaged will list everything not managed by chezmoi. You can add entire directories with chezmoi add.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-can-i-tell-what-dotfiles-in-my-home-directory-are-currently-managed-by-chezmoi","title":"How can I tell what dotfiles in my home directory are currently managed by chezmoi?","text":"
chezmoi managed will list everything managed by chezmoi.
"},{"location":"user-guide/frequently-asked-questions/usage/#if-theres-a-mechanism-in-place-for-the-above-is-there-also-a-way-to-tell-chezmoi-to-ignore-specific-files-or-groups-of-files-eg-by-directory-name-or-by-glob","title":"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)?","text":"
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 called .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.
"},{"location":"user-guide/frequently-asked-questions/usage/#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","title":"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?","text":"
Yes. Running chezmoi add will update the source state with the target. To see diffs of what would change, without actually changing anything, use chezmoi diff.
"},{"location":"user-guide/frequently-asked-questions/usage/#once-ive-made-a-change-to-the-source-directory-how-do-i-commit-it","title":"Once I've made a change to the source directory, how do I commit it?","text":"
You have several options:
chezmoi cd opens a shell in the source directory, where you can run your usual version control commands, like git add and git commit.
chezmoi git runs git in 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.
"},{"location":"user-guide/frequently-asked-questions/usage/#ive-made-changes-to-both-the-destination-state-and-the-source-state-that-i-want-to-keep-how-can-i-keep-them-both","title":"I've made changes to both the destination state and the source state that I want to keep. How can I keep them both?","text":"
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.
"},{"location":"user-guide/frequently-asked-questions/usage/#can-i-use-chezmoi-to-manage-my-shell-history-across-multiple-machines","title":"Can I use chezmoi to manage my shell history across multiple machines?","text":"
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. chezmoi 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 shell histories.
Instead, consider using a dedicated tool for sharing shell history across multiple machines, like atuin. You can use chezmoi to install and configure atuin.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-install-pre-requisites-for-templates","title":"How do I install pre-requisites for templates?","text":"
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:
chezmoi will make sure to execute it before templating other files.
Tip
You can use scriptEnv to inject data into your scripts through environment variables.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-write-a-literal-or-in-a-template","title":"How do I write a literal {{ or }} in a template?","text":"
{{ and }} are chezmoi's default template delimiters, and so need escaping, for example:
{{ \"{{\" }}\n{{ \"}}\" }}\n
results in
{{\n}}\n
For longer tokens containing a {{ and a }} you can use a longer literal, for example:
{{ \"{{ .Target }}\" }}\n
results in
{{ .Target }}\n
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-run-a-script-when-a-git-repo-external-changes","title":"How do I run a script when a git-repo external changes?","text":"
Use a run_onchange_after_*.tmpl script that includes the HEAD commit. For example, if ~/.emacs.d is a git-repo external, then create:
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-run-a-script-periodically","title":"How do I run a script periodically?","text":"
Use a run_once_*.tmpl script that includes the current time truncated to a suitable unit. For example, to run a script daily:
~/.local/share/chezmoi/run_once_daily.tmpl
#!/bin/sh\n\n# {{ now | date \"2006-01-02\" }}\necho \"new day\"\n
For weekly, use the week number from the output of date, for example:
~/.local/share/chezmoi/run_once_weekly.tmpl
#!/bin/sh\n\n# {{ output \"date\" \"+%V\" | trim }}\necho \"new week\"\n
Or, approximate the week number with template functions:
~/.local/share/chezmoi/run_once_weekly.tmpl
#!/bin/sh\n\n# {{ div now.YearDay 7 }}\necho \"new week\"\n
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-enable-shell-completions","title":"How do I enable shell completions?","text":"
chezmoi includes shell completions for bash, fish, powershell, and zsh. If you have installed chezmoi via your package manager then the shell completion should already be installed. For PowerShell, you need to manually add the completion script to your profile. 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.
"},{"location":"user-guide/frequently-asked-questions/usage/#how-do-i-use-tools-that-i-installed-with-flatpak","title":"How do I use tools that I installed with Flatpak?","text":"
Command line programs installed with Flatpak cannot be run directly. Instead, they must be run with flatpak run. This can either be added by using a wrapper script or by configuring chezmoi to invoke flatpak run with the correct arguments directly. Wrapper scripts are recommended, as they work with the doctor command.
"},{"location":"user-guide/frequently-asked-questions/usage/#use-a-wrapper-script","title":"Use a wrapper script","text":"
Create a wrapper script with the exact same name as the command that invokes flatpak run and passes all arguments to the wrapped command.
For example, to wrap KeePassXC installed with Flatpak, create the script:
keepassxc-cli
#!/bin/bash\n\nflatpak run --command=keepassxc-cli org.keepassxc.KeePassXC -- \"$@\"\n
Note that the script is called keepassxc-cli without any .sh extension, so it has the exact same name as the keepassxc-cli command that chezmoi invokes by default. Ensure that this script is in your path and is executable.
"},{"location":"user-guide/frequently-asked-questions/usage/#configure-chezmoi-to-invoke-flatpak-run","title":"Configure chezmoi to invoke flatpak run","text":"
For tools that chezmoi invokes with .command and .args configuration variables, you can configure chezmoi to invoke flatpak directly with the correct arguments.
For example, to use VSCodium installed with Flatpak as your diff command, add the following to your config file:
Note that the command is flatpak, the first two arguments are run and the name of app, and any further arguments are passed to the app.
"},{"location":"user-guide/machines/containers-and-vms/","title":"Containers and VMs","text":"
You can use chezmoi to manage your dotfiles in GitHub Codespaces, Visual Studio Codespaces, and Visual Studio Code Remote - Containers.
For a quick start, you can clone the chezmoi/dotfiles repository which supports Codespaces out of the box.
The workflow is different to using chezmoi on a new machine, notably:
These systems will automatically clone your dotfiles repo to ~/dotfiles, so there is no need to clone your repo yourself.
The installation script must be non-interactive.
When running in a Codespace, the environment variable CODESPACES will be set to true. You can read its value with the env template function.
First, if you are using a chezmoi configuration file template, ensure that it is non-interactive when running in Codespaces, for example, .chezmoi.toml.tmpl might contain:
{{- $codespaces:= env \"CODESPACES\" | not | not -}}\nsourceDir = {{ .chezmoi.sourceDir | quote }}\n\n[data]\n name = \"Your name\"\n codespaces = {{ $codespaces }}\n{{- if $codespaces }}{{/* Codespaces dotfiles setup is non-interactive, so set an email address */}}\n email = \"your@email.com\"\n{{- else }}{{/* Interactive setup, so prompt for an email address */}}\n email = {{ promptString \"email\" | quote }}\n{{- end }}\n
Info
Setting the sourceDir configuration variable to .chezmoi.sourceDir is required because Codespaces clones your dotfiles repo to a different one to chezmoi's default.
This sets the codespaces template variable, so you don't have to repeat (env \"CODESPACES\") in your templates. It also sets the sourceDir configuration to the --source argument passed in chezmoi init.
Second, create an install.sh script that installs chezmoi and your dotfiles and add it to .chezmoiignore and your dotfiles repo:
The generated script installs the latest version of chezmoi in ~/.local/bin if needed, and then chezmoi init ... invokes chezmoi to create its configuration file and initialize your dotfiles. --apply tells chezmoi to apply the changes immediately, and --source=... tells chezmoi where to find the cloned dotfiles repo, which in this case is the same folder in which the script is running from.
Finally, modify any of your templates to use the codespaces variable if needed. For example, to install vim-gtk on Linux but not in Codespaces, your run_once_install-packages.sh.tmpl might contain:
{{- if (and (eq .chezmoi.os \"linux\") (not .codespaces)) -}}\n#!/bin/sh\nsudo apt install -y vim-gtk\n{{- end -}}\n
"},{"location":"user-guide/machines/general/","title":"General","text":""},{"location":"user-guide/machines/general/#determine-whether-the-current-machine-is-a-laptop-or-desktop","title":"Determine whether the current machine is a laptop or desktop","text":"
The following template sets the $chassisType variable to \"desktop\" or \"laptop\" on macOS, Linux, and Windows.
"},{"location":"user-guide/machines/general/#determine-how-many-cpu-cores-and-threads-the-current-machine-has","title":"Determine how many CPU cores and threads the current machine has","text":"
The following template sets the $cpuCores and $cpuThreads variables to the number of CPU cores and threads on the current machine respectively on macOS, Linux and Windows.
{{- if gt .cpu.threads .cpu.cores -}}\nHyperthreaded!\n{{- else -}}\nNot hyperthreaded!\n{{- end -}}\n
"},{"location":"user-guide/machines/linux/","title":"Linux","text":""},{"location":"user-guide/machines/linux/#combine-operating-system-and-linux-distribution-conditionals","title":"Combine operating system and Linux distribution conditionals","text":"
There can be as much variation between Linux distributions as there is between operating systems. Due to text/template's eager evaluation of conditionals, this means you often have to write templates with nested conditionals:
{{ if eq .chezmoi.os \"darwin\" }}\n# macOS-specific code\n{{ else if eq .chezmoi.os \"linux\" }}\n{{ if eq .chezmoi.osRelease.id \"debian\" }}\n# Debian-specific code\n{{ else if eq .chezmoi.osRelease.id \"fedora\" }}\n# Fedora-specific code\n{{ end }}\n{{ end }}\n
This can be simplified by combining the operating system and distribution into a single custom template variable. Put the following in your configuration file template:
This defines the .osid template variable to be {{ .chezmoi.os }} on machines without an os-release file, or to be {{ .chezmoi.os }}-{{ .chezmoi.osRelease.id }} on machines with an os-release file.
You can then simplify your conditionals to be:
{{ if eq .osid \"darwin\" }}\n# macOS-specific code\n{{ else if eq .osid \"linux-debian\" }}\n# Debian-specific code\n{{ else if eq .osid \"linux-fedora\" }}\n# Fedora-specific code\n{{ end }}\n
"},{"location":"user-guide/machines/macos/","title":"macOS","text":""},{"location":"user-guide/machines/macos/#use-brew-bundle-to-manage-your-brews-and-casks","title":"Use brew bundle to manage your brews and casks","text":"
Homebrew's brew bundle subcommand allows you to specify a list of brews and casks to be installed. You can integrate this with chezmoi by creating a run_once_ script. For example, create a file in your source directory called run_once_before_install-packages-darwin.sh.tmpl containing:
{{- if eq .chezmoi.os \"darwin\" -}}\n#!/bin/bash\n\nbrew bundle --no-lock --file=/dev/stdin <<EOF\nbrew \"git\"\ncask \"google-chrome\"\nEOF\n{{ end -}}\n
Note
The Brewfile is embedded directly in the script with a bash here document. chezmoi will run this script whenever its contents change, i.e. when you add or remove brews or casks.
"},{"location":"user-guide/machines/macos/#determine-the-hostname","title":"Determine the hostname","text":"
The result of the hostname command on macOS depends on the network that the machine is connected to. For a stable result, use the scutil command:
{{ $computerName := output \"scutil\" \"--get\" \"ComputerName\" | trim }}\n
"},{"location":"user-guide/machines/macos/#run-script-after-every-macos-update","title":"Run script after every macOS update","text":"
You can automate a script to run after each macOS update by creating a run_onchange_ script and using the output template function to run sw_vers:
"},{"location":"user-guide/machines/windows/","title":"Windows","text":""},{"location":"user-guide/machines/windows/#detect-windows-subsystem-for-linux-wsl","title":"Detect Windows Subsystem for Linux (WSL)","text":"
WSL can be detected by looking for the string Microsoft or microsoft in /proc/sys/kernel/osrelease, which is available in the template variable .chezmoi.kernel.osrelease, for example:
{{ if eq .chezmoi.os \"linux\" }}\n{{ if (.chezmoi.kernel.osrelease | lower | contains \"microsoft\") }}\n# WSL-specific code\n{{ end }}\n{{ end }}\n
"},{"location":"user-guide/machines/windows/#run-a-powershell-script-as-admin-on-windows","title":"Run a PowerShell script as admin on Windows","text":"
If you use gsudo, it has tips on writing self-elevating scripts.
"},{"location":"user-guide/machines/windows/#notes-on-running-elevated-scripts","title":"Notes on running elevated scripts","text":"
However you decide to run a script in an elevated prompt, as soon as the non-elevated script returns, chezmoi will move to the next step in its processing (running more scripts, creating files, etc.). Ensure that the elevated script completes before the non-elevated script exits, or subsequent steps may not run as expected. In the example above, this is accomplished by passing -Wait to PowerShell's Start-Process cmdlet.
Note that by including -NoExit in $CommandLine, the new (elevated) PowerShell process/window will not exit automatically on completion. This means you'll need to close the new window by hand for chezmoi to continue its steps. If this manual intervention is desired, it would be convenient to print a message as the script's last command to indicate completion for you to safely close the elevated window. If you want no manual intervention, you can remove -NoExit from $CommandLine, but then you likely won\u2019t see the output of the elevated script, which will make it more difficult to determine if something went wrong during its execution.
Template functions allow you to retrieve secrets from many popular password managers. Using a password manager allows you to keep all your secrets in one place, make your dotfiles repo public, and synchronize changes to secrets across multiple machines.
The output of op item get $UUID --format json is available as the onepassword template function. chezmoi parses the JSON output and returns it as structured data. For example, if the output is:
chezmoi will verify the availability and validity of a session token in the current environment. If it is missing or expired, you will be interactively prompted to sign-in again.
In the past chezmoi used to exit with an error when no valid session was available. If you'd like to restore this behavior, set the onepassword.prompt configuration variable to false, for example:
~/.config/chezmoi/chezmoi.toml
[onepassword]\n prompt = false\n
Danger
Do not use prompt on shared machines. A session token verified or acquired interactively will be passed to the 1Password CLI through a command line parameter, which is visible to other users of the same system.
chezmoi has experimental support for secrets automation with 1Password Connect and 1Password Service Accounts. These might be used on restricted machines where you cannot or do not wish to install a full 1Password desktop application.
When these features are used, the behavior of the 1Password CLI changes, so chezmoi requires explicit configuration for either connect or service account modes using the onepassword.mode configuration option. The default, if not specified, is account:
~/.config/chezmoi/chezmoi.toml
[onepassword]\n mode = \"account\"\n
In account mode, chezmoi will stop with an error if the environment variable OP_SERVICE_ACCOUNT_TOKEN is set, or if both environment variables OP_CONNECT_HOST and OP_CONNECT_TOKEN are set.
Info
Both 1Password Connect and Service Accounts prevent the CLI from working with multiple accounts. If you need access to secrets from more than one 1Password account, do not use these features with chezmoi.
The AWS shared profile name and region can be specified in chezmoi's config file with awsSecretsManager.profile and awsSecretsManager.region respectively. By default, these values will be picked up from the standard environment variables and config files used by the standard AWS tooling.
~/.config/chezmoi/chezmoi.toml
[awsSecretsManager]\n profile = myWorkProfile\n region = us-east-2\n
chezmoi includes support for Bitwarden using the Bitwarden CLI (bw), Bitwarden Secrets CLI (bws), and rbw commands to expose data as a template function.
If required, unlock your Bitwarden vault (API key and SSO logins always require an explicit unlock step):
bw unlock\n
Set the BW_SESSION environment variable, as instructed.
Bitwarden Session One-liner
The BW_SESSION value can be set directly. The exact combination differs based on whether you are currently logged into Bitwarden and how you log into Bitwarden.
export BW_SESSION=$(bw unlock --raw) # You are already logged in with any method\nexport BW_SESSION=$(bw login $BITWARDEN_EMAIL --raw) # You are not logged in and log in with an email\nexport BW_SESSION=$(bw login --sso && bw unlock --raw) # You are not logged in and login with SSO or API key\n
The structured data from bw get is available as the bitwarden template function in your config files, for example:
Custom fields can be accessed with the bitwardenFields template function. For example, if you have a custom field named token you can retrieve its value with:
Attachments can be accessed with the bitwardenAttachment and bitwardenAttachmentByRef template function. For example, if you have an attachment named id_rsa, you can retrieve its value with:
You can use any command line tool that outputs secrets either as a string or in JSON format. Choose the binary by setting secret.command in your configuration file. You can then invoke this command with the secret and secretJSON template functions which return the raw output and JSON-decoded output respectively. All of the above secret managers can be supported in this way:
chezmoi includes support for Doppler using the doppler CLI to expose data through the doppler and dopplerProjectJson template functions.
Log in using:
doppler login\n
It is now possible to interact with the doppler CLI in two different, but similar, ways. Both make use of the command doppler secrets download --json --no-file behind the scenes but present a different experience.
The doppler function is used in the following way:
All secrets from the specified project/config combination are cached for subsequent access and will not requery the doppler CLI for another secret in the same project/config. This caching mechanism enhances performance and reduces unnecessary CLI calls.
The dopplerProjectJson presents the secrets as json structured data and is used in the following way:
It is important to note that neither of the above parse any individual secret as json. This can be achieved by using the fromJson function, for example:
If you want to specify the private key to use for the decryption, structured data can be retrieved with the ejsonDecryptWithKey template function, for example:
Additional attributes are available through the keepassxcAttribute function. For example, if you have an entry called SSH Key with an additional attribute called private-key, its value is available as:
chezmoi includes an experimental mode to support using KeePassXC with YubiKeys. Set keepassxc.mode to open and keepassxc.args to the arguments required to set your YubiKey, for example:
For retrieving more complex data, use the keeper template function with a UID to retrieve structured data from keeper get or the keeperDataFields template function which restructures the output of keeper get in to a more convenient form, for example:
"},{"location":"user-guide/password-managers/keychain-and-windows-credentials-manager/","title":"Keychain and Windows Credentials Manager","text":"
chezmoi includes support for Keychain (on macOS), GNOME Keyring (on Linux and FreeBSD), and Windows Credentials Manager (on Windows) via the zalando/go-keyring library.
Set values with:
$ chezmoi secret keyring set --service=$SERVICE --user=$USER\nValue: xxxxxxxx\n
The value can then be used in templates using the keyring function which takes the service and user as arguments.
For example, save a GitHub access token in keyring with:
$ chezmoi secret keyring set --service=github --user=$GITHUB_USERNAME\nValue: xxxxxxxx\n
and then include it in your ~/.gitconfig file with:
chezmoi includes support for LastPass using the LastPass CLI to expose data as a template function.
Log in to LastPass using:
lpass login $LASTPASS_USERNAME\n
Check that lpass is working correctly by showing password data:
lpass show --json $LASTPASS_ENTRY_ID\n
where $LASTPASS_ENTRY_ID is a LastPass Entry Specification.
The structured data from lpass show --json id is available as the lastpass template function. The value will be an array of objects. You can use the index function and .Field syntax of the text/template language to extract the field you want. For example, to extract the password field from first the \"GitHub\" entry, use:
chezmoi automatically parses the note value of the LastPass entry as colon-separated key-value pairs, so, for example, you can extract a private SSH key like this:
chezmoi includes support for Vault using the Vault CLI to expose data as a template function.
The vault CLI needs to be correctly configured on your machine, e.g. the VAULT_ADDR and VAULT_TOKEN environment variables must be set correctly. Verify that this is the case by running:
vault kv get -format=json $KEY\n
The structured data from vault kv get -format=json is available as the vault template function. You can use the .Field syntax of the text/template language to extract the data you want. For example:
{{ (vault \"$KEY\").data.data.password }}\n
"},{"location":"user-guide/tools/diff/","title":"Diff","text":""},{"location":"user-guide/tools/diff/#use-a-custom-diff-tool","title":"Use a custom diff tool","text":"
By default, chezmoi uses a built-in diff. You can use a custom tool by setting the diff.command and diff.args configuration variables. The elements of diff.args are interpreted as templates with the variables .Destination and .Target containing filenames of the file in the destination state and the target state respectively. For example, to use meld, specify:
If you generate your config file from a config file template, then you'll need to escape the {{ and }} as {{ \"{{\" }} and {{ \"}}\" }}. That way your generated config file contains the {{ and }} you expect.
"},{"location":"user-guide/tools/diff/#use-vscode-as-the-diff-tool","title":"Use VSCode as the diff tool","text":"
To use VSCode as the diff tool, add the following to your config:
"},{"location":"user-guide/tools/diff/#use-delta-as-the-diff-tool","title":"Use delta as the diff tool","text":"
To use delta as the diff tool you must set both diff.command and diff.pager to delta, for example:
TOMLYAML ~/.config/chezmoi/chezmoi.toml
[diff]\ncommand = \"delta\"\npager = \"delta\"\n
~/.config/chezmoi/chezmoi.yaml
diff:\n command: \"delta\"\n pager: \"delta\"\n
"},{"location":"user-guide/tools/diff/#dont-show-scripts-in-the-diff-output","title":"Don't show scripts in the diff output","text":"
By default, chezmoi diff will show all changes, including the contents of scripts that will be run. You can exclude scripts from the diff output by setting the diff.exclude configuration variable in your configuration file, for example:
~/.config/chezmoi/chezmoi.toml
[diff]\n exclude = [\"scripts\"]\n
"},{"location":"user-guide/tools/diff/#dont-show-externals-in-the-diff-output","title":"Don't show externals in the diff output","text":"
To exclude diffs from externals, either pass the --exclude=externals flag or set diff.exclude to [\"externals\"] in your config file.
"},{"location":"user-guide/tools/diff/#customize-the-diff-pager","title":"Customize the diff pager","text":"
You can change the diff format, and/or pipe the output into a pager of your choice by setting diff.pager configuration variable. For example, to use diff-so-fancy specify:
~/.config/chezmoi/chezmoi.toml
[diff]\n pager = \"diff-so-fancy\"\n
The pager can be disabled using the --no-pager flag or by setting diff.pager to an empty string.
"},{"location":"user-guide/tools/diff/#show-human-friendly-diffs-for-binary-files","title":"Show human-friendly diffs for binary files","text":"
Similar to git, chezmoi includes a \"textconv\" feature that can transform file contents before passing them to the diff program. This is primarily useful for generating human-readable diffs of binary files.
For example, to show diffs of macOS .plist files, add the following to your configuration file:
This will pipe all .plist files through plutil -convert xml1 -o - - before showing differences.
"},{"location":"user-guide/tools/editor/","title":"Editor","text":""},{"location":"user-guide/tools/editor/#use-your-preferred-editor-with-chezmoi-edit-and-chezmoi-edit-config","title":"Use your preferred editor with chezmoi edit and chezmoi edit-config","text":"
By default, chezmoi will use your preferred editor as defined by the $VISUAL or $EDITOR environment variables, falling back to a default editor depending on your operating system (vi on UNIX-like operating systems, notepad.exe on Windows).
You can configure chezmoi to use your preferred editor by either setting the $EDITOR environment variable or setting the edit.command variable in your configuration file.
The editor command must only return when you have finished editing the files. chezmoi will emit a warning if your editor command returns too quickly.
In the specific case of using VSCode or Codium as your editor, you must pass the --wait flag, for example, in your shell config:
"},{"location":"user-guide/tools/editor/#use-chezmoi-with-emacs","title":"Use chezmoi with emacs","text":"
github.com/tuh8888/chezmoi.el provides convenience functions for interacting with chezmoi from emacs, and is available in MELPA.
"},{"location":"user-guide/tools/http-or-socks5-proxy/","title":"HTTP or SOCKS5 proxy","text":"
chezmoi supports HTTP, HTTPS, and SOCKS5 proxies. Set the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables, or their lowercase equivalents, for example:
"},{"location":"user-guide/tools/merge/","title":"Merge","text":""},{"location":"user-guide/tools/merge/#use-a-custom-merge-command","title":"Use a custom merge command","text":"
By default, chezmoi uses vimdiff. You can use a custom command by setting the merge.command and merge.args configuration variables. The elements of merge.args are interpreted as templates with the variables .Destination, .Source, and .Target containing filenames of the file in the destination state, source state, and target state respectively. For example, to use neovim's diff mode, specify:
If you generate your config file from a config file template, then you'll need to escape the {{ and }} as {{ \"{{\" }} and {{ \"}}\" }}. That way your generated config file contains the {{ and }} you expect.
"},{"location":"user-guide/tools/merge/#use-vscode-as-the-merge-tool","title":"Use VSCode as the merge tool","text":"
To use VSCode as the merge tool, add the following to your config: