---
tags:
  - Documentation
  - Bookstack
  - Notes
---
# Chezmoi Guide

# Guide

**chezmoi** is a powerful, go-anywhere tool for managing your dotfiles across multiple machines. Unlike simple symlinking, it treats your configuration as a source-controlled project, allowing you to manage secrets, use templates for different OSs, and keep everything in a Git repository.

Now, just remember to always edit your dotfiles templates. Chezmoi give you some helpers:   
 chezmoi cd # will cd you to the dotfiles repo directory to edit files, or use;   
 chezmoi edit ~/.zshrc # will open the template in your editor

Whenever you change the template or the data file, just update everything:   
 chezmoi update

push the changes to your repo:   
 chezmoi cd   
 git add .   
 git commit -m "Update dotfiles"   
 git push

   
If you create new dotfiles, let's say you started to use Fish, then don't forget to add it to Chezmoi like this:   
 chezmoi add --autotemplate ~/.fishrc

   
You can use the convenience script to install the dotfiles on any machine with a single command. Simply run the following command in your terminal:   
 export GITHUB\\\_USERNAME=mmcfetridge1969   
 sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply $GITHUB\\\_USERNAME

   
Apply will install all the dependencies and add files to your $HOME.   
 chezmoi apply

Update - From time to time, start the update simply with:   
 chezmoi diff   
 chezmoi update

## 1. Getting Started

To begin, you’ll need to initialize your local state. This creates a hidden directory (usually `~/.local/share/chezmoi`) where the "source" versions of your files live.

- **Initialize:** `chezmoi init`
- **Add a file:** `chezmoi add ~/.bashrc`
    
    
    - *This moves the file's logic into the source directory and leaves the original file in your home folder untouched.*
- **Edit a file:** `chezmoi edit ~/.bashrc`
    
    
    - *This opens the source version in your default editor ($EDITOR).*

## 2. The Core Workflow

Once you have added files, you need to manage the synchronization between your **source state** (the repo) and your **destination state** (your home directory).

<table id="bkmrk-command-action-chezm"><thead><tr><td>**Command**</td><td>**Action**</td></tr></thead><tbody><tr><td><span>`chezmoi diff`</span></td><td><span>See changes between your source state and your actual home files.</span></td></tr><tr><td><span>`chezmoi apply`</span></td><td><span>Push changes from your source state to your home directory.</span></td></tr><tr><td><span>`chezmoi cd`</span></td><td><span>Launch a shell in the source directory (great for Git commits).</span></td></tr><tr><td><span>`chezmoi update`</span></td><td><span>Pulls the latest changes from your repo and applies them in one go.</span></td></tr></tbody></table>

## 3. Using Templates

One of chezmoi's best features is the ability to use **text/template** logic. This allows one `.zshrc` file to work differently on macOS than it does on Linux.

1. **Turn a file into a template:**
    
    `chezmoi add --template ~/.zshrc` (or rename it manually in the source dir to `dot_zshrc.tmpl`).
2. **Add Logic:**
    
    Inside the file, you can use snippets like:
    
    <div class="code-block ng-tns-c2069566202-501 ng-animate-disabled ng-trigger ng-trigger-codeBlockRevealAnimation"><div class="formatted-code-block-internal-container ng-tns-c2069566202-501"><div class="animated-opacity ng-tns-c2069566202-501"><div class="code-block-decoration header-formatted gds-emphasized-body-m ng-tns-c2069566202-501 ng-star-inserted"><span class="ng-tns-c2069566202-501">Bash</span><div class="buttons ng-tns-c2069566202-501 ng-star-inserted"></div></div></div></div></div>```
    {{ if eq .chezmoi.os "darwin" }}
    alias ls='ls -G'
    {{ else }}
    alias ls='ls --color=auto'
    {{ end }}
    
    ```
    
    <div class="code-block ng-tns-c2069566202-501 ng-animate-disabled ng-trigger ng-trigger-codeBlockRevealAnimation"><div class="formatted-code-block-internal-container ng-tns-c2069566202-501"><div class="animated-opacity ng-tns-c2069566202-501"></div></div></div>

## 4. Managing Secrets

Never hardcode API keys or passwords in your dotfiles. Chezmoi integrates natively with password managers like **1Password, Bitwarden, KeepassXC, and LastPass**.

- **Example (Bitwarden):**
    
    `{{ (bitwarden "item" "my-api-key").notes }}`
- **Keep it Private:** When you run `chezmoi apply`, it fetches the secret and injects it into the destination file without ever storing the secret in your Git repo.

## 5. Syncing to a New Machine

To set up a brand new computer with all your settings in seconds:

1. **Install chezmoi.**
2. **Run the init command with your repo URL:**
    
    `chezmoi init https://github.com/username/dotfiles.git`
3. **Review and Apply:**
    
    `chezmoi diff` (to check)
    
    `chezmoi apply` (to execute)

> \[!TIP\]
> 
> Use `chezmoi status` to see a quick summary of which files have changed and are waiting to be managed or updated.