Manage your dotfiles securely across multiple machines.
-
Declarative: you declare the desired state of files, directories, and symbolic links in your home directory and
chezmoi
updates your home directory to match that state. -
Flexible: your dotfiles can be templates (using
text/template
syntax). Predefined variables allow you to change behaviour depending on operating system, architecture, and hostname. -
Secure:
chezmoi
can retreive secrets from Bitwarden, LastPass, your Keychain (on macOS), and GNOME Keyring (on Linux). -
Robust:
chezmoi
updates all files and symbolic links atomically (usinggoogle/renameio
) so you are never left with incomplete files that could lock you out, even if the update process is interrupted. -
Portable:
chezmoi
's configuration uses only visible, regular files and directories and so is portable across version control systems and operating systems. -
Transparent:
chezmoi
includes verbose and dry run modes so you can review exactly what changes it will make to your home directory before making them. -
Fast, easy to use, and familiar:
chezmoi
runs in fractions of a second and includes commands to make most operations trivial. You can use the version control system of your choice to manage your configuration, and many different formats (e.g. JSON, YAML, TOML, etc.) are supported for the configuration file.
Binaries and packages for multiple platforms, including RedHat, Debian, FreeBSD, and OpenBSD, are available on the releases page.
On macOS you can install chezmoi
with Homebrew:
$ brew install twpayne/taps/chezmoi
If you have Go installed you can install the latest version from HEAD
:
$ go get -u github.com/twpayne/chezmoi
Manage an existing file with chezmoi
:
$ chezmoi add ~/.bashrc
This will create a directory called ~/.local/share/chezmoi
with permissions
0600
where chezmoi
will store its state, if it does not already exist, and
copy ~/.bashrc
to ~/.local/share/chezmoi/dot_bashrc
.
You should manage your ~/.local/share/chezmoi
directory with the version
control system of your choice. chezmoi
will ignore all files and directories
beginning with a .
in this directory, so directories like .git
and .hg
will not pollute your home directory.
Edit the desired state:
$ chezmoi edit ~/.bashrc
This will open ~/.local/share/chezmoi/dot_bashrc
in your $EDITOR
. Make some
changes and save them.
See what changes chezmoi
would make:
$ chezmoi diff
Apply the changes:
$ chezmoi -v apply
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.
For a full list of commands run:
$ chezmoi help
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 configuration
files where needed.
For example, your home ~/.gitconfig
on your personal machine might look like:
[user]
name = John Smith
email = john@home.org
Whereas at work it might be:
[user]
name = John Smith
email = john@company.com
To handle this, on each machine create a file called
~/.config/chezmoi/chezmoi.yaml
defining what might change. For your home
machine:
data:
name: John Smith
email: john@home.org
If you intend to store private data (e.g. access tokens) in
~/.config/chezmoi/chezmoi.yaml
, make sure it has permissions 0600
. See
"Keeping data private" below for more discussion on this.
If you prefer, you can use any format supported by Viper for your configuration file. This includes JSON, YAML, TOML, and more.
Then, add ~/.gitconfig
to chezmoi
using the -T
flag to automatically turn
it in to a template:
$ chezmoi add -T ~/.gitconfig
You can then open the template (which will be saved in the file
~/.local/share/chezmoi/dot_gitconfig.tmpl
):
$ chezmoi edit ~/.gitconfig
The file should look something like:
[user]
name = {{ .name }}
email = {{ .email }}
chezmoi
will substitute the variables from the data
section of your
~/.config/chezmoi/chezmoi.yaml
file when calculating the desired state of
.gitconfig
.
For more advanced usage, you can use the full power of the
text/template
language to include or
exclude sections of file. chezmoi
provides the following automatically
populated variables:
Variable | Value |
---|---|
chezmoi.arch |
Architecture, e.g. amd64 , arm , etc. as returned by runtime.GOARCH. |
chezmoi.group |
The group of the user running chezmoi . |
chezmoi.homedir |
The home directory of the user running chezmoi . |
chezmoi.hostname |
The hostname of the machine chezmoi is running on. |
chezmoi.os |
Operating system, e.g. darwin , linux , etc. as returned by runtime.GOOS. |
chezmoi.username |
The username of the user running chezmoi . |
For example, in your ~/.local/share/chezmoi/dot_bashrc.tmpl
you might have:
# common config
export EDITOR=vi
# machine-specific configuration
{{- if eq .chezmoi.hostname "work-laptop" }}
# this will only be included in ~/.bashrc on work-laptop
{{- end }}
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. See "Under the hood" below.
chezmoi
automatically detects when files and directories are private when
adding them by inspecting their permissions. Private files and directories are
stored in ~/.local/share/chezmoi
as regular, public files with permissions
0644
and the name prefix private_
. For example:
$ chezmoi add ~/.netrc
will create ~/.local/share/chezmoi/private_dot_netrc
(assuming ~/.netrc
is
not world- or group- readable, as it should be). This file is still private
because ~/.local/share/chezmoi
is not group- or world- readable or
executable. chezmoi
checks that the permissions of ~/.local/share/chezmoi
are 0700
on every run and will print a warning if they are not.
It is common that you need to store access tokens in config files, e.g. a Github access token. There are several ways to keep these tokens secure, and to prevent them leaving your machine.
Typically, ~/.config/chezmoi/chezmoi.yaml
is not checked in to version
control and has permissions 0600. You can store tokens as template values in
the data
section. For example, if your ~/.config/chezmoi/chezmoi.yaml
contains:
data:
github:
user: <github-username>
token: <github-token>
Your ~/.local/share/chezmoi/private_dot_gitconfig.tmpl
can then contain:
{{- if .github }}
[github]
user = {{ .github.user }}
token = {{ .github.token }}
{{- end }}
Any config files containing tokens in plain text should be private (permissions
0600
).
chezmoi
includes support for Bitwarden using the
Bitwarden CLI to expose data as a template
function.
Log in to Bitwarden using:
$ bw login <bitwarden-email>
Unlock your Bitwarden vault:
$ bw unlock
Set the BW_SESSION
environment variable, as instructed. You can also pass the
session directly to chezmoi
using the --bitwarden-session
flag.
The structured data from bw get
is available as the bitwarden
template
function in your config files, for example:
username = {{ (bitwarden "item" "example.com").login.username }}
password = {{ (bitwarden "item" "example.com").login.password }}
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>
Check that lpass
is working correctly by showing password data:
$ lpass show -j <lastpass-entry-id>
where <lastpass-entry-id>
is a LastPass Entry
Specification.
The structured data from lpass show -j 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:
githubPassword = {{ (index (lastpass "Github") 0).password }}
chezmoi
automatically parses the note
value of the Lastpass entry, so, for
example, you can extract a private SSH key like this:
{{ (index (lastpass "SSH") 0).note.privateKey }}
Keys in the note
section written as CamelCase Words
are converted to
camelCaseWords
.
chezmoi
includes support for Keychain (on macOS), GNOME Keyring (on Linux),
and Windows Credentials Manager (on Windows) via the
zalando/go-keyring
library.
Set passwords with:
$ chezmoi keyring set --service=<service> --user=<user>
Password: xxxxxxxx
The password 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 keyring set --service=github --user=$GITHUB_USERNAME
Password: xxxxxxxx
and then include it in your ~/.gitconfig
file with:
[github]
user = {{ .github.user }}
token = {{ keyring "github" .github.user }}
You can query the keyring from the command line:
$ chezmoi keyring get --service=github --user=$GITHUB_USERNAME
chezmoi
takes a -c
flag specifying the file to read its configuration from.
You can encrypt your configuration and then only decrypt it when needed:
$ gpg -d ~/.config/chezmoi/chezmoi.yaml.gpg | chezmoi -c /dev/stdin apply
chezmoi
has some helper commands to assist managing your source directory
with version control. The default version control system is git
but you can
change this by setting sourceVCSCommand
in your
~/.config/chezmoi/chezmoi.yaml
file, for example, if you want to use
Mercurial:
sourceVCSCommand: hg
chezmoi source
is then a shortcut to running sourceVCSCommand
in your
~/.local/share/chezmoi
directory. For example you can push the current branch
with:
$ chezmoi source push
Extra arguments are passed along unchanged, although you'll need to use --
stop chezmoi
from interpreting extra flags. For example:
$ chezmoi source pull -- --rebase
The source
command accepts the usual -n
and -v
flags, so you can see
exactly what it will run without executing it.
As a shortcut,
$ chezmoi cd
starts a shell in your source directory, which can be very useful when performing multiple VCS operations.
It is occasionally useful to import entire archives of configuration into your
home directory. The import
command does this. For example, to import the
latest version
github.com/robbyrussell/oh-my-zsh
to your ~/.oh-my-zsh
directory, run:
$ curl -s -L -o oh-my-zsh-master.tar.gz https://github.com/robbyrussell/oh-my-zsh/archive/master.tar.gz
$ chezmoi import --strip-components 1 --destination ~/.oh-my-zsh oh-my-zsh-master.tar.gz
Note that this only updates the source state. You will need to run
$ chezmoi apply
to update your home directory.
chezmoi
can create an archive containing the target state. This can be useful
for generating target state on a different machine or for simply inspecting the
target state. A particularly useful command is:
$ chezmoi archive | tar tvf -
which lists all the files in the target state.
For an example of how chezmoi
stores its state, see
github.com/twpayne/dotfiles
.
chezmoi
stores the desired state of files, symbolic links, and directories in
regular files and directories in ~/.local/share/chezmoi
. This location can be
overridden with the -s
flag or by giving a value for sourceDir
in
~/.config/chezmoi/chezmoi.yaml
. Some state is encoded in the source names.
chezmoi
ignores all files and directories in the source directory that begin
with a .
. The following prefixes and suffixes are special.
Prefix/suffix | Effect |
---|---|
private_ prefix |
Remove all group and world permissions from the target file or directory. |
empty_ prefix |
Ensure the file exists, even if is empty. By default, empty files are removed. |
exact_ prefix |
Remove anything not managed by chezmoi . |
executable_ prefix |
Add executable permissions to the target file. |
symlink_ prefix |
Create a symlink instead of a regular file. |
dot_ prefix |
Rename to use a leading dot, e.g. dot_foo becomes .foo . |
.tmpl suffix |
Treat the contents of the source file as a template. |
Order is important, the order is exact_
, private_
, empty_
, executable_
,
symlink_
, dot_
, .tmpl
.
Different target types allow different prefixes and suffixes:
Target type | Allowed prefixes and suffixes |
---|---|
Directory | exact_ , private_ , dot_ |
Regular file | private_ , empty_ , executable_ , dot_ , .tmpl |
Symbolic link | symlink_ , dot_ , .tmpl |
chezmoi
, by default, operates on your home directory, but this can be
overridden with the --target
command line flag or by specifying targetDir
in your ~/.config/chezmoi/chezmoi.yaml
. In theory, you could use chezmoi
to
manage any aspect of your filesystem. That said, although you can do this, you
probably shouldn't. Existing configuration management tools like
Puppet, Chef,
Ansible, and Salt are
much better suited to whole system configuration management.
chezmoi
was inspired by Puppet, but created because Puppet is a slow overkill
for managing your personal configuration files. The focus of chezmoi
will
always be personal home directory management. If your needs grow beyond that,
switch to a whole system configuration management tool.
Releases are managed with goreleaser.
To create a new release, push a tag, eg:
$ git tag -a v0.1.0 -m "First release"
$ git push origin v0.1.0
To run a local "snapshot" build without publishing:
$ TRAVIS_BUILD_NUMBER=1 goreleaser --snapshot --rm-dist --debug
The MIT License (MIT)
Copyright (c) 2018 Tom Payne
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.