How to Set Up Dotfiles: GNU Stow or chezmoi (September 2026)?

Every time I set up a new machine, I used to spend hours reconfiguring my shell, editor, and other tools. Then I discovered dotfiles management. Now I can reproduce my entire development environment in minutes. This guide shows you how to set up a reproducible dotfiles repo managed with GNU Stow or chezmoi, two of the most popular tools for this task. I have tested both approaches and will walk you through each step, including the gotchas I learned along the way.

What Are Dotfiles and Why Manage Them?

Dotfiles are configuration files in Unix-like systems that start with a dot, like .bashrc, .vimrc, or .gitconfig. The dot makes them hidden by default, but they control how your system behaves. Your shell settings, editor preferences, and tool configurations all live in these files.

Managing dotfiles means tracking these files in a version control system like Git. Without management, you lose your customizations when you switch machines or reinstall your OS. With proper management, you can restore your setup in minutes on any computer.

Version-controlling dotfiles gives you several benefits. You can track changes over time and revert if something breaks. You can share your setup with others or copy it between machines. And you get a backup of your configurations without manual effort.

There are three main approaches to dotfiles management. The bare Git repository method uses Git directly in your home directory. Dedicated tools like GNU Stow and chezmoi provide extra features and structure. Each approach has tradeoffs I will explain in this guide.

How to Set Up a Reproducible Dotfiles Repo Managed With GNU Stow or chezmoi?

Before diving into setup, you need to choose between GNU Stow and chezmoi. Both tools solve the same problem but use different strategies. GNU Stow uses symbolic links to connect your dotfiles directory to your home directory. Chezmoi copies files and can handle machine-specific configurations automatically.

You will need basic command line familiarity and Git installed on your system. Both tools work on Linux and macOS. The setup process differs significantly between them, so I will cover each in detail.

Setting Up GNU Stow for Dotfiles Management

GNU Stow is a symlink farm manager that helps you organize software packages. For dotfiles, it creates symbolic links from a central directory to your home directory. This approach keeps all configs in one place while making them appear in the correct locations.

Installing GNU Stow

On most Linux distributions, install Stow using your package manager. For Debian-based systems like Ubuntu, run:

sudo apt install stow

On macOS with Homebrew, use:

brew install stow

Verify the installation by running stow --version. You should see version information confirming the install worked.

Creating Your Dotfiles Directory Structure

The key to GNU Stow is its directory structure. Stow expects a specific layout that mirrors your home directory. Create a dotfiles directory first:

mkdir ~/dotfiles

Inside this directory, create subdirectories for each tool or package. For example, if you want to manage your Bash configuration, create a bash directory. Inside that, recreate the path where the file should live. For .bashrc, which lives in your home directory, the structure looks like:

~/dotfiles/bash/.bashrc

For a file like .config/nvim/init.vim, you would create:

~/dotfiles/nvim/.config/nvim/init.vim

This mirrored structure is what confuses most new users. The directory inside your dotfiles folder mimics the structure starting from your home directory.

Stowing Your Dotfiles

Once your files are in place, navigate to your dotfiles directory and run Stow. To link your Bash configuration:

cd ~/dotfiles

stow bash

Stow creates symbolic links in your home directory pointing to the files in your dotfiles directory. Your .bashrc now lives in ~/dotfiles/bash/.bashrc but appears at ~/.bashrc.

You can stow multiple packages at once. Run stow vim for your Vim config, stow git for your Git configuration, and so on. Each package gets its own subdirectory.

Unstowing and Restowing

To remove the symlinks without deleting your files, use the unstow command:

stow -D bash

This removes the symlinks but keeps your dotfiles in the repository. Use this when you want to test changes or switch configurations temporarily.

After editing a file in your dotfiles directory, the changes appear immediately because the symlink points to the actual file. No restowing needed for content changes. You only restow when you add new files or change the directory structure.

Version Control Your Dotfiles

Turn your dotfiles directory into a Git repository to track changes:

cd ~/dotfiles

git init

git add .

git commit -m "Initial dotfiles commit"

Create a repository on GitHub or another Git hosting service and push your dotfiles. This gives you a backup and makes setting up new machines straightforward.

Common GNU Stow Pitfalls

The mirrored directory structure confuses most people at first. Remember that the directory inside your dotfiles folder represents the path relative to your home directory. Take time to plan your structure before moving files.

Stow fails if a file already exists in the target location. Move existing dotfiles to your dotfiles directory before running stow. Alternatively, delete the original file and then stow.

Symlinks can break if you move or delete your dotfiles directory. This is a tradeoff of the symlink approach. If you move your dotfiles, you must restow everything.

Setting Up chezmoi for Dotfiles Management

Chezmoi takes a different approach. Instead of symlinks, it manages your dotfiles as actual files in your home directory. It keeps a source directory where you edit files, then applies changes when you tell it to. This approach gives you more flexibility for machine-specific configurations.

Installing chezmoi

Chezmoi offers several installation methods. On Linux and macOS, the recommended approach uses a shell script:

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

You can also use package managers. On macOS with Homebrew:

brew install chezmoi

On Debian-based Linux:

sudo apt install chezmoi

Verify installation with chezmoi --version.

Initializing chezmoi

After installation, initialize chezmoi to create its source directory:

chezmoi init

This creates a .local/share/chezmoi directory in your home folder. This is your source directory where you will edit your dotfiles. chezmoi also creates a configuration file at .config/chezmoi/chezmoi.toml (or JSON or YAML, depending on your preference).

To initialize with an existing dotfiles repository from GitHub:

chezmoi init https://github.com/username/dotfiles.git

This clones your repository and sets up chezmoi on a new machine in one command.

