1# gotools
2
3gotools is a collection of command-line utilities for working with Go.
4
5## gobench
6
7`gobench` automated running Go benchmarks across your current working tree and a base Git branch (usually `main`).
8It alternates benchmark runs to minimise system noise, and pipes the output into `benchstat` for comparison.
9This allows you to see the impact of your unmerged changes.
10
11### Installation
12
13`gobench` requires `benchstat` to be installed:
14
15```console
16$ go install golang.org/x/perf/cmd/benchstat@latest
17```
18
19Then install `gobench`:
20
21```console
22$ go install alexwlchan.net/projects/gotools/cmd/gobench@latest
23```
24
25### Usage and flags
26
27Run `gobench` and pass arguments you'd pass to `go test` to choose which benchmark to run.
28For example:
29
30```console
31$ gobench ./control/controlapi -bench=BenchmarkDevices
32```
33
34There are optional flags to control the `gobench` behaviour:
35
36*   `-base` (default `main`) -- set the base Git branch or commit to compare against
37*   `-samples` (default `6`) -- the numebr of alternating sample rounds to run
38*   `-no-sync` (default `false`) -- skip copying dirty/untracked working tree files to the base worktree
39
40### Demo: measuring an optimisation
41
421.  Check out this repo at `main`.
432.  Create a new feature branch:
44
45    ```console
46    $ git checkout -b fib-faster
47    ```
48
493.  In `example/fib/fib_test.go`, replace `FibRecursive(20)` with `FibIterative(20)`.
504.  Commit your changes.
515.  Run `gobench` to measure the performance impact:
52
53    ```console
54    $ go run ./cmd/gobench ./example/fib -bench=BenchmarkFib
55    ```
56
57## License
58
59This project is shared under the [MIT license](./LICENSE).