Dotfiles Repository

This repository contains my personal dotfiles and shell configuration for Linux, Windows (PowerShell), and cross-platform development environments.

What This Repository Contains

• Shell Configuration: Bash startup scripts, aliases, and environment setup
• Tool Configurations: Git, Vim, Tmux, Python, Node.js, Rust, and more
• Custom Scripts: Utility scripts in the bin/ directory
• Cross-Platform Support: Linux bash and Windows PowerShell configurations
• Modular Design: Organized by tool/functionality with conditional loading

Quick Setup

1. Clone the Repository

git clone https://github.com/harleypig/dotfiles.git ~/projects/dotfiles
cd ~/projects/dotfiles

2. Create Symbolic Links

The repository uses symbolic links to connect configuration files to your home directory:

# Create the main shell startup link
ln -sf ~/projects/dotfiles/shell-startup ~/.bash_profile

# Optional: Link other shell files if needed
ln -sf ~/projects/dotfiles/shell-startup ~/.bashrc
ln -sf ~/projects/dotfiles/shell-startup ~/.profile

3. Configure Custom Files

Dotlinks Files

The repository supports multiple dotlinks configurations for different environments:

• dotlinks-default: Default configuration for most users
• dotlinks-harleypig.com: Specific configuration for harleypig.com environment
• dotlinks-sweetums: Configuration for sweetums environment

Which one is used: check-dotfiles reads the first of these that exists:

1. ~/.dotlinks, your own list;
2. dotlinks-$HOSTNAME, the file named after this host;
3. dotlinks-default.

A host with its own file needs no setup. Create ~/.dotlinks only to override the per-host or default list:

# Start from an existing list and edit it
cp dotlinks-default ~/.dotlinks

File format — one entry per line, environment variables expanded:

# Single-column: symlink name derived from basename of source
$DOTFILES/dot-general/.bashrc

# Two-column: explicit symlink name (required when basename doesn't match)
$DOTFILES/config/foo .foorc

