Skip to main content

​
General Questions

GNU Stow is used because it creates symbolic links from a centralized dotfiles repository to your home directory, making it easy to:
  • Version control: All configs in one git repository
  • Easy deployment: Single command to install all configs
  • Selective installation: Choose which configs to install
  • Safe updates: Changes are immediately reflected without copying
Configuration (from .stowrc):
--target=~        # Install symlinks to home directory
--ignore=.stowrc  # Don't symlink the stow config itself
--dotfiles        # Convert 'dot-' prefix to '.'
--verbose=1       # Show what's being done
The --dotfiles flag is particularly useful because it allows files like dot-config/ in the repository to become .config/ in your home directory, making them visible in git without being hidden.Example:
  • Repository: dot-config/hypr/hyprland.conf
  • Home directory: ~/.config/hypr/hyprland.conf (symlinked)
The 12-factor approach (from 12factor.net) is a methodology for building maintainable applications. In the context of these dotfiles:Separation of Configuration and Code:
  • Base configurations are tracked in git
  • Environment-specific settings go in local files (not tracked)
  • Local files are automatically loaded if they exist
Example from tmux.conf:127:
# Load local configuration if it exists (Config factor)
if-shell "[ -f ~/.config/tmux/tmux.local.conf ]" 'source ~/.config/tmux/tmux.local.conf'
Benefits:
  • Same base config works on multiple machines
  • Machine-specific tweaks in local files
  • Base config stays clean and portable
  • No risk of committing sensitive local settings
Recommended practice:
  • Keep shared settings in tracked files
  • Put machine-specific settings in .local.conf files
  • Add .local.conf to .gitignore
Yes! The configuration is modular and can be used selectively.Option 1: Selective Stow Instead of installing all dotfiles, stow specific directories:
# Only install tmux config
stow dot-config/tmux

# Only install hypr config
stow dot-config/hypr
Option 2: Copy Individual Files Copy specific config files you want:
cp -r dot-config/tmux ~/.config/
Option 3: Use as Reference Browse the repository and copy snippets to your existing configs:
  • Tmux keybindings from tmux.conf
  • Hyprland animations from modules/look.conf
  • Waybar modules from waybar/config.jsonc
Modular Structure: Each application’s config is independent:
  • dot-config/tmux/ - Complete tmux setup
  • dot-config/hypr/ - Hyprland window manager
  • dot-config/waybar/ - Status bar
  • dot-config/rofi/ - Application launcher
Dependencies between configs are minimal, making it easy to pick what you need.

​
Configuration Questions

The repository includes separate configuration files for laptop and desktop setups.Current Setup:
  • Desktop config: ~/.config/hypr/hyprland.conf
  • Laptop config: ~/.config/hypr/modules/hyprland-laptop.conf
Key Differences:
SettingDesktopLaptop
Primary MonitoreDP-1eDP-1
Secondary MonitorHDMI-A-2Disabled
Gaps (inner)0px4px
Gaps (outer)0px5px
Border ColorBlue gradientCyan/Green gradient
Display Moduledisplays.confdisplays-laptop.conf
Method 1: Symlink Switching (Recommended)
# Switch to laptop config
cd ~/.config/hypr
mv hyprland.conf hyprland-desktop.conf
ln -s modules/hyprland-laptop.conf hyprland.conf

# Switch back to desktop
rm hyprland.conf
mv hyprland-desktop.conf hyprland.conf
Method 2: Environment-Based Create a script in your shell profile:
# In ~/.bashrc or ~/.zshrc
if [ -f /sys/class/power_supply/BAT0 ]; then
    # Laptop detected
    export HYPR_CONFIG="laptop"
else
    # Desktop
    export HYPR_CONFIG="desktop"
fi
Method 3: Local Override Keep the base config and override specific settings in a local file sourced at the end.After switching, reload Hyprland: Super + Shift + R
The configuration uses Catppuccin Mocha theme across multiple applications.Tmux (tmux.conf:51):
set -g @catppuccin_flavour 'mocha'
Available flavours: latte, frappe, macchiato, mochaHyprland Border Colors: Edit variables in hyprland.conf:
# Desktop (line 17)
$active_border_color = rgba(89b4faff) rgba(89dcebee) 90deg

