dotfiles/README.md

Arch Linux Dotfiles & Hyprland Setup

This repository manages your personal dotfiles and a modular, Wayland-ready desktop environment for Arch Linux using paru.

---

Features

• Modular setup: each aspect (packages, symlinks, shell, Neovim, Hyprland, sound, browsers, devtools, etc.) is handled by its own script in modules/.
• All dotfiles and app configs are version-controlled and symlinked to your home directory.
• Device-aware: uses $DOTFILES_DEVICE and $HOSTNAME to select device-specific config fragments (e.g., laptop/desktop, monitor layouts).
• Out-of-the-box integration for Hyprland, Waybar, Rofi, Mako, Alacritty, wlogout, and more.
• Modern sound stack (PipeWire, WirePlumber, pavucontrol, etc.).
• Volume notifications: see current volume as a Mako popup at the bottom center when changed.
• Multi-monitor workspace rules: workspace 1 always on laptop, others on external (DP-1) if connected; all on laptop if standalone.
• Brave browser always launches on workspace 10 and autostarts with Hyprland.
• TTY/console uses German nodeadkeys layout (de-latin1-nodeadkeys).
• Devtools module installs git, Python, Node.js, Docker, VS Code, opencode-bin, and more.
• Easily extensible: add new modules, fragments, or configs as needed.

---

Setup

1. Clone this repository:

   git clone https://github.com/yourusername/dotfiles.git ~/git/dotfiles
   cd ~/git/dotfiles
   

2. Run the setup script:

   ./setup.sh
   

When you run setup.sh, your device profile is detected via host-profiles.conf (mapping $HOSTNAME to $DOTFILES_DEVICE, e.g., laptop or desktop). This ensures that device-specific configs (battery, backlight, touchpad, monitor layout, etc.) are applied correctly for your hardware. You can also set the environment variable manually to override:

DOTFILES_DEVICE=desktop ./setup.sh

The script will install all required packages and symlink dotfiles and configs (including everything in .config/) to your home directory, using the correct device-specific fragments for Hyprland, Waybar, and more.

---

Customization & Extending

• Add new dotfiles to the repo root (e.g., .zshrc, .tmux.conf).
• Place app configs in .config/ (e.g., .config/hypr/hyprland.conf).
• Add or edit modules in the modules/ directory to automate more setup steps.
• To add custom scripts, place them in .local/bin/ in the repo; they will be symlinked to ~/.local/bin/.
• To add browsers, edit modules/06-browsers.sh (Chrome, Firefox, Brave supported out of the box).
• To add devtools, edit modules/50-devtools.sh (includes VS Code, opencode-bin, lazygit, etc.).
• To add new device types (e.g., tablet, server), update host-profiles.conf and add corresponding config fragments (e.g., hypridle-tablet.conf).
• To add new fragment types, extend the fragment_types array in modules/02-symlinks.sh.

---

Requirements

• Arch Linux
• paru (will be installed automatically if missing)
• For TTY keymap: kbd package (should be present on most systems)

---

Quick Reference: Main Modules

Module	Purpose
01-packages.sh	Base packages (shell, tools, etc.)
02-symlinks.sh	Symlinks dotfiles/configs, device-aware
03-shell.sh	Shell setup (Zsh, keymap)
04-nvim.sh	Neovim (AstroNvim) setup
05-sound.sh	Sound stack (PipeWire, etc.)
06-hyprland.sh	Hyprland, Waybar, Rofi, etc.
07-browsers.sh	Browsers (Chrome, Firefox, Brave)
50-devtools.sh	Devtools (git, VS Code, etc.)
99-postinstall.sh	Post-install steps

---

Troubleshooting

• Missing device-specific fragment: If you see a warning about a missing fragment (e.g., hypridle-laptop.conf), create the file in .config/hypr/includes/ or update your host-profiles.conf mapping.
• Symlink warnings: If a non-empty directory exists where a symlink should be, the script will warn and skip removal for safety. Manually back up and remove if needed.
• Package install errors: Ensure your Arch system is up to date and AUR is reachable. Rerun setup.sh after fixing network or package issues.
• Updating dotfiles: Pull the latest changes and re-run ./setup.sh to sync configs and packages.

---

Safety & Idempotence

• All scripts are safe to re-run and will not overwrite user files unintentionally.
• Symlinking logic only removes symlinks or empty directories; non-empty directories are preserved with a warning.

---

Notable Integrations & Tips

• Browsers: Chrome, Firefox, and Brave are installed via the browser module. Brave autostarts and is always on workspace 10.
• Devtools: Includes VS Code (visual-studio-code-bin), opencode-bin, lazygit, and more.
• Volume OSD: Volume changes show a notification at the bottom center of the screen (Mako).
• Multi-monitor: Workspace 1 is always on the laptop display, others on DP-1 if connected.
• TTY Keymap: Console uses German nodeadkeys layout for all users (system-wide via localectl).
• No official Teams/Outlook client: Use the web app or AUR wrappers for best compatibility.
• TortoiseGit alternative: Use GitKraken, Sublime Merge, SmartGit, or lazygit for graphical Git workflows.

---

License

MIT