Dotfiles Improvements
This directory contains suggested improvements for your dotfiles project. These additions enhance functionality, maintainability, and user experience.
Summary of Additions
| Category | Files Added | Description |
|---|---|---|
| Machine Config | zsh/lib/machines.zsh, machines/*.zsh |
Per-machine configuration support |
| Performance | bin/dotfiles-profile.sh |
Startup time profiling |
| Notifications | zsh/functions/notifications.zsh |
Long-running command notifications |
| Security | bin/dotfiles-diff.sh |
Diff, audit, and secret detection |
| Project Env | zsh/functions/project-env.zsh |
Auto-load project environments |
| Analytics | bin/dotfiles-analytics.sh |
Enhanced history analytics |
| Testing | tests/run-tests.zsh, tests/test_*.zsh |
Unit testing framework |
| First-Run | bin/dotfiles-tour.sh |
Interactive tour and changelog |
| FZF Extras | zsh/functions/fzf-extras.zsh |
Additional fuzzy finders |
| Plugin Mgr | zsh/lib/plugins.zsh |
Lightweight plugin management |
Installation
Option 1: Copy All Files
# Backup first
cp -r ~/.dotfiles ~/.dotfiles.backup.$(date +%Y%m%d)
# Copy improvements
cp -r /path/to/improvements/* ~/.dotfiles/
Option 2: Selective Installation
Copy only the features you want:
# Machine-specific configs
cp zsh/lib/machines.zsh ~/.dotfiles/zsh/lib/
mkdir -p ~/.dotfiles/machines
cp machines/*.zsh ~/.dotfiles/machines/
# Notifications
cp zsh/functions/notifications.zsh ~/.dotfiles/zsh/functions/
# Profiling
cp bin/dotfiles-profile.sh ~/.dotfiles/bin/
chmod +x ~/.dotfiles/bin/dotfiles-profile.sh
Option 3: Integration
Add to your .zshrc to load new features:
# In ~/.dotfiles/zsh/.zshrc, add after other sources:
# Load machine-specific configuration
[[ -f "$DOTFILES_DIR/zsh/lib/machines.zsh" ]] && \
source "$DOTFILES_DIR/zsh/lib/machines.zsh"
# Load notifications
[[ -f "$DOTFILES_DIR/zsh/functions/notifications.zsh" ]] && \
source "$DOTFILES_DIR/zsh/functions/notifications.zsh"
# Load project environments
[[ -f "$DOTFILES_DIR/zsh/functions/project-env.zsh" ]] && \
source "$DOTFILES_DIR/zsh/functions/project-env.zsh"
# Load FZF extras
[[ -f "$DOTFILES_DIR/zsh/functions/fzf-extras.zsh" ]] && \
source "$DOTFILES_DIR/zsh/functions/fzf-extras.zsh"
Feature Details
1. Machine-Specific Configuration
Files: zsh/lib/machines.zsh, machines/*.zsh
Automatically loads different settings based on hostname or machine type.
# See current machine detection
machine-info
# Create config for this machine
machine-create
# Edit machine config
machine-edit
# List all machine configs
machines
Configuration hierarchy:
dotfiles.conf(base)machines/default.zsh(shared overrides)machines/type-<type>.zsh(laptop/desktop/server/virtual)machines/<hostname>.zsh(machine-specific)~/.zshrc.local(local, not synced)
2. Startup Profiling
File: bin/dotfiles-profile.sh
Measure and optimize shell startup time.
dotfiles-profile.sh # Quick timing (5 runs)
dotfiles-profile.sh --detailed # zprof function-level analysis
dotfiles-profile.sh --benchmark # Hyperfine benchmark
dotfiles-profile.sh --compare # Full vs minimal shell
dotfiles-profile.sh --tips # Optimization suggestions
dotfiles-profile.sh --all # Run everything
3. Long-Running Command Notifications
File: zsh/functions/notifications.zsh
Get notified when commands taking longer than 60 seconds complete.
# Toggle notifications
notify-toggle
# Test notification
notify-test
# Show status
notify-status
# Adjust threshold
df_notify_threshold 120 # 2 minutes
Configuration in dotfiles.conf:
DF_NOTIFY_ENABLED="true"
DF_NOTIFY_THRESHOLD="60"
DF_NOTIFY_METHODS="desktop bell"
4. Diff & Security Audit
File: bin/dotfiles-diff.sh
Compare configurations and audit for security issues.
dotfiles-diff.sh # Show uncommitted changes
dotfiles-diff.sh --installed # Compare installed vs source
dotfiles-diff.sh --symlinks # Verify symlink integrity
dotfiles-diff.sh --secrets # Scan for exposed secrets
dotfiles-diff.sh --permissions # Check file permissions
dotfiles-diff.sh --audit # Full security audit
5. Project-Local Environments
File: zsh/functions/project-env.zsh
Auto-load project settings when entering directories (like direnv).
# Create project env file
project-env create
# Edit current project's env
project-env edit
# Show status
project-env status
# Allow/deny files
project-env allow .dotfiles-local
project-env deny .dotfiles-local
Features:
- Auto-loads
.dotfiles-local,.envrc, or.env.local - Auto-activates Python virtualenvs
- Auto-switches Node versions via
.nvmrc - Security prompts for untrusted directories
6. Enhanced Shell Analytics
File: bin/dotfiles-analytics.sh
Advanced command history analysis.
dotfiles-analytics.sh # Dashboard
dotfiles-analytics.sh hourly # Commands by hour
dotfiles-analytics.sh weekly # Usage by day of week
dotfiles-analytics.sh projects # Group by directory
dotfiles-analytics.sh trends # 30-day trends
dotfiles-analytics.sh complexity # Command complexity
dotfiles-analytics.sh tools # Tool usage breakdown
dotfiles-analytics.sh suggestions # Alias suggestions
7. Testing Framework
Files: tests/run-tests.zsh, tests/test_*.zsh
Simple unit testing for shell functions.
# Run all tests
./tests/run-tests.zsh
# Run specific test file
./tests/run-tests.zsh utils
# Or use alias
dftest
Writing tests:
describe "my function"
it "should do something"
assert_eq "$(my_func)" "expected"
it "should handle errors"
assert_fail "my_func invalid_arg"
8. First-Run Experience & Tour
File: bin/dotfiles-tour.sh
Interactive introduction for new users.
dotfiles-tour.sh # Interactive tour
dotfiles-tour.sh --quick # Quick reference card
dotfiles-tour.sh --changelog # Recent changes
9. FZF Extras
File: zsh/functions/fzf-extras.zsh
Additional fuzzy finders.
| Command | Description |
|---|---|
envf |
Browse environment variables |
pathf |
Explore PATH directories |
procf |
Process manager |
killf |
Fuzzy kill processes |
aliasf |
Browse aliases |
funcf |
Browse functions |
histf |
Enhanced history search |
ff |
Find files |
fdir |
Find directories |
gbf |
Git branch switcher |
glogf |
Git commit browser |
10. Plugin Manager
File: zsh/lib/plugins.zsh
Lightweight plugin management without heavy frameworks.
# Install a plugin
plugin install zsh-users/zsh-autosuggestions
# List plugins
plugin list
# Update all plugins
plugin update
# Remove a plugin
plugin remove zsh-autosuggestions
# Show recommended plugins
plugin recommended
# Lazy-load a plugin
plugin lazy zsh-nvm nvm node npm
New Aliases Reference
| Alias | Command | Description |
|---|---|---|
dfprofile |
dotfiles-profile.sh |
Startup profiling |
dfdiff |
dotfiles-diff.sh |
Show changes |
dfaudit |
dotfiles-diff.sh --audit |
Security audit |
dftour |
dotfiles-tour.sh |
Interactive tour |
dfanalytics |
dotfiles-analytics.sh |
Enhanced analytics |
dftest |
tests/run-tests.zsh |
Run tests |
quickref |
dotfiles-tour.sh --quick |
Quick reference |
profile |
dotfiles-profile.sh |
Startup profiling |
audit |
dotfiles-diff.sh --audit |
Security audit |
tour |
dotfiles-tour.sh |
Interactive tour |
Configuration Options
Add to dotfiles.conf:
# === NEW: Notification Settings ===
DF_NOTIFY_ENABLED="true"
DF_NOTIFY_THRESHOLD="60"
DF_NOTIFY_METHODS="desktop bell"
DF_NOTIFY_SOUND="/usr/share/sounds/freedesktop/stereo/complete.oga"
DF_NOTIFY_ONLY_FAILURES="false"
# === NEW: Project Environment ===
DF_PROJECT_ENV_ENABLED="true"
DF_PROJECT_ENV_FILES=".dotfiles-local .envrc .env.local"
DF_PROJECT_ENV_TRUSTED_DIRS="$HOME/projects $HOME/work"
DF_PROJECT_AUTO_VENV="true"
DF_PROJECT_AUTO_NVM="true"
# === NEW: Plugin Manager ===
DF_PLUGIN_DIR="$HOME/.dotfiles/zsh/plugins"
Verification
After installation, verify everything works:
# Health check
dfd
# Run tests
dftest
# Profile startup
dfprofile
# Security audit
dfaudit
# Take the tour
dftour
File Structure
dotfiles-improvements/
├── bin/
│ ├── dotfiles-analytics.sh # Enhanced history analytics
│ ├── dotfiles-diff.sh # Diff and security audit
│ ├── dotfiles-profile.sh # Startup profiling
│ └── dotfiles-tour.sh # First-run experience
├── machines/
│ ├── default.zsh # Shared machine config
│ ├── type-laptop.zsh # Laptop-specific
│ └── type-server.zsh # Server-specific
├── tests/
│ ├── run-tests.zsh # Test runner
│ ├── test_config.zsh # Config tests
│ └── test_utils.zsh # Utils tests
├── zsh/
│ ├── aliases-extended.zsh # Extended aliases
│ ├── functions/
│ │ ├── fzf-extras.zsh # Additional fzf utilities
│ │ ├── notifications.zsh # Command notifications
│ │ └── project-env.zsh # Project environments
│ └── lib/
│ ├── machines.zsh # Machine detection
│ └── plugins.zsh # Plugin manager
└── README.md # This file