nix/README.md
2025-07-29 21:59:01 +02:00

784 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Personal Nix Configuration
A comprehensive Nix configuration for macOS using nix-darwin and home-manager, featuring a modern development environment with vim-centric workflows and beautiful aesthetics. Largely generated and maintained with Claude Code.
## ✨ Features
- **🎨 Beautiful UI**: Gruvbox dark theme across all applications
- **⌨️ Vim-centric**: Consistent vim keybindings throughout the stack
- **🚀 Modern CLI**: Enhanced tools with fuzzy finding, syntax highlighting, and smart completion
- **📦 Modular Design**: Separate configuration files for easy maintenance
- **🔄 Portable**: Reproducible across machines with a single command
## 🚀 Quick Install
Install directly from GitHub without cloning:
```bash
# Darwin system configuration
sudo darwin-rebuild switch --flake github:Logan-Lin/nix-config
# Home Manager configuration
home-manager switch --flake github:Logan-Lin/nix-config#yanlin
```
## 📁 Configuration Architecture
```
.
├── flake.nix # Main flake configuration and package definitions
├── tmux.sh # Tmux session automation script
├── modules/ # Nix configuration modules
│ ├── git.nix # Git configuration with aliases and settings
│ ├── nvim.nix # Neovim configuration with plugins and keymaps
│ ├── ssh.nix # SSH client configuration and host management
│ ├── tmux.nix # Tmux setup with vim-like navigation
│ └── zsh.nix # Zsh with Powerlevel10k and modern CLI tools
├── config/ # Configuration files
│ ├── p10k.zsh # Powerlevel10k theme configuration
│ └── projects.nix # Project shortcuts configuration
└── scripts/ # Utility scripts
├── project-launcher.sh # Universal project launcher
└── templates/ # Tmux session templates
├── basic.sh # Basic development template
├── content.sh # Content workflow template
└── research.sh # Research workflow template
```
## 🛠️ Software Configurations
### 📝 Neovim
**Theme**: Gruvbox dark with hard contrast
**Leader Key**: `<Space>`
#### Key Features:
- **File Explorer**: nvim-tree with dotfile filtering
- **Syntax Highlighting**: Treesitter with all grammar support
- **Git Integration**: vim-fugitive for git operations
- **Status Line**: lualine with gruvbox theme and relative paths
- **System Clipboard**: Seamless integration for copy/paste
- **Markdown Rendering**: render-markdown.nvim for beautiful in-buffer markdown preview
#### Keybindings:
| Key | Mode | Action |
|-----|------|--------|
| `<Space>e` | Normal | Toggle file explorer |
| `<Space>w` | Normal | Save file |
| `<Space>q` | Normal | Quit |
| `<Space>o` | Normal | Open file with system default app |
| `<Space>f` | Normal | Show current file in Finder |
| `<Space>y` | Normal/Visual | Copy to system clipboard |
| `<Space>p` | Normal/Visual | Paste from system clipboard |
| `<Space>gs` | Normal | Git status |
| `<Space>gd` | Normal | Git diff |
| `<Space>gc` | Normal | Git commit |
| `<Space>gp` | Normal | Git push |
| `<Space>md` | Normal | Toggle markdown rendering |
### 🖥️ Tmux
**Prefix Key**: `Ctrl+a` (instead of default `Ctrl+b`)
**Theme**: Gruvbox dark with visual prefix indicator
#### Key Features:
- **Prefix Indicator**: Shows `<Prefix>` in status bar when prefix is active
- **Vim-like Navigation**: hjkl for pane movement
- **Smart Splitting**: Maintains current directory when creating panes
- **Copy Mode**: System clipboard integration with pbcopy
#### Keybindings:
| Key | Action |
|-----|--------|
| `Ctrl+a` | Prefix key |
| `Ctrl+a \|` | Split window vertically |
| `Ctrl+a -` | Split window horizontally |
| `Ctrl+a h/j/k/l` | Navigate panes (vim-style) |
| `Ctrl+a H/J/K/L` | Resize panes |
| `Ctrl+a r` | Reload tmux config |
| `Ctrl+a Ctrl+a` | Quick pane cycling |
#### Copy Mode (Ctrl+a [):
| Key | Action |
|-----|--------|
| `v` | Begin selection |
| `y` | Copy selection to system clipboard |
| `r` | Toggle rectangle selection |
### 🌟 Git Configuration
**Configuration**: `modules/git.nix`
**Purpose**: Declarative git configuration with user info, aliases, and sensible defaults
#### Key Features:
- **User Identity**: Name and email managed declaratively
- **SSH Integration**: Disabled credential helper to use SSH keys
- **Comprehensive Aliases**: Shortcuts for common git operations
- **Sensible Defaults**: Cross-platform compatible settings
#### Complete Aliases Reference:
| Alias | Command | Description |
|-------|---------|-------------|
| `git st` | `status` | Show working tree status |
| `git co` | `checkout` | Switch branches or restore files |
| `git br` | `branch` | List, create, or delete branches |
| `git ci` | `commit` | Record changes to repository |
| `git cm "msg"` | `commit -m` | Quick commit with message |
| `git ca` | `commit --amend` | Amend the last commit |
| `git up` | `pull --rebase` | Pull and rebase (cleaner history) |
| `git d` | `diff` | Show unstaged changes |
| `git dc` | `diff --cached` | Show staged changes |
| `git ds` | `diff --stat` | Show diff statistics |
| `git lg` | `log --color --graph...` | Beautiful colored log with graph |
| `git lga` | `log --color --graph... --all` | Same as lg but all branches |
| `git last` | `log -1 HEAD` | Show the last commit |
| `git sl` | `stash list` | List all stashes |
| `git sp` | `stash pop` | Apply and remove latest stash |
| `git ss` | `stash save` | Save current changes to stash |
| `git unstage` | `reset HEAD --` | Remove files from staging area |
| `git visual` | `!gitk` | Launch gitk GUI |
#### Configuration Management:
Edit git settings in `modules/git.nix`, then apply:
```bash
home-manager switch --flake .#yanlin
```
#### Benefits:
-**Reproducible**: Same git config across all machines
-**Version Controlled**: Git settings tracked with other configurations
-**SSH Integration**: Works seamlessly with SSH module
-**Override Defaults**: Properly disables nix's default credential helper
### 🔐 SSH Configuration
**Configuration**: `modules/ssh.nix`
**Purpose**: Declarative SSH client configuration and host management
#### Key Features:
- **Declarative Hosts**: All SSH hosts defined in nix configuration
- **Version Controlled**: SSH config tracked with git alongside other configurations
- **Reproducible**: Same SSH setup deployable across multiple machines
- **Security**: Private keys remain local and untracked
#### Host Management:
Edit SSH hosts in `modules/ssh.nix`, then apply changes:
```bash
home-manager switch --flake .#yanlin
```
#### Configured Hosts:
- **aicloud**: Development server via proxy jump
- **nas**: Network storage server
- **pi**: Raspberry Pi home server
- **cm**: Compute module
- **personal-vps**: Cloud VPS instance
- **zero**: Pi Zero device
- **ucloud-a40**: A40 GPU cluster
- **ucloud-h100**: H100 GPU cluster
#### Security Best Practices:
-**SSH configuration**: Managed by nix (hosts, ports, usernames)
-**Private keys**: Keep local in `~/.ssh/keys/` (not tracked by nix)
-**known_hosts**: Generated locally (not synced)
**Important**: Only the SSH client configuration is managed by nix. Private keys and sensitive data remain local and secure.
### 🐚 Zsh with Powerlevel10k
**Theme**: Powerlevel10k lean style with 2-line prompt
**Vim Mode**: Enabled with visual indicators
#### Key Features:
- **Smart Completion**: Case-insensitive with menu selection
- **Autosuggestions**: Fish-like command suggestions
- **Syntax Highlighting**: Real-time command syntax highlighting
- **History Management**: Shared history with deduplication
- **Vim Mode Indicators**: Cursor shape changes and prompt symbols
#### Vim Mode Indicators:
- **Insert Mode**: Line cursor `|` + `` prompt (green)
- **Normal Mode**: Block cursor `█` + `` prompt
- **Fast Switching**: 10ms escape timeout for responsive mode changes
#### Vim Mode Keybindings:
| Key | Mode | Action |
|-----|------|--------|
| `Esc` | Insert | Switch to normal mode |
| `i/a/I/A` | Normal | Switch to insert mode |
| `k/j` | Normal | History search backward/forward |
| `/` | Normal | History incremental search backward |
| `?` | Normal | History incremental search forward |
| `Ctrl+Right/Left` | Insert | Word movement |
#### Aliases:
**Navigation:**
```bash
l, ll, la # Enhanced ls commands
.., ..., .... # Quick directory navigation
home, config # Jump to common directories
nix-config # Jump to nix configuration
```
**Git:**
```bash
g, gs, ga, gc, gp, gl, gd, gco, gb # Git shortcuts
glog # Beautiful git log with graph
```
**Modern CLI:**
```bash
cat → bat # Syntax highlighted file viewing
find → fd # Fast file finding
grep → rg # Ripgrep for fast searching
top → btop # Beautiful system monitor
```
**Nix:**
```bash
hm # home-manager shortcut
hms # Quick home-manager switch
```
### 🚀 Project Shortcuts
**Configuration**: `config/projects.nix`
**Purpose**: Quick access to project workspaces with tmux sessions
#### Example Projects:
- **`blog`**: Personal blog with code + content workflow
- **`nix-config`**: Nix configuration with basic development workflow
#### Usage:
```bash
proj # List all available projects
blog # Launch blog project tmux session
nix-config # Launch nix-config project tmux session
```
#### Template Types:
- **Basic**: Single directory (nvim + ai + git + shell)
- **Content**: Code directory + separate content directory
- **Research**: Code directory + separate paper directory + optional remote server
#### Research Template Remote Server Support:
The research template supports optional remote server connections with these features:
- **Remote Server Window**: Window 7 with dual horizontal panes for parallel remote work
- **Automatic Connection**: SSH to configured server with automatic directory navigation
- **Reconnect Alias**: Type `r` in any remote pane to easily reconnect after network drops
- **Configuration**: Add `server` and `remoteDir` fields to research projects
**Example Configuration:**
```nix
mdshortcut = {
template = "research";
# ... other fields ...
server = "aicloud"; # SSH host from ~/.ssh/config
remoteDir = "~/MDS"; # Remote directory path
};
```
#### Adding New Projects:
Edit `config/projects.nix` and run `hms` to rebuild configuration.
### 🌟 Git Visualization
**Tool**: lazygit
**Purpose**: Simple terminal UI for git commands with intuitive interface
Launch with `lazygit` in any git repository for:
- Interactive commit graph and branch visualization
- Streamlined staging, committing, and diff viewing
- Easy branch management and merging
- File tree navigation with git status
- Intuitive keyboard shortcuts and help system
### 🌟 Code Editing & Auto-completion
**Tool**: Neovim with NixVim
**Purpose**: Modern text editor with declarative configuration and basic auto-completion
Configured with essential plugins and basic auto-completion for improved productivity:
#### Key Features:
- **Gruvbox theme**: Dark theme with hard contrast for better readability
- **Tree-sitter**: Advanced syntax highlighting for multiple languages
- **File explorer**: nvim-tree for project navigation
- **Auto-completion**: Basic word and path completion without language servers
- **Git integration**: vim-fugitive for version control operations
- **Markdown rendering**: Live preview for documentation
#### Auto-completion Usage:
**Basic completion:**
```
Ctrl+Space # Trigger completion menu manually
Tab # Navigate to next completion item
Shift+Tab # Navigate to previous completion item
Enter # Accept selected completion
Ctrl+e # Close completion menu
```
**Completion sources:**
- **Buffer completion**: Suggests words from currently open files
- **Path completion**: Suggests file and directory paths when typing paths
#### Essential Keybindings:
**File operations:**
```
<leader>e # Toggle file explorer (nvim-tree)
<leader>w # Save current file
<leader>q # Quit current buffer
<leader>o # Open file with system default app
<leader>f # Show current file in Finder
```
**System clipboard:**
```
<leader>y # Copy selection to system clipboard
<leader>p # Paste from system clipboard
```
**Git operations:**
```
<leader>gs # Git status
<leader>gd # Git diff
<leader>gc # Git commit
<leader>gp # Git push
```
**Note**: Leader key is set to spacebar. Basic auto-completion provides word suggestions from open files and path completion without requiring language server setup.
### 🌟 File Synchronization & Backup
**Tool**: rsync
**Purpose**: Declarative file synchronization and backup management
Configured with comprehensive exclude patterns and backup presets:
#### Configuration Files:
- `~/.rsync-exclude` - Common exclude patterns (macOS metadata, temp files)
- `~/.rsync-backup.conf` - Standard backup options with safety features
- `~/.local/bin/rsync-backup` - Convenient backup wrapper script
- `~/.rsync-aliases` - Shell aliases for common operations
#### Usage Examples:
**Using the backup wrapper:**
```bash
# Quick backup with progress and safety
rsync-backup ~/Documents/ /backup/documents/
# The script automatically applies exclude patterns and safety options
```
**Using shell aliases (source ~/.rsync-aliases first):**
```bash
rsync-quick source/ dest/ # Basic backup with progress
rsync-dry source/ dest/ # Dry run for testing (safe)
rsync-sync source/ dest/ # Sync without deleting files
rsync-mirror source/ dest/ # Mirror with delete (exact copy)
```
**Manual rsync with config:**
```bash
# Use the backup configuration file
rsync $(cat ~/.rsync-backup.conf | grep -v '^#' | tr '\n' ' ') source/ dest/
# Or with custom exclude patterns
rsync -avh --progress --exclude-from=~/.rsync-exclude source/ dest/
```
**Features:**
- Automatic exclusion of temporary files and macOS metadata
- Progress indication and compression for network transfers
- Safety options including partial transfers and dry-run capability
- Preserves extended attributes and ACLs on macOS
### 🌟 Reference Management
**Tool**: papis
**Purpose**: Command-line reference manager for academic papers and documents
A powerful bibliography manager that stores documents and metadata in a human-readable format:
#### Key Features:
- **Document Library**: Centralized storage at `~/Documents/Library/papis`
- **BibTeX Integration**: Import/export references in standard academic formats
- **PDF Management**: Automatic file organization and retrieval
- **Search & Filter**: Fast document discovery with fuzzy finding (fzf)
- **Metadata Storage**: Human-readable YAML files for bibliographic data
- **Editor Integration**: Configured with nvim for editing document metadata
#### Usage Examples:
**Adding documents:**
```bash
# Add a paper from DOI
papis add --from doi 10.1000/example.doi
# Add a PDF file with interactive metadata entry
papis add paper.pdf
# Add from arXiv
papis add --from arxiv 2301.12345
# Add from URL
papis add --from url https://example.com/paper.pdf
```
**Searching and browsing:**
```bash
# List/search documents
papis list
papis list "machine learning"
papis list author:smith year:2023
# Open documents (uses fzf picker)
papis open
papis open bohm
# Open document folder
papis open -d einstein
```
**Document management:**
```bash
# Edit document metadata
papis edit bohm
# Export to BibTeX
papis export --all --format bibtex > references.bib
papis export --format bibtex query_term > references.bib
# List documents with custom format
papis list --format '{doc[author]} - {doc[title]} ({doc[year]})'
```
**Workflow Aliases:**
```bash
# Bibliography formatting
pals # List documents with formatted template
pals "machine learning" # Search and format specific documents
# File operations
pafile filename.pdf [query] # Add file from ~/Downloads/ to existing entry
paurl [url] [query] # Add file from URL to existing entry
# Directory access (shell function)
pafinder # Open first document directory in Finder
pafinder "query" # Open first matching document directory
pafinder author:einstein # Open first Einstein paper directory
pafinder --sort year smith # Open newest Smith paper directory
```
**Configuration location**: `modules/papis.nix` with embedded configuration
**Main library**: `~/Documents/Library/papis`
**Editor**: nvim (configured automatically)
**Picker**: fzf for interactive document selection
### 🌟 Python Development & Package Management
**Tool**: uv
**Purpose**: Extremely fast Python package installer and resolver, written in Rust
A modern replacement for pip, virtualenv, pip-tools, and more - providing 10-100x faster performance:
#### Key Features:
- **Unified toolchain**: Single tool replaces pip, virtualenv, pip-tools, poetry, and more
- **High performance**: 10-100x faster than pip with global caching and Rust implementation
- **Drop-in compatibility**: Works with existing requirements.txt files and PyPI packages
- **Modern dependency resolution**: Better handling of complex dependency trees
- **Virtual environment management**: Automatic venv creation and management
#### Usage Examples:
**Project initialization and management:**
```bash
# Create a new Python project
uv init my-project
cd my-project
# Add dependencies (creates/updates pyproject.toml)
uv add requests pandas numpy
# Add development dependencies
uv add --dev pytest black isort
# Install dependencies from requirements.txt or pyproject.toml
uv sync
```
**Virtual environment management:**
```bash
# Create virtual environment (automatic when needed)
uv venv
# Activate virtual environment
source .venv/bin/activate
# Install packages in virtual environment
uv pip install package-name
# Run commands in virtual environment context
uv run python script.py
uv run pytest
```
**Package installation and management:**
```bash
# Install packages (faster than pip)
uv pip install requests
uv pip install -r requirements.txt
# Upgrade packages
uv pip install --upgrade package-name
# Install specific versions
uv pip install "django>=4.0,<5.0"
```
**Tool usage (like pipx):**
```bash
# Install and run CLI tools
uv tool install black
uv tool run black --help
# Run tools without installing
uv tool run ruff check .
```
**Migration from pip/virtualenv:**
- Replace `pip install` with `uv pip install` for faster installs
- Replace `python -m venv` with `uv venv` for faster environment creation
- Use `uv add` instead of manually editing requirements.txt
- Use `uv sync` to install from lock files for reproducible environments
## 📦 Included Packages
### Development Tools
- **Python 3.12**: With uv (modern Python package manager)
- **LaTeX**: Full TeXLive distribution
- **Claude Code**: AI-powered coding assistant
- **Git UI**: Beautiful git graph visualization
### CLI Utilities
- **fzf**: Fuzzy finder for files, commands, and history
- **fd**: Fast, user-friendly alternative to find
- **ripgrep (rg)**: Fast text search
- **bat**: Syntax-highlighted cat replacement
- **btop**: Modern system monitor
- **httpie**: Modern HTTP client for API testing
- **lazysql**: LazyGit-style TUI database management tool
- **sqlite3**: Official SQLite command-line interface
- **lftp**: Scriptable FTP client for automation
- **termscp**: Comprehensive TUI file transfer client (FTP/SFTP/SCP/S3)
- **rsync**: Fast file synchronization and backup with comprehensive configuration
- **zoxide**: Smart cd with frecency algorithm
#### fd Usage Examples
```bash
fd filename # Find files/directories named "filename"
fd "*.nix" # Find all Nix files
fd -t f config # Only files (-t f = type file)
fd -t d config # Only directories (-t d = type directory)
fd -e js # All files with .js extension
fd -H hidden # Include hidden files (-H)
fd | fzf # Pipe to fzf for interactive selection
```
#### fzf Usage Examples
```bash
fzf # Interactive file finder
ls | fzf # Fuzzy find from any list
history | fzf # Search command history
fd | fzf # Fast file finding with fuzzy selection
fd -t d | fzf # Find and select directories only
rg "pattern" | fzf # Search text then fuzzy filter results
# Preview files while browsing
fzf --preview 'bat --style=numbers --color=always {}'
```
**Built-in zsh keybindings:**
- `Ctrl+T` - Insert selected files/directories into command line
- `Ctrl+R` - Search command history interactively
- `Alt+C` - Change to selected directory
#### httpie Usage Examples
```bash
# Simple HTTP requests
http GET api.example.com/users
http POST api.example.com/users name="John" email="john@example.com"
http PUT api.example.com/users/1 name="Jane"
http DELETE api.example.com/users/1
# With authentication headers
http GET api.example.com/protected Authorization:"Bearer your-token"
http GET api.example.com/api X-API-Key:"your-api-key"
```
#### lazysql Usage Examples
```bash
# Launch TUI database management (LazyGit-style interface)
lazysql
# Connect to different databases
lazysql -h localhost -u username -p password -d database_name # MySQL
lazysql --url postgres://user:pass@localhost/dbname # PostgreSQL
lazysql --url sqlite://./database.db # SQLite
lazysql --url "mysql://user:pass@localhost/db" # MySQL URL format
# With config file (recommended for credentials)
lazysql --config ~/.config/lazysql/config.yml
# Interactive TUI operations:
# - Navigate tables with j/k (vim-style)
# - View table structure and data
# - Execute SQL queries in editor mode
# - Export query results
# - Browse database schema
```
**Key lazysql features:**
- **LazyGit-inspired interface**: Familiar navigation for developers
- **Multi-database support**: MySQL, PostgreSQL, SQLite
- **SQL editor**: Syntax highlighting and query execution
- **Export capabilities**: Save query results to files
- **Connection management**: Save and reuse database connections
#### sqlite3 Usage Examples
```bash
# Connect to SQLite database
sqlite3 ai.db
# One-liner queries (no interactive session)
sqlite3 ai.db "SELECT COUNT(*) FROM users;"
sqlite3 ai.db "SELECT * FROM users WHERE active = 1;"
# Common SQLite dot commands (inside sqlite3 shell)
.tables # List all tables
.schema # Show all table schemas
.schema users # Show specific table schema
.mode csv # Set output format (csv, json, html, etc.)
.headers on # Show column headers
.output results.csv # Redirect output to file
.output stdout # Reset output to terminal
# Import/Export operations
.backup backup.db # Create database backup
.restore backup.db # Restore from backup
.dump # Export entire database as SQL
.dump users # Export specific table as SQL
# Execute SQL script file
.read script.sql # Run SQL commands from file
sqlite3 ai.db < script.sql # Alternative: pipe script to sqlite3
# Database inspection
.dbinfo # Show database information
.indices table_name # Show indexes for table
.exit # Exit sqlite3 shell
```
**Key sqlite3 features:**
- **Universal compatibility**: Works with any SQLite database
- **Scriptable**: Perfect for automation and batch operations
- **Lightweight**: Minimal overhead for quick queries
- **Import/Export**: Built-in CSV, JSON, and SQL dump capabilities
- **Backup tools**: Simple database backup and restore operations
#### termscp Usage Examples
```bash
# Launch TUI file transfer client
termscp
ftp # Alias for termscp
# Quick connections
termscp ftp://user@host.com
termscp sftp://user@host.com:2222
termscp scp://user@host.com
# Advanced features
termscp --config # Configure settings and bookmarks
termscp --version # Show version information
```
**Key termscp features:**
- **Rich TUI**: Interactive file browser with dual-pane view
- **Multi-protocol**: FTP, SFTP, SCP, S3, WebDAV support
- **Bookmarks**: Save frequently accessed servers
- **File operations**: Create, rename, delete, search, edit files
- **Synchronization**: Sync directories between local and remote
- **Themes**: Customizable interface themes
#### Powerful Tool Combinations
```bash
# Find and open file with nvim using interactive selection
nvim $(fd --type f | fzf)
# Find and edit Nix configuration files
nvim $(fd "*.nix" | fzf)
# Search text content and open matching file
nvim $(rg -l "search_term" | fzf)
# Preview files while selecting which one to edit
nvim $(fd --type f | fzf --preview 'bat --color=always {}')
# Find and edit files in specific directory
nvim $(fd --type f . ~/.config | fzf)
```
### Fonts
- **Nerd Fonts**: FiraCode and JetBrains Mono with icon support
## 🔄 Usage & Workflow
### Daily Workflow
1. **Terminal**: Beautiful zsh with vim mode and modern tools
2. **Tmux**: Session management with vim navigation
3. **Neovim**: Code editing with git integration
4. **Git UI**: Visual git operations and branch management
### Environment Management
```bash
# Refresh shell environment after nix changes
exec zsh
# Update and rebuild configuration
nix flake update
sudo darwin-rebuild switch --flake .
home-manager switch --flake .#yanlin
# Quick home-manager rebuild
hms
```
### Clipboard Integration
The configuration provides seamless clipboard integration:
- **Neovim**: `<Space>y/p` for system clipboard
- **Tmux**: Copy mode automatically uses system clipboard
- **Terminal**: Standard Cmd+C/V works everywhere
## 💻 Machine Configurations
- **`iMac`**: iMac configuration
- **`MacBook-Air`**: MacBook Air configuration
Both machines use the same base configuration with potential for machine-specific customizations.
### Machine-specific Usage:
```bash
# For MacBook Air
sudo darwin-rebuild switch --flake .#MacBook-Air
# For iMac
sudo darwin-rebuild switch --flake .#iMac
```