jessfraz/dotfiles: a personal dotfiles repo you install with make

What jessfraz/dotfiles actually is

This repository is one person's machine configuration, published under the MIT licence. The README opens with the line "My dotfiles. Buyer beware ;)", which is a fair description of the genre: the files work for the author's hardware and habits, and the value to anyone else is as a reference or a starting point. The top level holds shell configuration (.aliases, .bash_prompt, .exports, .functions, .inputrc), X11 files (.Xdefaults, .Xprofile, .Xresources, .xsessionrc), a .gitconfig, an .i3 directory, and a .codex directory. There is also a bin directory of scripts, an etc directory of system files, a usr directory, a nix directory with flake.nix and flake.lock, and a central-park.jpg that the Makefile links into ~/Pictures.

The intended audience is narrow. Someone who wants a dotfiles manager with profiles, per-host configuration and rollback will not find those here. Someone who wants to read a real, complete, Shell-based setup and copy the parts they like, or fork it and strip it down, is the right reader. The presence of flake.nix alongside a plain Makefile suggests two install paths coexist in the tree, though the README only documents the make one.

How the Makefile installs dotfiles into $HOME

The mechanism is symlinks, driven by make. The default target is all, which depends on bin, usr, dotfiles and etc, so a bare make runs all four in that order. Nothing is copied: the repository stays where it is and the files in it are linked into place.

The dotfiles target walks the repository root with find, matching names that start with a dot, and excludes .gitignore, .git, .config, .github, swap files and .gnupg. For each match it runs ln -sfn into $HOME. Because the flag is -n, an existing symlink at the destination is replaced rather than followed, and -f removes an existing file first. That means running make in a home directory that already has a real .gitconfig or .bash_prompt will replace those files with links into the checkout. There is no backup step and no dry run in the Makefile.

After the loop, the target does four more things: it links the repository's gitignore file to ~/.gitignore, runs git update-index --skip-worktree on the repository's .gitconfig so local edits are not tracked, creates ~/.config and links the .i3 directory there as sway, creates ~/.local/share and ~/Pictures, links central-park.jpg into ~/Pictures, and finally merges .Xdefaults and .Xresources with xrdb and rebuilds the font cache with fc-cache. The xrdb and fc-cache calls end in || true, so a machine without X11 does not fail the target there.

Installing jessfraz/dotfiles and writing a first .extra file

The README documents a single install command. Clone the repository, then run make from its root. The README says this "will create symlinks from this repo to your home folder." The bin target uses sudo to link each script in bin into /usr/local/bin, skipping files whose names end in -backlight and swap files.

git clone https://github.com/jessfraz/dotfiles.git
cd dotfiles
make

Because the bin and etc targets call sudo, expect password prompts. The etc target creates /etc/docker/seccomp and links files from the repository's etc directory to the same paths under /etc, then runs systemctl --user daemon-reload and sudo systemctl daemon-reload, and enables and starts systemd-networkd and systemd-resolved. That last part is the most invasive step in the whole install and it is not optional if you run the default target.

Personal values go in a .extra file rather than in the tracked dotfiles. The README gives this example, which sets Git identity and a Gmail address for mutt:

GIT_AUTHOR_NAME="Your Name"
GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
git config --global user.name "$GIT_AUTHOR_NAME"
GIT_AUTHOR_EMAIL="email@you.com"
GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
git config --global user.email "$GIT_AUTHOR_EMAIL"
GH_USER="nickname"
git config --global github.user "$GH_USER"

The README does not state which file sources .extra, so check the shell files in the repository before assuming it is picked up automatically. To run the project's own checks, the README says the tests use shellcheck and run in a container, so nothing needs to be installed locally:

make test

No uninstall, no dry run, and a systemd dependency

The clearest limitation is that there is no inverse of make. Nothing in the README or the Makefile removes the symlinks it created, and since the dotfiles target overwrites existing files with ln -sfn, a home directory with real configuration files in it is modified in place. If you have a hand-written .bash_prompt, running make replaces it with a link. Recovering the original means restoring it from a backup you made yourself.

The etc target is the second constraint. It enables and starts systemd-networkd and systemd-resolved on the host. On a system that uses NetworkManager, or on a non-systemd distribution, that is at best a no-op and at worst a change to how networking comes up. The target does not ask first. The Makefile also contains a LAPTOP_XORG_FILE variable pointing at /etc/X11/xorg.conf.d/10-dell-xps-display.conf, which is a hint that parts of the setup assume specific Dell XPS hardware; the visible Makefile excerpt does not show that variable being used, so treat it as a marker of the author's machine rather than a documented feature.

Finally, the README documents no rollback, no per-host branching and no way to install only part of the set. If you want a subset, you invoke the individual targets, for example make dotfiles, and accept that you are reading the Makefile to find out what each one touches.

How this differs from GNU Stow as a dotfiles manager

Stow is the usual alternative for people who want symlink-based dotfiles. The difference is in the unit of installation. Stow operates on packages: you keep each application's files in its own directory, and stow creates the links, with an unstow command that removes them. This repository has no package boundaries and no removal path. Its unit is the whole repository root, filtered by a find expression, and the only undo is manual.

That makes Stow the better choice when you want to add and remove applications over time, or when several machines need different subsets. This repository is the better read when you want to see how far a single Makefile can go: it links binaries into /usr/local/bin, drops files into /etc, reloads systemd units, merges X resources and rebuilds the font cache, all from one command. Stow does none of that, because it only manages symlinks under a target directory. If your setup stops at files in $HOME, Stow covers it with less risk. If you want the system-level steps automated, this Makefile shows one way, at the cost of the undo story.

Maintenance, licence and what a fork costs you

The repository is not archived. No last push date was retrieved, and there are no releases, so there is no version to pin and no changelog to read. Upgrades happen by pulling the branch and running make again, which re-creates every symlink. Since the links point into the checkout, a pull changes your live configuration immediately; there is no staged apply step.

The licence is MIT, which permits use, modification and redistribution provided the copyright notice and permission notice are kept. That matters here because a fork is the realistic adoption path: the README describes the files as personal, and the Makefile encodes one machine's assumptions. If you fork, keep the LICENSE file in place. This is a description of the licence text, not legal advice; check the LICENSE file and your own obligations.

The ongoing cost is mostly in the etc target. Every pull that changes a file under etc requires sudo again, and the systemd enable and start lines run each time. A fork that removes the etc target, or guards it behind a separate make invocation, would cut that cost to a plain symlink refresh.

Editorial conclusion

Adopt this if you want a working, MIT-licensed example of a make-driven dotfiles repo to read or fork, and you are comfortable with the installer symlinking into $HOME, /usr/local/bin and /etc and running sudo systemctl commands. Do not adopt it as-is if you expect an uninstall, a dry run, or a setup that does not assume an Arch-style Linux desktop with sway, i3 and systemd. Before running make, read the dotfiles, bin and etc targets in the Makefile, and check whether the files it links already exist in your home directory, because ln -sfn will replace them.

Frequently asked questions

Official sources

1. Official README
2. Project repository