Skip to content

LITl-l/dotfiles

BranchesTags

Repository files navigation

Dotfiles

A declarative, reproducible dotfiles configuration using Nix and Home Manager. Works on Linux, macOS, and WSL2.

🚀 Features

  • Declarative Configuration - Everything defined in Nix for reproducibility
  • Cross-Platform - Works on Linux, macOS, and WSL2
  • Home Manager - Manages user environment with Nix
  • Modern Tool Stack - Latest CLI tools and applications
  • Vi Mode Everything - Consistent vi keybindings across all tools
  • GPU-Accelerated Terminal - WezTerm with cross-platform support
  • Automated CI - GitHub Actions validates all configurations

📦 Included Tools

Shell Environment

  • Fish - Modern shell with vi mode, Catppuccin colors, and excellent autosuggestions
    • z plugin - Directory jumper for quick navigation
    • fzf.fish plugin - Enhanced fuzzy finding integration
    • Custom functions for git, file search, and Nix shortcuts
  • Starship - Fast, customizable prompt with git integration and language detection
  • Zoxide - Smart directory jumper with frecency algorithm (better than cd)
  • Direnv - Per-directory environment variables with Nix integration

Terminal & Editor

  • WezTerm - GPU-accelerated terminal (Linux/macOS, uses Windows WezTerm for WSL2)
  • Neovim - Extensible editor with mini.nvim for minimal, powerful setup
  • Tmux - Terminal multiplexer with Catppuccin theme

Development Tools

  • Git - Version control with delta for beautiful diffs
  • Lazygit - Terminal UI for git operations
  • GitHub CLI - Manage GitHub from the command line

Modern CLI Utilities

  • eza - Modern ls replacement with icons and git integration
  • fd - Modern find replacement (fast, user-friendly)
  • ripgrep - Modern grep replacement (recursive, fast)
  • bat - cat with syntax highlighting and line numbers
  • fzf - Fuzzy finder for files, history, and more
  • delta - Beautiful git diffs with syntax highlighting
  • jq / yq-go - JSON and YAML processors
  • htop - Interactive process viewer
  • tree - Directory tree visualizer

Nix Development Tools

  • nixpkgs-fmt - Nix code formatter
  • nil - Nix Language Server for IDE integration
  • home-manager - Declarative user environment manager
  • Development shell with additional tools available via nix develop

🛠️ Installation

Prerequisites

  • Git - For cloning this repository
  • Curl - For installing Nix
  • Linux, macOS, or WSL2 - Tested on Ubuntu 22.04+, macOS 13+, WSL2

Quick Install

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

# Run the installer
./install.sh

The installer will:

  1. Install Nix with flakes enabled
  2. Install Home Manager
  3. Build and activate your configuration
  4. Set Fish as your default shell
  5. Set up all tools and configurations

Manual Installation

If you prefer more control:

# 1. Install Nix (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# 2. Enable flakes (if not already enabled)
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

# 3. Clone dotfiles
git clone https://github.com/yourusername/dotfiles.git ~/dotfiles
cd ~/dotfiles

# 4. Build and activate (choose your platform)
# For Linux:
nix build .#homeConfigurations."user@linux".activationPackage
./result/activate

# For WSL2:
nix build .#homeConfigurations."user@wsl".activationPackage
./result/activate

# For macOS:
nix build .#homeConfigurations."user@darwin".activationPackage
./result/activate

📁 Project Structure

