$ cat dotfiles.md

4 min read
dotfilesshellzshvimgitdevelopmentautomationcross-platform
Project screenshot

Overview

This dotfiles repository is a comprehensive, cross-platform development environment configuration system designed for modern software development workflows. It provides consistent, powerful configurations across macOS, Windows, and Linux, with support for multiple shells, editors, and development tools.

Philosophy

  • Cross-Platform: One configuration, multiple operating systems
  • Modular: Pick and choose what you need
  • Automated: One-command setup and updates
  • Documented: Clear explanations for every configuration
  • Maintained: Regular updates with modern best practices

Supported Platforms

Operating Systems

  • macOS: Ventura, Sonoma (Intel and Apple Silicon)
  • Windows: Windows 10, Windows 11 (PowerShell, WSL2)
  • Linux: Debian, Ubuntu, Fedora, Arch

Shells

  • Zsh: Primary shell with extensive customization
  • Bash: Fallback with similar configuration
  • PowerShell: Windows-native shell support

Features

🐚 Shell Configuration

Zsh (Primary)

  • Starship Prompt: Fast, customizable, cross-platform prompt
  • Plugin Management: zinit for fast plugin loading
  • Auto-completion: Intelligent command completion
  • Syntax Highlighting: Real-time command syntax highlighting
  • History Management: Shared history across sessions
  • Aliases: Productivity-boosting command shortcuts

Bash (Fallback)

  • Similar configuration to Zsh
  • Compatible aliases and functions
  • Starship prompt integration

🎨 Terminal Emulators

Kitty (Primary)

  • GPU-accelerated rendering
  • True color support
  • Ligature support for programming fonts
  • Split windows and tabs
  • Custom key bindings
  • Cross-platform configuration

Tmux

  • Session management
  • Window and pane splitting
  • Custom status bar
  • Mouse support
  • Plugin ecosystem

✏️ Editor Configuration

VS Code

  • Language-specific settings
  • Extension recommendations
  • Keybindings and snippets
  • Theme configuration
  • Workspace settings

JetBrains IDEs

  • IntelliJ IDEA
  • PyCharm
  • WebStorm
  • Rider
  • Shared settings and keymaps

Vim/Neovim

  • Modern plugin management
  • Language server protocol (LSP)
  • Syntax highlighting
  • Code completion
  • File navigation

🛠️ Development Tools

Git

  • Global configuration
  • Useful aliases
  • Diff and merge tools
  • Commit templates
  • GPG signing support

Node.js/JavaScript

  • npm configuration
  • nvm for version management
  • ESLint and Prettier settings
  • TypeScript configuration

Python

  • pip configuration
  • Virtual environment management
  • pyenv for version management
  • Poetry for dependency management

C#/.NET

  • .NET SDK configuration
  • NuGet settings
  • Project templates

Installation

Quick Start

# Clone repository
git clone https://github.com/cameronrye/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# Run setup script
./install.sh

Platform-Specific Setup

macOS:

# Install Homebrew first
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Run dotfiles setup
./install.sh

Linux (Debian/Ubuntu):

# Update package lists
sudo apt update

# Run dotfiles setup
./install.sh

Windows (PowerShell):

# Run as Administrator
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
.\install.ps1

Configuration Structure

dotfiles/
├── shell/              # Shell configurations
│   ├── zshrc
│   ├── bashrc
│   └── aliases
├── terminal/           # Terminal emulator configs
│   ├── kitty/
│   └── tmux/
├── editors/            # Editor configurations
│   ├── vscode/
│   ├── vim/
│   └── jetbrains/
├── git/                # Git configuration
│   ├── gitconfig
│   └── gitignore_global
├── tools/              # Development tool configs
│   ├── node/
│   ├── python/
│   └── dotnet/
└── scripts/            # Setup and utility scripts
    ├── install.sh
    ├── backup.sh
    └── update.sh

Key Features

🚀 Starship Prompt

A minimal, fast, and customizable prompt showing:

  • Current directory
  • Git branch and status
  • Programming language versions (Node, Python, etc.)
  • Command execution time
  • Exit status indicators
  • Custom symbols and colors

📦 Package Management

macOS (Homebrew):

  • Brewfile for declarative package management
  • Automatic installation of CLI tools
  • Cask support for GUI applications

Linux (apt/dnf/pacman):

  • Package lists for each distribution
  • Automated installation scripts

Windows (Chocolatey/Scoop):

  • Package manifests
  • Automated setup scripts

🔄 Synchronization

  • Backup Script: Save current configurations
  • Update Script: Pull latest changes and apply
  • Restore Script: Restore from backup
  • Diff Tool: Compare local and repository configs

Customization

Personal Overrides

Create local override files that won’t be tracked:

# Zsh local overrides
~/.zshrc.local

# Git local config
~/.gitconfig.local

# Environment variables
~/.env.local

Modular Loading

Enable/disable features by commenting out sections:

# In .zshrc
# source ~/.dotfiles/shell/plugins/docker.zsh  # Disable Docker plugins
source ~/.dotfiles/shell/plugins/git.zsh       # Enable Git plugins

Included Tools & Plugins

Shell Plugins

  • zsh-autosuggestions: Fish-like autosuggestions
  • zsh-syntax-highlighting: Real-time syntax highlighting
  • zsh-completions: Additional completion definitions
  • fzf: Fuzzy finder for files and history
  • ripgrep: Fast text search
  • bat: Cat clone with syntax highlighting
  • exa: Modern ls replacement

Git Enhancements

  • delta: Better diff viewer
  • lazygit: Terminal UI for Git
  • gh: GitHub CLI integration

Development Utilities

  • direnv: Directory-specific environment variables
  • asdf: Universal version manager
  • docker: Container management
  • kubectl: Kubernetes CLI

Productivity Features

Aliases

# Navigation
alias ..='cd ..'
alias ...='cd ../..'
alias ~='cd ~'

# Git shortcuts
alias gs='git status'
alias ga='git add'
alias gc='git commit'
alias gp='git push'

# Modern replacements
alias ls='exa --icons'
alias cat='bat'
alias find='fd'
alias grep='rg'

Functions

# Create directory and cd into it
mkcd() { mkdir -p "$1" && cd "$1"; }

# Extract any archive
extract() { ... }

# Git commit with conventional commits
gcm() { git commit -m "$1"; }

Maintenance

Update Dotfiles

# Pull latest changes
cd ~/.dotfiles
git pull

# Re-run installation
./install.sh

Backup Current Config

# Create backup
./scripts/backup.sh

# Backups stored in ~/.dotfiles/backups/

Restore from Backup

# List available backups
./scripts/backup.sh --list

# Restore specific backup
./scripts/backup.sh --restore 2025-10-18

Platform-Specific Features

macOS

  • Homebrew Bundle: Declarative package management
  • macOS Defaults: System preference automation
  • App Store CLI: Install Mac App Store apps
  • Touch ID: sudo authentication

Windows

  • WSL2 Integration: Seamless Linux environment
  • PowerShell Profile: Windows-native shell config
  • Windows Terminal: Modern terminal configuration
  • Chocolatey: Package management

Linux

  • Distribution Detection: Auto-detect package manager
  • Desktop Environment: GNOME, KDE, i3 configurations
  • Systemd Services: Custom service definitions

Security

  • GPG Integration: Commit signing
  • SSH Configuration: Secure key management
  • Credential Storage: Secure credential helpers
  • Environment Variables: Sensitive data in local files

Performance

  • Lazy Loading: Plugins loaded on demand
  • Compilation: Zsh script compilation for speed
  • Caching: Completion and command caching
  • Profiling: Built-in performance measurement

Documentation

Each configuration file includes:

  • Purpose and functionality
  • Dependencies and requirements
  • Customization options
  • Platform-specific notes
  • Troubleshooting tips

Community

  • Issues: Bug reports and feature requests
  • Discussions: Questions and ideas
  • Pull Requests: Contributions welcome
  • Wiki: Extended documentation

Inspiration

This dotfiles repository draws inspiration from:

  • Mathias Bynens: macOS defaults
  • Thoughtbot: Shell configuration
  • Holman: Topical organization
  • Community: Countless dotfiles repositories

Future Enhancements

  • GUI Installer: Visual setup wizard
  • Cloud Sync: Sync settings across machines
  • Profile System: Multiple configuration profiles
  • Plugin Manager: Custom plugin ecosystem
  • Testing: Automated configuration testing

Status: Production Ready
License: MIT
Maintained: Active Development