Basic use of Chezmoi

Chezmoi is a cross-platform configuration file management tool that helps you synchronize configuration files across multiple devices.

Common Daily Operations

Edit Configuration

chezmoi edit $FILENAME

Apply Configuration

chezmoi apply

When editing configurations, Chezmoi only modifies the Source State.

Pull Updates

chezmoi update

These are the most commonly used operations in daily use.

Setting Up Chezmoi on a New Machine

Taking macOS as an example:

Install chezmoi

brew install chezmoi

If Homebrew is not installed, refer to the official installation guide for installation methods on various systems.

Initialize Chezmoi

chezmoi init

After running this, a Git repository will be created locally at ~/.local/share/chezmoi to store all files tracked by Chezmoi.

Add Files to Track

chezmoi add $FILEPATH

Create a New Configuration Repository on GitHub This repository is typically named dotfiles, but you can change it to any name you prefer. Later, you only need to modify the Git remote URL.
Configure the GitHub Repository Note: Replace $GITHUB_USERNAME and $REPOSITORY_NAME

chezmoi cd
git remote add origin https://github.com/$GITHUB_USERNAME/$REPOSITORY_NAME.git
git push -u origin main
exit

Quickly Initialize on Another Machine

chezmoi init https://github.com/$GITHUB_USERNAME/dotfiles.git
chezmoi apply

This allows you to quickly synchronize configurations to the new machine.

Chezmoi Configuration

Source file storage path: ~/.local/share/chezmoi
Configuration file path: ~/.config/chezmoi/chezmoi.toml

The configuration file supports TOML.### Automatically Commit Updates to the Repository After Modifying Files

Open or create ~/.config/chezmoi/chezmoi.toml and add the following:

[git]
autoCommit = true
autoPush = true

After this configuration, modifications will be automatically committed and pushed to the repository when chezmoi apply is executed.

Configuring the Default Editor

For example, to set VS Code as the default editor:

[edit]
command = "code"
args = ["--wait"]

Merging Configuration Files

If you accidentally modify ~/.zshrc directly, you can run:

chezmoi merge ~/.zshrc

This will merge the changes back into the file managed by Chezmoi.

Filtering Invalid Files

Add rules to ~/.local/share/chezmoi/.chezmoiremove to ignore files. For example, to automatically remove .DS_Store:

**/.DS_Store

Other Operations

Stop managing a file but keep it: chezmoi forget $FILEPATH
Remove management and delete the file: chezmoi remove $FILEPATH

Principles of File Mapping

Chezmoi manages configuration files through filename mapping rules:

dot_filename → $HOME/.filename
dir/file     → $HOME/dir/file

For example, dot_zshrc corresponds to ~/.zshrc.

Therefore, you can also directly edit files under ~/.local/share/chezmoi and then run:

chezmoi apply

to apply the changes to the actual configuration.

Use chezmoi cd to quickly navigate to the ~/.local/share/chezmoi directory.

Chezmoi explains in detail why it does not use symbolic links like GNU Stow in the article “Why doesn’t chezmoi use symlinks like GNU Stow?”.

⸻

Ignoring Files That Should Not Be Added

Configure in ~/.local/share/chezmoi/.chezmoiignore:

**/.DS_Store
**/.AppleDouble
**/.LSOverride

**/Thumbs.db
**/
```ehthumbs.db

**/*~
**/#*#
**/.TemporaryItems

**/Library/Application Support/com.mitchellh.ghostty/*.tmp

**/.vscode
**/.idea
**/.history

**/node_modules
**/package-lock.json
**/pnpm-lock.yaml
**/yarn.lock

**/tmp
**/temp

**/*.cache

References

chezmoi Docs↗