DEV Community

Cover image for How to Manage Your Dotfiles Like a Pro with Git and Stow
insideee.dev
insideee.dev

Posted on • Edited on

How to Manage Your Dotfiles Like a Pro with Git and Stow

#dotfiles #git #stow #programming

Have You Ever Managed Your Dotfiles? 🤔

If you’re a developer, chances are you’ve customized your environment—tweaking your .config, .bashrc, .czrc, .zshrc, .vimrc, or .tmux.conf to fit your workflow. But have you ever switched machines and realized you forgot to back them up? Or worse, you messed up your config and wished you had version control?

That’s where dotfile management comes in. Instead of manually copying files, let’s explore how to use Git to store them—and how GNU Stow can make managing them effortless. 🚀

My dotfiles configurations:

GitHub logo crafts-cnc / .dotfiles

This repo leverages GNU Stow to simplify symlink management, making it easy to install and update configurations across different machines.

insideee.dev's Dotfiles

fish screenshot nvim screenshot

Warning: Don’t blindly use my settings unless you know what that entails. Use at your own risk!

đź“Ś Contents

  • Neovim – Custom plugins, keybindings, and themes
  • Tmux – Optimized terminal workflow
  • Git – Configuration for efficient version control
  • Karabiner – Custom key mappings for Vim efficiency
  • Fish Shell – Enhanced terminal experience
  • GNU Stow – Simple dotfiles management

🚀 Setting Up a New Machine with This Repo

This repository uses GNU Stow to manage dotfiles efficiently with symlinks. Follow these steps to set up your new machine:

1. Install Required Packages

Install Stow & Essential Tools

macOS:

brew install stow git fish tmux neovim
Enter fullscreen mode Exit fullscreen mode

Linux (Debian/Ubuntu):

sudo apt update && sudo apt install stow git fish tmux neovim
Enter fullscreen mode Exit fullscreen mode

Linux (Arch):

sudo pacman -S stow git fish tmux neovim
Enter fullscreen mode Exit fullscreen mode

Install Fisher

A plugin manager for Fish
macOS:

curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source && fisher install jorgebucaran/fisher
Enter fullscreen mode Exit fullscreen mode

Install Tide

…
View on GitHub

Installing Stow 🛠️

Before we dive into using Stow, let's install it on your system.

On macOS (using Homebrew): 

brew install stow
Enter fullscreen mode Exit fullscreen mode

On Debian/Ubuntu: 

sudo apt update && sudo apt install stow -y
Enter fullscreen mode Exit fullscreen mode

On Arch Linux: 

sudo pacman -S stow
Enter fullscreen mode Exit fullscreen mode

Once installed, you can verify the installation by running:

stow --version
Enter fullscreen mode Exit fullscreen mode

The Old-School Way: Manual Syncing with Git đź“‚

Before discovering Stow, I used to manage my dotfiles like this:

  1. Copy the dotfiles to a dedicated folder: 
   mkdir -p ~/.dotfiles
   cp -r -f -v ~/.config ~/.dotfiles/.config
   cp -r -f -v ~/.zshrc ~/.dotfiles/.zshrc
   ...
Enter fullscreen mode Exit fullscreen mode
  1. Initialize a Git repository and push to GitHub: 
   cd ~/.dotfiles
   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin git@github.com:yourusername/.dotfiles.git
   git push -u origin main
Enter fullscreen mode Exit fullscreen mode
  1. Manually restore dotfiles when needed: 
   cp -r -f -v ~/.dotfiles/.config ~/.config
   cp -r -f -v ~/.dotfiles/.zshrc ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

This worked, but it was tedious. Every time I updated my dotfiles, I had to manually copy them back and forth. There had to be a better way—and that’s when I found GNU Stow. 🎉

Meet Stow: A Simple Yet Powerful Tool for Dotfiles 🛠️

GNU Stow is a symlink farm manager that helps manage the installation of software packages by creating symbolic links (symlinks) in a structured way.

  • It allows users to keep software files organized in a single directory (source) and symlink them into another location (target) without directly copying or modifying the files.
  • It was originally designed for managing software packages, but it’s perfect for handling dotfiles.

How Stow Works

  • Instead of copying files, Stow creates symbolic links from a central directory (like ~/.dotfiles) to their actual locations (like ~/.config).
  • This means you only need to track files in one place, and Stow takes care of placing them in the right locations.
Concept Explanation Example (macOS)
package_name The folder that contains the files you want to symlink (e.g., a software package or configuration files). A directory named vim that contains configuration files for Vim.
Source Directory The location where packages are stored before being linked. ~/.dotfiles/ is the source directory where vim, git, and tmux configurations are stored.
Target Directory The location where symlinks will be created, pointing to files in the package. ~/.config/ is the target directory where the actual symlinks will be placed.

GNU Stow cheat sheet

Example of Stow in Action đź”—

Imagine your dotfiles are structured like this:

~/.dotfiles/
├── nvim/
│   ├── .config/nvim/init.lua
├── tmux/
│   ├── .tmux.conf
├── zshrc/
│   ├── .zshrc
Enter fullscreen mode Exit fullscreen mode

Instead of manually copying them, you can simply run:

stow -d ~/.dotfiles -t ~ nvim
stow -d ~/.dotfiles -t ~ tmux
stow -d ~/.dotfiles -t ~ zshrc
Enter fullscreen mode Exit fullscreen mode

