Frequently Asked Questions

General Questions

Why use GNU Stow for managing dotfiles?

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)

What is the 12-factor design approach mentioned in the configs?

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

Can I use parts of this config without installing everything?

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

How do I switch between laptop and desktop configs?

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:

Setting	Desktop	Laptop
Primary Monitor	eDP-1	eDP-1
Secondary Monitor	HDMI-A-2	Disabled
Gaps (inner)	0px	4px
Gaps (outer)	0px	5px
Border Color	Blue gradient	Cyan/Green gradient
Display Module	displays.conf	displays-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

How do I customize the Catppuccin theme colors?

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:

Update tmux theme plugin
Modify Hyprland color variables
Replace waybar CSS
Update rofi theme path

Where are application logs located?

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'

How do I reload configurations without logging out?

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

How do I keep my configs updated with upstream changes?

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

What dependencies need to be installed?

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

How do I uninstall or remove these configs?

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

How do I add custom keybindings to Hyprland?

Keybindings are defined in ~/.config/hypr/modules/keybindings.conf.To add custom bindings without modifying the base file:

Create a local keybindings file:

touch ~/.config/hypr/modules/keybindings-local.conf

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

Source it in hyprland.conf:

# At the end of your imports section
source = modules/keybindings-local.conf

Reload Hyprland: Super + Shift + R

View all current bindings:

hyprctl binds

Can I use this config on multiple machines with different hardware?

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

How do I debug Waybar module scripts?

Waybar includes custom scripts that may need debugging:Scripts in config:

~/.config/waybar/toggle_temp.sh
~/.config/waybar/cycle-power-profile.sh

Debugging Steps:

Make scripts executable:

chmod +x ~/.config/waybar/*.sh

Test script directly:

bash -x ~/.config/waybar/cycle-power-profile.sh

Check script dependencies:

# For power profile script
which powerprofilesctl
powerprofilesctl list

View waybar output:

# Kill waybar and run in foreground
killall waybar
waybar 2>&1 | tee ~/waybar-debug.log

Validate JSON config:

# Check for syntax errors
jsonlint ~/.config/waybar/config.jsonc

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:

Check the Common Issues page
Review configuration files in ~/.config/ for inline comments
Consult application-specific documentation:
Check the source repository README for updates
Review git commit history for context on specific changes

Get Started

Configuration

Platform Guides

Customization

Troubleshooting

Frequently Asked Questions

General Questions

Configuration Questions

Installation & Updates

Advanced Questions

Still Have Questions?

Build docs developers (and LLMs) love

Get Started

Configuration

Platform Guides

Customization

Troubleshooting

Documentation Index

​General Questions

​Configuration Questions

​Installation & Updates

​Advanced Questions

​Still Have Questions?

Build docs developers (and LLMs) love

General Questions

Configuration Questions

Installation & Updates

Advanced Questions

Still Have Questions?