# Laptop (line 17)
$active_border_color = rgba(33ccffee) rgba(00ff99ee) 180deg
Waybar: Catppuccin colors are defined in waybar/style.css. Modify CSS variables:
@define-color base   #1e1e2e;
@define-color mantle #181825;
@define-color crust  #11111b;
Custom Theme: To use a completely different theme:
  1. Update tmux theme plugin
  2. Modify Hyprland color variables
  3. Replace waybar CSS
  4. Update rofi theme path
Different applications store logs in different locations:Hyprland:
# Current session log
cat /tmp/hypr/$(ls -t /tmp/hypr/ | head -1)/hyprland.log

# List all session logs
ls -lt /tmp/hypr/
Waybar:
# If run as systemd service
journalctl --user -u waybar -f

# If run manually, check stdout/stderr
waybar 2>&1 | tee ~/waybar.log
Tmux: Tmux doesn’t have separate logs, but plugin errors appear in tmux status:
# Check tpm installation
ls ~/.config/tmux/plugins/tpm
System logs:
# General system log
journalctl -xe

# User session logs
journalctl --user -xe

# Display manager logs (GDM/SDDM)
journalctl -u gdm -f
X11/Wayland session logs:
# Wayland session
cat ~/.local/share/wayland-sessions/

# Check environment
echo $XDG_SESSION_TYPE  # Should show 'wayland'
Most configurations can be reloaded without a full logout:Hyprland:
# Reload config
hyprctl reload

# Or use keybind
Super + Shift + R

# Restart Hyprland (preserves session)
hyprctl dispatch exit
Waybar:
# Hard reload (recommended for config changes)
killall waybar && waybar &

# Soft reload (style changes only)
killall -SIGUSR2 waybar

# Using just command
cd ~/.config/waybar && just reload
Tmux:
# From outside tmux
tmux source ~/.config/tmux/tmux.conf

# From inside tmux
# Press: Ctrl+Space then type:
:source ~/.config/tmux/tmux.conf

# Reload all tmux sessions
tmux list-sessions -F '#{session_name}' | xargs -I {} tmux send-keys -t {} 'tmux source ~/.config/tmux/tmux.conf' Enter
Environment Variables:
# Source shell config
source ~/.bashrc  # or ~/.zshrc

# For Hyprland env vars, reload is needed
hyprctl reload
When Full Logout is Required:
  • Display manager configuration changes
  • Systemd user service modifications
  • Major Hyprland structural changes
  • Graphics driver updates

​
Installation & Updates

If you forked or cloned this repository, you can pull updates:Method 1: Direct Pull (if you haven’t made changes)
cd ~/dotfiles  # or wherever you cloned it
git pull origin main
Method 2: Merge Upstream (if you’ve customized)
# Add upstream remote (once)
git remote add upstream https://github.com/shawal-mbalire/dotfiles

# Fetch and merge updates
git fetch upstream
git merge upstream/main

# Resolve any conflicts with your customizations
Method 3: Cherry-pick Specific Changes
# View upstream commits
git fetch upstream
git log upstream/main

# Cherry-pick specific commits
git cherry-pick <commit-hash>
Best Practice:
  • Keep your customizations in .local.conf files
  • Document your changes in a separate file
  • Use git branches for experimental changes
  • Review changes before merging: git diff upstream/main
The configuration has several dependencies organized by component:Core (Required for Hyprland):
# Arch
yay -S hyprland-git wofi drun waybar

# Fedora
sudo dnf install hyprland waybar wofi
Fonts (Required for proper rendering):
# Fedora
sudo dnf copr enable zawertun/hack-fonts
sudo dnf install hack-fonts jetbrains-mono-fonts
Waybar Dependencies:
sudo dnf install waybar jetbrains-mono-fonts sono-fonts pavucontrol brightnessctl
Optional but Recommended:
sudo dnf install hyprshot foot network-manager-applet power-profiles-daemon
Authentication:
sudo dnf install hyprpolkitagent
Tmux:
# Tmux itself
sudo dnf install tmux

