Andrew's Dotfiles Repo

Andrew Janke's personal configuration files and system setup scripts.

The idea here is to get as close as possible to being able to sit down at a fresh computer or user account, run just a couple commands, and have it fully set up the way I like it and be able to start working, instead of futzing around for hours with manual setup of GUI preference panels and the like.

Using this repo

Caution! This whole thing is a work in progress and it will probably never be "finished". I'm making this repo publicly available so other people can use my code and techniques. But it's not a product, it's not stable in either interface or behavior, and there is no support for it. I'm going to continue to change this stuff to meet my own needs, maybe in non-back-compatible ways, at any time. So you can't just clone the repo, use it directly, and expect it to be stable.

If you want to use this repo, make a copy, read and understand it, and load it in to your own dotfiles repo; then if you want, pull from upstream in a controlled, deliberate manner. (Probably not a GitHub fork of my repo; you want your own independent ("canonical") repo.)

Repo sections

There are a few different parts to this repo.

• dots – Unix-style configuration files for dropping in to your home directory.
• home-bin-jx – Portable-ish little Unix scripts and programs I want on all my computers. Linked in as ~/bin-jx.
• sys-setup – System and user configuration scripts that install things and adjust system settings.
• settings – Settings data files.
  • manual – Exported and imported settings files from various programs, managed manually.
  • iTerm2 – Shared data directory for iTerm2's "load settings from folder" preference sync thing.
• tools – Scripts for maintaining this repo itself, as opposed to configuring a machine. Currently just lint.

Overall Installation / Usage

To set up the dotfiles:

• Clone this repo locally, to its permanent location.
• Run the install-dotfiles command found in the root of the repo.

That will symlink your various ~/.* files to their definitions in the repo.

To set up a new Mac from scratch using sys-setup:

• Clone this repo locally, to its permanent location.
• Install Xcode and/or the Xcode CLT.
• In sys-setup:
  • ./setup-macos-homebrew
  • sudo ./setup-macos-system
  • ./setup-macos-user

Checking the code

There are two checks, both runnable from the repo root and both exiting non-zero on any problem, so they work in CI:

• ./dots/tests/run-tests – runs every dots/tests/test-* script. Those install into a throwaway $HOME, so they never touch your real one. Pass names to run a subset, e.g. run-tests bashy-paths.
• tools/lint – static-checks the shell scripts: shellcheck for bash/sh, and zsh -n for zsh, since shellcheck has no zsh dialect.

See doc/STYLE.md for the coding conventions these check against, including how to write files that are sourced by both bash and zsh.

Using in Dropbox - not recommended

I used to keep my "local" clone of this repo in my Dropbox cloud drive, but that didn't work great and I don't do it any more or recommend that others do it. Now I just keep it in a regular repo clone directory outside Dropbox or any other cloud drive.

The idea was to save the work of periodically doing git pulls on each computer where I used it, and automatically get the latest-and-greatest everywhere. But Dropbox isn't quite suited for that, for various reasons. My dotfiles are high prioirity and I want them synced right away, but when there's been a lot of data churn it can take Dropbox hours or days to catch up, and there isn't a great way to prioritize syncing of certain files. Cloud drive sync seems to have potential conflicts with git, which is its own data sync mechanism. I sometimes do want to have different computers using different branches or versions of my dotfiles. Some programs like Anaconda like to clumsily modify your dotfiles as part of their setup process, and when that happens I want to notice it, see where it happened, and undo it. As of 2021-ish, Dropbox really wants to make your files cloud-only, but I want all my dotfiles to be locally synced so they're captured by local-computer backups. And so on.

Design and implementation notes

See dots/README.md for info in the design of my dotfiles and shell configuration setup, and doc/STYLE.md for the shell coding conventions used throughout.

The setup-macos-system and setup-macos-user scripts can only have soft dependencies on setup-macos-homebrew, so that they can be run without it to configure a "clean" machine without a Homebrew installation. And as of 2024, the setup-macos-* scripts are most broken, because every new macOS release, Apple seems to remove or break some of the scripting or configurability support in macOS, and I'm too tired to try to keep up with it.

AI use disclosure

Some of the code in this repo was produced with the assistance of generative AI. Specifically, Claude Code. This AI use started on 8/6/2026 with commit cc15c1b ("deep selective linking"). The code in the git history prior to that is AI-clean.

License

All material in this project is licensed under the MIT License unless otherwise noted. See LICENSE.md.