Skip to content

Documentation

Complete documentation for this dotfiles repository.

For macOS, the canonical source is MAC_WORKSTATION_GUIDE.md.

📖 Table of Contents

Getting Started

Configuration

  • CONFIG_GUIDE.md - Detailed documentation of all configuration files
  • Git configuration and aliases
  • Zsh configuration
  • IdeaVim keybindings
  • And more...

Installation Details

  • INSTALLATION_GUIDE.md - Comprehensive guide covering:
  • What gets installed on each OS
  • Platform-specific instructions (macOS, Arch, Debian, WSL)
  • Customization options

  • Troubleshooting

  • SCRIPTS_EXPLAINED.md - Comparison of installation scripts:

  • Minimal vs. optional vs. full installers
  • What's in each script

  • Cross-platform considerations

  • ARCH_INSTALLER_FLOW.md - Detailed Arch Linux installer flow:

  • Step-by-step walkthrough
  • What gets installed automatically
  • Interactive prompts
  • Post-installation steps

Tools & Scripts

  • MODERN_CLI_TOOLS.md - Guide to modern CLI tools:
  • bat, eza, ripgrep, fd, fzf, zoxide, etc.
  • What they do and why they're useful

  • Usage examples

  • UTILITY_SCRIPTS.md - Documentation for utility scripts:

  • update.sh - Update all package managers
  • backup.sh - Backup configurations
  • cleanup.sh - Clean caches and free disk space
  • dev-check.sh - Check environment health
  • setup-gpg.sh - Set up GPG commit signing
  • MAC_SETUP_AND_LOCAL_AI.md - Practical macOS setup + local AI recommendations
  • ai/LOCAL_AI_SETUP.md - Exact local AI setup/run/remote workflow + troubleshooting
  • WALLPAPERS.md - Manage wallpapers from dotfiles
  • tutorials/TOOL_TUTORIALS.md - Official docs + YouTube tutorial links per tool
  • SETUP_DOCS_SITE.md - Browser-accessible docs via MkDocs + GitHub Pages

Advanced Topics

🎯 Quick Navigation

I want to...

📁 Repository Structure

.dotfiles/
├── README.md                 # Main repository README
├── docs/                     # All documentation (you are here)
├── config/                   # Configuration files
│   ├── git/                  # Git config
│   ├── zsh/                  # Zsh config
│   ├── ssh/                  # SSH config template
│   ├── tmux/                 # Tmux config
│   ├── curl/                 # Curl config
│   ├── claude/               # Claude Code settings
│   └── .editorconfig         # EditorConfig
├── os/                       # OS-specific installers
│   ├── mac/                  # macOS installers
│   ├── linux/                # Linux installers
│   └── windows/              # Windows/WSL installer
└── scripts/                  # Utility scripts
    ├── update.sh             # Update all package managers
    ├── backup.sh             # Backup configs
    ├── cleanup.sh            # Clean caches
    ├── dev-check.sh          # Health check
    └── setup-gpg.sh          # GPG setup

🚀 Quick Start Commands

# Install on new machine
git clone https://github.com/peciulevicius/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./install.sh

# Update everything
~/.dotfiles/scripts/update.sh

# Backup configurations
~/.dotfiles/scripts/backup.sh

# Clean up disk space
~/.dotfiles/scripts/cleanup.sh

# Check environment health
~/.dotfiles/scripts/dev-check.sh

# Set up GPG commit signing
~/.dotfiles/scripts/setup-gpg.sh

💡 Tips

  • Start with QUICKSTART.md if you're new
  • Refer to HOW_TO_INSTALL.md for complete installation
  • Check CONFIG_GUIDE.md to understand your configs
  • Run dev-check.sh to verify your setup
  • Use update.sh regularly to keep everything current

🔗 External Resources

🆘 Getting Help

  1. Check the relevant documentation file above
  2. Run dev-check.sh to diagnose issues
  3. Look for troubleshooting sections in the guides
  4. Search for similar issues in the repository

📝 Contributing

Found a bug or have a suggestion? Please: 1. Check existing documentation first 2. Create an issue describing the problem 3. Submit a pull request with improvements

Need help? Start with QUICKSTART.md or HOW_TO_INSTALL.md