Chezmoi vs GNU Stow for Dotfiles Across a Laptop and Home Servers

Dotfiles start innocently: a .bashrc you copied from somewhere, a few aliases, a Git config. Then you add a laptop, a home server, a NAS and a Raspberry Pi, and each one has a slightly different version of everything. The fix everybody eventually reaches for is a Git repository of dotfiles, plus a tool to put those files where they belong on each machine.

Two tools sit at opposite ends of that spectrum. GNU Stow is a tiny, decades-old program that creates symlinks from a folder into your home directory. Chezmoi is a modern, single-binary dotfile manager with templates, secrets and per-machine logic. I keep a dotfiles repository across a Mac, a Debian NAS, an Ubuntu server and a Pi that should not even have an interactive prompt, and I have used both. The right choice depends mostly on how different your machines are.

Symlinks or a managed copy

GNU Stow is a “symlink farm manager”. You arrange your repository into packages, folders such as zsh, git and nvim that mirror the layout of your home directory, and run stow zsh. Stow creates symlinks in your home directory pointing to the files in the repository. Edit ~/.zshrc and you are editing the file in the repository directly. There is nothing else: no templates, no secrets, no scripts. It is usually available from your distribution’s package manager.

Chezmoi keeps a “source state” in its own directory, normally a Git repository, and computes the “target state” for each machine, which it writes into your home directory as real files by default. Files can be templates that change based on the machine’s hostname, operating system or any data you define. Secrets can come from password managers or be encrypted in the repository. Scripts can run once, or whenever something changes, to install packages or set up a machine. It is a single binary with no dependencies.

A day of editing with each

With Stow, editing is natural. Open ~/.config/nvim/init.lua, change it, and the change is already in your repository because the file is a symlink. Commit and push when you like. On another machine, pull and the change is live. There is no second step to forget.

With Chezmoi, the file in your home directory is a generated copy. You edit with chezmoi edit, which opens the source and can apply it on save, or you edit the real file and run chezmoi re-add to copy changes back. If you forget, your change exists only on that machine and the next chezmoi apply can overwrite it, although Chezmoi warns about files changed since it last wrote them. chezmoi diff shows what would change before you apply. It is one more habit, and some people find it annoying at first.

Chezmoi can also manage files as symlinks, which brings back in-place editing for files that do not need templates, at the cost of some of its features.

When machines disagree

This is where the tools diverge. Real fleets are not identical. The Mac needs Homebrew paths, the servers use a different shell prompt, the Pi has no GUI tools, and work and personal Git configs use different email addresses.

With Stow, you handle differences by splitting packages, such as git-personal and git-work, and stowing different ones on different machines, or by putting conditional logic in the shell files themselves, for example checking the hostname in .zshrc. Both work, but the logic scatters across files and packages, and you must remember which packages belong on which machine.

With Chezmoi, a file can be a template. One .gitconfig template inserts the right email based on the hostname; one shell config adds Homebrew paths only on macOS; one SSH config includes extra hosts only on the laptop. Machine-specific data is set once per machine in a small config file, and templates read it. That PATH disagreement between two homelab boxes, and how a template fixes it, is covered in more depth in Chezmoi vs yadm for dotfiles.

Secrets in dotfiles

Dotfiles often want secrets: an API token in a tool’s config, credentials in a .netrc, a private SSH config with internal hostnames. Committing those to a Git repository, even a private one, is a bad habit.

Stow has no answer. You keep secrets out of the repository and create those files by hand on each machine, or add a separate encrypted solution yourself.

Chezmoi has two answers. Templates can fetch values from a password manager at apply time, with built-in support for tools such as 1Password, Bitwarden, KeePassXC, pass and others, so the repository contains only a reference. Or files can be encrypted with age or GPG and stored in the repository safely, decrypted when applied. For a public dotfiles repository, this is a big deal.

Setting up a new machine

Bootstrapping is where dotfile tools pay for themselves. With Stow, setting up a new machine means installing Stow and Git, cloning the repository, and running Stow for each package you want, after installing the programs themselves. It is quick if you have written a small script to do it.

Chezmoi turns this into one command: initialise from your repository and apply. Its run-once scripts can install packages with the right package manager for each operating system, set the default shell, or clone plugin managers, with templates choosing what runs where. A freshly installed server can go from nothing to your full environment in a minute. For people who rebuild servers often, or keep identical environments on a laptop and several servers such as the Ubuntu and Debian boxes common in homelabs, that is the main attraction.

A repository layout that works for both

Whichever tool you choose, a few habits make a dotfiles repository easier to live with:

• Keep it small. Only track files you have actually changed. Default configs do not need to be in Git.
• Split large configs. Shell configs that source a folder of small files, such as aliases, functions, paths and per-tool settings, are easier to manage than one long file, with Stow or Chezmoi.
• Put machine-local overrides in an untracked file. A line at the end of .zshrc that sources ~/.zshrc.local if it exists lets each machine add things without touching the repository. This is the simplest way to handle differences with Stow, and still useful with Chezmoi.
• Write a short README. List which packages or templates apply to which machines and how to bootstrap. You will need it in two years when you set up a new laptop.
• Keep the repository private unless you have checked it. Hostnames, internal IP ranges and usernames are not secrets, but you may not want them public.

What can go wrong

Stow’s failure modes are simple. If a real file already exists where Stow wants to create a symlink, it refuses and tells you, and you move the file out of the way. Some programs replace their config files instead of editing them in place, which turns your symlink into a regular file and silently disconnects it from the repository. Checking with git status and occasionally looking for broken links catches this.

Chezmoi’s failure modes are about the extra layer. Forgetting to re-add changes, templates with errors that stop an apply, or a password manager that is locked when you run apply on a headless server. It handles these clearly with error messages, and chezmoi doctor checks your setup. On servers without a password manager, use encrypted files with age instead of live lookups.

Moving from Stow to Chezmoi, or staying

Many people start with Stow and move to Chezmoi when their machines diverge or secrets appear. The move is easy: unstow your packages so real files are back in place, then chezmoi add each file. Convert files to templates one at a time as you find differences. There is no need to do everything at once.

Equally, if your machines are nearly identical and you have no secrets in your configs, there is no reason to move. Stow has worked the same way for decades and will keep doing so.

Picking by how different your machines are

Choose GNU Stow if your machines are similar, your dotfiles contain no secrets, and you want the simplest possible system: symlinks, a Git repository, and nothing else to learn. Editing in place with no extra step is a pleasure, and the tool will never surprise you.

Choose Chezmoi if your machines differ, such as a Mac laptop, Linux servers and a Pi, if your configs need secrets, or if you want new machines to set themselves up with one command. Its templates and scripts replace a pile of hand-written logic, at the cost of an extra step when editing.

Either way, the real win is having your configuration in Git at all. The tool is just how it gets home.