Skip to content

troubleshooting.md

Latest commit

 

History

History
227 lines (144 loc) · 3.71 KB

troubleshooting.md

File metadata and controls

227 lines (144 loc) · 3.71 KB

Troubleshooting

Common issues and solutions.

Installation Issues

Permission denied errors

Problem: permission denied when running setup

Solution:

chmod +x install/setup.sh
./install/setup.sh

Files already exist

Problem: Installation fails because config files exist

Solution: Use force mode (creates backup first)

make install-force

Backups are saved to ~/.dotfiles-backup-{timestamp}/

Template placeholders remain

Problem: Configs contain {{ user.name }} after installation

Solution: Create config.json from template

cp config.json.example config.json
# Edit config.json with your details
make install

Shell Issues

Slow shell startup

Problem: Shell takes >1s to start

Diagnosis:

# Benchmark startup time
./bin/shell-bench

# Profile zsh startup (shows what's slow)
time zsh -i -c exit

Solutions:

  • Disable unused modules: export DOTFILES_SKIP_WORKFLOW=1
  • Check for network-dependent operations
  • Review .zshrc for heavy operations

Command not found after install

Problem: Commands like eza, bat not found

Solution: Install modern CLI tools

make packages

Completions not working

Problem: Tab completion fails or shows warnings

Solution: Rebuild completion cache

rm -f ~/.zcompdump*
exec zsh

Git Issues

Git config not applied

Problem: Git configuration not working

Solution: Verify config was generated from template

# Check if config exists
cat config/git/gitconfig | head -5

# If it shows {{ placeholders }}, regenerate
make install

Delta not showing colors

Problem: Git diff not using delta

Solution: Ensure delta is installed and configured

which delta
git config --get core.pager  # Should show 'delta'

Tool-Specific Issues

tmux: command not found

Problem: tmux not available

Solution:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

nvim errors on startup

Problem: Neovim shows errors when opening

Solution: Update plugin manager

nvim --headless "+Lazy! sync" +qa

mise not found

Problem: Language runtime manager not available

Solution:

curl https://mise.run | sh

Platform-Specific

macOS: Operation not permitted

Problem: Can't write to /usr/local

Solution: Use Homebrew's recommended directory

# Apple Silicon (M1/M2)
# Homebrew installs to /opt/homebrew

# Intel
# Homebrew installs to /usr/local

Linux: zsh not default shell

Problem: bash still loads instead of zsh

Solution:

chsh -s $(which zsh)
# Logout and login again

WSL: Slow file operations

Problem: Shell slow on Windows Subsystem for Linux

Solution: Keep dotfiles in Linux filesystem

# Move to ~/ instead of /mnt/c/
cd ~
git clone https://github.com/vnykmshr/dotfiles.git .dotfiles

Recovery

Restore from backup

Problem: Need to undo dotfiles installation

Solution:

# List backups
ls -la ~ | grep dotfiles-backup

# Manually restore (replace {timestamp})
cp -r ~/.dotfiles-backup-{timestamp}/.zshrc ~/.zshrc
# Repeat for other files

Reset to clean state

Problem: Something's broken, need fresh start

Solution:

# Backup and reinstall everything
make reset

# Or manual cleanup
rm -rf ~/.dotfiles
rm ~/.zshrc ~/.gitconfig ~/.tmux.conf
# Then reinstall

Getting Help

If issues persist:

  1. Check logs: Installation creates logs in /tmp/
  2. Run tests: make test to verify setup
  3. Dry run: make install-dry-run to see what would change
  4. Open an issue: Include OS, shell version, error messages