# Plugin manager (manual)
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
Clipboard Manager:
# Arch
yay -S cliphist

# Or build from source
go install go.senan.xyz/cliphist@latest
Quick Install (Fedora): Use the waybar Justfile:
cd ~/.config/waybar
just install        # Core dependencies
just install-extra  # Optional dependencies
Since the configs are symlinked with GNU Stow, removal is clean:Method 1: Using Stow (Recommended)
cd ~/dotfiles  # Your dotfiles repository
stow -D .      # Remove all symlinks
Method 2: Remove Specific Configs
# Remove only hypr config
stow -D dot-config/hypr

# Remove only tmux config
stow -D dot-config/tmux
Method 3: Manual Removal Since they’re symlinks, you can just delete them:
rm ~/.config/hypr
rm ~/.config/tmux
rm ~/.config/waybar
# etc.
Verify Removal:
# Check if symlinks are gone
ls -la ~/.config/hypr

# Should show: No such file or directory
Clean Up:
# Remove plugin directories
rm -rf ~/.config/tmux/plugins

# Remove dotfiles repository
rm -rf ~/dotfiles
Note: Your original configs (if backed up) can be restored:
mv ~/.config/hypr.backup ~/.config/hypr

​
Advanced Questions

Keybindings are defined in ~/.config/hypr/modules/keybindings.conf.To add custom bindings without modifying the base file:
  1. Create a local keybindings file:
touch ~/.config/hypr/modules/keybindings-local.conf
  1. Add your custom bindings:
# Example custom keybindings
bind = $mainMod, T, exec, thunar
bind = $mainMod SHIFT, S, exec, hyprshot -m region
bind = $mainMod, V, exec, cliphist list | wofi -dmenu | cliphist decode | wl-copy
  1. Source it in hyprland.conf:
# At the end of your imports section
source = modules/keybindings-local.conf
  1. Reload Hyprland: Super + Shift + R
View all current bindings:
hyprctl binds
Yes! The configuration is designed to be portable:1. Use the laptop/desktop variants:
  • Symlink the appropriate config file for each machine
  • See “How do I switch between laptop and desktop configs?” above
2. Create machine-specific local configs:
# On machine 1
echo 'source = ~/.config/hypr/machine1.conf' >> ~/.config/hypr/hyprland.conf

# On machine 2
echo 'source = ~/.config/hypr/machine2.conf' >> ~/.config/hypr/hyprland.conf
3. Use hostname-based loading: Add to your hyprland.conf:
exec-once = [ -f ~/.config/hypr/$(hostname).conf ] && source ~/.config/hypr/$(hostname).conf
4. Git branch per machine:
# Create machine-specific branch
git checkout -b machine1

# Make machine-specific changes
# Merge updates from main when needed
git merge main
Environment Variables: The config already separates hardware-agnostic settings (animations, keybindings) from hardware-specific ones (monitors, input devices).
Waybar includes custom scripts that may need debugging:Scripts in config:
  • ~/.config/waybar/toggle_temp.sh
  • ~/.config/waybar/cycle-power-profile.sh
Debugging Steps:
  1. Make scripts executable:
chmod +x ~/.config/waybar/*.sh
  1. Test script directly:
bash -x ~/.config/waybar/cycle-power-profile.sh
  1. Check script dependencies:
# For power profile script
which powerprofilesctl
powerprofilesctl list
  1. View waybar output:
# Kill waybar and run in foreground
killall waybar
waybar 2>&1 | tee ~/waybar-debug.log
  1. Validate JSON config:
# Check for syntax errors
jsonlint ~/.config/waybar/config.jsonc
  1. Test module in isolation: Create a minimal config with just one module to test.
Common Issues:
  • Missing shebangs (#!/bin/bash)
  • Wrong permissions
  • Missing dependencies (check script commands)
  • Incorrect output format (waybar expects specific JSON/text)

​
Still Have Questions?

If your question isn’t answered here:
  1. Check the Common Issues page
  2. Review configuration files in ~/.config/ for inline comments
  3. Consult application-specific documentation:
  4. Check the source repository README for updates
  5. Review git commit history for context on specific changes

Build docs developers (and LLMs) love

Get started for freeTalk to us