Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shawal-mbalire/dotfiles/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation methods

Choose between a one-command quick install or manual installation for more control.
Before installing, ensure you have reviewed the system requirements for your distribution.

​
Quick install

The fastest way to get started is with the automated install script: 
curl -fsSL https://raw.githubusercontent.com/shawal-mbalire/dotfiles/main/install.sh | bash
This script will:
  • Clone the repository
  • Use rsync to copy configurations to your home directory
  • Preserve existing files (use with caution)
The quick install will copy files directly to your home directory. Back up any existing configurations before proceeding.

​
Manual installation

For more control over the installation process, follow these steps:
1

Clone the repository

git clone https://github.com/shawal-mbalire/dotfiles
cd dotfiles
2

Review the .stowrc configuration

The repository uses GNU Stow with these settings:
--target=~
--ignore=.stowrc
--dotfiles
--verbose=1
This configuration:
  • Targets your home directory (~)
  • Ignores the .stowrc file itself
  • Automatically renames dot- prefixes to .
  • Shows verbose output
3

Install with GNU Stow (recommended)

If you have GNU Stow installed, you can selectively install components:
# Install all configurations
stow .

# Or install specific components
stow dot-config/hypr
stow dot-config/fish
stow dot-config/waybar
GNU Stow creates symlinks, making it easy to update configurations by pulling git changes.
4

Alternative: Use rsync

If you prefer to copy files instead of symlinking:
rsync -avhu --progress dotfiles/ ~/
The flags mean:
  • -a: Archive mode (preserves permissions, timestamps)
  • -v: Verbose output
  • -h: Human-readable file sizes
  • -u: Update only (skip newer files)
  • --progress: Show transfer progress

​
Platform-specific installation

​
Fedora

For Fedora users, follow these comprehensive setup steps:
1

Authenticate with GitHub

gh auth login
2

Clone and setup the repository

gh repo clone shawal-mbalire/dotfiles
cp -r dotfiles/.git/ .git/
git pull
rm -rf dotfiles
3

Install core dependencies

sudo dnf install lua lua-devel luarocks go lua5.1
sudo dnf install hyprland hyprland-devel hyprlock hypridle hyprpolkitagent hyprpaper
sudo dnf install fish kitty rofi blueman pavucontrol waybar gh google-chrome nm-applet flatpak
sudo dnf install exa gammastep
4

Set Fish as default shell

echo /usr/bin/fish | sudo tee -a /etc/shells
chsh -s /usr/bin/fish
5

Optional: Remove GNOME

If you want a minimal Hyprland-only setup:
sudo dnf install hyprland sddm
sudo dnf remove gnome-shell --setopt protected_packages=
sudo dnf install nautilus  # Keep file manager
This removes GNOME entirely. Make sure Hyprland is working before removing your current desktop environment.

​
Arch Linux

For Arch-based distributions:
1

Install Hyprland and core tools

yay -Syyu hyprland-git wofi drun
2

Install Nerd Fonts

yay -S ttf-hack-nerd
3

Clone and install dotfiles

git clone https://github.com/shawal-mbalire/dotfiles
cd dotfiles
stow .  # Or use rsync method

​
Post-installation setup

After installing the dotfiles, complete these additional configuration steps:
1

Install Nerd Fonts

Required for proper icon display in Waybar and terminal.
sudo dnf copr enable zawertun/hack-fonts
sudo dnf install hack-fonts
2

Install tmux plugin manager

Required for tmux configuration:
git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm
Then open tmux and press Prefix + I to install plugins.
3

Set up Neovim

The configuration uses LazyVim. On first launch, plugins will auto-install:
nvim
Wait for Lazy to install all plugins.
4

Enable Hyprland polkit agent

For graphical authentication prompts:
sudo dnf copr enable solopasha/hypr
sudo dnf install hyprpolkitagent
systemctl --user enable --now hyprpolkitagent.service
Use systemctl --user without sudo for user services.
5

Verify Hyprland configuration

Before restarting Hyprland, verify the configuration is valid:
hyprland --config ~/.config/hypr/hyprland.conf --verify-config
6

Reload Hyprland

Apply the new configuration:
hyprctl reload
Or log out and log back in to Hyprland.

​
Optional applications

Install these applications based on your needs:

​
Snap packages

sudo snap install obsidian --classic
sudo snap install code-insiders --classic

​
Flatpak applications

flatpak install flathub app.zen_browser.zen
flatpak install flathub io.github.qurancompanion.QuranCompanion

​
Customization

The dotfiles are designed for easy customization:

​
Hyprland variables

Edit ~/.config/hypr/hyprland.conf to change core settings: 
# Change your terminal
$terminal = kitty  # or foot, alacritty, etc.

# Change your browser
$browser = flatpak run app.zen_browser.zen

# Adjust colors
$active_border_color = rgba(89b4faff) rgba(89dcebee) 90deg

# Modify gaps and rounding
$gaps_in = 5
$gaps_out = 10
$rounding = 8
After editing, reload Hyprland: 
hyprctl reload

​
Fish shell configuration

Edit ~/.config/fish/config.fish to customize your shell: 
# Change default editor
set -gx EDITOR /usr/bin/nvim

# Add custom abbreviations
abbr --add --global myabbr 'my command'

# Modify VI keybindings
fish_vi_key_bindings insert
Changes take effect in new shell sessions.

​
Waybar styling

Edit ~/.config/waybar/style.css to customize the status bar appearance. Reload Waybar: 
killall waybar && waybar &

​
Troubleshooting

Install Nerd Fonts (see post-installation step 1) and ensure your Waybar config references the correct font:
"font": "JetBrainsMono Nerd Font 10"
Check the configuration for syntax errors:
hyprland --config ~/.config/hypr/hyprland.conf --verify-config
Check logs:
cat /tmp/hypr/$(ls -t /tmp/hypr | head -n 1)/hyprland.log
Abbreviations are only available in interactive shells. Verify Fish is your login shell:
echo $SHELL
Should output /usr/bin/fish.
Ensure hyprpolkitagent is running:
systemctl --user status hyprpolkitagent.service
If not running:
systemctl --user enable --now hyprpolkitagent.service

​
Next steps

Hyprland configuration

Explore the modular Hyprland setup

Fish shell

Learn about Fish configuration and keybindings

Build docs developers (and LLMs) love

Get started for freeTalk to us