zshdb(1)

📦 version 1.1.4, in arch rolling

🐚 zshdb(1) — the zsh debugger, but make it cute

okay so bestie, gather round, because this is the manual page for zshdb — from the User Contributed Perl Documentation gang, no less — and I'm gonna walk you through it like we're texting at 2am. 💅✨

🌸 NAME 🌸

zshdb — literally just the zsh debugger. that's the whole name. iconic, honestly. 🎀

✨ SYNOPSIS ✨

two whole ways to summon it, bestie:

zshdb [options] [--] script-name [script options]

zshdb [options] -c execution-string

💖 DESCRIPTION 💖

so zshdb is itself a zsh script, and what it does is arrange for another zsh script to be debugged — like it sets everything up behind the scenes so your actual script gets watched. 👀 the debugger's command interface is similar to gdb(1), which is highkey a slay because if you know gdb you're already halfway home.

here's the tea though 🫖: if you run zshdb script and you need to pass options to the script being debugged, put -- before the script name. that tells zshdb "bestie stop processing options, everything after this is for the script." no cap, it's that simple. 💫

🔥 OPTIONS 🔥

  • -h | --help — prints a usage message on standard error and exits with a return code of 100. yes, 100, not 0. we don't know why either, it's just the vibe. 💀
  • -A | --annotation level — sets it to output extra stack and status info, which lets front-ends like emacs track what's going on without polling (obsessed, honestly). this is needed for regression testing. using this option is equivalent to issuing:
set annotation LEVEL

inside the debugger. 🦋

  • -B | --basename — wherever a filename shows up in debugger output, give just the basename only. also needed for regression testing. using this option is equivalent to issuing:
set basename on

inside the debugger. 🎀

  • -n | --nx | --no-init — normally the debugger reads debugger commands in ~/.zshdbinit if that file exists, before accepting user interaction. .zshdbinit is analogous to Perl's .perldb or GNU gdb's .gdbinit — it's the profile where a user stashes their own personal customizations. ✨ with the -n option, that init file will not be read. super useful for regression testing or for tracking down a problem in your own .zshdbinit profile. 🙈
  • -c | --command command-string — instead of naming a script file, you can hand over an execution string to be debugged. use this option for that. easy. 💜
  • -q | --quiet — do not print the introductory version and copyright info. again useful in regression testing, where we don't want a changeable copyright date messing up the regression-test matching. 😌
  • -x | --eval-command debugger-cmdfile — run the debugger commands in debugger-cmdfile before accepting user input. important detail: these commands are read after any .zshdbinit commands. again, useful for running regression-testing debug scripts. 🧚
  • -L | --library debugger-library — the debugger needs to source (or include) a bunch of functions, and those live in a library. if this option isn't given, the default library location is relative to the installed zshdb script: ../lib/zshdb. keep that path exact, bestie. 📁
  • -T | --tempdir temporary-file-directory — the debugger needs some temporary filesystem storage to save persistent info across a subshell return, or to evaluate an expression. the default directory is /tmp, but you can use this option to set where debugger temporary files get created. 🍓
  • -t | --tty tty-name — debugger output usually goes to a terminal rather than stdout or stdin (which the debugged program might be using). figuring out the tty or pseudo-tty is normally done automatically, but if you want to control where the debugger output goes, use this option. 🖥️
  • -V | --version — show the version number and the no-warranty bit, and exit with return code 1. yep, 1. it's giving chaotic but we respect it. 💀👑

💀 BUGS 💀

okay, the not-so-slay parts, and I'm telling you straight because that's what besties do:

  • the way this script arranges debugging to happen is by including (or actually source-ing) some debug-support code, and then sourcing the given script or command string.
  • one problem with sourcing a debugged script: the program name stored in $0 will not be the name of the script being debugged. 😭 the debugged script will appear in a call stack not as the top item, but as the item below zshdb.
  • the zshdb script options assume a version of zsh with debugging support: zsh 4.3.6-dev-2 or later. don't skip that, fr fr.
  • the debugger slows things down a little, because it has to intercept every statement and check whether some action needs to be taken. it's the price of being watched. 💅

🦋 SEE ALSO 🦋

👑 AUTHOR 👑

the current version is maintained (or not) by Rocky Bernstein. 💜

 Copyright (C) 2009 Rocky Bernstein
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
⚠️ real talk: that warranty disclaimer is not a joke, bestie — no warranty, no guarantees, read the license before you ship it. 🫶

okay that's the whole page, you ate that 💅✨ this was zshdb version 1.1.4dev, dated 2026-04-09 — go debug something iconic 🐚💖

📦 where this page comes from