Which Dotfiles Should You Commit to Git (and Which to Ignore)

Nov 5, 2025 · 3 min read

Which Dotfiles Should You Commit to Git (and Which to Ignore)

Managing dotfiles across multiple machines is a common developer headache. You’ve spent hours perfecting your shell configuration, editor settings, and tool preferences—but which files belong in version control? More importantly, how do you sync them without exposing sensitive data or creating a maintenance nightmare?

This article compares the two most popular dotfiles management approaches—Git bare repositories and GNU Stow—while addressing the critical security considerations that determine what should and shouldn’t be committed.

Key Takeaways

Never commit secrets or sensitive data to your dotfiles repository
Git bare repositories offer a minimalist, dependency-free approach
GNU Stow provides better organization through symlinks and modular structure
Choose based on your complexity needs and workflow preferences

What to Commit: The Security-First Approach

Before choosing a management method, understand what belongs in your dotfiles repository. The golden rule: never commit secrets.

Safe to Commit

Shell configurations (.bashrc, .zshrc, .config/fish/)
Editor settings (.vimrc, .config/nvim/)
Git configuration (.gitconfig without credentials)
Terminal emulator configs (.alacritty.yml, .config/kitty/)
Window manager settings (.config/i3/, .config/sway/)
Tool configurations (.tmux.conf, .config/starship.toml)

Never Commit

SSH private keys (~/.ssh/id_*)
API tokens and credentials
Database connection strings
License keys
Browser cookies or session data
Command history files (.bash_history, .zsh_history)

For configuration files that mix public settings with secrets, use templating or separate the sensitive parts into sourced files that remain local.

Git Bare Repository: The Minimalist Method

The Git bare repository approach treats your home directory as a working tree without cluttering it with a .git folder. This method requires no additional tools—just Git.

Setup Process

git init --bare $HOME/.dotfiles
alias config='git --git-dir=$HOME/.dotfiles --work-tree=$HOME'
config config --local status.showUntrackedFiles no

Managing Files

config add ~/.vimrc
config commit -m "Add vim configuration"
config push origin main

Pros:

Zero dependencies beyond Git
Direct version control without symlinks
Works identically across all Unix-like systems
No intermediate storage location

Cons:

Easy to accidentally commit sensitive files
Requires discipline with .gitignore
Can interfere with other Git repositories in subdirectories
Less intuitive for organizing modular configurations

GNU Stow: The Organized Approach

GNU Stow manages dotfiles through symlinks, keeping your actual files organized in a dedicated directory while maintaining the expected paths in your home folder.

Directory Structure

~/.dotfiles/
├── vim/
│   └── .vimrc
├── git/
│   └── .gitconfig
└── shell/
    ├── .bashrc
    └── .zshrc

Deployment

cd ~/.dotfiles
stow vim git shell  # Creates symlinks in ~

Pros:

Clear, modular organization by application
Easy selective deployment per machine
Built-in conflict detection
Supports per-package ignore files (.stow-local-ignore)

Cons:

Requires GNU Stow installation
Some applications don’t handle symlinks well (systemd, certain editors)
Can break when applications overwrite symlinks
Additional abstraction layer to understand

Choosing Your Configuration Management Strategy

Your choice between Git bare repository and GNU Stow depends on your specific needs:

Use Git bare repository when:

You want zero dependencies
Your dotfiles are relatively simple
You prefer direct version control
You’re comfortable with Git internals

Use GNU Stow when:

You manage complex, modular configurations
You need per-application organization
You deploy different configs to different machines
You prefer visual directory structure

Best Practices for Developer Productivity

Regardless of your chosen method, follow these version control best practices:

Use .gitignore aggressively: Start with * and explicitly allow files
Separate public from private: Keep a private repository for sensitive configs
Document your setup: Include installation and deployment instructions
Test on a fresh system: Regularly verify your bootstrap process
Use conditional loading: Handle OS-specific configurations gracefully

For team environments, consider maintaining a separate “blessed” configuration repository with sensible defaults while allowing individual customization through local overrides.

Conclusion

Both Git bare repositories and GNU Stow solve the dotfiles management problem effectively—the choice comes down to your complexity needs and tool preferences. The critical factor isn’t which method you choose, but maintaining strict separation between public configurations and sensitive data. Start with a security-first mindset, choose the approach that matches your workflow, and you’ll have a portable, version-controlled environment that boosts your developer productivity without compromising security.

FAQs

Yes, you can combine both approaches. Use GNU Stow to organize your dotfiles in a dedicated directory, then initialize that directory as a Git repository for version control. This gives you the organizational benefits of Stow with Git's version tracking.

Create separate branches for each machine or use conditional statements in your config files. For shell configs, check hostname or environment variables. Many tools support include directives to load machine-specific files that aren't tracked in Git.

Some applications require actual files instead of symlinks. For these cases, use deployment scripts that copy files instead of linking them, or consider using the Git bare repository method which works with actual files in their expected locations.

No, only commit specific application configurations you actively maintain. Many programs store cache, state, and temporary data in .config that shouldn't be version controlled. Be selective and only track configuration files you've customized.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.