Let's break it down:

  • stow: The command to run GNU Stow.
  • -d ~/.dotfiles: Specifies the source directory where the dotfiles are stored (~/.dotfiles). Stow assumes that inside this directory, there are subdirectories for different applications (e.g., nvim, zsh, etc.).
  • -t ~: Sets the target directory (~, which is your home directory). Stow will create symlinks in this directory.
  • nvim: The subdirectory inside ~/.dotfiles that contains the actual configuration files for Neovim. Stow will take the files inside ~/.dotfiles/nvim and symlink them into your home directory.

This creates symlinks:

~/.config/nvim/init.lua → ~/.dotfiles/nvim/.config/nvim/init.lua
~/.tmux.conf → ~/.dotfiles/tmux/.tmux.conf
~/.zshrc → ~/.dotfiles/zshrc/.zshrc
Enter fullscreen mode Exit fullscreen mode

Alternatively, you can use:

cd ~/.dotfiles
stow -v .
Enter fullscreen mode Exit fullscreen mode

This applies symlinks for all directories inside .dotfiles. The -v flag gives verbose output, so you can see what Stow is doing.

[!WARNING]
When using stow -v . a little different.

What It Does:

  • -v → Enables verbose mode, showing which symlinks are created.
  • . → Assumes you are inside ~/.dotfiles and applies stow to all directories inside it.

and the output should creates symlinks become:

~/nvim/.config/nvim/init.lua  →  ~/.dotfiles/nvim/.config/nvim/init.lua
~/tmux/.tmux.conf → ~/.dotfiles/tmux/.tmux.conf
~/zshrc/.zshrc                 →  ~/.dotfiles/zshrc/.zshrc

To remove symlinks, you can run:

stow -D tmux
Enter fullscreen mode Exit fullscreen mode

To restow (apply changes after updating dotfiles):

stow -R tmux
Enter fullscreen mode Exit fullscreen mode

How to Manage Dotfiles with Stow and Git (Step by Step) đź“Ś

Here’s a simple workflow to manage dotfiles with Stow and Git:

1. Create a dotfiles Directory 

mkdir -p ~/.dotfiles
cd ~/.dotfiles
Enter fullscreen mode Exit fullscreen mode

2. Organize Your Dotfiles

Let's move all dotfiles you want to stow and manage.

mv -f ~/.config ~/.dotfiles/.config
mv -f ~/.tmux.conf ~/.dotfiles/.tmux.conf
mv -f ~/.zshrc ~/.dotfiles/.zshrc
Enter fullscreen mode Exit fullscreen mode

3. Use Stow to Create Symlinks

Apply all dotfiles at once:

stow -v .
Enter fullscreen mode Exit fullscreen mode

Awesome 🤠

4. Initialize a Git Repository and Push to GitHub 

cd ~/.dotfiles
git init

git add .
git commit -m "Initial dotfiles setup"
git remote add origin git@github.com:yourusername/.dotfiles.git
git push -u origin main
Enter fullscreen mode Exit fullscreen mode

5. Restore Dotfiles on a New Machine 🖥️

When setting up a new machine, simply clone the repo and re-run Stow:

git clone git@github.com:yourusername/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles
stow -v .
Enter fullscreen mode Exit fullscreen mode

That’s it! No more copying files manually. 🚀

Note: make sure stow installed.

Ignoring Files with stow-local-ignore đź“ś

Sometimes, you may want Stow to ignore specific files or directories within your dotfiles setup. For this, you can use a .stow-local-ignore file inside the respective package directory.

How to Use .stow-local-ignore

  1. Create a .stow-local-ignore file inside the package directory: 
   touch ~/.dotfiles/.stow-local-ignore
Enter fullscreen mode Exit fullscreen mode
  1. Add the names of files or directories you want Stow to ignore: 
   .DS_Store
   .gitconfig
   .git
   .gitignore

   backup/
   tmp_config.json
Enter fullscreen mode Exit fullscreen mode
  1. Now, when running Stow, these files will be skipped while symlinking.

This is useful for keeping temporary or machine-specific files out of your Stow-managed dotfiles!

Bonus: Ignore Unwanted Files 🛑

To avoid pushing unnecessary files, create a .gitignore:

# Ignore system-specific files
.history
.local
.cache
Enter fullscreen mode Exit fullscreen mode

This keeps your repo clean and portable.

Conclusion 🎯

Managing dotfiles manually is painful, but with Git and Stow, you can:

âś” Keep all your configurations versioned and backed up.\
âś” Easily sync dotfiles across machines.\
âś” Avoid cluttering your home directory with redundant copies.

Try setting up Stow today—it might just change the way you manage your development environment forever! 💡

Do you have a favorite dotfile management trick? Share your thoughts in the comments! đź’¬

insideee_dev image

insideee.dev

Web Developer 🧑‍💻

🚀 Follow me on X(Twitter)

🚀 Connect with me on Linkedin

🚀 Checkout my GitHub

See you soon.

Thanks for reading!

Top comments (0)

Read next

jacob_barsimantov_4b4505d profile image

What do you guys think is the easiest coding language to learn

Jacob Barsimantov -

sugarlata profile image

Hacking a Ghost XL

sugarlata -

stevsharp profile image

Setting Up MediatR in a Minimal API

Spyros Ponaris -

jack_aurthor profile image

The Future of IT: How Automation & AI Are Revolutionizing Development

Jack Aurthor -