dotfiles/
├── flake.nix                   # Nix flake entry point
├── flake.lock                  # Locked dependencies
├── home.nix                    # Main Home Manager configuration
├── install.sh                  # Nix-based installation script
├── install-legacy.sh           # Legacy bash-based installer (deprecated)
├── README.md                   # This file
├── CLAUDE.md                   # Claude Code instructions
│
├── modules/                    # Nix modules for each tool
│   ├── common.nix             # Common settings (SSH, GPG, readline)
│   ├── fish.nix               # Fish shell configuration
│   ├── wezterm.nix            # WezTerm terminal
│   ├── neovim.nix             # Neovim editor
│   ├── starship.nix           # Starship prompt
│   ├── git.nix                # Git configuration
│   └── tmux.nix               # Tmux multiplexer
│
├── config/                     # Application configs
│   └── wezterm/
│       └── wezterm.lua        # WezTerm config with OS detection
│
├── nvim/                       # Neovim configuration
│   ├── init.lua               # Main config
│   ├── README.md              # Neovim-specific documentation
│   └── lua/config/            # Lua modules
│       ├── options.lua        # Editor options
│       ├── keymaps.lua        # Key mappings
│       ├── autocmds.lua       # Auto commands
│       ├── plugins.lua        # Plugin configuration
│       └── util.lua           # Utility functions
│
├── wezterm/                    # WezTerm documentation
│   └── README.md
│
├── git/                        # Git documentation
│   └── README.md
│
├── tmux/                       # Tmux documentation
│   └── README.md
│
├── starship/                   # Starship documentation
│   └── README.md
│
├── lazygit/                    # Lazygit documentation
│   └── README.md
│
├── Legacy tools/               # Deprecated bash-based configs
│   ├── zsh/                   # (Use Fish via Nix instead)
│   ├── sheldon/               # (Use Fish plugins via Nix instead)
│   ├── homebrew/              # (Use Nix packages instead)
│   ├── docker/                # (Standalone tool, not managed by Nix)
│   ├── proto/                 # (Standalone tool, not managed by Nix)
│   └── eza/                   # (Use eza via Nix packages instead)
│
└── .github/
    └── workflows/
        └── nix-check.yml      # CI workflow

⚙️ Configuration

Note: This repository includes legacy bash-based installation scripts in individual tool directories (zsh/, docker/, etc.). These are deprecated and maintained only for reference. The modern, recommended approach is using the Nix flakes configuration described in this document.

Platform-Specific Setup

The configuration automatically detects your platform and applies the correct settings:

  • Linux (Generic): Full configuration with WezTerm - use user@linux
  • WSL2: Configuration without WezTerm (uses Windows WezTerm) - use user@wsl
  • NixOS on WSL2: Optimized for NixOS on WSL2 - use nixos@wsl
  • macOS (Apple Silicon): Full configuration with WezTerm - use user@darwin

NixOS Configuration

If you're running NixOS (including NixOS-WSL), use the nixos@wsl configuration:

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

# Build and activate for NixOS on WSL2
nix build .#homeConfigurations."nixos@wsl".activationPackage
./result/activate

# Or use home-manager directly
home-manager switch --flake .#nixos@wsl

This configuration:

  • Sets the username to nixos (default NixOS-WSL user)
  • Sets home directory to /home/nixos
  • Disables WezTerm (uses Windows terminal)
  • Enables all other tools and configurations

WSL2 WezTerm Configuration

When using WSL2, WezTerm runs on the Windows side but needs to access configuration from WSL. This setup creates a direct symbolic link from Windows to the WSL dotfiles directory.

Quick Setup (Recommended):

Use the automated setup script to get the exact commands for your system:

cd ~/dotfiles
./setup-wsl-wezterm.sh

The script will:

  • Verify you're in a WSL environment
  • Detect your WSL distribution name and username
  • Check that the wezterm config exists in dotfiles
  • Provide customized PowerShell commands for Windows setup

Manual Setup:

If you prefer to set up manually:

Windows Side (PowerShell as Administrator):

# 1. Create .config directory if it doesn't exist
New-Item -ItemType Directory -Path "$env:USERPROFILE\.config" -Force

# 2. Create symbolic link directly to WSL dotfiles wezterm directory
# Replace <distro> with your WSL distribution name (check with: wsl -l -v)
# Replace <username> with your WSL username
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\wezterm" -Target "\\wsl$\<distro>\home\<username>\dotfiles\wezterm\"

# Example for NixOS:
# New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\wezterm" -Target "\\wsl$\NixOS\home\nixos\dotfiles\wezterm\"

# Example for Ubuntu:
# New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\wezterm" -Target "\\wsl$\Ubuntu\home\user\dotfiles\wezterm\"

# 3. Restart WezTerm

# 4. Verify configuration is loaded (theme, fonts, keybindings should match)

Directory Structure:

