dotfiles/README.md

ADLee's Dotfiles

Personal configuration for a productive development environment on Arch Linux and CachyOS.

ADLee Theme Prompt

┌｢alee@catchthesethighs｣ ｢~/.dotfiles ⎇ main｣ ｢⇑3｣ 
└%

Quick Start

git clone https://github.com/adlee-was-taken/dotfiles.git ~/.dotfiles
cd ~/.dotfiles && ./install.sh

See INSTALL.md for detailed instructions.

---

Features Overview

Category	Features
Shell	Two-line prompt • Command timer • Git integration • Smart suggestions • Command palette (Ctrl+Space)
Automation	Auto-load project environments • Long-running command notifications • Machine-specific configs
Diagnostics	Enhanced analytics • Startup profiling • Security audits • Health checks • Testing framework
Tmux	Simple templates • Tmuxinator integration • Workspace management • Layout saving
System	Systemd helpers • Btrfs utilities • Snapper snapshots with limine integration
Development	Python project templates • SSH manager • Password manager • Secrets vault
Tools	Plugin manager • FZF extras • Directory bookmarks • Custom MOTD

---

Core Commands

Dotfiles Management

Command	Alias	Description
dotfiles-doctor.sh	dfd	Health check and diagnostics
dotfiles-doctor.sh --fix	dffix	Auto-fix common issues
dotfiles-sync.sh push	dfpush	Push changes to git
dotfiles-sync.sh pull	dfpull	Pull latest changes
dotfiles-update.sh	dfu	Update dotfiles from repo
dotfiles-vault.sh	vault	Manage encrypted secrets
source ~/.zshrc	reload	Reload shell configuration

Quick Edit: v.zshrc, v.conf, v.alias, v.motd, v.theme

New Commands

Command	Description
dotfiles-analytics.sh	Enhanced history analytics (hourly, weekly, trends, suggestions)
dotfiles-profile.sh	Startup time profiling and optimization tips
dotfiles-diff.sh	Show changes, audit security, check permissions
dotfiles-tour.sh	Interactive tour and feature walkthrough
dotfiles-compile.sh	Compile zsh files for faster startup
dftest	Run test suite

---

Systemd Helpers

Command	Description
sc <args>	sudo systemctl <args>
scr <service>	Restart + show status
sce <service>	Enable + start
scd <service>	Disable + stop
sclog <service>	Follow journal logs
sc-failed	Show failed services
sc-boot	Boot time analysis
sc-search <query>	Search for services
scf	Interactive manager (fzf)

Additional: scs (status), scstart, scstop, screload, sc-timers, jctl, jctlf

---

Btrfs & Snapper

Btrfs Commands

Command	Alias	Description
btrfs-usage	btru	Filesystem usage statistics
btrfs-health	btrh	Quick health check
btrfs-scrub	-	Start data integrity check
btrfs-balance	-	Balance filesystem
btrfs-compress	btrc	Compression statistics
btrfs-info	btri	Full filesystem information

Snapper Snapshots

Command	Alias	Description
snap-create "desc"	snap	Create snapshot
snap-list	snapls	List recent snapshots
snap-check	snapcheck	Verify limine boot menu sync
sys-update	-	System update with pre/post snapshots
sys-rollback <num>	rollback	Rollback to snapshot

Note: Snapshots automatically sync to limine boot menu via limine-snapper-sync service.

---

Tmux Workspaces

Tmuxinator-based workspace management for complex projects with per-pane commands, environment variables, and startup scripts.

Commands

Command	Alias	Description
txi <name>	-	Start/attach tmuxinator project
txi-new <n> [tmpl]	txin	Create project (dev, ops, web, data, minimal)
txi-edit <name>	txie	Edit project YAML
txi-list	txil	List projects
txi-delete <name>	txid	Delete project
txif	-	Fuzzy search projects
txi-templates	txit	Show available templates

---

Machine-Specific Configuration

Per-machine settings that sync via git without conflicts.

Commands

Command	Description
machine-info	Show current machine detection
machine-create	Create config for this machine
machine-edit	Edit machine config
machines	List all machine configs

Configuration Hierarchy

1. dotfiles.conf (base settings)
2. machines/default.zsh (shared overrides)
3. machines/type-<type>.zsh (laptop/desktop/server/virtual)
4. machines/<hostname>.zsh (machine-specific)
5. ~/.zshrc.local (local, not synced)

Auto-Detection: Automatically loads correct config based on hostname and hardware.

---

Project Environments

Automatically activates project-specific settings when entering directories.

Commands

Command	Description
project-env status	Show current configuration
project-env create	Create .dotfiles-local in current directory
project-env edit	Edit current project's settings
project-env allow <file>	Trust a project environment file
project-env on/off	Enable/disable auto-loading

