Skip to content
cuberhausPublic

About

Personal Linux dotfiles for Arch, Manjaro, Ubuntu, and macOS — shell, editor, and tooling configs.

Topics

Resources

Security policy

Stars

6 stars

Watchers

2 watching

Forks

Latest commit

 

History

2,034 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Cuberhaus's dotfiles

Lint Markdown XMonad Vim

Table of Contents

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.

How it works

Why cuberhaus/dotfiles?

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.

Installation

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 install

On other operating systems, install stow before running make install:

  • Arch/Manjaro: sudo pacman -S stow
  • macOS: brew install stow

Usage

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.

Volatile config files

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-apply

Bootstrap

OS-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=1

The restore verifies that rclone and its drive: remote work, the target app is installed and closed, and the remote directory exists before copying.

Dual-boot hardware clock

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-work

For an existing physical Linux installation, run:

make dual-boot-utc

The 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:

  1. Sources base_functions (shared logging helpers and $DOTFILES auto-detection).
  2. Sources the OS-specific *_functions file (package lists and installer functions).
  3. Runs a system update.
  4. Calls installer functions in dependency order (base packages, WM-specific, optional apps).
  5. Converges service, group, and hardware-specific state where applicable.
  6. Switches the default shell to zsh.
  7. Installs the native automation schedules shown below.

inotify watch limit

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.

Doom Emacs Org visual-line movement

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.

Desktop notifications

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-automations

Preview or remove scheduler registrations without deleting logs or state:

make uninstall-automations-dry-run
make uninstall-automations

make 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.

What's inside

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

Supported OS

  • Arch Arch
  • Manjaro Manjaro
  • Ubuntu Ubuntu
  • macOS macOS

Window Managers

  • Xmonad (Main config)
  • i3 (Second best)
  • Cinnamon desktop
  • Gnome

WIP

About

Personal Linux dotfiles for Arch, Manjaro, Ubuntu, and macOS — shell, editor, and tooling configs.

Topics

Resources

Security policy

Stars

6 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages