dotfiles/INSTALL.md

Installation Guide

Complete installation guide for ADLee's Dotfiles on Arch Linux and CachyOS.

Table of Contents

• Requirements
• Quick Install
• Step-by-Step Installation
• Post-Installation
• Optional Tools
• Customization
• Updating
• Uninstalling
• Troubleshooting

---

Requirements

Operating System

• Arch Linux or CachyOS (other Arch-based distros may work but are untested)

Required Packages

These are installed automatically by install.sh:

Package	Purpose
git	Version control
curl	HTTP requests
zsh	Shell

Recommended Packages

Package	Purpose	Install
fzf	Fuzzy finder (command palette)	sudo pacman -S fzf
bat	Better cat with syntax highlighting	sudo pacman -S bat
eza	Modern ls replacement	sudo pacman -S eza
tmux	Terminal multiplexer	sudo pacman -S tmux
neovim	Modern vim	sudo pacman -S neovim

For Full Functionality

Package	Purpose	Install
age or gpg	Vault encryption	sudo pacman -S age
lastpass-cli	Password manager	paru -S lastpass-cli
snapper	Btrfs snapshots	sudo pacman -S snapper
limine-snapper-sync	Boot menu sync	paru -S limine-snapper-sync
compsize	Btrfs compression stats	sudo pacman -S compsize
gum	Interactive wizard	sudo pacman -S gum

---

Quick Install

One-Liner

git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles && cd ~/.dotfiles && ./install.sh

With Interactive Wizard

git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh --wizard

---

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

2. Review Configuration (Optional)

Edit dotfiles.conf before installing to customize:

vim dotfiles.conf

Key settings to review:

# Your identity
USER_FULLNAME="Your Name"
USER_EMAIL="you@example.com"
USER_GITHUB="yourusername"

# Feature toggles
INSTALL_FZF="ask"        # true, false, or ask
INSTALL_BAT="ask"
INSTALL_EZA="ask"
INSTALL_NEOVIM="ask"
SET_ZSH_DEFAULT="ask"

# MOTD style
MOTD_STYLE="compact"     # compact, mini, full, or none

3. Run the Installer

./install.sh

The installer will:

1. Detect your OS (Arch/CachyOS only)
2. Install core dependencies (git, curl, zsh)
3. Backup existing configuration files
4. Install Oh-My-Zsh
5. Install zsh plugins (autosuggestions, syntax-highlighting)
6. Configure git (prompts for name/email if not set)
7. Create symlinks for all dotfiles
8. Optionally set zsh as default shell
9. Offer to install optional tools

4. Restart Your Terminal

exec zsh

Or simply close and reopen your terminal.

---

Post-Installation

Verify Installation

dfd    # or: dotfiles-doctor.sh

This runs a health check and reports any issues.

Fix Any Issues

dffix  # or: dotfiles-doctor.sh --fix

Initialize the Secrets Vault

If you plan to use the vault for storing API keys:

vault init

Set Up LastPass (Optional)

# Install
paru -S lastpass-cli

# Login
lpass login your@email.com

# Test
pw list

Configure Snapper (CachyOS/Btrfs)

If using btrfs with snapshots:

# Install snapper
sudo pacman -S snapper

# Create config for root
sudo snapper -c root create-config /

# Install limine sync (if using limine bootloader)
paru -S limine-snapper-sync
sudo systemctl enable limine-snapper-sync.service

# Verify
snap-validate-service

---

Optional Tools

AUR Helper

If you don't have an AUR helper:

# Install paru (recommended)
sudo pacman -S --needed base-devel
git clone https://aur.archlinux.org/paru.git /tmp/paru
cd /tmp/paru && makepkg -si

Recommended Tool Installation

# All recommended tools at once
sudo pacman -S fzf bat eza tmux neovim fd ripgrep

# AUR packages
paru -S lastpass-cli glow

Espanso (Text Expansion)

# Install
paru -S espanso-wayland  # or espanso-x11 for X11

# Start service
espanso service start

# Link config
ln -sf ~/.dotfiles/espanso ~/.config/espanso

# Personalize
./setup/setup-espanso.sh

---

Customization

Local Overrides

Create ~/.zshrc.local for machine-specific settings that won't be synced:

# ~/.zshrc.local

# Machine-specific aliases
alias proj='cd ~/my-local-project'

# Local environment variables
export MY_LOCAL_VAR="value"

# Override settings
MOTD_STYLE="mini"

Adding Custom Functions

Add .zsh files to ~/.dotfiles/zsh/functions/ – they're auto-loaded.

Custom Tmux Templates

Add templates to ~/.dotfiles/.tmux-templates/:

# ~/.dotfiles/.tmux-templates/mytemplate.tmux
# My custom layout
split-window -h -p 40
split-window -v -p 30
select-pane -t 0

Use with: tw-create myproject mytemplate

Custom Bookmarks

bookmark work ~/projects/work
bookmark docs ~/Documents
j work    # jump to bookmark

---

Updating

Update Dotfiles

dfu    # or: dotfiles-update.sh

This will:

1. Pull latest changes from git
2. Optionally re-run the installer to update symlinks

Check for Updates

dfv    # or: dotfiles-version.sh

Sync Across Machines

# Push local changes
dfpush "Updated aliases"

# Pull remote changes
dfpull

# Check sync status
dfs

---

Uninstalling

Remove Symlinks Only

./install.sh --uninstall

This will:

1. Remove all symlinks created by the installer
2. Offer to restore backed-up files

Complete Removal

./install.sh --uninstall --purge

This will:

1. Remove all symlinks
2. Offer to restore backups
3. Delete the ~/.dotfiles directory

Manual Cleanup

If needed, manually remove:

rm -rf ~/.dotfiles
rm -f ~/.zshrc ~/.gitconfig ~/.vimrc ~/.tmux.conf
rm -rf ~/.config/nvim
rm -f ~/.local/bin/dotfiles-*

---

Troubleshooting

Command Not Found

If dotfiles commands aren't available:

# Ensure PATH includes ~/.local/bin
echo $PATH | grep -q ".local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc.local

# Reload
source ~/.zshrc

Oh-My-Zsh Issues

# Reinstall Oh-My-Zsh
rm -rf ~/.oh-my-zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended

# Reinstall plugins
git clone --depth 1 https://github.com/zsh-users/zsh-autosuggestions ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
git clone --depth 1 https://github.com/zsh-users/zsh-syntax-highlighting ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting

Broken Symlinks

# Check for broken symlinks
dfd

# Fix automatically
dffix

MOTD Not Showing

Check configuration:

# In dotfiles.conf
ENABLE_MOTD="true"
MOTD_STYLE="compact"

# Force show
motd --force

Slow Shell Startup

Compile zsh files for faster loading:

dfcompile

Profile startup time:

# Add to top of ~/.zshrc
zmodload zsh/zprof

# At bottom of ~/.zshrc
zprof

# Then start new shell and review output

Git Configuration Issues

# Check current config
git config --global --list

# Set manually
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

FZF Not Working

# Verify installation
which fzf

# Check if sourced correctly
[[ -d "$HOME/.fzf" || -f "/usr/share/fzf/key-bindings.zsh" ]] && echo "FZF available"

# Source manually if needed
source /usr/share/fzf/key-bindings.zsh
source /usr/share/fzf/completion.zsh

Permission Denied on Scripts

# Fix permissions
chmod +x ~/.dotfiles/install.sh
chmod +x ~/.dotfiles/bin/*.sh

Or use:

dffix

---

Install Options Reference

./install.sh [OPTIONS]

Options:
  (none)         Standard installation
  --wizard       Interactive TUI wizard
  --skip-deps    Skip dependency installation
  --deps-only    Only install dependencies
  --uninstall    Remove symlinks
  --purge        With --uninstall, also remove ~/.dotfiles
  --help         Show help

---

Getting Help

# Dotfiles health check
dfd

# Version and update info
dfv

# Command help
dotfiles-cli help

For issues, check the GitHub repository.