Setting Up Cross-Platform Dotfiles with GNU Stow

How I unified my Linux (Hyprland) and macOS development environments into a single dotfiles repository managed with GNU Stow.

Managing configuration files across multiple machines and operating systems used to be a constant source of frustration. After years of manually syncing configs, I finally built a unified dotfiles repository that handles both Linux and macOS seamlessly using GNU Stow.

The Problem

I run Hyprland on Arch Linux at my workstation and macOS on my laptop. The tools overlap significantly — Neovim, Kitty, Zsh, Tmux — but the platform-specific details (Homebrew paths, clipboard commands, window manager configs) differ enough to cause headaches.

The Solution: Layered Directories

The repository is split into three layers:

—common/ — everything that works on both platforms (Neovim, Tmux, Zsh, Starship)
—linux/ — Hyprland, Waybar, Rofi, Swaync
—macos/ — Brewfile and system preferences script

Installation

GNU Stow symlinks each directory into your home folder. The entire setup comes down to:

# Clone and install everything

git clone https://github.com/iampramodphuyal/dotfiles ~/dotfiles

cd ~/dotfiles && ./install.sh

The installer detects your platform, stows the appropriate directories, sets up Oh My Zsh, and installs packages. A single script handles both operating systems without any manual branching on your part.

← Back to Blog