110 lines
4.9 KiB
Markdown
110 lines
4.9 KiB
Markdown
---
|
||
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. |