Windows:
  %USERPROFILE%\.config\wezterm\   → (symlink to \\wsl$\<distro>\home\<user>\dotfiles\wezterm\)
    ├── wezterm.lua                → Main entry point
    ├── platform.lua               → OS detection
    ├── theme.lua                  → Colors and visual settings
    ├── fonts.lua                  → Font configuration
    ├── appearance.lua             → Window appearance
    ├── keybindings.lua            → Keyboard shortcuts
    ├── mouse.lua                  → Mouse bindings
    ├── domains.lua                → Domain configs (WSL, SSH, local)
    └── performance.lua            → Performance settings

WSL:
  ~/dotfiles/wezterm/              → Source of truth (all config files)

How it works:

  1. Your dotfiles wezterm configuration is at ~/dotfiles/wezterm/ in WSL
  2. Windows %USERPROFILE%\.config\wezterm is a symbolic link directly to WSL ~/dotfiles/wezterm/
  3. Windows WezTerm looks for config at %USERPROFILE%\.config\wezterm\wezterm.lua
  4. This resolves through the symlink to your dotfiles repo
  5. Result: All config changes in dotfiles auto-sync to Windows WezTerm

Modular Configuration:

The WezTerm config is now organized into modules:

  • theme.lua - Color schemes and visual effects
  • fonts.lua - Font family and sizing (platform-specific)
  • appearance.lua - Window decorations, opacity, padding, tabs
  • keybindings.lua - All keyboard shortcuts
  • mouse.lua - Mouse button and wheel bindings
  • domains.lua - WSL, SSH, and local shell configuration
  • performance.lua - Rendering and FPS settings
  • platform.lua - OS detection utilities

Edit any module and WezTerm will pick up changes on reload (Ctrl+Shift+Alt+R or Cmd+Shift+R).

Troubleshooting:

If WezTerm doesn't detect the configuration:

  1. Verify the symlink was created correctly:

    # On Windows PowerShell:
Get-Item "$env:USERPROFILE\.config\wezterm" | Select-Object LinkType, Target
# Should show:
# LinkType: SymbolicLink
# Target: \\wsl$\<distro>\home\<username>\dotfiles\wezterm

  2. Check that source files exist in WSL:

    # On WSL:
ls -la ~/dotfiles/wezterm/
# Should show wezterm.lua and all module files

  3. Verify WSL path is accessible from Windows:

    • Open Windows Explorer
    • Navigate to: \\wsl$\<distro>\home\<username>\dotfiles\wezterm
    • You should see all the .lua files

  4. Common issues:

    • Symlink creation fails: Enable Developer Mode in Windows Settings, or run PowerShell as Administrator
    • WezTerm shows blank config: Make sure you're using the correct WSL distribution name (check with wsl -l -v)
    • Permission denied: Ensure WSL filesystem is accessible from Windows
    • File vs Directory error: If %USERPROFILE%\.config\wezterm is a file instead of a symlink, delete it first: 
      Remove-Item "$env:USERPROFILE\.config\wezterm" -Force

Git Identity

Create ~/.config/git/config.local to set your Git identity:

[user]
    name = Your Name
    email = your.email@example.com

Customization

All configuration is in Nix files. To customize:

  1. Edit the relevant module in modules/
  2. Rebuild with nix-rebuild or ./install.sh --rebuild

🔄 Updating

Update All Packages

cd ~/dotfiles
./install.sh --update

Or use the convenience alias:

nix-update

Rebuild Without Updating

cd ~/dotfiles
./install.sh --rebuild

Or:

nix-rebuild

Rollback Changes

Nix allows you to rollback to previous configurations:

# List generations
home-manager generations

# Rollback to previous generation
home-manager generations | head -2 | tail -1 | awk '{print $7}' | xargs -I {} {}/activate

🎨 Theme

All tools use the Catppuccin Mocha color scheme for a consistent look:

  • Dark, comfortable colors
  • Excellent contrast
  • Beautiful syntax highlighting

⌨️ Key Bindings

Fish Shell

Vi Mode Navigation:

  • Press Esc - Enter normal mode
  • Visual mode indicators: 🅝 NORMAL, 🅘 INSERT, 🅥 VISUAL, 🅡 REPLACE
  • Cursor changes by mode (block/line/underscore)

Built-in Keybindings:

  • Ctrl+R - Search command history with fzf
  • Ctrl+F - Accept autosuggestion
  • Alt+F - Accept one word from autosuggestion
  • Alt+E - Edit command in $EDITOR

