Skip to content

Latest commit

 

History

History
132 lines (94 loc) · 3.38 KB

QUICKSTART.md

File metadata and controls

132 lines (94 loc) · 3.38 KB
Raw

chezmoi Quick Start Guide

Concepts

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.

Start using chezmoi on your current machine

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

Using chezmoi across multiple machines

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

Next steps

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.