Dotfiles

This repo is my home base for my Arch Linux development environment dotfiles. I am using Stow to make sure I am version controlling only the files I want.

Quick Start

1. Clone this repository to your home directory:

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

2. Clone the theme-switcher (separate project):

   git clone https://github.com/StephenGunn/theme-switcher.git ~/projects/theme-switcher
   ln -sf ~/projects/theme-switcher/scripts/theme-switch ~/.local/bin/theme-switch

3. Install essential packages:

   # Install base packages
   ./scripts/install.sh
   
   # Install configuration files
   ./link.sh
   
   # Install Nerd Fonts
   ./scripts/install_nerd_fonts.sh
   
   # Restore systemd services
   ./scripts/restore_systemd_services.sh
   
   # Configure HyprPanel
   ./scripts/configure_hyprpanel.sh

Requirements

• Git
• Stow

Configurations Included

• Shells

  • fish (primary shell with plugins)
  • zsh (with oh-my-zsh)

• Terminal Emulators

  • alacritty
  • kitty
  • wezterm
  • ghostty

• Window Manager & UI

  • hyprland
  • waybar
  • hyprpanel (AGS-based desktop UI)

• Development Tools

  • neovim
  • tmux
  • git

• Utilities

  • rofi/wofi (application launchers)
  • fzf (fuzzy finder)
  • starship (prompt)
  • zoxide (smarter cd)
  • yazi (file manager)
  • thunar (GTK file manager - source of truth for bookmarks)
  • lazygit (git TUI)

Utility Scripts

The scripts/ directory contains several helpful scripts:

• install.sh - Installs packages from packages/core.md + packages/<hostname>.md
• config.sh - Sets up configuration for various tools
• configure_system_defaults.sh - Sets up XDG default applications (file manager, browser, editor)
• sync_bookmarks.sh - Syncs GTK bookmarks (Thunar) to Qt format (one-way)
• backup_systemd_services.sh - Backs up enabled systemd user services
• restore_systemd_services.sh - Restores systemd user services
• setup_systemd_backup_cron.sh - Sets up weekly automatic backups of systemd services
• install_nerd_fonts.sh - Installs Nerd Fonts needed for proper icons
• configure_hyprpanel.sh - Configures HyprPanel and sets up autostart

How to Use Stow

Stow is used to create symlinks from this repository to your home directory:

# Use the provided script (recommended)
./link.sh

# Or manually with stow
stow -t ~ .

Multi-Machine Support

This repo supports multiple machines (desktop, tablet, etc.) using hostname-based configs.

Adding a New Machine

1. Create host-specific Hyprland config:

   # Copy from existing host and modify
   cp .config/hypr/hosts/jovian.conf .config/hypr/hosts/<hostname>.conf
   # Edit monitors and workspaces for your hardware
   nvim .config/hypr/hosts/<hostname>.conf

2. Create host-specific packages (optional):

   # Only needed if machine needs different packages than core
   cp packages/jovian.md packages/<hostname>.md
   # Edit to add/remove packages
   nvim packages/<hostname>.md

3. Run setup on the new machine:

   ./scripts/install.sh   # Installs core.md + <hostname>.md
   ./link.sh              # Links dotfiles + creates hosts/current.conf

How It Works

• Hyprland: monitors.conf sources hosts/current.conf, which is symlinked to hosts/<hostname>.conf by link.sh
• Packages: install.sh reads packages/core.md (all machines) + packages/<hostname>.md (machine-specific)
• Single branch: No need for separate branches per machine

Current Hosts

Hostname	Description	Notes
jovian	Desktop	Dual monitors, gaming, heavy apps
surfarch	Surface Pro 8	Single high-DPI display, tablet

Structure