Features

• Auto-loads .dotfiles-local, .envrc, or .env.local files
• Auto-activates Python virtualenvs
• Auto-switches Node versions via .nvmrc
• Security prompts for untrusted directories
• Trusted directory configuration

---

Command Palette & Bookmarks

Command Palette (Ctrl+Space)

Fuzzy search through:

• Aliases and functions
• Command history
• Git commands
• Bookmarks
• Quick actions

Directory Bookmarks

Command	Alias	Description
bookmark add <name> [path]	bm	Save bookmark
bookmark list	bm list	List bookmarks
bookmark go <name>	bmg	Jump to bookmark
bm	-	Fuzzy search bookmarks (fzf)

---

Enhanced Analytics & Profiling

Analytics Commands

Command	Description
dotfiles-analytics.sh	Dashboard with top commands
dfanalytics hourly	Commands by hour of day
dfanalytics weekly	Usage by day of week
dfanalytics projects	Commands grouped by directory
dfanalytics trends	30-day usage trends
dfanalytics tools	Tool usage breakdown (Git, Docker, etc.)
dfanalytics suggestions	Alias suggestions and typo detection

Profiling Commands

Command	Description
dotfiles-profile.sh	Quick startup time measurement (5 runs)
dfprofile --detailed	Function-level analysis with zprof
dfprofile --benchmark	Hyperfine benchmark (if installed)
dfprofile --compare	Compare full shell vs minimal
dfprofile --tips	Optimization suggestions

---

Security & Diagnostics

Diff & Audit

Command	Description
dotfiles-diff.sh	Show uncommitted git changes
dfdiff --installed	Compare installed vs source files
dfdiff --symlinks	Verify symlink integrity
dfdiff --secrets	Scan for exposed secrets
dfdiff --permissions	Check file permissions
dfdiff --audit	Full security audit

Notifications

Command	Description
notify-toggle	Enable/disable notifications
notify-status	Show configuration and capabilities
notify-test	Send test notification

Configuration: Desktop notifications + terminal bell for commands >60s (configurable).

---

Plugin Manager

Lightweight plugin management without heavy frameworks.

Command	Description
plugin install <repo>	Install from GitHub (e.g., zsh-users/zsh-autosuggestions)
plugin load <name>	Load installed plugin
plugin lazy <n> <cmds>	Lazy-load plugin on command use
plugin update	Update all plugins
plugin list	List installed plugins
plugin remove <name>	Remove plugin
plugin recommended	Show recommended plugins

---

FZF Extras

Enhanced fuzzy finders for system exploration.

Command	Description
envf	Browse environment variables
pathf	Explore PATH directories
procf	Process manager with actions
killf	Fuzzy kill processes
aliasf	Browse aliases
funcf	Browse functions
histf	Enhanced history search
ff [dir]	Find files
ffo [dir]	Find and open file
fdir [dir]	Find and cd to directory
gbf	Git branch switcher
glogf	Git commit browser

---

Secrets & Passwords

Vault (Encrypted Storage)

Command	Description
vault init	Initialize encrypted vault
vault set <key>	Store secret
vault get <key>	Retrieve secret
vault list	List stored keys
vault shell	Export secrets to environment

Password Manager (LastPass)

Command	Description
pw <query>	Search and copy password
pw show <item>	Show entry details
pw list	List all entries
pw gen [len]	Generate password (default: 20 chars)
pwf	Fuzzy search (fzf)

---

Python Project Templates

Command	Alias	Template
py-new <name>	pynew	Basic Python project
py-flask <name>	pyflask	Flask web application
py-fastapi <name>	pyfast	FastAPI REST API
py-cli <name>	pycli	CLI tool with Click
py-data <name>	pydata	Data science project with Jupyter
venv	-	Activate virtualenv (auto-detects)

All templates include: virtual environment, .gitignore, git initialization, and dependencies.

---

SSH Manager

Command	Alias	Description
ssh-save <n> <user@host>	sshs	Save connection profile
ssh-connect <name>	sshc	Connect (auto-creates tmux session)
ssh-list	sshl	List saved profiles
sshf	-	Fuzzy search connections

Profiles support: custom ports, SSH keys, options, and auto-tmux integration.

---

Testing Framework

Simple unit testing for shell functions.

# Run all tests
dftest

# Run specific test file
dftest utils

# Write tests (tests/test_*.zsh)
describe "my function"
it "should do something"
assert_eq "$(my_func)" "expected"

---

Common Aliases

Navigation

.., ..., ...., ~, c. (dotfiles dir)

Git

