Dotfiles

Unix-first dotfiles for macOS, Linux, and Windows (via WSL2).

Warning

Feel free to take what you want, but review before installing. cargo make init installs packages and symlinks configs into your home directory.

---

Architecture

The core dev environment (zsh, Neovim, CLI tools) targets unix; Windows reaches it through WSL2. Both platforms converge on the same common/ configs, and only the GUI layer differs.

flowchart LR
    subgraph macOS
        M[Ghostty, AeroSpace]
    end
    subgraph Linux
        L[Ghostty, GNOME]
    end
    subgraph Windows
        W[WezTerm, komorebi] --> WSL[WSL2]
    end
    M --> C["common/<br/>zsh, Neovim, tmux, CLI tools"]
    L --> C
    WSL --> C

Loading

---

Principles

1. Unix-first: configs are written for unix. Windows uses WSL2 to run them.
2. Performance-first: preference for modern, Rust-based tools (eza, bat, ripgrep, fd).
3. Easy installation: dotter for symlinks, cargo-make for setup automation.

---

Install

Prerequisites

Install Rust and cargo-make:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify
rustc --version && cargo --version

# Install cargo-make
cargo install cargo-make

Clone and init

git clone git@github.com:msetsma/.dotfiles.git
cd .dotfiles
cargo make init

Linux (native)

Tested target: Surface Pro 7 on GNOME (Fedora or Ubuntu with the linux-surface kernel). linux/install-tools.sh detects dnf, apt, or pacman.

cargo make linux-surface   # optional: linux-surface kernel + iptsd (reboot after)
cargo make init            # packages, zinit, fonts, zsh as login shell, hostname mitch-linux, dotter
cargo make linux-desktop   # GNOME keybinds that mirror AeroSpace

Details in linux/README.md.

Windows (two-step setup)

On Windows, run init twice: once on the Windows host for native apps, and once inside WSL2 for the dev environment.

# 1. Windows host (PowerShell/cmd): installs Scoop packages, WezTerm, komorebi
cargo make init

# 2. Inside WSL2: installs zsh, zinit, CLI tools, symlinks common/ configs
cargo make init

The repo lives on the Windows filesystem and is accessed from WSL2 via /mnt/c/Users/<you>/.dotfiles. Extra Windows tweaks are in windows/README.md.

View available commands

cargo make help    # Quick reference
cargo make info    # All commands

---

Common Tasks

Setup & updates

cargo make init            # Complete environment setup
cargo make update          # Update all tools and packages
cargo make check-outdated  # Check for available updates
cargo make doctor          # System health check

Package management (cross-platform)

cargo make pkg-export      # Export packages
cargo make pkg-import      # Import packages
cargo make pkg-cleanup     # Cleanup old versions
cargo make pkg-doctor      # Check for issues

Platform-specific: brew-* (macOS), scoop-* (Windows), apt (WSL2/Linux).

Dotfile deployment

dotter # Deploy dotfiles via dotter

Python CLI tools (uv)

cargo make uv-tools-list     # List installed tools
cargo make uv-tools-export   # Export to uv-tools.txt
cargo make uv-tools-install  # Install from uv-tools.txt
cargo make uv-tools-upgrade  # Upgrade all

Utilities

cargo make clean           # Cleanup caches
cargo make info            # Show all available commands

---

Tools

Note

Common tools are cross-platform. Installation methods differ by OS.

Common (all platforms)

Neovim | Zsh + zinit | tmux | Mise | Dotter | Cargo-Make | Starship | fzf | eza | bat | ripgrep | fd | lazygit | Bottom | Ruff | Glance | JetBrains Mono

macOS-only (GUI layer)

Ghostty | AeroSpace

Linux-only (GUI layer)

Ghostty | GNOME | linux-surface

Windows-only (GUI layer)

WezTerm | Firefox + Betterfox | komorebi | whkd | yasb | Scoop

---

Moshi (remote coding from iPhone)

flowchart LR
    A[iPhone] -->|SSH / Tailscale| B[Windows sshd] --> C[nushell] --> D[herdr] --> E[Claude Code]

Loading

Push notifications come from native moshi-hook (experimental on Windows, Herdr only).

Setup: docs/ssh-mosh-setup-guide.md

---

Platform Detection

Shell configs use common/zsh/platform.zsh to detect the runtime environment:

Variable	Environment
IS_MAC	macOS (Darwin)
IS_WSL	WSL2 (Linux with Microsoft kernel)
IS_WSL_INTEROP	WSL2 with Windows interop enabled
IS_LINUX	generic Linux

This drives platform-specific behavior like clipboard (pbcopy vs clip.exe), URL opening (open vs wslview), and credential storage (Keychain vs env files).

---

Gotchas

Compiler suite

• macOS: Clang (via Xcode command line tools)
• Windows: MSVC (Visual Studio Build Tools, "Desktop development with C++" workload)
• WSL2/Linux: GCC (installed by cargo make init: build-essential, gcc gcc-c++, or base-devel)

WSL2 line endings

The repo uses .gitattributes to enforce LF line endings for shell scripts. This prevents issues when the repo lives on the Windows filesystem and is accessed from WSL2 via /mnt/c.

WSL2 hostname

Dotter uses hostname-based machine configs (.dotter/<hostname>.toml). If your WSL2 hostname matches your Windows hostname, set a distinct one in /etc/wsl.conf:

[network]
hostname = <host>-wsl

---

License

MIT