dotfiles/
├── .config/
│   ├── hypr/
│   │   ├── hosts/           # Machine-specific configs
│   │   │   ├── current.conf # Symlink to active host (gitignored)
│   │   │   ├── jovian.conf  # Desktop config
│   │   │   └── surfarch.conf # Tablet config
│   │   ├── monitors.conf    # Sources hosts/current.conf
│   │   ├── workspaces.conf  # (in host config)
│   │   └── ...              # Shared configs
│   ├── fish/
│   ├── nvim/
│   └── ...
├── packages/
│   ├── core.md              # Shared packages (all machines)
│   ├── jovian.md            # Desktop-specific packages
│   └── surfarch.md          # Tablet-specific packages
├── scripts/
│   ├── install.sh           # Reads packages/*.md based on hostname
│   └── ...
└── link.sh                  # Creates symlinks + hosts/current.conf

Maintaining the Repository

• To backup your current systemd services: ./scripts/backup_systemd_services.sh
• To set up automatic weekly backups: ./scripts/setup_systemd_backup_cron.sh
• To update package lists after installing new software: edit scripts/install.sh
• After making changes, commit and push to your repository

Theme Switcher Integration

This dotfiles repo integrates with a separate theme-switcher project for unified theming.

Setup

# Clone theme-switcher (separate git repo)
git clone https://github.com/StephenGunn/theme-switcher.git ~/projects/theme-switcher

# Create symlink for easy access
ln -sf ~/projects/theme-switcher/scripts/theme-switch ~/.local/bin/theme-switch

Usage

• Keybinding: Super + T - Opens theme selector
• Command: theme-switch - Opens theme selector
• Direct: theme-switch <theme-name> - Switch directly

Available Themes

1. Gruvbox Dark
2. Catppuccin Mocha
3. Nord
4. Kanagawa Dark
5. Everforest
6. Tokyo Night

What Gets Themed

• Ghostty (terminal) - Custom theme files
• Neovim (editor) - Native colorschemes (live reload)
• Hyprland (window manager) - Color scheme files
• HyprPanel (desktop panel) - Complete theme files
• Rofi (launcher) - .rasi theme files
• Thunar (file manager) - GTK themes
• Yazi (TUI file manager) - Flavor system
• Starship (prompt) - Pywal-generated colors
• Dunst (notifications) - Pywal-generated config
• Wallpapers - Random selection with smooth transitions (swww)

Adding New Themes

Each theme needs the following files in ~/projects/theme-switcher/themes/<theme-name>/:

• config.json - Theme configuration
• hyprpanel.json - HyprPanel colors (simplified 20-line or full 375-line format)
• colors.json - Pywal color palette (16 colors)
• <theme-name>.conf - Hyprland color definitions
• <theme-name>.rasi - Rofi theme
• wallpapers/ - Directory with wallpaper images
• Custom Ghostty theme in ~/.config/ghostty/themes/<ThemeName>

HyprPanel Theme Format:

• Simplified (20 keys): Basic colors, HyprPanel auto-fills the rest
• Complete (375 keys): Full control over every UI element
• Both work! Simplified is easier to maintain.

More Info

See the theme-switcher repository for documentation.

Bookmarks & File Dialogs

Source of Truth: Thunar (GTK Bookmarks)

• Primary file: ~/.config/gtk-3.0/bookmarks
• Sync direction: GTK → Qt (one-way, optional)
• Used by: Thunar, Firefox file dialogs, most Linux apps

Managing Bookmarks

1. In Thunar: Navigate to folder, press Ctrl+D
2. Edit directly: nvim ~/.config/gtk-3.0/bookmarks
3. Sync to Qt apps (optional): ./scripts/sync_bookmarks.sh

Bookmarks automatically appear in:

• ✅ Thunar sidebar
• ✅ Firefox/Zen save dialogs
• ✅ Most application file dialogs
• ✅ Any GTK file chooser

See BOOKMARKS_SYNC.md for detailed documentation.

Documentation

• SYSTEM_DEFAULTS.md - Default applications and XDG configuration
• BOOKMARKS_SYNC.md - How bookmarks work across programs
• GTK_BOOKMARKS.md - GTK bookmarks and file dialog configuration
• SETUP_COMPLETE.md - Recent setup summary and installation steps
• CLAUDE.md - Instructions for Claude Code when working with this repo

Links & References

• GNU Stow
• Managing dotfiles with stow
• Original Inspiration