Adding Your First Dotfile

Use the add command to bring an existing dotfile under chezmoi management:

chezmoi add ~/.bashrc

Chezmoi copies the file to your source directory. The file now lives in ~/.local/share/chezmoi/dot_bashrc. Chezmoi uses a naming convention where files starting with a dot get a dot_ prefix.

Add other configuration files the same way:

chezmoi add ~/.vimrc

chezmoi add ~/.config/nvim/init.vim

The chezmoi Workflow: Edit, Diff, Apply

Chezmoi separates editing from applying changes. Edit a managed file using:

chezmoi edit ~/.bashrc

This opens the file in your source directory using your default editor. Make your changes and save. The file in your home directory has not changed yet.

Check what changes will apply:

chezmoi diff

This shows the difference between your source files and your home directory. Review the output to make sure your changes look correct.

Apply changes when ready:

chezmoi apply

Chezmoi copies files from your source directory to your home directory. Your dotfiles are now updated. Some users appreciate this extra step because it prevents accidental changes.

For quick edits without the review step, use:

chezmoi edit --apply ~/.bashrc

Managing Machine-Specific Configurations

Chezmoi excels at handling different configurations for different machines. Use templates to include or exclude sections based on the hostname or operating system.

In a template file, use conditionals:

{{ if eq .chezmoi.hostname "work-laptop" }}

# Work-specific settings

export WORK_ENV=true

{{ end }}

Chezmoi evaluates templates when applying files. The same repository produces different outputs on different machines.

You can also have entirely different files for different machines. Create an alternate file ending with the hostname:

.bashrc for the default file
.bashrc_your-hostname for machine-specific version

Chezmoi automatically uses the machine-specific version when present.

Pushing to GitHub

Your chezmoi source directory is just a Git repository. Initialize it and push to GitHub:

cd ~/.local/share/chezmoi

git init

git add .

git commit -m "Initial commit"

git remote add origin https://github.com/username/dotfiles.git

git push -u origin main

Your dotfiles are now backed up and shareable. To set up on a new machine, run the init command with your repository URL.

GNU Stow vs chezmoi: Which Should You Choose

Both tools solve the dotfiles problem, but they suit different workflows. Here is how they compare on key features:

Approach: GNU Stow uses symbolic links. Your dotfiles directory contains the actual files, and symlinks point from your home directory to this location. Chezmoi uses actual files. It copies files to your home directory when you apply changes.

Directory structure: GNU Stow requires a mirrored directory structure that can feel unintuitive. You must recreate the path structure inside your dotfiles directory. Chezmoi uses a flat source directory with its own naming convention.

Machine-specific configs: GNU Stow has no built-in support for different configurations on different machines. You would need separate repositories or branches. Chezmoi has native templating and alternate file support for machine-specific configurations.

Encryption: GNU Stow does not handle encryption. You would need a separate tool for secrets. Chezmoi has built-in encryption support using age or GPG for sensitive files like API keys.

Learning curve: GNU Stow is simpler conceptually but the directory structure causes confusion. Chezmoi has more commands and features to learn, but its workflow is explicit and predictable.

Speed: GNU Stow is fast because symlinks are instant. Chezmoi is slightly slower because it copies files, though the difference is negligible for dotfiles.

Choose GNU Stow if: You want simplicity, you only manage dotfiles on similar machines, and you prefer symlinks. You do not need encryption or templating.

Choose chezmoi if: You manage multiple machines with different configurations, you need encryption for secrets, or you prefer a clear edit-review-apply workflow.

Both tools work well for basic dotfiles management. The right choice depends on your workflow and needs. You can even switch between them later, though migration requires some effort.

Reproducibility Best Practices

Regardless of which tool you choose, follow these practices to make your dotfiles truly reproducible across machines.

Never commit secrets. API keys, passwords, and tokens should never go in your dotfiles repository. Use environment variables or a separate secrets manager. Chezmoi’s encryption helps here, but you must remember to use it.

Create a bootstrap script. Write a shell script that installs your required tools, package managers, and dependencies. Include package installation commands for your preferred tools. Run this script first on a new machine before applying your dotfiles.

Test your setup regularly. Try restoring your dotfiles on a fresh machine or virtual machine every few months. This catches missing dependencies or broken configurations before you actually need them.

Document your setup. Add a README to your dotfiles repository explaining how to bootstrap a new machine. Include prerequisites, installation commands, and any manual steps required.

Keep machine-specific configs separate. Clearly mark which configurations are universal and which are machine-specific. This prevents accidentally copying settings from your work laptop to your personal machine.

Use branches for experiments. When trying new configurations, create a branch in your repository. Test the changes before merging to your main configuration.

Migrating between tools. If you switch from GNU Stow to chezmoi, first remove all symlinks by unstowing. Then add your files to chezmoi from your existing dotfiles directory. Going the other direction, apply chezmoi changes, remove the chezmoi source directory, and recreate your files in a Stow-compatible structure.

Frequently Asked Questions

Conclusion

Managing dotfiles with GNU Stow or chezmoi transforms how you set up and maintain your development environment. Both tools give you version control, easy backup, and quick restoration on new machines. GNU Stow offers simplicity through symbolic links but requires understanding its directory structure. Chezmoi provides powerful features like templating and encryption at the cost of a steeper learning curve.

I recommend trying both approaches on a test machine. Set up a basic configuration with each tool and see which workflow feels natural to you. The best dotfiles manager is the one you will actually use consistently. Once you commit to one, add a bootstrap script and test your setup regularly. A reproducible dotfiles repo managed with GNU Stow or chezmoi saves hours on every new machine and gives you confidence that your environment is backed up and portable.