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.

See also: Source Reference (full list from headers) · Config (where to add your own) · Architecture (functions dir merge)

🛤️ 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`

☁️ Cloud Sync Functions¶

Function	Usage	Purpose
`pin`	`pin [dir]`	Interactive pin menu — choose mirror or cache strategy
`pin_mirror`	`pin_mirror [dir] [remote]`	Create/update mirror (bisync) pin
`pin_cache`	`pin_cache [dir] [remote]`	Create/update cache (VFS pre-heat) pin
`unpin`	`unpin [dir] [remote\\|all]`	Remove pins from a directory

See Cloud Sync for full documentation, configuration, and the cloudsync CLI.

🖥️ 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
📡 API / Source	Per-function generated docs (source/functions/)
🏗️ Architecture	Function loading in boot sequence
👤 Config	Custom functions directory
📐 Header Standard	Function file header format
📚 Documentation Index	Full doc nav