Skip to content

🛠️ ZSHAND Functions Reference¶

📋 Reusable utility functions loaded at startup. Available in every terminal session. Each function file includes a documentation header with USAGE, DEPENDENCIES, EXAMPLES, and SEE ALSO.

🛤️ Path Functions¶

Function	Usage	Purpose
`add_path`	`add_path ~/bin`	Safely add to PATH (`-a` append, `-r` recursive)
`zpath`	`zpath`	Audit PATH, fpath, manpath
`pathfix`	`pathfix`	Audit and repair PATH (missing dirs, duplicates)

🔀 Git Functions¶

Function	Usage	Purpose
`tossh`	`tossh [dir]`	Convert GitHub HTTPS remotes to SSH
`gundo`	`gundo`	Git undo menu (unstage, soft reset, squash, hard reset)
`gitprune`	`gitprune`	Delete merged local branches
`_gitid`	(chpwd hook)	Auto Git identity from project `.env`

🖥️ System Functions¶

Function	Usage	Purpose
`health`	`health`	Environment health check (cache, runtimes, Atuin, SSH, clipboard, disk)
`pkgsync`	`pkgsync`	Verify package sync (core + optional, MCHOSE bins, clipboard)
`zports`	`zports [term]`	Active network listeners (lsof)
`ztop`	`ztop`	Workstation dashboard (uptime, Git, cache, zpulse)
`extract`	`extract <file>`	Universal archive extraction (optional delete source)
`zopt`	`zopt [pattern]`	List Zsh options (optional filter)
`tog`	`tog <option>`	Toggle Zsh option on/off (e.g. `tog autocd`)

🔧 Helper Functions¶

Function	Usage	Purpose
`dcopy`	`dcopy`	Copy CWD path to clipboard
`fcopy`	`fcopy <file>`	Copy file contents to clipboard
`zbak`	`zbak <file>`	Timestamped backup to `.backups`
`fnew`	`fnew <name>`	Create function stub and open in editor
`google`	`google "query"`	Open Google search in browser
`jfmt`	`jfmt [file]`	Pretty-print JSON (file or stdin)
`seek`	`seek "pattern"`	Search zshand files (ripgrep)

📊 Logging Functions¶

Function	Usage	Purpose
`zlog`	`zlog [cmd]`	View session log (summary, `-t`, `-list`, `-clean`, `failed`, `search`)
`logstat`	`logstat`	30-day log statistics (commands, success rate, top commands)
`bootlog`	`bootlog [view\\|tail\\|clear\\|path]`	Shell init log viewer

📚 Reference Functions¶

Function	Usage	Purpose
`zhelp`	`zhelp`	Master command reference
`zwidgets`	`zwidgets`	Keyboard map (widget bindings)

✏️ Adding Custom Functions¶

Create ~/.config/zshand/functions/my_func.zsh:

# ── my_func — Short description ──────────────────────────────────────────────
#
# USAGE:
#   my_func [args]
#
# ─────────────────────────────────────────────────────────────────────────────

my_func() {
    local arg="${1:-default}"
    echo "Processing: $arg"
}

Rebuild: zr
Use it: my_func value

📏 Naming Conventions¶

No prefix — user-facing functions (dcopy, health, seek)
z prefix — framework-related (zpath, zlog, zopt, ztop)
_ prefix — internal/hook-only (_gitid, _zlog_viewer)
.zsh extension — sourced at startup, no shebang needed

🔀 Override Behavior¶

User functions with the same basename replace framework functions:

~/.config/zshand/functions/seek.zsh  →  replaces $ZSHAND/functions/seek.zsh
~/.config/zshand/functions/my_new.zsh  →  added alongside framework functions

Document	Purpose
📂 functions/README.md	In-tree quick reference
🏗️ ARCHITECTURE.md	Function loading in boot sequence
🎨 STYLE_GUIDE.md	Naming and code conventions
👤 USER_CONFIG.md	Custom functions directory
📐 HEADER_STANDARD.md	Function file header format