Skip to main content

​
Quick Start Guide

This guide will help you start using chezmoi to manage your dotfiles on your current machine and then sync them across multiple machines.

​
Concepts

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.
For a more detailed explanation, see the concepts reference.

​
Start Using chezmoi on Your Current Machine

Assuming you have already installed chezmoi, follow these steps to start managing your dotfiles:
1

Initialize chezmoi

Create a new git repository where chezmoi will store its source state:
chezmoi init
This creates a new git local repository in ~/.local/share/chezmoi. By default, chezmoi only modifies files in the working copy.
2

Manage your first file

Add your first dotfile to chezmoi:
chezmoi add ~/.bashrc
This will copy ~/.bashrc to ~/.local/share/chezmoi/dot_bashrc.
3

Edit the source state

Edit the file in chezmoi’s source directory:
chezmoi edit ~/.bashrc
This will open ~/.local/share/chezmoi/dot_bashrc in your $EDITOR. Make some changes and save the file.
You don’t have to use chezmoi edit to edit your dotfiles. You can edit them directly in the source directory or use your preferred editor workflow.
4

Preview changes

See what changes chezmoi would make:
chezmoi diff
This shows you exactly what will change before you apply it.
5

Apply the changes

Apply your changes to your home directory:
chezmoi -v apply
The -v (verbose) flag prints out exactly what changes are being made. You can also use -n (dry run) to see what would happen without making actual changes.
The combination -n -v is very useful to see exactly what changes would be made without making them.
6

Commit your changes

Open a shell in the source directory to commit your changes:
chezmoi cd
git add .
git commit -m "Initial commit"
7

Create a GitHub repository

Create a new repository on GitHub called dotfiles and push your repo:
git remote add origin [email protected]:$GITHUB_USERNAME/dotfiles.git
git branch -M main
git push -u origin main
chezmoi can be configured to automatically add, commit, and push changes to your repo.
8

Exit the source directory

Return to where you were:
exit

​
Workflow Diagram

This diagram summarizes the workflow:

​
Using chezmoi Across Multiple Machines

Once you’ve set up chezmoi on your first machine, you can easily sync your dotfiles to other machines.
1

Initialize with your dotfiles repo

On a second machine, initialize chezmoi with your dotfiles repo:
chezmoi init https://github.com/$GITHUB_USERNAME/dotfiles.git
Private GitHub repos require authentication. Use SSH:
chezmoi init [email protected]:$GITHUB_USERNAME/dotfiles.git
This will check out the repo and any submodules and optionally create a chezmoi config file for you.
2

Review changes

Check what changes chezmoi will make to your home directory:
chezmoi diff
3

Apply changes

If you’re happy with the changes, apply them:
chezmoi apply -v
4

Edit files if needed

If you’re not happy with changes to a specific file, you can:Edit the file:
chezmoi edit $FILE
Or merge changes:
chezmoi merge $FILE
This invokes 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.
5

Keep machines in sync

Pull and apply the latest changes from your repo:
chezmoi update -v

​
Multi-Machine Workflow Diagram

​
Set Up a New Machine with a Single Command

You can install your dotfiles on a new machine with a single command: 
chezmoi init --apply https://github.com/$GITHUB_USERNAME/dotfiles.git
If you use GitHub and your dotfiles repo is called dotfiles, you can use the shorthand $GITHUB_USERNAME instead of the full URL.

​
Single-Command Setup Diagram

​
Common Commands Reference

All chezmoi commands accept these useful flags:
  • -v or --verbose: Print out exactly what changes will be made
  • -n or --dry-run: Don’t make any actual changes
  • -n -v: Combination to see exactly what would change without making changes
Example:
chezmoi -n -v apply
  • chezmoi init: Initialize chezmoi
  • chezmoi add <file>: Add a file to chezmoi
  • chezmoi edit <file>: Edit a file in the source state
  • chezmoi diff: Show what would change
  • chezmoi apply: Apply changes to your home directory
  • chezmoi update: Pull and apply latest changes from repo
  • chezmoi cd: Open a shell in the source directory
chezmoi works seamlessly with Git. You can use chezmoi to manage your dotfiles repo:
# Enter the source directory
chezmoi cd

# Use git commands as normal
git status
git add .
git commit -m "Update dotfiles"
git push

# Exit back to where you were
exit
chezmoi can be configured to automatically commit and push changes.
chezmoi works with any git hosting service:

​
Next Steps

For a full list of commands, run: 
chezmoi help
chezmoi has much more functionality to explore:

User Guide

Learn about templates, secrets management, and advanced features

Command Overview

Complete reference of all chezmoi commands

Daily Operations

Day-to-day workflows and best practices

Example Repos

See how other people use chezmoi
Good next steps include adding more dotfiles, using templates to manage files that vary from machine to machine, and learning how to retrieve secrets from your password manager.

Build docs developers (and LLMs) love

Get started for freeTalk to us