Skip to content

README.md

Latest commit

 

History

History
266 lines (196 loc) · 7.76 KB

README.md

File metadata and controls

266 lines (196 loc) · 7.76 KB

Dotfiles

Version-controlled terminal and application configurations for consistent development environment across machines.

Overview

This repository contains my personal dotfiles, primarily focused on Alacritty terminal configuration optimized for:

  • Claude/Codex CLI interactive sessions
  • WSL Ubuntu with zsh
  • High-performance terminal rendering (RTX 5090 optimized)
  • Multi-line input support with proper keybindings

Why Version Control Dotfiles?

  • History & Rollback: Revert breaking changes easily
  • Synchronization: Share configs across Windows/macOS/Linux machines
  • Auditable Changes: Clear commit history of what changed and why
  • Safe Experimentation: Use branches to test new configurations
  • Backup & Recovery: Never lose your carefully tuned configs
  • Reproducible Setup: Quick setup on new machines

Repository Structure

dotfiles/
├── alacritty/
│   ├── alacritty.toml           # Main Alacritty config with modular imports
│   ├── themes/
│   │   ├── fonts.toml           # Font configuration (FiraCode Nerd Font)
│   │   ├── colors.toml          # Color scheme (Tokyo Night)
│   │   └── keybindings.toml     # Keybindings (Claude/Codex optimized)
│   └── fallback/
│       ├── alacritty-minimal.toml      # Minimal fallback config
│       └── alacritty-powershell.toml   # PowerShell variant
├── scripts/
│   ├── install.ps1              # Windows installation script
│   └── uninstall.ps1            # Windows uninstallation script
├── .gitignore
└── README.md

Installation

Windows (Primary)

Requirements:

  • PowerShell with Administrator privileges
  • Git installed and configured
  • Alacritty installed

Steps:

  1. Clone this repository:

    cd ~
git clone https://github.com/alterspective-io/dotfiles.git
cd dotfiles

  2. Run the installation script:

    # Open PowerShell as Administrator
.\scripts\install.ps1

    This script will:

    • Create junctions/symlinks from %APPDATA%\alacritty to your dotfiles
    • Back up any existing configurations automatically
    • Set up the modular config structure

  3. Restart Alacritty to load the new configuration

macOS / Linux

Note: While this repo is currently Windows-focused, you can adapt it for Unix systems:

cd ~
git clone https://github.com/alterspective-io/dotfiles.git
cd dotfiles

# Create symlinks manually or adapt the PowerShell script
mkdir -p ~/.config/alacritty
ln -sf "$(pwd)/alacritty/alacritty.toml" ~/.config/alacritty/alacritty.toml
ln -sf "$(pwd)/alacritty/themes" ~/.config/alacritty/themes

Configuration Highlights

Alacritty Features

  • Modular Configuration: Separated into fonts, colors, and keybindings for easy customization
  • WSL Integration: Launches Ubuntu WSL with zsh by default
  • Claude/Codex Optimized:
    • Shift+Enter for multi-line input (newline without submit)
    • Enter for normal submit
    • Proper raw mode support for TUI applications
  • Clipboard Integration: OSC 52 support for WSL → Windows clipboard
  • Performance Tuned: 10k line scrollback, GPU-accelerated rendering
  • Visual Customization: Tokyo Night color scheme, FiraCode Nerd Font with ligatures

Key Bindings (Partial List)

Keybinding Action
Shift+Enter Insert newline (multi-line input)
Ctrl+Shift+C Copy
Ctrl+Shift+V Paste
Ctrl+Plus/Minus Increase/Decrease font size
Ctrl+Shift+F Search forward
F11 Toggle fullscreen

See alacritty/themes/keybindings.toml for complete list.

Making Changes

Workflow

  1. Edit configs in the dotfiles repository:

    cd ~/dotfiles/alacritty/themes
# Edit fonts.toml, colors.toml, or keybindings.toml

  2. Test immediately: Alacritty auto-reloads config (live_config_reload = true)

  3. Commit changes:

    cd ~/dotfiles
git add .
git commit -m "Update keybindings: fix Shift+Enter for Claude CLI"
git push

  4. Sync to other machines:

    cd ~/dotfiles
git pull
# Config automatically updates (if using symlinks/junctions)

Branching for Experiments

cd ~/dotfiles
git checkout -b experiment-new-colorscheme

# Make changes
# Test thoroughly

# If good, merge:
git checkout main
git merge experiment-new-colorscheme

# If bad, abandon:
git checkout main
git branch -D experiment-new-colorscheme

Fallback / Safe Mode

If you make a breaking change, use the minimal fallback config:

alacritty --config-file ~\dotfiles\alacritty\fallback\alacritty-minimal.toml

This uses:

  • Simple high-contrast colors
  • Built-in Consolas font (no dependencies)
  • Minimal keybindings
  • No transparency
  • No advanced features

Uninstallation

To remove the symlinks/junctions and revert to local configs:

# Open PowerShell as Administrator
cd ~\dotfiles
.\scripts\uninstall.ps1

This will remove the links and notify you about any backup files.

Troubleshooting

Symlink/Junction Issues on Windows

  • Symptom: Config not loading, or "file not found" errors
  • Solution:
    • Ensure you ran install.ps1 as Administrator
    • Check if junctions exist: Get-Item $env:APPDATA\alacritty\alacritty.toml | Select-Object *
    • Try using the fallback config to verify Alacritty works

Import Paths Not Resolving

  • Symptom: Alacritty warns about unused/missing imports
  • Check: The main alacritty.toml uses relative paths (themes/fonts.toml)
  • Verify: The themes/ junction exists in %APPDATA%\alacritty\

Live Reload Not Working

  • Check: live_config_reload = true in alacritty.toml
  • Note: Some changes (like font family) may require a full Alacritty restart

WSL Integration Issues

  • Symptom: Alacritty opens but WSL doesn't launch
  • Check:
    • WSL Ubuntu is installed: wsl -l -v
    • The shell path in alacritty.toml is correct: program = "wsl.exe"

Contributing to This Repo

This is a personal dotfiles repo, but if you're collaborating or syncing across your own machines:

  1. Pull before editing: Always git pull before making changes on a new machine
  2. Descriptive commits: Explain why you changed a setting, not just what
  3. Test before pushing: Ensure the config works before sharing to other machines
  4. Tag stable versions: Use git tag v1.0-stable to mark known-good configs

OS-Specific Configs

Currently, this repo uses a single alacritty.toml optimized for Windows + WSL. To support multiple OSes:

Option 1: Conditional Imports (recommended)

import = [
    "themes/base.toml",
    "themes/windows.toml",  # Only exists on Windows machine
    "themes/macos.toml",    # Only exists on macOS machine
]

Alacritty ignores missing import files.

Option 2: Separate Branches

  • main branch: Windows config
  • macos branch: macOS config
  • Pull the appropriate branch on each machine

License

This is a personal configuration repository. Feel free to fork and adapt for your own use.

Changelog

See Git commit history for detailed changes. Major milestones:

  • 2025-10-18: Initial version with Alacritty config, modular structure, Windows install scripts

Resources

Maintained by: alterspective-io Primary System: Windows 11 Business N | Intel Core Ultra 9 285K | RTX 5090 Last Updated: 2025-10-18