Custom Functions:

  • f - Interactive file search with preview (fd + fzf + bat)
  • fd_dir - Interactive directory search and cd (fd + fzf + eza)
  • mkcd <dir> - Create directory and cd into it
  • extract <file> - Extract any archive format
  • rebuild - Rebuild home-manager configuration
  • nix-search <pkg> - Search for Nix packages

Neovim

  • <Space> - Leader key
  • <Space>e - File explorer
  • <Space>ff - Find files
  • <Space>fg - Live grep
  • <Space>fb - Find buffers
  • <Space>w - Save file

Tmux

  • Ctrl+a - Prefix key
  • Prefix | - Split vertically
  • Prefix - - Split horizontally
  • Prefix h/j/k/l - Navigate panes
  • Prefix H/J/K/L - Resize panes

WezTerm

  • Ctrl+Shift+D - Split horizontal
  • Ctrl+D - Split vertical
  • Ctrl+Shift+H/J/K/L - Navigate panes
  • Ctrl+Alt+H/J/K/L - Resize panes
  • Ctrl+Shift+T - New tab
  • Ctrl+Shift+W - Close pane

🧪 CI/CD

GitHub Actions automatically:

  • Validates Nix flake syntax
  • Builds all platform configurations
  • Checks code formatting
  • Validates module structure
  • Tests Fish and Neovim configs
  • Runs security audits

🐛 Troubleshooting

Nix installation fails

If the Determinate installer fails, try the official installer:

sh <(curl -L https://nixos.org/nix/install) --daemon

Fish shell not default after installation

# Find fish path
which fish

# Add to /etc/shells if needed
echo $(which fish) | sudo tee -a /etc/shells

# Change shell
chsh -s $(which fish)

# Log out and back in

Configuration build fails

# Check flake for errors
nix flake check

# Try building with more verbose output
nix build .#homeConfigurations."user@linux".activationPackage --print-build-logs --show-trace

WezTerm config not loading

# Check if config is linked correctly
ls -la ~/.config/wezterm/

# Manually link if needed
ln -sf ~/dotfiles/wezterm/wezterm.lua ~/.config/wezterm/wezterm.lua

Fonts not displaying correctly

Install a Nerd Font. With Nix:

# Add to home.nix packages:
pkgs.nerdfonts

Or manually install JetBrains Mono Nerd Font from Nerd Fonts.

🔧 Advanced Usage

Using the Development Shell

The repository includes a Nix development shell with additional tools:

cd ~/dotfiles
nix develop

# Now you have access to:
# - nixpkgs-fmt (format Nix files)
# - nil (Nix LSP)
# - home-manager CLI

Testing Configuration Changes

Before activating changes system-wide, you can test build them:

# Test build for your platform
nix build .#homeConfigurations."user@linux".activationPackage

# Check flake for errors
nix flake check

# Format Nix files
nixpkgs-fmt **/*.nix

Legacy Installation (Deprecated)

⚠️ Not Recommended: The repository contains legacy bash-based installation scripts (install-legacy.sh and tool-specific install.sh scripts). These are maintained for reference only and are no longer the recommended installation method.

The legacy approach:

  • Used bash scripts to manually install tools
  • Required manual configuration of dotfiles
  • Didn't provide reproducibility guarantees
  • Used Homebrew on macOS, manual installs on Linux

Migration: If you're using the legacy setup, consider migrating to the Nix-based approach for better reproducibility and cross-platform consistency.

📚 Learning Resources

Nix & Home Manager

Tools

🤝 Contributing

Contributions are welcome! Feel free to:

  • Open issues for bugs or feature requests
  • Submit pull requests with improvements
  • Share your customizations

📝 License

This project is licensed under the MIT License.

🙏 Acknowledgments

  • NixOS - For the amazing package manager
  • Home Manager - For user environment management
  • Catppuccin - For the beautiful color scheme
  • mini.nvim - For the modular Neovim plugins
  • All the open source tool maintainers

🔗 Related Projects

Note: This configuration replaces the previous bash-script-based setup with a fully declarative Nix-based approach for better reproducibility and cross-platform support.

About

No description, website, or topics provided.

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages