xero/dotfiles: a GNU Stow-based Linux config collection for tty and Neovim users

What xero/dotfiles actually solves

The README opens with the problem it was written against: keeping a git repository in the root of your home directory is a bad idea, and the existing dotfile managers it mentions carry too many dependencies. The author's answer is GNU Stow, described in the README as a free, portable, lightweight symlink farm manager. The repository holds versioned config directories (zsh, tmux, neovim, git, gpg, ssh, bin, fun, bash, blink, dbcli, neovide, wallpaper, xorg) and Stow links them into place.

Who this is for: someone who already works in a terminal, wants zsh, tmux and Neovim configured the way another terminal user configured them, and prefers reading shell scripts over learning a manager's own DSL. The README is explicit that the author lives in the tty, xorg free, and that the window manager configs (2bwm, windowchef) were moved to the classic branch and are not actively maintained. So this is not a desktop rice starter kit, despite the r/unixporn framing.

How Stow turns the repo into your home directory

Stow creates symlinks in the parent directory of wherever you run it, so the working directory matters. The README says the author keeps the repo at ~/.local/src/dotfiles and therefore suffixes every command with -t ~, otherwise the links land in ~/.local/. Cloning to ~/dotfiles lets you drop the flag, which the README notes with a wink.

The mapping is structural, not configurable. Stow recreates the exact folder layout of the repo, which is why the fun scripts live at /fun/bin/food and install with a target of /usr/local/ rather than /usr/local/bin. The same rule explains why stow zsh -t ~ produces a link at ~/.config/zsh.

One constraint is stated plainly: Stow can only create a symlink if a config file does not already exist. If a program's installation wrote a default file, you delete it first. Directories are exempt; files are not. That is the single most common failure when applying this repo to a machine that already has a shell or editor configured.

Installing xero/dotfiles with stow and a first run

Stow itself comes from the distribution package manager. The README lists apt, brew, dnf, pacman and yum, or a source build from savannah.gnu.org.

apt install stow

Then clone the repository and link the pieces you want. The README's own example clones to ~/.local/src/dotfiles and runs Stow from there with -t ~:

git clone [email protected]:xero/dotfiles.git ~/.local/src/dotfiles &&
cd ~/.local/src/dotfiles &&
stow bin fun git gpg ssh tmux neovim zsh -t ~

The shorter path in the README's tl;dr section clones into the home directory and runs stow zsh with no target flag, which links the zsh config into place. To undo it, the README gives stow -D zsh.

Neovim needs its plugin manager before the config is useful. The setup script creates the lazy.nvim directory and then syncs headlessly:

mkdir ~/.local/nvim &&
git clone --filter=blob:none --single-branch https://github.com/folke/lazy.nvim.git ~/.local/share/nvim/lazy
nvim --headless "+Lazy! sync" +qa
nvim --headless "+MasonUpdate" +qa

The first command should finish without opening an editor window; the second updates Mason. tmux needs its own plugin bootstrap, which the setup script handles by cloning tpm into ~/.config/tmux/plugins/tpm and running install_plugins.sh. The README also documents installing the whole thing through the setup script in the repository root rather than typing these commands by hand.

The setup script is the real installer, and it is opinionated

The setup file at the repository root is what the README points to for a full installation. It goes beyond Stow: it clones tpm for tmux, runs the tmux-thumbs installer through expect with a hardcoded menu choice, bootstraps lazy.nvim, and ends by creating two system users:

sudo useradd -g src -d ~/.local/src src
sudo useradd -d ~/.local/src/dotfiles dotfiles

Those commands assume a specific home layout and a src group. On a machine where that group does not exist, or where ~ expands differently under sudo, they will fail or create something you did not intend. This is the point where a reader should stop and read rather than pipe. The README does not describe a dry-run mode, a rollback, or an uninstall path beyond stow -D for individual packages. There is no documented way to reverse the useradd calls.

The expect invocation for tmux-thumbs is the other sharp edge. It spawns an interactive installer and sends carriage return plus 2 to pick an option. If the upstream installer changes its prompt order, the script silently selects the wrong thing or hangs.

Where xero/dotfiles is the wrong tool

The clearest boundary is in the README itself: window manager configs for 2bwm, windowchef and similar moved to the classic branch and are not actively maintained, because the author works without X. If you are searching for a Hyprland or niri setup, this repository does not contain one, and the classic branch is where the older X configs sit.

A second boundary is conflict handling. Stow refuses to link over an existing file, so on a machine that already has a .zshrc or an init.lua, you must move or delete those first. A manager that merges or backs up automatically would be less work here. The README acknowledges this and points to a GitHub issue for more detail, but the repository does not ship a conflict resolver.

Third, the terminal setup is tied to a specific workflow: Blink Shell on an iPad connected to a VPS, with Hack Nerd Font shipped as base64 CSS inside the blink directory. If you use a local terminal emulator, that directory is simply irrelevant to you. Nothing breaks, but a meaningful chunk of the repository is not for your case.

How this compares to a dotfiles manager with its own CLI

The README names the alternative category directly: dotfile managers listed at dotfiles.github.io/utilities, which it criticizes for having lots of dependencies. The difference in approach is real. A dedicated manager typically keeps a manifest or a mapping file and knows how to back up, adopt and restore files; Stow has no state beyond the symlinks it created, so the repository tree itself is the configuration.

That trade cuts both ways. With Stow you can inspect the result with ls -l and understand everything immediately, and stow -D zsh removes the links without a database to consult. But you get no backup of the file you deleted, no per-host templating, and no way to express "this file only on that machine" other than separate Stow packages. The README's answer to multi-user sharing is running Stow again with a different target, as in sudo stow zsh -t /root, which is simple but means root and your user share one source of truth with no divergence handling.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-20, roughly two months before this writing. Two releases are listed: evangelion on 2025-03-11 and miasma on 2024-08-30. The README's own description calls the dotfiles perpetual wip, which is a fair summary of what to expect: updates arrive, but nothing promises API stability in the config layout.

Upgrade cost is concentrated in Neovim. The setup script pins nothing; lazy.nvim syncs whatever the plugin specs resolve to at the time you run it, and MasonUpdate pulls current language servers. A config that worked at the last push can break after a plugin's next release, and the repository offers no lockfile. Updating the dotfiles themselves is a git pull followed by re-running Stow, which is cheap; updating the Neovim side is the part that can cost an evening.

The licence is CC0-1.0, a public domain dedication. In practical terms that is permissive for copying and adapting the config text, but CC0 is written for content rather than software, and it contains no patent grant. If your organization cares about that distinction, that is a question for your own counsel, not something this repository answers.

Editorial conclusion

Adopt xero/dotfiles if you already work in a tty, use Neovim, and want a Stow-managed tree you can read and edit rather than a framework with plugins. Do not adopt it if you need a maintained window manager setup (those configs moved to the classic branch), if you expect an installer that handles existing files for you, or if you are not comfortable deleting default configs before Stow can link. Verify first that stow is packaged for your distribution, read the setup script line by line, and check whether the fun scripts you want already exist in /usr/local/bin, because Stow will refuse to overwrite a file that is already there.

Frequently asked questions

Official sources

1. License: CC0-1.0
2. Project website
3. README
4. Releases
5. xero/dotfiles on GitHub