Opinionated defaults. This repo is not meant to be used by everyone, just a personal configuration to take ideas out of. However, if you are brave enough you can install it with the instructions below. You are advised to read the installation scripts beforehand.
The canonical checkout is ~/cuberhaus/dotfiles. The ~/cuberhaus directory
collects this repository alongside the other Cuberhaus repositories, while
dotfiles remains a GNU Stow package.
GNU Stow treats the parent directory as
the "stow directory" and this repository as the package. The Makefile passes
$HOME as the deployment target, so sibling repositories under ~/cuberhaus
are unaffected.
So, the structure looks like this:
~/cuberhaus/
└── dotfiles/ (this repo)
├── .config/ ──┐
├── .local/ │ GNU Stow symlinks
├── .vim/ ├──────────────────► $HOME/
├── .xmonad/ │ ├── .config/ → ~/cuberhaus/dotfiles/.config/
├── .zshenv ──┘ ├── .local/ → ~/cuberhaus/dotfiles/.local/
├── Makefile (make targets) └── ...
└── .local/scripts/
└── bootstrap/ (OS-specific setup)
GNU Stow creates symlinks from $HOME
into this repo so that every config file stays version-controlled in one place.
The Makefile wraps stow and exposes common tasks. Bootstrap scripts install
packages and perform one-time setup for each supported OS.
VS Code user settings live in .config/Code/User/settings.json. Chat-tool
terminals use /bin/bash --noprofile --norc with BASH_ENV and ENV removed,
so they do not source personal shell startup files. Normal terminals still use
zsh. Agent terminals retain VS Code's inherited environment and prepend the
active workspace's .venv/bin, making its python executable available without
activating a shell environment; this is not an empty-environment sandbox.
GH_PAGER, GIT_PAGER, and PAGER are set to cat to avoid pager-driven
alternate-screen transitions implicated in the VS Code 1.137 chat-terminal
marker hang. Other full-screen programs can still trigger that path. These Bash
arguments prevent automatic shell-integration injection in that build, so agent
command detection may be less precise.
Create a new agent terminal after changing the profile. Remove
chat.tools.terminal.terminalProfile.linux to return to the default profile.
Interactive Bash gets a dependency-free prompt from .bashrc that mirrors the
zsh p10k "lean" look: blue path, git branch with ahead/behind and
staged/unstaged/untracked counters, and a prompt character that turns red after
a failed command. user@host is only shown over SSH or as root. man pages and
the completion list are colored too. PS1 is assigned once and never rewritten,
which keeps the VS Code and Cursor shell integration working. Set NO_COLOR=1
for the same layout without colors, or PROMPT_GIT=0 to hide the git segment in
huge repositories. TERM=dumb shells keep the stock prompt, and the chat-tool
terminals above stay uncolored because they skip .bashrc.
The $DOTFILES variable (exported by .zshenv) points to the repo root,
auto-detected by resolving the .zshenv symlink. Scripts and configs that
need to reference the repo should use $DOTFILES.
Bootstrap profiles also start directly from their running checkout. Before
linking any files, they install GNU Stow through the selected platform when
needed, show the Stow dry run and any conflict-backup plan, and ask for an
explicit confirmation. Declining continues provisioning through checkout paths
without linking files. Pass BOOTSTRAP_ARGS="--no-stow" to opt out explicitly;
an unattended or noninteractive bootstrap also leaves Stow unchanged rather
than assuming consent.
GUI-capable Unix bootstraps also clone the Obsidian vault to
~/cuberhaus/obsidian_vault and run its plugin-install target after installing
Obsidian. Set OBSIDIAN_VAULT_ROOT to use another checkout path. The WSL
bootstrap skips this GUI-specific step.
Clone the repo with its submodules and use GNU Stow to symlink everything into $HOME:
cd ~
mkdir -p cuberhaus
git clone --recurse-submodules https://github.com/cuberhaus/dotfiles cuberhaus/dotfiles
cd cuberhaus/dotfiles
sudo apt install stow # Pop!_OS, Ubuntu, and Debian
make installOn other operating systems, install
stowbefore runningmake install:
- Arch/Manjaro:
sudo pacman -S stow- macOS:
brew install stow
Common tasks are available via make:
make help # Show all targets
make install # Symlink dotfiles into $HOME
make uninstall # Remove symlinks from $HOME
make restow # Back up conflicts, then re-stow (cleans stale links)
make dry-run # Preview Stow and the conflict backup, change nothing
make lint # Run shellcheck on all scripts
make test # Run deterministic unit tests
make install-omp # Install pinned Oh My Pi only (keeps OpenCode/Pi)
make install-omo # Install pinned OmO Native too (no OpenCode plugin)
make check # Run tests, Gitleaks, and all linters
make audit-installation # Report installation drift without changing the machine
make doctor # Check tools, links, config, environment, packages, and schedules
make config-status # Show Stow deployment and source-checkout drift
make config-diff # Compare tracked configs with existing home targets
make config-import # Preview reverse import; add APPLY=1 to adopt
make maintenance-digest # Show last successful scheduled maintenance runs
make workspace # Sync workspace, then refresh repos.json
make submodules # Init and update submodules
make update # Pull latest for every submodule
make bootstrap-<os> # Run bootstrap (arch, manjaro, ubuntu, mac, work)
Run make audit-installation regularly on each Unix machine to compare the
current checkout, Stow-managed configs and aliases, packages declared by the
active bootstrap profile, and native automations. The target changes nothing
and exits 1 when it finds actionable drift. It auto-detects the profile from
the DOTFILES_PROFILE line that bootstrap-work records in
~/.config/distro, else from DISTRO there, else from the operating system;
use make audit-installation PROFILE=arch|manjaro|ubuntu|ubuntu-windows|mac|work
to override detection. Package expectations are parsed only from functions the
selected bootstrap actually calls, so commented optional bundles are excluded.
On a terminal the report uses colour so that what to do stands out: the command
under each Fix: is cyan and the # note under it gray (advice that is not a
command, such as "Start a new login shell", stays plain); an expected package
that is not installed is red, and a package that is installed but declared
nowhere in the bootstrap is yellow. There is no colour when the output is piped
or redirected, when NO_COLOR is set, or when TERM is dumb, and
--list-extra never uses it.
The audit also looks the other way. A package that is installed by hand but
that the selected bootstrap does not declare is reported as a [NOTICE], which
never changes the exit code, with a Fix: command that removes it
(sudo apt-get remove …, sudo snap remove …, sudo pacman -Rs …, or
brew uninstall …). The command only names packages that look like your own
choices: on apt, those that a sudo apt command in the retained apt logs
installed on request (dependencies are skipped). Kernel, boot loader, firmware,
driver, and Canonical-published snap packages are listed in a notice of their
own, without a command. Nothing is removed for you. For each package you can
remove it, declare it in the bootstrap's *_functions file, or accept it by
listing manager:name in ~/.config/dotfiles/known-extra-packages (one per
line, # comments allowed; the file is per machine and not in this
repository). python3 .local/scripts/audit_installation.py --list-extra prints
the current list in that format, so appending its output to that file accepts
everything listed at once. Long lists wrap to the width of the terminal.
An app that came with its own installer (an AppImage, Zed, GPT4All) is in no
package manager's database, so that check cannot see it. The audit reads the
launchers in ~/.local/share/applications instead and lists, as one [NOTICE],
every launcher that starts a program from your home folder and that the selected
bootstrap does not declare. A launcher counts as declared when an active line of
the bootstrap names its file. Nothing is removed for you, and a Fix: command
appears under an app only when the place of its program proves what belongs to
it: an AppImage, a folder of its own in ~/.local/opt, ~/.opt, ~/opt or
~/Applications, a *.app folder in ~/.local (Zed), or the folder of a Qt
installer (GPT4All, which keeps a maintenancetool there). The command is
rm -rI -- …, so it asks once before it deletes; it removes the app, the links
to it in ~/.local/bin and ~/bin, and its launchers and desktop shortcuts,
and never its settings or data. Under any other app there is no command: use
its own uninstaller, or delete it yourself. To keep one, list app:NAME (the
launcher's file name without .desktop, as the notice shows it) in the same
~/.config/dotfiles/known-extra-packages file; --list-extra prints the apps in
that format too. An app that leaves no launcher is not seen.
On the ubuntu and work profiles, Cursor and Antigravity (and VS Code on
work) update through apt. A release upgrade disables third-party apt sources,
after which the weekly full-upgrade skips them silently; the audit reports that
as drift for each installed IDE package. make repair REPAIR=ide-repos
re-enables the sources and refreshes the package lists, and DRY_RUN=true
previews its sudo commands first. See
IDE update channels.
The work and ubuntu bootstraps also install asusctl (ASUS Linux's daemon
for platform profiles, fan curves, and the battery charge limit), but only on a
supported ASUS laptop; other machines skip it. They then set the keyboard
backlight to a rainbow when the keyboard supports it. make repair REPAIR=asusctl
and make repair REPAIR=asusctl-lighting repeat the two steps and DRY_RUN=true
previews them. See asusctl.
The work bootstrap also installs the NVIDIA Container Toolkit (GPU access for
containers) from NVIDIA's apt repository, but only on a machine with an NVIDIA
GPU; other machines skip it. It installs the package only, so run
sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker
yourself to give Docker the NVIDIA runtime. make repair REPAIR=nvidia-container-toolkit
repeats the step, which also re-enables its apt source after a release upgrade,
and DRY_RUN=true previews its sudo commands. See
NVIDIA Container Toolkit.
The ubuntu and work bootstraps also install
OpenLogi, a Linux alternative to Logitech
Options+ for Bolt and Unifying receivers. It has no apt repository, so the step
downloads the signed .deb from GitHub and checks its signature before sudo
lets apt open it; a failure only warns. Replug the receiver after the first install,
and stop Solaar first if you used it, because only one program can own a receiver.
OPENLOGI_VERSION=0.8.11 pins a release. See OpenLogi.
The ubuntu and work bootstraps install the video editors OpenShot (the official
snap, which is newer than Ubuntu's package and avoids the PPA's dependency stack) and
Blender (its classic snap), and also try the free DaVinci Resolve on a machine with an
NVIDIA GPU. Blackmagic offers the Resolve download only behind a registration form, so
download DaVinci_Resolve_<version>_Linux.zip into ~/Downloads once and run
make repair REPAIR=davinci-resolve (DRY_RUN=true previews it); until then the
bootstrap only warns. See
Video editing.
Configuration import is preview-first. make config-import shows the Stow
--adopt operations; make config-import APPLY=1 performs them and then shows
the changed source files. Review git diff before committing. Use
make config-status for deployment drift and make config-diff for content
differences between tracked files and existing $HOME targets.
Some tracked files (e.g. user_preferences.json for Warp, vlc-qt-interface.conf for VLC) are rewritten by their apps on every launch. They are kept in the repo so default settings are versioned, but the constant runtime changes make git status noisy and block git pull.
These files are automatically masked with git update-index --skip-worktree when cloning via clone-all or when running make install / make restow / OS bootstrap. No manual setup step is required.
When you intentionally want to update one of them in the repo:
git update-index --no-skip-worktree .config/warp-terminal/user_preferences.json
# edit / copy the new settings you want to keep
git add .config/warp-terminal/user_preferences.json
git commit -m "update warp settings"
.local/scripts/apply-skip-worktree # re-applyOS-specific bootstrap scripts live in .local/scripts/bootstrap/.
Read the script for your OS before running it — they install hundreds
of packages and change system settings.
make bootstrap-arch # Arch
make bootstrap-manjaro # Manjaro
make bootstrap-ubuntu # Ubuntu
make bootstrap-mac # macOS
make bootstrap-work # Work machine (Ubuntu + NVIDIA workstation)Bootstrap targets are deterministic and noninteractive by default. They derive
machine-specific setup from current state: systemd converges service state,
missing group memberships are added, and laptop configuration runs only when
laptop-detect identifies a laptop. High-DPI changes remain opt-in; use
make bootstrap-unattended PROFILE=<os> HIGH_DPI=yes when intended. Pass
BOOTSTRAP_ARGS= to restore interactive prompts for a direct bootstrap-<os>
target. Before a work bootstrap, run sudo -v in the same terminal. The work
entrypoint verifies cached credentials and keeps its direct sudo calls
noninteractive instead of waiting for a password prompt.
Each bootstrap target also ensures the private cuberhaus/cuberhaus-workspace
sibling exists. Authenticate gh before a first run; the target clones the
repository, restores its pinned skills without prompting, and then syncs the
workspace files. Existing checkouts are reused, and an interrupted initial
skill restore is retried on the next run. Set RESTORE_WORKSPACE_SKILLS=0 only
when the generated skill payloads must be skipped.
App-data restores are guarded and preview-first:
make restore-app APP=thunderbird # rclone dry run
make restore-app APP=thunderbird APPLY=1 # perform restore
make bootstrap-ubuntu RESTORE_APPS="thunderbird calibre anki" RESTORE_APPLY=1The restore verifies that rclone and its drive: remote work, the target app
is installed and closed, and the remote directory exists before copying.
For a machine that boots both Windows and physical Linux, opt in to a UTC hardware clock during bootstrap:
make bootstrap-ubuntu BOOTSTRAP_ARGS=--dual-boot-utc
# Also supported: bootstrap-arch, bootstrap-manjaro, and bootstrap-workFor an existing physical Linux installation, run:
make dual-boot-utcThe helper rejects WSL and non-systemd systems. It enables network time, waits
for NTPSynchronized=yes, then runs timedatectl set-local-rtc 0 and verifies
LocalRTC=no. It refuses to change the RTC if synchronization cannot be
established. Configure Windows with WinDotfiles' -DualBootUtcRtc option as
well; changing only one operating system leaves the original disagreement in
place.
Verify with timedatectl: it should report System clock synchronized: yes,
NTP service: active, and RTC in local TZ: no. Do not use
timedatectl set-local-rtc 1 as a permanent workaround because local RTC is
fragile across DST and timezone changes. The option is intentionally not
forwarded to the WSL or macOS bootstrap targets.
Each bootstrap entrypoint follows the same pattern:
- Sources
base_functions(shared logging helpers and$DOTFILESauto-detection). - Sources the OS-specific
*_functionsfile (package lists and installer functions). - Runs a system update.
- Calls installer functions in dependency order (base packages, WM-specific, optional apps).
- Converges service, group, and hardware-specific state where applicable.
- Switches the default shell to zsh.
- Installs the native automation schedules shown below.
The physical Linux bootstraps (ubuntu, arch, manjaro, and work) raise
fs.inotify.max_user_watches to 524288. Editors, Obsidian, and file syncers
share one per-user pool of file watches, and some distributions cap it low:
Ubuntu's localsearch package ships 65536. When the pool is exhausted Obsidian
fails to open with ENOSPC: System limit for number of file watchers reached.
The step persists the value in /etc/sysctl.d/99-inotify.conf, whose 99-
prefix sorts after the distro defaults, and applies it to the running kernel. It
is idempotent, never lowers a limit that is already higher, and only warns if the
live write fails. Set INOTIFY_MAX_USER_WATCHES=<n> to choose another value.
The WSL and macOS bootstraps skip it.
To apply it to an existing machine without re-running the bootstrap:
bash -c 'source .local/scripts/bootstrap/base_functions; configure_inotify_watches'Verify with cat /proc/sys/fs/inotify/max_user_watches. To undo it, remove
/etc/sysctl.d/99-inotify.conf and run sudo sysctl --system.
After changing .doom.d/config.el, run doom sync, then
restart Doom Emacs (or evaluate the changed form). In an Org buffer with a
soft-wrapped paragraph, g j and g k in Evil normal state move by displayed
screen lines; a count such as 3 g j moves three displayed lines. Confirm that
the same keys retain their ordinary Evil behavior in a non-Org buffer.
The bootstrap installs these automations without requiring a separate command:
| Automation | Linux | macOS |
|---|---|---|
~/cuberhaus pull |
Daily 11:00 via user systemd |
Daily 11:00 via launchd |
| Desktop shortcut cleanup | Daily 10:45 via user systemd |
Not installed |
Package upgrades are deliberately not scheduled, because an unattended upgrade
can break the machine. Run them by hand with update (the operating system's
packages) or updateall (also npm, pip, Emacs and the shell and editor
plugins); -n previews either one. make install-automations removes the
weekly package jobs that older versions installed, and make audit-installation
reports one that is still enabled.
The workspace pull matches the shell helper's depth-3 discovery but uses
git pull --ff-only --no-edit with credential prompts disabled. Repositories
without upstreams are skipped; diverged or unauthenticated repositories are
left unchanged and reported.
On Linux, Persistent=true runs a missed timer when the machine becomes
available. On macOS, the agent runs at login as well as on schedule, with a
20-hour state guard preventing duplicate pulls. WSL deliberately installs no
duplicate timers because Windows Task Scheduler owns the same automations.
The shortcut cleanup moves loose .desktop and .url launchers from the Desktop
into Desktop/Shortcuts. It accepts --dry-run.
On Linux, the scheduled jobs report through the desktop notification service
(gdbus, with notify-send as a fallback). A progress bar appears only once a
run has lasted ten seconds, with one step per repository or folder.
When the run ends, a summary appears if something changed or went wrong. A run
that had nothing to do shows nothing and closes any bar it had opened, so a
healthy day is silent. A failed run ends with a warning or error summary that
names what failed; the journal keeps the details. Where the desktop supports
notification actions, the summaries are clickable: a failed workspace pull
opens a terminal in the first failed repository with git status showing why
the pull failed, and the shortcut cleanup opens the Shortcuts folder. The
systemd services pass --notify; run a script by hand with --notify to see
the same output. macOS and WSL show no notifications. See
docs/agents/automation-notifications.md.
For an existing checkout, restow the new files and install the schedules:
make restow
make install-automationsPreview or remove scheduler registrations without deleting logs or state:
make uninstall-automations-dry-run
make uninstall-automationsmake uninstall removes scheduler registrations before unstowing the files, so
no active job is left pointing at a removed script.
Inspect the schedules and logs:
# Linux
systemctl --user list-timers 'cuberhaus-*'
journalctl --user -u cuberhaus-workspace-pull.service
journalctl --user -u cuberhaus-desktop-shortcut-cleanup.service
# macOS
launchctl print "gui/$UID/com.cuberhaus.workspace-pull"
tail -f "$HOME/Library/Logs/Cuberhaus/workspace-pull.log"The portable wrappers are make maintenance-status,
make maintenance-logs LINES=100, and make maintenance-digest.
See .local/README.md for a detailed breakdown of the
scripts directory.
| Category | Tool / Config | Notes |
|---|---|---|
| Shells | zsh (antigen, p10k), bash (git-aware prompt) | XDG-compliant $ZDOTDIR in .config/zsh/ |
| Editors | Vim, Neovim, Doom Emacs, personal Emacs (chemacs) | Vim config at .vim/vimrc; Emacs literate config in .config/emacs.org |
| Terminals | kitty, Alacritty, termite | |
| Window Managers | XMonad (+xmobar), i3 (+i3blocks +polybar), qtile, sway | XMonad is the primary config; i3 is the secondary |
| Desktop Environments | Cinnamon, GNOME | |
| Utilities | tmux, ranger, dunst, picom, rofi, fzf, bat, eza | |
| Themes | Arc, Dracula, OneDark, base16 | Managed via toggle_theme script |
- Xmonad (Main config)
- i3 (Second best)
- Cinnamon desktop
- Gnome
Gentoo (experimental bootstrap, never run on a real machine)- Openbox