paulirish/dotfiles: Paul Irish's fish, bash and git config, and what is reusable

What paulirish/dotfiles is, and who it is actually for

This is one person's configuration repository: fish and bash shell config, git config, a vim config, tmux config, Homebrew scripts and a set of macOS defaults. The README is unusually direct about the intended audience. It says the repo is maintained as the author's own dotfiles, that he is aware people use it for theirs, and that suggestions may be declined if they are not of personal value to him. It also points anyone starting fresh toward mathiasbynens/dotfiles or alrra/dotfiles as forks to consider, and names paulmillr/dotfiles and gf3/dotfiles as other setups.

That framing matters when you decide whether to adopt it. The repository is not a framework with a stable configuration surface. It is a working environment that happens to be public. If you want a curated set of shell behaviours to read and borrow from, that is exactly what it offers. If you want a tool that installs a known-good environment on any machine, this is not that, and the author says so before you find out the hard way.

The parts the README singles out: .inputrc, fish functions, z and cdf

The README calls .inputrc the readline config and claims it makes typing into the prompt better. The concrete behaviours it lists: tab completion without the "Display all 1745 possibilities? (y or n)" prompt, case insensitivity, and typing cat followed by the up arrow to page through previous cat invocations. Those are readline settings, so they apply to bash and to any other readline-based tool that reads the same file, not just to the shell you launch.

The fish side is where most of the day-to-day content lives. The README points at fish/aliases.fish, fish/functions.fish and the fish/functions/ directory, alongside the bash equivalents .aliases and .functions. It describes both the bash and fish configuration as well maintained, and notes that fish users need to initialise submodules.

Folder navigation gets its own section. z jumps to a directory by a learned match, and the README is honest that "z learns only once its installed so you'll have to cd around for a bit to get it taught." Alongside it are ... style aliases that shorten cd ../.. and deeper variants, and cdf, which changes to whatever folder is currently open in Finder. The README gives this example:

z dotfiles
z blog
....      # drop back equivalent to cd ../../..
z public
cdf       # cd to whatever's up in Finder

The example is the whole tutorial. There is no configuration file documented for z, no list of tuning options, and no explanation of where it stores what it learns. You use it and it improves.

Installing paulirish/dotfiles and getting to a first useful shell

The README does not present a single install command. It lists manual-run scripts instead: setup-a-new-machine.sh for applications, symlink-setup.sh for symlinks across the dotfiles and vim config, .macos for a fresh macOS setup, and brew.sh plus brew-cask.sh for Homebrew initialisation. Because fish is the primary shell, the README also states that fish users should run a submodule update.

The order that follows from those files is clone, initialise submodules, then run the symlink script. The README's own setup section gives the submodule step for fish users:

git submodule update --init

After that, run the symlink script that the README lists under manual run:

./symlink-setup.sh

The README does not document what symlink-setup.sh overwrites, whether it backs up existing files, or how to undo it. That is the single largest gap in the repository's documentation, and it is the reason to read the script before running it rather than after. If your home directory already contains a .gitconfig, a .vimrc or a .bashrc you care about, inspect the script first.

The machine-level scripts are a separate decision. setup-a-new-machine.sh is described as "random apps i need installed", brew.sh and brew-cask.sh as Homebrew initialisation, and .macos as macOS defaults that the README explicitly says you should probably run only after reviewing it, pointing at Mathias's repo as the canonical source for that file. Treat those as three independent choices, not one install.

Where this repository will fight you

The README's own opening warning is the main limitation: it does not suggest you wholesale use these dotfiles. That is not modesty, it is an accurate description of a repository shaped around one person's habits. Aliases encode his workflow, the macOS defaults encode his preferences, and the app list in setup-a-new-machine.sh is his list.

The documentation is thin in specific places. There is no stated licence in the repository metadata, which means the terms under which you may reuse the content are not declared. There are no releases, so there is no version to pin and no changelog to read before pulling. The symlink script's behaviour on conflicting files is undocumented. The SSH section is explicitly personal: the README says the author has been doing hardware-key authentication for a while, forgot how he learned it, and could not find it documented anywhere, then gives a two-step procedure of listing your ecdsa-sha2-nistp256 key and pasting it into the remote authorized_keys.

The repository is also a moving target in a way that matters for anyone mirroring it. The README's own 2020 update section concedes that Rust tools have changed things: it names bat as a cat replacement, delta as nicer than the diff-so-fancy project the author started, eza as a better ls, and git-fuzzy as deprecating his git recent script. A repository whose author is publicly retiring his own scripts in favour of other tools is one you should read, not one you should freeze into a team image.

How it compares with the alternatives it names

The README itself is the best comparison source, because it names four other dotfiles repositories and a set of management tools. mathiasbynens/dotfiles and alrra/dotfiles are recommended as starting points for people beginning anew, which implies a broader, more general-purpose setup than Paul's. paulmillr/dotfiles and gf3/dotfiles are listed as other great setups without further qualification. The distinction is intent: those are offered as bases to fork, this one is offered as a personal configuration to borrow from.

The more interesting comparison is the management layer, and here the README is candid that it is unfinished business. The "Dotfiles mgmt todo" section lists homesick, the Atlassian bare-repository approach, nix-community/home-manager and chezmoi as things the author would like to migrate to. That is a meaningful signal. A bare git repository in your home directory, or a manager like chezmoi, gives you templating, per-machine differences and an uninstall path. This repository gives you symlink-setup.sh and a set of files. The author knows the difference and has written it down.

For the shell layer specifically, the 2020 update points elsewhere for the pieces that used to be homegrown: delta over diff-so-fancy, eza over ls, git-fuzzy over git recent. If you are choosing tools today, those pointers are more current than the scripts they replace.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-13. There are no releases, so "upgrading" means pulling the main branch and re-running symlink-setup.sh, or copying individual files by hand. Neither path has a documented rollback.

The practical upgrade cost is re-reading diffs before you apply them. Because the files are symlinked into your home directory, a pull changes your live shell configuration the moment you re-run the symlink script. There is no versioned release to hold back on, and the README does not describe a mechanism for keeping local edits separate from upstream ones. If you fork and edit, you own the merge conflicts.

On licensing: the repository metadata does not state a licence. That is not a legal opinion, it is an observation about the material. For personal use on your own machines the question rarely arises. For redistributing the files, bundling them into a product, or shipping them to a team, the absence of a declared licence is a real unknown, and the README's own suggestion to fork other repositories does not resolve it either.

Editorial conclusion

Adopt this repository if you are comfortable reading shell config and want specific pieces: the .inputrc readline behaviour, the fish aliases and functions, the z and cdf navigation helpers, or the git aliases in .gitconfig. Do not adopt it as a turnkey installer for a fresh machine: the README says it is maintained as Paul's own dotfiles, that suggestions may be declined if they are not of personal value to him, and that newcomers should consider forking mathiasbynens/dotfiles or alrra/dotfiles instead. Before running anything, read setup-a-new-machine.sh, symlink-setup.sh, brew.sh, brew-cask.sh and .macos, because those are the files that change your machine rather than just your shell, and confirm each one does what you expect on your own system.

Frequently asked questions

Official sources

1. Issues
2. paulirish/dotfiles on GitHub
3. README