Metadata-Version: 2.4
Name: bashthing
Version: 0.2.0
Summary: Deterministic profiler for bash scripts. DEBUG trap + strace/dtruss + execsnoop + ShellCheck in a single pass.
Keywords: bash,profiler,performance,shell,tracing
Author: Kevin Turcios
Author-email: Kevin Turcios <turcioskevinr@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/KRRT7/bashthing
Project-URL: Repository, https://github.com/KRRT7/bashthing.git
Project-URL: Issues, https://github.com/KRRT7/bashthing/issues
Project-URL: Changelog, https://github.com/KRRT7/bashthing/blob/main/docs/changelog.md
Description-Content-Type: text/markdown

# bashthing

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

![bashthing — Find what's slowing down your Bash scripts](.github/assets/bashthing-social-preview.png)

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

## Install

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

## Usage

```bash
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.

```bash
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.

```bash
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.

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

### `flamegraph`

Generate a standalone interactive SVG flamegraph from a saved trace.

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

### `compare`

Compare the wall time and hotspots of two traces.

```bash
bashthing compare baseline.db optimized.db
```

### `lint`

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

```bash
bashthing lint script.sh
```

## Optional backends

| Name | Collects | Typical dependency |
| --- | --- | --- |
| `shellcheck` | Static performance findings | ShellCheck |
| `syscalls` | System calls and durations | `strace` on Linux or `dtruss` on macOS |
| `execs` | Spawned processes | `execsnoop` |
| `probes` | Bash and operating-system probes | bpftrace on Linux or DTrace on macOS |

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](docs/contributing.md).

## License

[MIT](LICENSE)