Single-column entries create ~/.<name> where <name> is the basename of the source path. Two-column entries use the second field as the symlink name, allowing sources whose basename differs from the desired ~/<name> (e.g., config/foo → .foorc). Comments (#) and blank lines are ignored.

Bin-Dirs Files

The bin-dirs-defaults file specifies additional directories to add to your PATH:

# Default bin directories (in order of precedence)
$HOME/bin
$HOME/.local/bin
$HOME/.vim/bin
$HOME/.cabal/bin
$HOME/.cargo/bin
$HOME/.minecraft/bin
$HOME/go/bin
$HOME/.dotnet/tools
$HOME/Dropbox/bin
$HOME/videos/bin
$PROJECTS_DIR/depot_tools
$PROJECTS_DIR/android-sdk/tools
$PROJECTS_DIR/android-sdk/platform-tools

When to customize: If you have additional tool directories or want to change the PATH order.

How to set up:

# Use defaults (no action needed)
# The system will automatically use bin-dirs-defaults

# Or create custom bin directories
cp bin-dirs-defaults ~/.bin-dirs
# Edit ~/.bin-dirs to customize your PATH

4. Set Up the Sibling Repositories

Dotfiles expects three companion repositories cloned beside it, in $PROJECTS_DIR — the directory holding the dotfiles checkout, which shell-startup sets from where ~/.bash_profile points (~/projects by default). Each is optional: when one is missing, login still completes, and the login checks that use it skip it or warn.

• dotvim — the Vim configuration, expected at $PROJECTS_DIR/dotvim (override with $XDG_DOTVIM). One command clones it with its submodules and links ~/.vim and ~/.vimrc:

  check-dotvim --setup

  Every interactive login re-runs the check (without --setup) and warns if dotvim is missing or its links are wrong; touch ~/.nocheckdotvim to skip it.

• dotagents — the Claude Code agent configuration, developed at $PROJECTS_DIR/dotagents. The live installation at ~/.claude is a separate clone that dotagents installs and updates itself, with its own bin/publish-config; dotfiles does not link it. See dotagents' installations inventory.

  git clone git@github.com:Harleypig-LLC/dotagents.git "$PROJECTS_DIR/dotagents"

• private_dotfiles — a private repository, expected at $PROJECTS_DIR/private_dotfiles. It holds what cannot be published: the API keys loaded at login, the per-scope credentials ghx and linx read, and private-dotlinks-default, the private counterpart of dotlinks-default. Clone it from its private remote to that path; the next interactive login links its dotlinks entries. Override the list with ~/.privatedotlinks, or touch ~/.nocheckprivatelinks to skip it.

5. Test the Setup

# Start a new login shell to test
bash -l

# Verify environment variables
echo "DOTFILES: $DOTFILES"
echo "XDG_CONFIG_HOME: $XDG_CONFIG_HOME"

# Check if completions are working
complete -p | grep git

6. (Optional) Enable pre-commit hooks

The repo ships two pre-commit configs: .pre-commit-config.yaml (check-only, gates git commit) and .pre-commit-config-fix.yaml (auto-fixers, run manually).

# Install the git hook so the check config runs on every commit
pre-commit install

# Apply auto-fixes (formatting, trailing whitespace) before committing
pre-commit run --config .pre-commit-config-fix.yaml --all-files

# Ad-hoc check without committing
pre-commit run --all-files

--all-files checks every file, as the CI pre-commit job does; a normal commit only checks the files it touches. See the dotagents repo's rules/pre-commit.md for the full command reference (install variants, autoupdate, validate-config, gc).

Architecture Overview

Shell Startup System

The .bash_profile, .bashrc, and .profile files all link to the same shell-startup file. This unified approach provides:

• Simplicity: One central file to understand and modify
• Consistency: Same configuration regardless of how bash is started
• Vim Integration: Ensures aliases work when shelling from vim
• Modular Loading: Individual tool configurations in config/shell-startup/

Directory Structure

├── bin/                     # Custom utility scripts
├── config/                  # Tool-specific configurations
│   ├── completions/         # Bash completion files
│   ├── shell-startup/       # Modular shell startup files
│   ├── git/                 # Git configuration
│   ├── vim/                 # Vim configuration
│   └── ...                  # Other tool configs
├── docs/                    # Documentation
├── powershell/              # Windows PowerShell configuration
├── shell-startup            # Main shell startup script
├── dotlinks-default         # Default dotlinks configuration
├── bin-dirs-defaults        # Default PATH directories
└── README.md               # This file

Modular Configuration

Tool configurations are organized in config/shell-startup/ with conditional loading. Each module sets up environment variables, aliases, and completions for specific tools:

Core Configuration:

• 000-loadtokens: Load authentication tokens
• 010-general: General environment setup, aliases and bash history
• app_env_vars: Application-specific environment variables
• bash_prompt: Custom bash prompt configuration

Development Tools:

• aider: Aider AI coding assistant
• claude: Claude Code CLI environment settings, when installed
• docker: Docker CLI bash completion
• gcloud: gcloud-sa, switch the shell's gcloud configuration and GOOGLE_APPLICATION_CREDENTIALS
• gh: GitHub CLI bash completion, for both gh and ghx
• git: Git configuration and aliases
• go: Go language environment
• grok: xAI grok CLI on PATH, with bash completion
• jbang: jbang Java script runner on PATH, under XDG once migrated
• mise: mise polyglot tool version manager, when installed
• node: Node.js and NVM configuration
• perl: Perl environment and configuration
• python: Python environment, venv helpers and poetry completion
• rust: Rust and Cargo setup
• terraform: Terraform alias and bash completion

Applications:

• cuda: NVIDIA CUDA configuration
• less: Less pager configuration
• tmux: Tmux configuration
• vim: Vim configuration

Completion:

• ssh-config-completion: SSH host completion

Startup Checks:

• zzz-check-dotfiles: Verify the dotfile links, after every other module has loaded
• zzz-check-dotvim: Verify the dotvim repo and its links

Modules load in name order. A module whose name ends in _inactive is kept in the directory but never loaded.

Configuration Directories

The config/ directory contains tool-specific configurations organized by application. Each tool may have its own subdirectory with configuration files and documentation:

• Development: ansible, docker, gh, git, go, npm, perl, python, pypoetry
• CLI Tools: act, glow, htop, linode-cli, opencode, pgcli, snyk, yamllint
• Applications: audacity, Cursor, cursor, gnome-initial-setup-done
• Configuration: completions, configstore, readline, shell-startup, subdir
• Task Management: task (taskwarrior)
• Other: Bitwarden CLI, burn-my-windows, coc, pudb, test, user-dirs.dirs, yapf

Most tools follow the XDG Base Directory specification (see below). For tool-specific documentation, check for README files within each subdirectory.

XDG Base Directory Specification

This repository follows the XDG Base Directory Specification for organizing configuration, data, and cache files:

Environment Variables:

• $XDG_CONFIG_HOME (default: ~/.config) - Configuration files
• $XDG_DATA_HOME (default: ~/.local/share) - Data files
• $XDG_CACHE_HOME (default: ~/.cache) - Cache files
• $XDG_STATE_HOME (default: ~/.local/state) - State files

Benefits:

• Clean home directory (no dot-file clutter)
• Organized configuration structure
• Easy backup and synchronization
• Standard across modern Linux applications

Tool Support: Most modern tools respect XDG variables. For tools that don't natively support XDG, configurations in this repository use XDG paths where possible through aliases, wrapper scripts, or tool-specific configuration options.

Cross-Platform Support

Linux/Unix (Primary)

• Shell: Bash with comprehensive completion system
• Package Management: Supports apt, pacman, and other package managers
• Development Tools: Git, Vim, Tmux, Python, Node.js, Rust, Go
• System Integration: XDG Base Directory specification

Windows (Work in Progress)

The repository includes PowerShell configuration for Windows environments:

• PowerShell Profiles: Located in powershell/ directory
• Git for Windows: Integration with Git Bash and PowerShell
• Cross-Platform Scripts: Some utilities work in both environments

Note: Windows support is actively being developed. Some features may be incomplete or require manual setup.

Git for Windows

When using Git for Windows:

• Git Bash: Uses the same bash configuration as Linux
• PowerShell: Uses Windows-specific PowerShell profiles
• MSYS Integration: Handles symlink creation appropriately

Setup for Git for Windows:

# In Git Bash
ln -sf ~/projects/dotfiles/shell-startup ~/.bash_profile

# PowerShell setup (manual)
# Copy powershell/ files to appropriate PowerShell profile location

Customization

Adding New Tools

1. Create shell-startup file: Add config/shell-startup/newtool
2. Add completion: Place completion file in config/completions/
3. Update PATH: Add to bin-dirs-defaults or ~/.bin-dirs

Environment-Specific Configuration

1. Create custom dotlinks: Copy and modify dotlinks-default
2. Custom bin directories: Create ~/.bin-dirs file
3. Tool-specific configs: Add files to config/ directory

Troubleshooting

Common Issues

1. Symbolic links not working: Ensure you're using absolute paths
2. Completions not loading: Check file permissions and tool installation
3. PATH issues: Verify bin-dirs-defaults or ~/.bin-dirs configuration
4. Environment variables: Use bash -l to test login shell behavior

Debug Mode

# Enable debug output
DEBUG=1 bash -l

# Check specific configurations
bash -l -c 'echo "DOTFILES: $DOTFILES"'

Documentation

Core Documentation:

• WORKFLOW.md: Repository workflow, development guidelines, and tool setup procedures
• TESTS.md: Testing framework, strategy, and how to write tests
• CLAUDE.md: AI agent behavior specification and requirements

Additional Documentation:

• Bash Completion: Detailed explanation of the completion system
• Git Aliases: List of available git aliases
• Conventions: Coding and configuration conventions

Contributing

This is a personal dotfiles repository, but suggestions and improvements are welcome. Please:

1. Test changes thoroughly
2. Document new features
3. Maintain backward compatibility
4. Follow existing conventions

License

See LICENSE file for details.