Dotfiles

Reproducible workstation dotfiles for this Ubuntu machine.

Repo Layout

• config/: app configs (i3, kitty, nvim, picom, gtk-3.0, gtk-4.0)
• home/: shell/login files (.bashrc, .profile, optional .Xresources, .xinitrc, .gitconfig)
• localbin/: user-facing helper scripts
• bootstrap/: install/link scripts
• system/: verification scripts and tracked system metadata
• docs/: practical usage docs and generated repo map

nnn behavior currently lives in shell startup plus localbin/nnn-opener; there is no tracked config/nnn/ tree at the moment.

Quickstart

git clone <remote> ~/workspace/dotfiles
cd ~/workspace/dotfiles
./bootstrap/install.sh
./bootstrap/link.sh

Current Runtime Behavior (Important)

• i3 binds execute helper scripts by absolute repo path (/home/sf/workspace/dotfiles/localbin/...).
• bootstrap/link.sh also symlinks every localbin/* file into ~/.local/bin for shell use.
• ~/.local/bin is prepended in both home/.bashrc and home/.profile.
• Firefox launch from i3 goes through localbin/firefox-session, which prefers fox before generic firefox.
• Per-workspace i3-resurrect save/restore wrappers use double-press confirmation and prune Firefox + VS Code replay commands from workspace_<n>_programs.json.

Docs

• docs/architecture.md: repo structure, invariants, and how bootstrap/runtime/verification fit together
• docs/bootstrap.md: install/link flow, idempotency, and recovery
• docs/i3-workflow.md: keybind workflow, save/restore behavior, and i3-resurrect gotchas
• docs/command-surface.md: user-facing scripts, aliases/functions, and safety notes
• docs/command-surface-policy.md: command-surface invariants
• docs/repo-map.md: generated structural index of the tracked tree

Verify

make repo-map
i3 -C -c config/i3/config
./system/check-no-external-user-paths.sh
./system/verify-i3-helper-paths.sh

Notes

• host/<hostname>/link.sh is sourced at the end of bootstrap/link.sh when present.
• Existing files are never overwritten by link script; they are moved to ~/dotfiles_link_backup_<timestamp>/.
• This repo does not track secrets, SSH keys, browser profiles, or runtime caches.