Maintaining consistent dotfiles across multiple machines is one of those problems that seems minor until you've spent an afternoon wondering why your shell aliases work on your work laptop but not your home machine. Chezmoi solves this by managing your dotfiles in a Git repository and giving you the tooling to keep every machine in sync — with support for templates, encrypted secrets, and one-command bootstrapping on a new system.

### Installing Chezmoi

**macOS (Homebrew):**
```bash
brew install chezmoi
```

**Debian/Ubuntu:**
```bash
sudo apt install chezmoi
```

**Universal install script (any platform):**
```bash
sh -c "$(curl -fsLS get.chezmoi.io)"
```

The install script places a binary in `~/.local/bin/chezmoi` or wherever your `$PATH` points. Verify it's working:

```bash
chezmoi --version
```

### Getting Started

Initialize chezmoi with:

```bash
chezmoi init
```

This creates a source directory at `~/.local/share/chezmoi/` — this is where chezmoi stores managed versions of your dotfiles. It's a Git repository by default, so you can push it to GitHub or any Git host to sync across machines.

Add a dotfile to chezmoi's management:

```bash
chezmoi add ~/.zshrc
chezmoi add ~/.gitconfig
chezmoi add ~/.config/starship.toml
```

This copies each file into the source directory. To edit a managed file, always edit through chezmoi so it tracks the canonical version:

```bash
chezmoi edit ~/.zshrc
```

After editing, apply your changes to the actual files in your home directory:

```bash
chezmoi apply
```

To see what changes would be applied before committing:

```bash
chezmoi diff
```

This shows a diff between your current home directory files and what chezmoi would apply — useful for reviewing changes before they take effect.

### Using Templates for Machine-Specific Configuration

The real power of chezmoi comes from templates. If you have configuration that should differ between machines — like a different Git email for work versus personal projects — you can use chezmoi's templating syntax rather than maintaining separate dotfiles.

Rename a managed file to add the `.tmpl` extension:

```bash
mv ~/.local/share/chezmoi/dot_gitconfig ~/.local/share/chezmoi/dot_gitconfig.tmpl
```

Then use Go template syntax inside the file:

```ini
[user]
  name = Your Name
  {{- if eq .chezmoi.hostname "work-macbook" }}
  email = you@company.com
  {{- else }}
  email = you@personal.com
  {{- end }}
```

Chezmoi exposes machine data like `chezmoi.hostname`, `chezmoi.os`, and `chezmoi.arch` as template variables. You can also define your own variables in `~/.config/chezmoi/chezmoi.toml`:

```toml
[data]
  name = "Your Name"
  work = false
```

And reference them in templates as `.name`, `.work`, and so on.

### Encrypting Secrets With Age

Dotfiles often contain sensitive data — API tokens, SSH passphrases, or application credentials. Chezmoi integrates with `age` for encrypting files at rest in your source repository.

Install age (`brew install age`), then configure chezmoi to use it:

```toml
[age]
  identity = "~/.config/chezmoi/key.txt"
  recipient = "age1..."
```

Generate a key with `age-keygen -o ~/.config/chezmoi/key.txt`. From there, `chezmoi add --encrypt ~/.ssh/config` adds the file in encrypted form. The decrypted version is only ever written to your home directory — the repository only contains the encrypted blob.

### Syncing Across Machines

The one-liner to bootstrap chezmoi on a new machine from your existing dotfiles repository:

```bash
chezmoi init --apply https://github.com/username/dotfiles.git
```

This clones your dotfiles repository, runs the templating engine for the current machine, and applies everything in one step. A fresh machine goes from zero to your full development environment in under a minute.

After making changes on any machine:

```bash
chezmoi cd          # Navigate to source directory
git add -A
git commit -m "Update zshrc"
git push
```

On another machine:

```bash
chezmoi update      # Pull from Git and apply changes
```

---

### Chezmoi + DeployHQ: Consistent Environments for Reliable Deployments

One of the underappreciated benefits of managing your dotfiles with chezmoi is that your deployment workflow becomes more predictable. When every developer on a team has consistent SSH key management, Git configuration, and tooling across their machines, deployments behave the same way regardless of who triggers them.

[DeployHQ](https://www.deployhq.com) sits on the deployment side of this workflow. Once your code is pushed to Git, DeployHQ handles getting it to production — SSH, SFTP, or cloud providers — with configurable build commands, environment variables, and automatic deployments via webhook.

The combination is particularly effective for teams: chezmoi ensures every developer's local environment is set up consistently (SSH keys, Git config, editor settings, shell aliases), and DeployHQ ensures the deployment pipeline is automated and repeatable. There's no "it works on my machine" when both sides of the workflow are managed.

For a new team member, the onboarding flow becomes:
1. `chezmoi init --apply https://github.com/your-org/dotfiles.git` to set up the local environment
2. Connect to the team's DeployHQ account to get access to existing deployment pipelines
3. Push code to the shared repository and DeployHQ handles the rest

---

Ready to automate your deployments? [Sign up for DeployHQ](https://www.deployhq.com/signup) to connect your Git repository and start shipping reliably. Questions? Reach us at [support@deployhq.com](mailto:support@deployhq.com) or on Twitter at [@deployhq](https://x.com/deployhq).