jessfraz/dotfiles: A Production Dotfiles Repo with Nix Flake and Legacy Linux Paths

What jessfraz/dotfiles Contains and Who Would Use It

dotfiles repositories are collections of configuration files for shells, editors, and development tools. They are named after the Unix convention of prefixing hidden files with a dot. Jess Frazelle's dotfiles repository is a well-known example that covers shell aliases, Bash prompt configuration, Git settings, export variables, and various Unix tool configurations for a development workstation.

The repository is primarily a personal setup rather than a redistributable tool, and the GitHub description says "buyer beware." Its value for other developers is as a reference: how to structure a dotfiles repository, how to manage secrets without committing them, how to set up a Nix flake for Home Manager, and how to run CI tests on shell scripts. The last push was on 2026-09-25.

Two Installation Paths: Nix Flake and Legacy Makefile

The README documents two separate installation methods that co-exist in the same repository.

For Nix users, the repository ships a flake.nix that exposes homeManagerModules.default. The README specifies that the host configuration must supply the username, home directory, and state version. The global-nix module enables Bash completion and installs Zoo and rustup completion files used by the .nixbash startup fragment. This approach uses Home Manager's declarative model, meaning the configuration is applied by the Nix toolchain rather than by symlinking.

For legacy Linux systems, the Makefile installs everything:

$ make

The Makefile's dotfiles target finds every hidden file in the repository (excluding .gitignore, .git, .config, .github, .*.swp, and .gnupg) and creates a symlink in the user's home directory for each one. It also symlinks the i3 configuration to .config/sway, creates the .local/share directory structure, copies a wallpaper to ~/Pictures, and runs xrdb and fc-cache as side effects. Developers adopting this approach should review the Makefile's targets before running make, since it also installs files from bin/ to /usr/local/bin and files from etc/ to system paths using sudo.

Keeping Secrets Out: The .extra File Pattern

The README describes using a .extra file to store environment variables and credentials that should never be committed to the repository. The convention is to source .extra at shell startup, so it augments the committed configuration without appearing in Git history.

The README shows this structure:

###
### Git credentials
###

GIT_AUTHOR_NAME="Your Name"
GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
git config --global user.name "$GIT_AUTHOR_NAME"
GIT_AUTHOR_EMAIL="[email protected]"
GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
git config --global user.email "$GIT_AUTHOR_EMAIL"
GH_USER="nickname"
git config --global github.user "$GH_USER"

###
### Gmail credentials for mutt
###
export [email protected]
export GMAIL_NAME="Your Name"
export [email protected]

This pattern is a practical answer to the problem that dotfiles need real Git configuration to work correctly, but a committed .gitconfig with a real name and email exposes personal information in a public repository. The .extra pattern separates the per-machine secrets from the structural configuration.

Testing with Nix Checks and shellcheck

The repository includes a test suite that runs through two mechanisms.

For the Nix path, the README describes running:

$ nix flake check --no-update-lock-file

This command runs native Nix checks that include a complete Home Manager fixture and an editor smoke test. The README states that CI builds these checks on three platforms: x86-64 Linux, ARM Linux, and ARM macOS. It also clarifies that homeConfigurations outputs are test fixtures, not host profiles, and should not be activated directly.

For shell scripts, the Makefile exposes a test target:

$ make test

This runs shellcheck on the shell scripts inside a container. shellcheck is a static analysis tool for shell scripts that catches common errors, undefined variables, and portability issues. Running it in a container means the test environment is consistent across machines without requiring a local shellcheck installation.

Repository Layout and Scope

The top-level directory includes dotfiles covering Bash configuration (.aliases, .bash_prompt, .exports, .functions, .nixbash), X11 settings (.Xdefaults, .Xprofile, .Xresources), Git (.gitconfig, gitignore), and terminal configuration (.irssi/, .urxvt/). There are also directories for i3 tiling window manager configuration (.i3/), system files (etc/), and scripts (bin/).

A .codex/ directory and a .gemini/ directory appear in the top-level entries, suggesting that configuration for AI coding tools has been added recently. The .dockerfunc file is a shell fragment with Docker-related functions. The flake.nix and flake.lock files represent the Nix configuration. The repository is licensed under MIT.

For the Vim configuration specifically, the README points to a separate repository at github.com/jessfraz/.vim rather than including .vimrc here.

Limitation: Personal Repository, Not a Portable Tool

Unlike a dotfiles manager such as GNU Stow, which is a general-purpose symlink tool designed for any dotfiles collection, jessfraz/dotfiles is a concrete personal setup rather than a portable framework. GNU Stow provides a minimal, tool-agnostic approach: it creates symlinks from a source directory tree to a target, without any opinions about which files belong where.

jessfraz/dotfiles takes the opposite approach: the Makefile and Nix configuration are written for a specific set of tools and directory conventions. Adopting it wholesale on a different system means adapting the Makefile targets for local paths, removing tool-specific configurations that are not needed, and potentially breaking the Home Manager flake if the username or state version does not match. The Nix path in particular requires a working Nix installation with flakes enabled, which is not a standard default on most Linux distributions.

The Makefile also runs xrdb, fc-cache, and systemctl calls as side effects of the install target. On a system without X11 or systemd, those commands will fail. The Makefile suppresses some errors with `|| true`, but teams running the installer on non-standard setups should review the Makefile targets before executing make.

Editorial conclusion

jessfraz/dotfiles is worth examining for developers who want a concrete example of a dual-path dotfiles setup that works on both Nix and legacy Linux systems, and who want to understand how CI validation with shellcheck fits into that workflow. As a personal repository, the configuration is not designed for direct adoption; the README states "buyer beware" in the description. Before using any part of it, verify that the Nix Home Manager setup matches the target system's username and state version, and check that homeConfigurations outputs are not activated directly since the README specifies they are test fixtures. Keep credentials and environment variables in a local .extra file that is never committed.

Frequently asked questions

Official sources

1. Official README
2. Project repository