- Concepts
- Start using chezmoi on your current machine
- Using chezmoi across multiple machines
- Next steps
chezmoi stores the desired state of your dotfiles in the directory
~/.local/share/chezmoi
. When you run chezmoi apply
, chezmoi calculates the
desired contents and permissions for each dotfile and then makes any changes
necessary so that your dotfiles match that state.
Assuming that you have already installed chezmoi, initialize chezmoi with:
$ chezmoi init
This will create a new git repository in ~/.local/share/chezmoi
where chezmoi
will store its source state. By default, chezmoi only modifies files in the
working copy. It is your responsibility to commit and push changes, but chezmoi
can automate this for you if you want.
Manage your first file with chezmoi:
$ chezmoi add ~/.bashrc
This will copy ~/.bashrc
to ~/.local/share/chezmoi/dot_bashrc
.
Edit the source state:
$ chezmoi edit ~/.bashrc
This will open ~/.local/share/chezmoi/dot_bashrc
in your $EDITOR
. Make some
changes and save the file.
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.
Next, open a shell in the source directory, to commit your changes:
$ chezmoi cd
$ git add .
$ git commit -m "Initial commit"
Create a new repository on GitHub called dotfiles
and then push your repo:
$ git remote add origin git@github.com:username/dotfiles.git
$ git branch -M main
$ git push -u origin main
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
On a second machine, initialize chezmoi with your dotfiles repo:
$ chezmoi init https://github.com/username/dotfiles.git
This will check out the repo and any submodules and optionally create a chezmoi config file for you. It won't make any changes to your home directory until you run:
$ chezmoi apply
If your dotfiles repo is https://github.com/username/dotfiles.git
then the
above two commands can be combined into just:
$ chezmoi init --apply username
On any machine, you can pull and apply the latest changes from your repo with:
$ chezmoi update
For a full list of commands run:
$ chezmoi help
chezmoi has much more functionality. Good starting points are adding more dotfiles, and using templates to manage files that vary from machine to machine and retrieve secrets from your password manager. Read the how-to guide to explore.