g, gs (status), ga (add), gc (commit), gp (push), gl (pull), gd (diff), gco (checkout), gb (branch), glog

Docker

d, dc (compose), dps, dpa, di (images), dex (exec -it)

System

h (history), c (clear), myip, ports

Tool Integration

• ls/ll/la/lt → eza (if installed)
• cat → bat (if installed)

---

Configuration

Edit ~/.dotfiles/dotfiles.conf for global settings:

# Display
DF_WIDTH="74"
MOTD_STYLE="compact"          # compact, mini, full, none

# Features
ENABLE_SMART_SUGGESTIONS="true"
ENABLE_COMMAND_PALETTE="true"
ENABLE_SHELL_ANALYTICS="false"

# Notifications
DF_NOTIFY_ENABLED="true"
DF_NOTIFY_THRESHOLD="60"
DF_NOTIFY_METHODS="desktop bell"

# Project Environments
DF_PROJECT_ENV_ENABLED="true"
DF_PROJECT_AUTO_VENV="true"
DF_PROJECT_AUTO_NVM="true"

# Tmuxinator
TMUXINATOR_ENABLED="auto"
TW_PREFER_TMUXINATOR="true"

# Plugin Manager
DF_PLUGIN_DIR="$HOME/.dotfiles/zsh/plugins"

Local Overrides

• ~/.zshrc.local - User-specific settings (not synced)
• machines/<hostname>.zsh - Machine-specific config (synced)

---

Repository Structure

~/.dotfiles/
├── install.sh              # Main installer
├── dotfiles.conf           # Central configuration
├── bin/                    # Management scripts
│   ├── dotfiles-doctor.sh
│   ├── dotfiles-sync.sh
│   ├── dotfiles-analytics.sh
│   ├── dotfiles-profile.sh
│   ├── dotfiles-diff.sh
│   ├── dotfiles-tour.sh
│   └── ...
├── zsh/
│   ├── .zshrc
│   ├── aliases.zsh
│   ├── lib/                # Core libraries
│   │   ├── bootstrap.zsh   # Single entry point
│   │   ├── config.zsh
│   │   ├── colors.zsh
│   │   ├── utils.zsh
│   │   ├── machines.zsh
│   │   └── plugins.zsh
│   ├── themes/adlee.zsh-theme
│   └── functions/          # Feature modules
│       ├── motd.zsh
│       ├── command-palette.zsh
│       ├── tmuxinator.zsh
│       ├── project-env.zsh
│       ├── notifications.zsh
│       ├── fzf-extras.zsh
│       ├── systemd-helpers.zsh
│       ├── btrfs-helpers.zsh
│       ├── snapper.zsh
│       ├── ssh-manager.zsh
│       ├── password-manager.zsh
│       ├── python-templates.zsh
│       └── smart-suggest.zsh
├── machines/               # Per-machine configs
│   ├── default.zsh
│   ├── type-laptop.zsh
│   └── type-server.zsh
├── tests/                  # Test framework
│   ├── run-tests.zsh
│   └── test_*.zsh
├── vim/.vimrc
├── tmux/.tmux.conf
├── espanso/                # Text expansion
└── setup/                  # Setup wizards

---

First-Run Experience

After installation, run the interactive tour:

dotfiles-tour.sh          # Full interactive walkthrough
dotfiles-tour.sh --quick  # Quick reference card

Or verify installation:

dfd              # Health check
dftest           # Run tests
dfprofile        # Check startup time

---

Recommended Workflow

1. Initial Setup

   ./install.sh
   dotfiles-tour.sh
   machine-create  # Create machine-specific config
   

2. Daily Use

   Ctrl+Space      # Command palette
   tw myproject    # Start workspace
   dfd             # Regular health checks
   

3. Customization

   v.conf          # Edit configuration
   machine-edit    # Edit machine config
   plugin install  # Add plugins
   

4. Maintenance

   dfupdate        # Pull latest changes
   dfprofile       # Check performance
   dfaudit         # Security audit
   plugin update   # Update plugins
   

---

Optimization Tips

1. Startup Time

   dfprofile --tips        # Get optimization suggestions
   dfcompile              # Compile zsh files
   plugin lazy <name>     # Lazy-load heavy plugins
   

2. Analytics

   dfanalytics suggestions  # Find alias opportunities
   dfanalytics tools       # Identify unused tools
   

3. Machine-Specific

   • Laptops: Use MOTD_STYLE="mini" for faster startup
   • Servers: Disable DF_NOTIFY_ENABLED="false"
   • VMs: Use type-virtual.zsh for minimal features

---

License

MIT License - See LICENSE

Author: Aaron D. Lee
Repository: https://github.com/adlee-was-taken/dotfiles
Version: 1.2.4