Skip to content
川流不息
Go back

Getting Started with Chezmoi

On this page
  1. Preface
  2. Why Chezmoi
  3. Basic Usage
  4. Installation
  5. Initialization
  6. Adding Files
  7. Committing
  8. Editing Files
  9. Syncing from Another Device
  10. Updating
  11. Managing Sensitive Files
  12. Generating a Key
  13. Configuring the Key
  14. Encrypting Files
  15. Decrypting Files

Preface

As passwordless SSH login has become common, we have more and more private and public keys to manage. Add to that the frequent switching between work computers and servers, and syncing these key files becomes a problem. To keep things simple, I used to commit my key files to a Git repository so they were easy to sync between machines — but that approach carries a big security risk. Even a private repository isn’t safe: accounts on cloud Git hosts (such as GitHub or GitLab) can be compromised through credential stuffing, or a leaked token can expose private repositories. Once a private key leaks, an attacker can log in to all your servers directly. Even if you later delete the key from Git, it still lingers in the .git history and can be recovered at any time.

By chance I came across an open-source project called Chezmoi. It is also Git-based, but it can encrypt sensitive content such as keys before storing it, preventing all kinds of leaks.

Why Chezmoi

chezmoi is currently the most elegant and secure cross-platform dotfiles manager. Its core idea: it maintains a hidden source directory locally (~/.local/share/chezmoi) under Git version control, and after encryption and template rendering it “applies” the final files to your actual home directory (~).

Basic Usage

Installation

sh -c "$(curl -fsLS https://get.chezmoi.io)"

Initialization

chezmoi init

A single command creates a Git repository in .local/share/chezmoi/. If you’re familiar with Git, everything after this is very simple.

Adding Files

  1. Add the files you need to the chezmoi repository
chezmoi add ~/.bashrc

With this command, chezmoi copies .bashrc into .local/share/chezmoi/ and renames it to dot_bashrc.

Committing

Now you can push the changes to a remote repository with Git:

chezmoi cd            # enter the source directory .local/share/chezmoi/
git remote add origin git@github.com:yourname/chezmoi.git
git add .
git commit -m "update dotfiles"
git push -u origin main

Editing Files

There are two ways to edit files.

Option one:

Either way, keep in mind that the Git repository holds a mirror of each real file, and know how a change to one gets synced to the other.

Syncing from Another Device

If a chezmoi repository already exists and you want the same configuration on a new device, just add the repository URL to the init command. This one command downloads the repository and copies its files to their real paths:

chezmoi init --apply git@github.com:yourname/chezmoi.git

Updating

When you’ve changed config files on one device and pushed them to the repository, other devices need just one command to sync the repository and update the real files:

chezmoi update

Managing Sensitive Files

The approach above only manages ordinary files in plain text. Uploading sensitive content such as private keys directly to a Git repository would leak it and could compromise everything that key protects. chezmoi natively supports symmetric or asymmetric encryption of sensitive files: the encrypted content is pushed to the repository, and other devices decrypt it after syncing. Of course, this encryption has a key of its own, which must be kept separately — like using one locked drawer to hold all your other keys, improving both security and convenience.

Generating a Key

Before encrypting SSH private keys, prepare a key for chezmoi. age asymmetric encryption is the usual choice:

age-keygen -o ~/.config/chezmoi/key.txt

This command generates a public/private key pair.

Configuring the Key

The key takes effect only after you add it to chezmoi’s configuration, using chezmoi edit-config:

encryption = "age"
[age]
    identity = "~/.config/chezmoi/key.txt"
    recipient = "public_key..."

Encrypting Files

Just like adding an ordinary file, add the --encrypt flag to indicate the file should be stored encrypted. chezmoi encrypts it automatically before storing it in the repository, and all later Git commands stay the same:

chezmoi add --encrypt ~/.ssh/id_rsa

You can tell from the file name that it has been encrypted:

~/.local/share/chezmoi/dot_ssh/encrypted_private_id_rsa.age

Decrypting Files

If the chezmoi repository contains encrypted files, other devices also need the age key to decrypt them:

After these two steps, all later chezmoi encryption and decryption happens transparently and automatically — very convenient.


Share this post:

Previous Post
Dual-Stack Access to a Home Network
Next Post
用 NAS 虚拟 OpenWrt 搭建家庭旁路由代理

评论