bashthing

bashthing profiles Bash scripts, identifies expensive commands and functions, and stores the results in a portable SQLite database.

Requires Python 3.14 and Bash 5 or newer. Optional system tracers may require elevated permissions.

Install

curl -LsSf uvx.sh/bashthing/install.sh | sh

Usage

bashthing profile path/to/script.sh
bashthing profile path/to/script.sh --all
bashthing optimize path/to/script.sh

profile

Profile one execution and save its trace in SQLite. The built-in DEBUG tracer is always enabled.

bashthing profile script.sh arg1 arg2 -o trace.db
bashthing profile script.sh --backend shellcheck --backend syscalls
bashthing profile script.sh --all --force
bashthing profile script.sh --input input.txt

Repeat --backend to select optional backends. --all enables every usable backend and reports why unavailable backends were skipped. Existing output files require --force; successful replacement is atomic. Use --no-report to save the trace without printing its report.

optimize

Run performance-focused linting, profile the script several times, generate a report and flamegraph, and print actionable suggestions.

bashthing optimize script.sh
bashthing optimize script.sh arg1 -n 10 -o results
bashthing optimize script.sh --input input.txt --force

The default is five profiles. Results include per-profile databases and an SVG flamegraph.

report

Print function and line-level hotspots from a saved trace.

bashthing report trace.db
bashthing report trace.db --top 50

flamegraph

Generate a standalone interactive SVG flamegraph from a saved trace.

bashthing flamegraph trace.db
bashthing flamegraph trace.db -o profile.svg

compare

Compare the wall time and hotspots of two traces.

bashthing compare baseline.db optimized.db

lint

Run bashthing's performance-focused ShellCheck rules without profiling. Requires shellcheck on PATH.

bashthing lint script.sh

Optional backends

Explicitly requested backends must be installed and usable. Some system tracing backends require root or additional operating-system permissions.

Run bashthing --help for all commands and options.

Development instructions are in docs/contributing.md.

License

MIT