dotfiles

Personal dotfiles. Minimal, portable, built-in-first.

Quick Start

Clone the repo:

git clone git@github.com:wparks/dotfiles.git ~/dotfiles

Set up symlinks:

cd ~/dotfiles
./setup.sh

Launch Emacs to install packages on first run:

emacs

Then optionally, install tree-sitter grammars:

make grammars

Verify everything works:

make test

Windows:

Clone the repo:

git clone git@github.com:wparks/dotfiles.git $env:USERPROFILE\dotfiles

Change to the repo directory:

cd $env:USERPROFILE\dotfiles

Set up symlinks (requires Developer Mode):

powershell -ExecutionPolicy Bypass -File setup.ps1

What's Inside

Directory	Config for
emacs.d/	Emacs (init.el, custom.el)

Emacs

See docs/PRINCIPLES.md for design philosophy.

Installing Emacs

macOS

Recommended install:

make install-mac

Installs Emacs 30.x via emacs-app (pre-built, tree-sitter included). For native compilation, try emacs-plus:

brew tap d12frosted/emacs-plus

brew install emacs-plus@30

Note: emacs-plus may fail to build on the latest macOS (Tahoe). emacs-app works fine without native-comp.

Alternatives:

Option	Native-comp	Tree-sitter	Notes
brew install --cask emacs-app	No	Yes	Reliable, pre-built binary
brew install emacs-plus@30	Yes	Yes	Best option when it builds; may fail on new macOS
brew install emacs-mac (railwaycat tap)	Varies	Yes	Mitsuharu Yamamoto's macOS-native port; good Mac integration

Windows

Download from https://ftp.gnu.org/gnu/emacs/windows/ — Emacs 29+ builds include native compilation. Set HOME environment variable to your user directory. Requires Developer Mode for symlinks.

Linux

Check your version (need 29+):

emacs --version

If older, build from source with --with-native-compilation --with-tree-sitter.

Language Support

C/C++, Python, Go, JSON, YAML, Swift, Zig, Markdown, Org, Emacs Lisp

Tree-sitter modes used where available (C/C++, Python, Go, JSON, YAML). Others use dedicated packages or built-in modes.

Verification

Run lint and mode/indentation tests in one shot:

make verify

Individual targets:

Find all Emacs installations and their capabilities:

make discover

Byte-compile lint + paren check:

make check

Verify mode activation and indentation:

make test

Install tree-sitter grammars:

make grammars

Check which LSP servers are installed:

make check-lsp

Install LSP servers for available toolchains (skips missing toolchains):

make install-lsp

Remove packages, grammars, caches for fresh start:

make clean

Test against a specific Emacs binary:

make test EMACS=/path/to/emacs

Structure

Path	Purpose
emacs.d/init.el	Main Emacs configuration
emacs.d/custom.el	Emacs-generated customization (do not hand-edit)
docs/PRINCIPLES.md	Design philosophy and direction
tests/emacs/	Emacs test scripts and sample files
setup.sh	Symlink setup (macOS / Linux)
setup.ps1	Symlink setup (Windows)
Makefile	lint, check, test, verify, discover, setup, grammars, check-lsp, install-lsp, install-mac, clean
TODO.md	Tracked work and future plans
emacs.d/elpa/	Installed packages (gitignored)
emacs.d/tree-sitter/	Compiled grammars (gitignored)
emacs.d/tmp/	Backups and auto-saves (gitignored)

License

MIT (see LICENSE.md)