Skip to main content

gobench: vendor a copy of the benchstat CLI

ID
9a09839
date
2026-11-04 05:36:43+00:00
author
Alex Chan <alex@alexwlchan.net>
parent
f3aa39b
message
gobench: vendor a copy of the benchstat CLI

This allows users to install gobench with a single `go install` command,
and doesn't require benchstat to be installed separately.
changed files
11 files, 1876 additions, 26 deletions

Changed files

CHANGELOG.md (69 → 180)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ab62f8..fc35ea3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v1.1.0 - 2026-11-04
+
+Vendor a copy of benchstat in gobench, so you don't need to install gobench separately.
+
 ## v1.0.0 - 2026-11-01
 
-Initial release with `gobench`.
+Initial release with gobench.

LICENSE (1053 → 2545)

diff --git a/LICENSE b/LICENSE
index e732212..adf5731 100644
--- a/LICENSE
+++ b/LICENSE
@@ -17,3 +17,33 @@ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
+
+# For files vendored from go/x/perf:
+
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md (1624 → 1660)

diff --git a/README.md b/README.md
index 5fafbda..1254846 100644
--- a/README.md
+++ b/README.md
@@ -4,34 +4,26 @@ gotools is a collection of command-line utilities for working with Go.
 
 ## gobench
 
-`gobench` automated running Go benchmarks across your current working tree and a base Git branch (usually `main`).
-It alternates benchmark runs to minimise system noise, and pipes the output into `benchstat` for comparison.
+gobench automates running Go benchmarks across your current working tree and a base Git branch/commit (usually `main`).
+It alternates benchmark runs to minimise system noise, and pipes the output into benchstat for comparison.
 This allows you to see the impact of your unmerged changes.
 
 ### Installation
 
-`gobench` requires `benchstat` to be installed:
-
-```console
-$ go install golang.org/x/perf/cmd/benchstat@latest
-```
-
-Then install `gobench`:
-
 ```console
 $ go install alexwlchan.net/gotools/cmd/gobench@latest
 ```
 
 ### Usage and flags
 
-Run `gobench` and pass arguments you'd pass to `go test` to choose which benchmark to run.
+Run gobench and pass arguments you'd pass to `go test` to choose which benchmark to run.
 For example:
 
 ```console
 $ gobench ./control/controlapi -bench=BenchmarkDevices
 ```
 
-There are optional flags to control the `gobench` behaviour:
+There are optional flags to control the gobench behaviour:
 
 *   `-base` (default `main`) -- set the base Git branch or commit to compare against
 *   `-samples` (default `6`) -- the numebr of alternating sample rounds to run
@@ -48,7 +40,7 @@ There are optional flags to control the `gobench` behaviour:
 
 3.  In `example/fib/fib_test.go`, replace `FibRecursive(20)` with `FibIterative(20)`.
 4.  Commit your changes.
-5.  Run `gobench` to measure the performance impact:
+5.  Run gobench to measure the performance impact:
 
     ```console
     $ go run ./cmd/gobench ./example/fib -bench=BenchmarkFib
@@ -57,3 +49,6 @@ There are optional flags to control the `gobench` behaviour:
 ## License
 
 This project is shared under the [MIT license](./LICENSE).
+
+This project includes code from [go/x/perf](https://cs.opensource.google/go/x/perf), which is described in the LICENSE file.
+All vendored files are labelled in the header comment.

cmd/gobench/benchstat.go (0 → 23728)

diff --git a/cmd/gobench/benchstat.go b/cmd/gobench/benchstat.go
new file mode 100644
index 0000000..c63c653
--- /dev/null
+++ b/cmd/gobench/benchstat.go
@@ -0,0 +1,546 @@
+// Note(alexwlchan, 2026-11-04): This file was retrieved from
+// https://cs.opensource.google/go/x/perf/+/be2c69fb:cmd/benchstat/main.go
+// so I can "embed" the benchstat CLI and users of gobench don't need to
+// install it separately.
+//
+// The only modification is commenting out the benchstat main() function
+// and updating the imports for the internal packages.
+
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Note: Blocks that begin with "$ benchstat" below will be tested by
+// doc_test.go.
+
+// Benchstat computes statistical summaries and A/B comparisons of Go
+// benchmarks.
+//
+// Usage:
+//
+//	benchstat [flags] inputs...
+//
+// Each input file should be in the Go benchmark format
+// (https://golang.org/design/14313-benchmark-format), such as the
+// output of “go test -bench .”. Typically, there should be two (or
+// more) inputs files for before and after some change (or series of
+// changes) to be measured. Each benchmark should be run at least 10
+// times to gather a statistically significant sample of results. For
+// each benchmark, benchstat computes the median and the confidence
+// interval for the median. By default, if there are two or more
+// inputs files, it compares each benchmark in the first file to the
+// same benchmark in each subsequent file and reports whether there
+// was a statistically significant difference, though it can be
+// configured to compare on other dimensions.
+//
+// # Example
+//
+// Suppose we collect results from running a set of benchmarks 10 times
+// before a particular change:
+//
+//	go test -run='^$' -bench=. -count=10 > old.txt
+//
+// And the same benchmarks 10 times after:
+//
+//	go test -run='^$' -bench=. -count=10 > new.txt
+//
+// The file old.txt contains:
+//
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	BenchmarkEncode/format=json-48         	  690848	      1726 ns/op
+//	BenchmarkEncode/format=json-48         	  684861	      1723 ns/op
+//	BenchmarkEncode/format=json-48         	  693285	      1707 ns/op
+//	BenchmarkEncode/format=json-48         	  677692	      1707 ns/op
+//	BenchmarkEncode/format=json-48         	  692130	      1713 ns/op
+//	BenchmarkEncode/format=json-48         	  684164	      1729 ns/op
+//	BenchmarkEncode/format=json-48         	  682500	      1736 ns/op
+//	BenchmarkEncode/format=json-48         	  677509	      1707 ns/op
+//	BenchmarkEncode/format=json-48         	  687295	      1705 ns/op
+//	BenchmarkEncode/format=json-48         	  695533	      1774 ns/op
+//	BenchmarkEncode/format=gob-48          	  372699	      3069 ns/op
+//	BenchmarkEncode/format=gob-48          	  394740	      3075 ns/op
+//	BenchmarkEncode/format=gob-48          	  391335	      3069 ns/op
+//	BenchmarkEncode/format=gob-48          	  383588	      3067 ns/op
+//	BenchmarkEncode/format=gob-48          	  385885	      3207 ns/op
+//	BenchmarkEncode/format=gob-48          	  389970	      3064 ns/op
+//	BenchmarkEncode/format=gob-48          	  393361	      3064 ns/op
+//	BenchmarkEncode/format=gob-48          	  393882	      3058 ns/op
+//	BenchmarkEncode/format=gob-48          	  396171	      3059 ns/op
+//	BenchmarkEncode/format=gob-48          	  397812	      3062 ns/op
+//
+// The file new.txt contains:
+//
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	BenchmarkEncode/format=json-48         	  714387	      1423 ns/op
+//	BenchmarkEncode/format=json-48         	  845445	      1416 ns/op
+//	BenchmarkEncode/format=json-48         	  815714	      1411 ns/op
+//	BenchmarkEncode/format=json-48         	  828824	      1413 ns/op
+//	BenchmarkEncode/format=json-48         	  834070	      1412 ns/op
+//	BenchmarkEncode/format=json-48         	  828123	      1426 ns/op
+//	BenchmarkEncode/format=json-48         	  834493	      1422 ns/op
+//	BenchmarkEncode/format=json-48         	  838406	      1424 ns/op
+//	BenchmarkEncode/format=json-48         	  836227	      1447 ns/op
+//	BenchmarkEncode/format=json-48         	  830835	      1425 ns/op
+//	BenchmarkEncode/format=gob-48          	  394441	      3075 ns/op
+//	BenchmarkEncode/format=gob-48          	  393207	      3065 ns/op
+//	BenchmarkEncode/format=gob-48          	  392374	      3059 ns/op
+//	BenchmarkEncode/format=gob-48          	  396037	      3065 ns/op
+//	BenchmarkEncode/format=gob-48          	  393255	      3060 ns/op
+//	BenchmarkEncode/format=gob-48          	  382629	      3081 ns/op
+//	BenchmarkEncode/format=gob-48          	  389558	      3186 ns/op
+//	BenchmarkEncode/format=gob-48          	  392668	      3135 ns/op
+//	BenchmarkEncode/format=gob-48          	  392313	      3087 ns/op
+//	BenchmarkEncode/format=gob-48          	  394274	      3062 ns/op
+//
+// The order of the lines in the file does not matter, except that the
+// output lists benchmarks in order of appearance.
+//
+// If we run “benchstat old.txt new.txt”, it will summarize the
+// benchmarks and compare the before and after results:
+//
+//	$ benchstat old.txt new.txt
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	                      │   old.txt   │               new.txt               │
+//	                      │   sec/op    │   sec/op     vs base                │
+//	Encode/format=json-48   1.718µ ± 1%   1.423µ ± 1%  -17.20% (p=0.000 n=10)
+//	Encode/format=gob-48    3.066µ ± 0%   3.070µ ± 2%        ~ (p=0.446 n=10)
+//	geomean                 2.295µ        2.090µ        -8.94%
+//
+// Before the comparison table, we see common file-level
+// configuration. If there are benchmarks with different configuration
+// (for example, from different packages), benchstat will print
+// separate tables for each configuration.
+//
+// The table then compares the two input files for each benchmark. It
+// shows the median and 95% confidence interval summaries for each
+// benchmark before and after the change, and an A/B comparison under
+// "vs base". The comparison shows that Encode/format=json got 17.20%
+// faster with a p-value of 0.000 and 10 samples from each input file.
+// The p-value measures how likely it is that any differences were due
+// to random chance (i.e., noise). In this case, it's extremely
+// unlikely the difference between the medians was due to chance. For
+// Encode/format=gob, the "~" means benchstat did not detect a
+// statistically significant difference between the two inputs. In
+// this case, we see a p-value of 0.446, meaning it's very likely the
+// differences for this benchmark are simply due to random chance.
+//
+// Note that "statistically significant" is not the same as "large":
+// with enough low-noise data, even very small changes can be
+// distinguished from noise and considered statistically significant.
+// It is, of course, generally easier to distinguish large changes
+// from noise.
+//
+// Finally, the last row of the table shows the geometric mean of each
+// column, giving an overall picture of how the benchmarks changed.
+// Proportional changes in the geomean reflect proportional changes in
+// the benchmarks. For example, given n benchmarks, if sec/op for one
+// of them increases by a factor of 2, then the sec/op geomean will
+// increase by a factor of ⁿ√2.
+//
+// # Filtering
+//
+// benchstat has a very flexible system of configuring exactly which
+// benchmarks are summarized and compared. First, all inputs are
+// filtered according to an expression provided as the -filter flag.
+//
+// Filters are built from key-value terms:
+//
+//	key:value     - Match if key equals value.
+//	key:"value"   - Same, but value is a double-quoted Go string that
+//	                may contain spaces or other special characters.
+//	"key":value   - Keys may also be double-quoted.
+//	key:/regexp/  - Match if key matches a regular expression.
+//	key:(val1 OR val2 OR ...)
+//	              - Short-hand for key:val1 OR key:val2. Values may be
+//	                double-quoted strings or regexps.
+//	*             - Match everything.
+//
+// These terms can be combined into larger expressions as follows:
+//
+//	x y ...       - Match if x, y, etc. all match.
+//	x AND y       - Same as x y.
+//	x OR y        - Match if x or y match.
+//	-x            - Match if x does not match.
+//	(...)         - Subexpression.
+//
+// Each key is one of the following:
+//
+//	.name         - The base name of a benchmark
+//	.fullname     - The full name of a benchmark (including configuration)
+//	.file         - The name of the input file or user-provided file label
+//	/{name-key}   - Per-benchmark sub-name configuration key
+//	{file-key}    - File-level configuration key
+//	.unit         - The name of a unit for a particular metric
+//
+// For example, the following matches benchmarks with "/format=json"
+// in the sub-name keys with file-level configuration "goos" equal to
+// "linux" and extracts the "ns/op" and "B/op" measurements:
+//
+//	$ benchstat -filter "/format:json goos:linux .unit:(ns/op OR B/op)" old.txt new.txt
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	                      │   old.txt   │               new.txt               │
+//	                      │   sec/op    │   sec/op     vs base                │
+//	Encode/format=json-48   1.718µ ± 1%   1.423µ ± 1%  -17.20% (p=0.000 n=10)
+//
+// # Configuring comparisons
+//
+// The way benchstat groups and compares results is configurable using
+// a similar set of keys as used for filtering. By default, benchstat
+// groups results into tables using all file-level configuration keys,
+// then within each table, it groups results into rows by .fullname
+// (the benchmark's full name) and compares across columns by .file
+// (the name of each input file). This can be changed via the
+// following flags:
+//
+//	-table KEYS   - Group results into tables by KEYS
+//	-row KEYS     - Group results into table rows by KEYS
+//	-col KEYS     - Compare across results with different values of KEYS
+//
+// Using these flags, benchstat "projects" each result into a
+// particular table cell. Each KEYS argument is a comma- or
+// space-separated list of keys, each of which can optionally also
+// specify a sort order (described below).
+//
+// Each key is one of the following:
+//
+//	.name         - The base name of a benchmark
+//	.fullname     - The full name of a benchmark (including configuration)
+//	.file         - The name of the input file or user-provided file label
+//	/{name-key}   - Per-benchmark sub-name configuration key
+//	{file-key}    - File-level configuration key
+//	.config       - All file-level configuration keys
+//
+// Some of these keys can overlap. For example, ".config" includes the
+// file-level key "goos", and ".fullname" includes the sub-name key
+// "/format". When keys overlap like this, benchstat omits the more
+// specific key from the general key. For example, if -table is the
+// full file-level configuration ".config", and -col is the specific
+// file key "goos", benchstat will omit "goos" from ".config".
+//
+// Finally, the -ignore flag can list keys that benchstat should
+// ignore when grouping results. Continuing the previous example, if
+// -table is ".config" and -ignore is "goos", benchstat will omit
+// "goos" from ".config", but also not use it for any grouping.
+//
+// For precise details of the filter syntax and supported keys, see
+// https://pkg.go.dev/golang.org/x/perf/benchproc/syntax.
+//
+// # Projection examples
+//
+// Returning to our first example, we can now see how the default
+// projection flags produce this output:
+//
+//	$ benchstat -table .config -row .fullname -col .file old.txt new.txt
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	                      │   old.txt   │               new.txt               │
+//	                      │   sec/op    │   sec/op     vs base                │
+//	Encode/format=json-48   1.718µ ± 1%   1.423µ ± 1%  -17.20% (p=0.000 n=10)
+//	Encode/format=gob-48    3.066µ ± 0%   3.070µ ± 2%        ~ (p=0.446 n=10)
+//	geomean                 2.295µ        2.090µ        -8.94%
+//
+// In this example, all benchmarks have the same file-level
+// configuration, consisting of "goos", "goarch", and "pkg", so
+// ".config" groups them into just one table. Within this table,
+// results are grouped into rows by their full name, including
+// configuration, and grouped into columns by the name of each input
+// file.
+//
+// Suppose we instead want to compare json encoding to gob encoding
+// from new.txt.
+//
+//	$ benchstat -col /format new.txt
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	          │    json     │                 gob                  │
+//	          │   sec/op    │   sec/op     vs base                 │
+//	Encode-48   1.423µ ± 1%   3.070µ ± 2%  +115.82% (p=0.000 n=10)
+//
+// The columns are now labeled by the "/format" configuration from the
+// benchmark name. benchstat still compares columns even though we've
+// only provided a single input file. We also see that /format has
+// been removed from the benchmark name to make a single row.
+//
+// We can simplify the output by grouping rows by just the benchmark name,
+// rather than the full name:
+//
+//	$ benchstat -col /format -row .name new.txt
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	       │    json     │                 gob                  │
+//	       │   sec/op    │   sec/op     vs base                 │
+//	Encode   1.423µ ± 1%   3.070µ ± 2%  +115.82% (p=0.000 n=10)
+//
+// benchstat will attempt to detect and warn if projections strip away
+// too much information. For example, here we group together json and
+// gob results into a single row:
+//
+//	$ benchstat  -row .name new.txt
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	       │    new.txt     │
+//	       │     sec/op     │
+//	Encode   2.253µ ± 37% ¹
+//	¹ benchmarks vary in .fullname
+//
+// Since this is probably not a meaningful comparison, benchstat warns
+// that the benchmarks it grouped together vary in a hidden dimension.
+// If this really were our intent, we could -ignore .fullname.
+//
+// # Sorting
+//
+// By default, benchstat sorts each dimension according to the order
+// in which it first observes each value of that dimension. This can
+// be overridden in each projection using the following syntax:
+//
+// {key}@{order} - specifies one of the built-in named sort orders.
+// This can be "alpha" or "num" for alphabetic or numeric sorting.
+// "num" understands basic use of metric and IEC prefixes like "2k"
+// and "1Mi".
+//
+// {key}@({value} {value} ...) - specifies a fixed value order for
+// key. It also specifies a filter: if key has a value that isn't any
+// of the specified values, the result is filtered out.
+//
+// For example, we can use a fixed order to compare the improvement of
+// json over gob rather than the other way around:
+//
+//	$ benchstat -col "/format@(gob json)" -row .name -ignore .file new.txt
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	       │     gob     │                json                 │
+//	       │   sec/op    │   sec/op     vs base                │
+//	Encode   3.070µ ± 2%   1.423µ ± 1%  -53.66% (p=0.000 n=10)
+//
+// # Overriding .file
+//
+// Often, you want to compare results from different files, but want
+// to provide more meaningful (or perhaps shorter) column labels than
+// raw file names. File name labels can be overridden by specifying an
+// input argument of the form "label=path" instead of just "path".
+// This provides a custom value for the .file key.
+//
+// For example, the following will perform the default comparison, but
+// label the columns O and N instead of old.txt and new.txt:
+//
+//	$ benchstat O=old.txt N=new.txt
+//	goos: linux
+//	goarch: amd64
+//	pkg: golang.org/x/perf/cmd/benchstat/testdata
+//	                      │      O      │                  N                  │
+//	                      │   sec/op    │   sec/op     vs base                │
+//	Encode/format=json-48   1.718µ ± 1%   1.423µ ± 1%  -17.20% (p=0.000 n=10)
+//	Encode/format=gob-48    3.066µ ± 0%   3.070µ ± 2%        ~ (p=0.446 n=10)
+//	geomean                 2.295µ        2.090µ        -8.94%
+//
+// # Units
+//
+// benchstat normalizes the units "ns" to "sec" and "MB" to "B" to
+// avoid creating nonsense units like "µns/op". These appear in the
+// testing package's default metrics and are also common in custom
+// metrics.
+//
+// benchstat supports custom unit metadata (see
+// https://golang.org/design/14313-benchmark-format). In particular,
+// "assume" metadata is useful for controlling the statistics used by
+// benchstat. By default, units use "assume=nothing", so benchstat
+// uses non-parametric statistics: median for summaries, and the
+// Mann-Whitney U-test for A/B comparisons.
+//
+// Some benchmarks measure things that have no noise, such as the size
+// of a binary produced by a compiler. These do not benefit from
+// repeated measurements or non-parametric statistics. For these
+// units, it's useful to set "assume=exact". This will cause benchstat
+// to warn if there's any variation in the measured values, and to
+// show A/B comparisons even if there's only one before and after
+// measurement.
+//
+// # Tips
+//
+// Reducing noise and/or increasing the number of benchmark runs will
+// enable benchstat to discern smaller changes as "statistically
+// significant". To reduce noise, make sure you run benchmarks on an
+// otherwise idle machine, ideally one that isn't running on battery
+// and isn't likely to be affected by thermal throttling.
+// https://llvm.org/docs/Benchmarking.html has many good tips on
+// reducing noise in benchmarks.
+//
+// It's also important that noise is evenly distributed across
+// benchmark runs. The best way to do this is to interleave before and
+// after runs, rather than running, say, 10 iterations of the before
+// benchmark, and then 10 iterations of the after benchmark. For Go
+// benchmarks, you can often speed up this process by using "go test
+// -c" to pre-compile the benchmark binary.
+//
+// Pick a number of benchmark runs (at least 10, ideally 20) and stick
+// to it. If benchstat reports no statistically significant change,
+// avoid simply rerunning your benchmarks until it reports a
+// significant change. This is known as "multiple testing" and is a
+// common statistical error. By default, benchstat uses an ɑ threshold
+// of 0.05, which means it is *expected* to show a difference 5% of
+// the time even if there is no difference. Hence, if you rerun
+// benchmarks looking for a change, benchstat will probably eventually
+// say there is a change, even if there isn't, which creates a
+// statistical bias.
+//
+// As an extension of this, if you compare a large number of
+// benchmarks, you should expect that about 5% of them will report a
+// statistically significant change even if there is no difference
+// between the before and after.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	"alexwlchan.net/gotools/internal/benchtab"
+	"golang.org/x/perf/benchfmt"
+	"golang.org/x/perf/benchmath"
+	"golang.org/x/perf/benchproc"
+)
+
+// TODO: Add a flag to perform Holm–Bonferroni correction for
+// family-wise error rates. This can be done after-the-fact on a
+// collection of benchstat.Comparison values.
+
+// TODO: -unit flag.
+
+// TODO: Support sorting by commit order.
+
+// TODO: Add some quick usage examples to the -h output?
+
+// TODO: If the projection results in a very sparse table, that's
+// usually the result of correlated keys. Can we detect that and
+// suggest fixes?
+
+// func main() {
+//     if err := benchstat(os.Stdout, os.Stderr, os.Args[1:]); err != nil {
+//         fmt.Fprintf(os.Stderr, "benchstat: %s\n", err)
+//     }
+// }
+
+func benchstat(w, wErr io.Writer, args []string) error {
+	flags := flag.NewFlagSet("", flag.ExitOnError)
+	flags.Usage = func() {
+		fmt.Fprintf(flags.Output(), `Usage: benchstat [flags] inputs...
+
+benchstat computes statistical summaries and A/B comparisons of Go
+benchmarks. It shows benchmark medians in a table with a row for each
+benchmark and a column for each input file. If there is more than one
+input file, it also shows A/B comparisons between the files. If a
+difference is likely to be noise, it shows "~".
+
+For details, see https://pkg.go.dev/golang.org/x/perf/cmd/benchstat.
+`)
+		flags.PrintDefaults()
+	}
+
+	thresholds := benchmath.DefaultThresholds
+	flagTable := flags.String("table", ".config", "split results into tables by distinct values of `projection`")
+	flagRow := flags.String("row", ".fullname", "split results into rows by distinct values of `projection`")
+	flagCol := flags.String("col", ".file", "split results into columns by distinct values of `projection`")
+	flagIgnore := flags.String("ignore", "", "ignore variations in `keys`")
+	flagFilter := flags.String("filter", "*", "use only benchmarks matching benchfilter `query`")
+	flags.Float64Var(&thresholds.CompareAlpha, "alpha", thresholds.CompareAlpha, "consider change significant if p < `α`")
+	// TODO: Support -confidence none to disable CI column? This
+	// would be equivalent to benchstat v1's -norange for CSV.
+	flagConfidence := flags.Float64("confidence", 0.95, "confidence `level` for ranges")
+	flagFormat := flags.String("format", "text", "print results in `format`:\n  text - plain text\n  csv  - comma-separated values (warnings will be written to stderr)\n")
+	flags.Parse(args)
+
+	if flags.NArg() == 0 {
+		flags.Usage()
+		os.Exit(2)
+	}
+
+	filter, err := benchproc.NewFilter(*flagFilter)
+	if err != nil {
+		return fmt.Errorf("parsing -filter: %s", err)
+	}
+
+	var parser benchproc.ProjectionParser
+	var parseErr error
+	mustParse := func(name, val string, unit bool) *benchproc.Projection {
+		var proj *benchproc.Projection
+		var err error
+		if unit {
+			proj, _, err = parser.ParseWithUnit(val, filter)
+		} else {
+			proj, err = parser.Parse(val, filter)
+		}
+		if err != nil && parseErr == nil {
+			parseErr = fmt.Errorf("parsing %s: %s", name, err)
+		}
+		return proj
+	}
+	tableBy := mustParse("-table", *flagTable, true)
+	rowBy := mustParse("-row", *flagRow, false)
+	colBy := mustParse("-col", *flagCol, false)
+	mustParse("-ignore", *flagIgnore, false)
+	residue := parser.Residue()
+	if parseErr != nil {
+		return parseErr
+	}
+
+	if thresholds.CompareAlpha < 0 || thresholds.CompareAlpha > 1 {
+		return fmt.Errorf("-alpha must be in range [0, 1]")
+	}
+	if *flagConfidence < 0 || *flagConfidence > 1 {
+		return fmt.Errorf("-confidence must be in range [0, 1]")
+	}
+	var format func(t *benchtab.Tables) error
+	switch *flagFormat {
+	default:
+		return fmt.Errorf("-format must be text or csv")
+	case "text":
+		format = func(t *benchtab.Tables) error { return t.ToText(w, false) }
+	case "csv":
+		format = func(t *benchtab.Tables) error { return t.ToCSV(w, wErr) }
+	}
+
+	stat := benchtab.NewBuilder(tableBy, rowBy, colBy, residue)
+	files := benchfmt.Files{Paths: flags.Args(), AllowStdin: true, AllowLabels: true}
+	for files.Scan() {
+		switch rec := files.Result(); rec := rec.(type) {
+		case *benchfmt.SyntaxError:
+			// Non-fatal result parse error. Warn
+			// but keep going.
+			fmt.Fprintln(wErr, rec)
+		case *benchfmt.Result:
+			if ok, err := filter.Apply(rec); !ok {
+				if err != nil {
+					// Print the reason we rejected this result.
+					fmt.Fprintln(wErr, err)
+				}
+				continue
+			}
+
+			stat.Add(rec)
+		}
+	}
+	if err := files.Err(); err != nil {
+		return err
+	}
+
+	tables := stat.ToTables(benchtab.TableOpts{
+		Confidence: *flagConfidence,
+		Thresholds: &thresholds,
+		Units:      files.Units(),
+	})
+	return format(tables)
+}

cmd/gobench/gobench.go (6736 → 6585)

diff --git a/cmd/gobench/gobench.go b/cmd/gobench/gobench.go
index ee57047..8e583d8 100644
--- a/cmd/gobench/gobench.go
+++ b/cmd/gobench/gobench.go
@@ -41,11 +41,6 @@ func run() error {
 		return errors.New("missing arguments for `go test`")
 	}
 
-	// Check that benchstat is installed
-	if _, err := exec.LookPath("benchstat"); err != nil {
-		return fmt.Errorf("benchstat is required: install with `go install golang.org/x/perf/cmd/benchstat@latest`")
-	}
-
 	// Prepare two copies of the Git repo: one on the branch, one on main.
 	pair, err := prepareGitRepos(*baseFlag, !*noSyncFlag)
 	if err != nil {
@@ -104,15 +99,15 @@ func run() error {
 	branchLabel := fmt.Sprintf("%s (%s)", branchName, branchCommit)
 
 	fmt.Println("\n== Benchmark results ==")
-	benchstatBin := "benchstat"
-	statCmd := exec.Command(
-		benchstatBin,
+	benchstatArgs := []string{
 		fmt.Sprintf("%s=%s", baseLabel, baseFile),
 		fmt.Sprintf("%s=%s", branchLabel, branchFile),
-	)
-	statCmd.Stdout = os.Stdout
-	statCmd.Stderr = os.Stderr
-	return statCmd.Run()
+	}
+	if err := benchstat(os.Stdout, os.Stderr, benchstatArgs); err != nil {
+		return fmt.Errorf("benchstat: %s", err)
+		fmt.Fprintf(os.Stderr, "benchstat: %s\n", err)
+	}
+	return nil
 }
 
 // runSingleBenchmark runs a single instance of a benchmark in a repo,

go.mod (310 → 457)

diff --git a/go.mod b/go.mod
index 9f3cd85..78d5e06 100644
--- a/go.mod
+++ b/go.mod
@@ -3,9 +3,11 @@ module alexwlchan.net/gotools
 go 1.27.0
 
 require (
+	github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794 // indirect
 	github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/schollz/progressbar/v3 v3.19.1 // indirect
+	golang.org/x/perf v0.0.0-20261009192801-be2c69fb417e // indirect
 	golang.org/x/sys v0.49.0 // indirect
 	golang.org/x/term v0.47.0 // indirect
 )

go.sum (897 → 1345)

diff --git a/go.sum b/go.sum
index d01825d..4378e57 100644
--- a/go.sum
+++ b/go.sum
@@ -1,9 +1,13 @@
+github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794 h1:xlwdaKcTNVW4PtpQb8aKA4Pjy0CdJHEqvFbAnvR5m2g=
+github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794/go.mod h1:7e+I0LQFUI9AXWxOfsQROs9xPhoJtbsyWcjJqDd4KPY=
 github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db h1:62I3jR2EmQ4l5rM/4FEfDWcRD+abF5XlKShorW5LRoQ=
 github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db/go.mod h1:l0dey0ia/Uv7NcFFVbCLtqEBQbrT4OCwCSKTEv6enCw=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/schollz/progressbar/v3 v3.19.1 h1:iv8BgwOvdML/S3p84uBpy/IMigv4U9594vPZYa2EdrU=
 github.com/schollz/progressbar/v3 v3.19.1/go.mod h1:LFL7jqimKxfhero4K1eCkUr/6R39AgQeiPCJtlTWIW8=
+golang.org/x/perf v0.0.0-20261009192801-be2c69fb417e h1:IB9P+pA897fozv0n9ldn+jTDNWtEMfbomaXXa4dKr74=
+golang.org/x/perf v0.0.0-20261009192801-be2c69fb417e/go.mod h1:xYyp99KTTskT614A1S1+yZiv1SUHKA71nswXA2C32pU=
 golang.org/x/sys v0.49.0 h1:XbzkgYJHdqh/8m2Uu0W/dQv8nktxx4BFHp1M0gROTXA=
 golang.org/x/sys v0.49.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
 golang.org/x/term v0.47.0 h1:cpyOwQkr2Nzxe2p6KnrTG7Ei2wtzjsuSjhpXXepZ/BM=

internal/benchtab/builder.go (0 → 11420)

diff --git a/internal/benchtab/builder.go b/internal/benchtab/builder.go
new file mode 100644
index 0000000..6c5aa0e
--- /dev/null
+++ b/internal/benchtab/builder.go
@@ -0,0 +1,425 @@
+// Note(alexwlchan, 2026-11-04): This file was retrieved from
+// https://cs.opensource.google/go/x/perf/+/be2c69fb:cmd/benchstat/internal/benchtab/builder.go
+
+// Copyright 2020 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package benchtab presents benchmark results as comparison tables.
+package benchtab
+
+import (
+	"encoding/csv"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"runtime"
+	"strings"
+	"sync"
+
+	"github.com/aclements/go-moremath/stats"
+	"golang.org/x/perf/benchfmt"
+	"golang.org/x/perf/benchmath"
+	"golang.org/x/perf/benchproc"
+)
+
+// TODO: Color by good/bad (or nothing for unknown units)
+
+// A Builder collects benchmark results into a Tables set.
+type Builder struct {
+	tableBy, rowBy, colBy *benchproc.Projection
+	residue               *benchproc.Projection
+
+	unitField *benchproc.Field
+
+	// tables maps from tableBy to table.
+	tables map[benchproc.Key]*builderTable
+}
+
+type builderTable struct {
+	// Observed row and col Keys within this group. Within the
+	// group, we show only the row and col labels for the data in
+	// the group, but we sort them according to the global
+	// observation order for consistency across groups.
+	rows map[benchproc.Key]struct{}
+	cols map[benchproc.Key]struct{}
+
+	// cells maps from (row, col) to each cell.
+	cells map[TableKey]*builderCell
+}
+
+type builderCell struct {
+	// values are the observed values in this cell.
+	values []float64
+	// residue is the set of residue keys mapped to this cell.
+	// It is used to check for non-unique keys.
+	residue map[benchproc.Key]struct{}
+}
+
+// NewBuilder creates a new Builder for collecting benchmark results
+// into tables. Each result will be mapped to a Table by tableBy.
+// Within each table, the results are mapped to cells by rowBy and
+// colBy. Any results within a single cell that vary by residue will
+// be reported as warnings. tableBy must have a ".unit" field.
+func NewBuilder(tableBy, rowBy, colBy, residue *benchproc.Projection) *Builder {
+	tableFields := tableBy.Fields()
+	unitField := tableFields[len(tableFields)-1]
+	if unitField.Name != ".unit" {
+		panic("tableBy projection missing .unit field")
+	}
+	return &Builder{
+		tableBy: tableBy, rowBy: rowBy, colBy: colBy, residue: residue,
+		unitField: unitField,
+		tables:    make(map[benchproc.Key]*builderTable),
+	}
+}
+
+// Add adds all of the values in result to the tables in the Builder.
+func (b *Builder) Add(result *benchfmt.Result) {
+	// Project the result.
+	tableKeys := b.tableBy.ProjectValues(result)
+	rowKey := b.rowBy.Project(result)
+	colKey := b.colBy.Project(result)
+	residueKey := b.residue.Project(result)
+	cellKey := TableKey{rowKey, colKey}
+
+	// Map to tables.
+	for unitI, tableKey := range tableKeys {
+		table := b.tables[tableKey]
+		if table == nil {
+			table = b.newTable()
+			b.tables[tableKey] = table
+		}
+
+		// Map to a cell.
+		c := table.cells[cellKey]
+		if c == nil {
+			c = new(builderCell)
+			c.residue = make(map[benchproc.Key]struct{})
+			table.cells[cellKey] = c
+			table.rows[rowKey] = struct{}{}
+			table.cols[colKey] = struct{}{}
+		}
+
+		// Add to the cell.
+		c.values = append(c.values, result.Values[unitI].Value)
+		c.residue[residueKey] = struct{}{}
+	}
+}
+
+func (b *Builder) newTable() *builderTable {
+	return &builderTable{
+		rows:  make(map[benchproc.Key]struct{}),
+		cols:  make(map[benchproc.Key]struct{}),
+		cells: make(map[TableKey]*builderCell),
+	}
+}
+
+// TableOpts provides options for constructing the final analysis
+// tables from a Builder.
+type TableOpts struct {
+	// Confidence is the desired confidence level in summary
+	// intervals; e.g., 0.95 for 95%.
+	Confidence float64
+
+	// Thresholds are the thresholds to use for statistical tests.
+	Thresholds *benchmath.Thresholds
+
+	// Units is the unit metadata. This gives distributional
+	// assumptions for units, among other properties.
+	Units benchfmt.UnitMetadataMap
+}
+
+// Tables is a sequence of benchmark statistic tables.
+type Tables struct {
+	// Tables is a slice of statistic tables. Within a Table, all
+	// results have the same table Key (including unit).
+	Tables []*Table
+	// Keys is a slice of table keys, corresponding 1:1 to
+	// the Tables slice. These always end with a ".unit"
+	// field giving the unit.
+	Keys []benchproc.Key
+}
+
+// ToTables finalizes a Builder into a sequence of statistic tables.
+func (b *Builder) ToTables(opts TableOpts) *Tables {
+	// Sort tables.
+	var keys []benchproc.Key
+	for k := range b.tables {
+		keys = append(keys, k)
+	}
+	benchproc.SortKeys(keys)
+
+	// We're going to compute table cells in parallel because the
+	// statistics are somewhat expensive. This is entirely
+	// CPU-bound, so we put a simple concurrency limit on it.
+	limit := make(chan struct{}, 2*runtime.GOMAXPROCS(-1))
+	var wg sync.WaitGroup
+
+	// Process each table.
+	var tables []*Table
+	for _, k := range keys {
+		cTable := b.tables[k]
+
+		// Get the configured assumption for this unit.
+		unit := k.Get(b.unitField)
+		assumption := opts.Units.GetAssumption(unit)
+
+		// Sort the rows and columns.
+		rowKeys, colKeys := mapKeys(cTable.rows), mapKeys(cTable.cols)
+		table := &Table{
+			Unit:       unit,
+			Opts:       opts,
+			Assumption: assumption,
+			Rows:       rowKeys,
+			Cols:       colKeys,
+			Cells:      make(map[TableKey]*TableCell),
+		}
+		tables = append(tables, table)
+
+		// Create all TableCells and fill their Samples. This
+		// is fast enough it's not worth parallelizing. This
+		// enables the second pass to look up baselines and
+		// their samples.
+		for k, cCell := range cTable.cells {
+			table.Cells[k] = &TableCell{
+				Sample: benchmath.NewSample(cCell.values, opts.Thresholds),
+			}
+		}
+
+		// Populate cells.
+		baselineCfg := colKeys[0]
+		wg.Add(len(cTable.cells))
+		for k, cCell := range cTable.cells {
+			cell := table.Cells[k]
+
+			// Look up the baseline.
+			if k.Col != baselineCfg {
+				base, ok := table.Cells[TableKey{k.Row, baselineCfg}]
+				if ok {
+					cell.Baseline = base
+				}
+			}
+
+			limit <- struct{}{}
+			cCell := cCell
+			go func() {
+				summarizeCell(cCell, cell, assumption, opts.Confidence)
+				<-limit
+				wg.Done()
+			}()
+		}
+	}
+	wg.Wait()
+
+	// Add summary rows to each table.
+	for _, table := range tables {
+		table.SummaryLabel = "geomean"
+		table.Summary = make(map[benchproc.Key]*TableSummary)
+
+		// Count the number of baseline benchmarks. If later
+		// columns don't have the same number of baseline
+		// pairings, we know the benchmark sets don't match.
+		nBase := 0
+		baseCol := table.Cols[0]
+		for _, row := range table.Rows {
+			if _, ok := table.Cells[TableKey{row, baseCol}]; ok {
+				nBase++
+			}
+		}
+
+		for i, col := range table.Cols {
+			var s TableSummary
+			table.Summary[col] = &s
+			isBase := i == 0
+
+			limit <- struct{}{}
+			table, col := table, col
+			wg.Add(1)
+			go func() {
+				summarizeCol(table, col, &s, nBase, isBase)
+				<-limit
+				wg.Done()
+			}()
+		}
+	}
+	wg.Wait()
+
+	return &Tables{tables, keys}
+}
+
+func mapKeys(m map[benchproc.Key]struct{}) []benchproc.Key {
+	var keys []benchproc.Key
+	for k := range m {
+		keys = append(keys, k)
+	}
+	benchproc.SortKeys(keys)
+	return keys
+}
+
+func summarizeCell(cCell *builderCell, cell *TableCell, assumption benchmath.Assumption, confidence float64) {
+	cell.Summary = assumption.Summary(cell.Sample, confidence)
+
+	// If there's a baseline, compute comparison.
+	if cell.Baseline != nil {
+		cell.Comparison = assumption.Compare(cell.Baseline.Sample, cell.Sample)
+	}
+
+	// Warn for non-singular keys in this cell.
+	nsk := benchproc.NonSingularFields(mapKeys(cCell.residue))
+	if len(nsk) > 0 {
+		// Emit a warning.
+		var warn strings.Builder
+		warn.WriteString("benchmarks vary in ")
+		for i, field := range nsk {
+			if i > 0 {
+				warn.WriteString(", ")
+			}
+			warn.WriteString(field.Name)
+		}
+
+		cell.Sample.Warnings = append(cell.Sample.Warnings, errors.New(warn.String()))
+	}
+}
+
+func summarizeCol(table *Table, col benchproc.Key, s *TableSummary, nBase int, isBase bool) {
+	// Collect cells.
+	//
+	// This computes the geomean of the summary ratios rather than
+	// ratio of the summary geomeans. These are identical *if* the
+	// benchmark sets are the same. But if the benchmark sets
+	// differ, this leads to more sensible ratios because it's
+	// still the geomean of the column, rather than being a
+	// comparison of two incomparable numbers. It's still easy to
+	// misinterpret, but at least it's not meaningless.
+	var summaries, ratios []float64
+	badRatio := false
+	for _, row := range table.Rows {
+		cell, ok := table.Cells[TableKey{row, col}]
+		if !ok {
+			continue
+		}
+		summaries = append(summaries, cell.Summary.Center)
+		if cell.Baseline != nil {
+			var ratio float64
+			a, b := cell.Summary.Center, cell.Baseline.Summary.Center
+			if a == b {
+				// Treat 0/0 as 1.
+				ratio = 1
+			} else if b == 0 {
+				badRatio = true
+				// Keep nBase check working.
+				ratios = append(ratios, 0)
+				continue
+			} else {
+				ratio = a / b
+			}
+			ratios = append(ratios, ratio)
+		}
+	}
+
+	// If the number of cells in this column that had a baseline
+	// is the same as the total number of baselines, then we know
+	// the benchmark sets match. Otherwise, they don't and these
+	// numbers are probably misleading.
+	if !isBase && nBase != len(ratios) {
+		s.Warnings = append(s.Warnings, fmt.Errorf("benchmark set differs from baseline; geomeans may not be comparable"))
+	}
+
+	// Summarize centers.
+	gm := stats.GeoMean(summaries)
+	if math.IsNaN(gm) {
+		s.Warnings = append(s.Warnings, fmt.Errorf("summaries must be >0 to compute geomean"))
+	} else {
+		s.HasSummary = true
+		s.Summary = gm
+	}
+
+	// Summarize ratios.
+	if !isBase && !badRatio {
+		gm := stats.GeoMean(ratios)
+		if math.IsNaN(gm) {
+			s.Warnings = append(s.Warnings, fmt.Errorf("ratios must be >0 to compute geomean"))
+		} else {
+			s.HasRatio = true
+			s.Ratio = gm
+		}
+	}
+}
+
+// ToText renders t to a textual representation, assuming a
+// fixed-width font.
+func (t *Tables) ToText(w io.Writer, color bool) error {
+	return t.printTables(func(hdr string) error {
+		_, err := fmt.Fprintf(w, "%s\n", hdr)
+		return err
+	}, func(table *Table) error {
+		return table.ToText(w, color)
+	})
+}
+
+// ToCSV renders t in CSV (comma-separated values) format.
+//
+// Warnings are written to a separate stream so as not to interrupt
+// the regular format of the CSV table.
+func (t *Tables) ToCSV(w, warnings io.Writer) error {
+	o := csv.NewWriter(w)
+	row := 1
+
+	err := t.printTables(func(hdr string) error {
+		o.Write([]string{hdr})
+		row++
+		return nil
+	}, func(table *Table) error {
+		nRows := table.ToCSV(o, row, warnings)
+		row += nRows
+		return nil
+	})
+	if err != nil {
+		return err
+	}
+	o.Flush()
+	return o.Error()
+}
+
+func (t *Tables) printTables(hdr func(string) error, cb func(*Table) error) error {
+	if len(t.Tables) == 0 {
+		return nil
+	}
+
+	var prevKey benchproc.Key
+	fields := t.Keys[0].Projection().FlattenedFields()
+
+	for i, table := range t.Tables {
+		if i > 0 {
+			// Blank line between tables.
+			if err := hdr(""); err != nil {
+				return err
+			}
+		}
+
+		// Print table key changes.
+		key := t.Keys[i]
+		for _, f := range fields {
+			if f.Name == ".unit" {
+				// Skip .unit because it's shown in the table itself.
+				continue
+			}
+			val := key.Get(f)
+			if prevKey.IsZero() || val != prevKey.Get(f) {
+				if err := hdr(fmt.Sprintf("%s: %s", f.Name, val)); err != nil {
+					return err
+				}
+			}
+		}
+		prevKey = key
+
+		// Print table.
+		if err := cb(table); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

internal/benchtab/table.go (0 → 11611)

diff --git a/internal/benchtab/table.go b/internal/benchtab/table.go
new file mode 100644
index 0000000..73fae8a
--- /dev/null
+++ b/internal/benchtab/table.go
@@ -0,0 +1,437 @@
+// Note(alexwlchan, 2026-11-04): This file was retrieved from
+// https://cs.opensource.google/go/x/perf/+/be2c69fb:cmd/benchstat/internal/benchtab/table.go
+//
+// The only modification is updating the import for internal/texttab.
+
+// Copyright 2020 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package benchtab
+
+import (
+	"encoding/csv"
+	"fmt"
+	"io"
+	"strings"
+
+	"alexwlchan.net/gotools/internal/texttab"
+	"golang.org/x/perf/benchmath"
+	"golang.org/x/perf/benchproc"
+	"golang.org/x/perf/benchunit"
+)
+
+// A Table summarizes and compares benchmark results in a 2D grid.
+// Each cell summarizes a Sample of results with identical row and
+// column Keys. Comparisons are done within each row between the
+// Sample in the first column and the Samples in any remaining
+// columns.
+type Table struct {
+	// Opts is the configuration options for this table.
+	Opts TableOpts
+
+	// Unit is the benchmark unit of all samples in this Table.
+	Unit string
+
+	// Assumption is the distributional assumption used for all
+	// samples in this table.
+	Assumption benchmath.Assumption
+
+	// Rows and Cols give the sequence of row and column Keys
+	// in this table. All row Keys have the same Projection and all
+	// col Keys have the same Projection.
+	Rows, Cols []benchproc.Key
+
+	// Cells contain the cells in the body of this table. Each key in
+	// this map is a pair of some Key from Rows and some Key
+	// from Cols. However, not all Pairs may be present in the
+	// map.
+	Cells map[TableKey]*TableCell
+
+	// Summary is the final row of this table, which gives summary
+	// information across all benchmarks in this table. It is
+	// keyed by Cols.
+	Summary map[benchproc.Key]*TableSummary
+
+	// SummaryLabel is the label for the summary row.
+	SummaryLabel string
+}
+
+// TableKey is a map key used to index a single cell in a Table.
+type TableKey struct {
+	Row, Col benchproc.Key
+}
+
+// TableCell is a single cell in a Table. It represents a sample of
+// benchmark results with the same row and column Key.
+type TableCell struct {
+	// Sample is the set of benchmark results in this cell.
+	Sample *benchmath.Sample
+
+	// Summary is the summary of Sample, as computed by the
+	// Table's distributional assumption.
+	Summary benchmath.Summary
+
+	// Baseline is the baseline cell used for comparisons with
+	// this cell, or nil if there is no comparison. This is the
+	// cell in the first column of this cell's row, if any.
+	Baseline *TableCell
+
+	// Comparison is the comparison with the Baseline cell, as
+	// computed by the Table's distributional assumption. If
+	// Baseline is nil, this value is meaningless.
+	Comparison benchmath.Comparison
+}
+
+// TableSummary is a cell that summarizes a column of a Table.
+// It appears in the last row of a table.
+type TableSummary struct {
+	// HasSummary indicates that Summary is valid.
+	HasSummary bool
+	// Summary summarizes all of the TableCell.Summary values in
+	// this column.
+	Summary float64
+
+	// HasRatio indicates that Ratio is valid.
+	HasRatio bool
+	// Ratio summarizes all of the TableCell.Comparison values in
+	// this column.
+	Ratio float64
+
+	// Warnings is a list of warnings for this summary cell.
+	Warnings []error
+}
+
+// RowScaler returns a common scaler for the values in row.
+func (t *Table) RowScaler(row benchproc.Key, unitClass benchunit.Class) benchunit.Scaler {
+	// Collect the row summaries.
+	var values []float64
+	for _, col := range t.Cols {
+		cell, ok := t.Cells[TableKey{row, col}]
+		if ok {
+			values = append(values, cell.Summary.Center)
+		}
+	}
+	return benchunit.CommonScale(values, unitClass)
+}
+
+// ToText renders t to a textual representation, assuming a
+// fixed-width font.
+func (t *Table) ToText(w io.Writer, color bool) error {
+	var o texttab.Table
+
+	// Each logical column expands to centerCols columns, plus
+	// deltaCols columns if there's a baseline.
+	const labelCols = 1
+	const centerCols = 3 // <center ±> <CI> <warnings>
+	const deltaCols = 3  // <P%> <(p=0.PPP n=N)> <warnings>
+
+	// startCol returns the index of the first centerCol of
+	// logical column exp.
+	startCol := func(exp int) int {
+		if exp == 0 {
+			return labelCols
+		}
+		// The width of experiment 0 is just centerCols. All
+		// later experiments are centerCols+deltaCols.
+		return labelCols + centerCols + (exp-1)*(centerCols+deltaCols)
+	}
+
+	var warningList []string
+	warningSet := make(map[string]int)
+	warn := func(msgs ...[]error) {
+		var footnotes []string
+		for _, msgs1 := range msgs {
+			for _, msg := range msgs1 {
+				s := msg.Error()
+				i, ok := warningSet[s]
+				if !ok {
+					i = len(warningList)
+					warningSet[s] = i
+					warningList = append(warningList, s)
+				}
+				footnotes = append(footnotes, superscript(i+1))
+			}
+		}
+		s := strings.Join(footnotes, " ")
+		o.Cell(s)
+	}
+
+	// Construct the header.
+	kt := benchproc.NewKeyHeader(t.Cols)
+	rEdge := startCol(len(t.Cols) + 1)
+	nodes := kt.Top
+	for len(nodes) > 0 {
+		// Process this level.
+		var nextNodes []*benchproc.KeyHeaderNode
+		o.Row()
+		for _, node := range nodes {
+			l := startCol(node.Start)
+			r := startCol(node.Start + node.Len)
+			// Configuration headers can span a lot of
+			// columns, so we add a vertical rule to more
+			// clearly delineate the columns they span. We
+			// also add some space so that each logical
+			// column in the rest of the table is better
+			// separated.
+			o.Col(l).Span(r-l, node.Value, texttab.Center, texttab.LeftMargin(" │ "))
+			nextNodes = append(nextNodes, node.Children...)
+		}
+		// Add a vertical bar down the right side to match the other
+		// separators.
+		o.Col(rEdge).Cell("", texttab.LeftMargin(" │"))
+		nodes = nextNodes
+	}
+
+	// Add the column labels row, set margins, and create stretch
+	// columns.
+	o.Row()
+	for i := range t.Cols {
+		l := startCol(i)
+		o.Col(l)
+
+		// Show the unit over the center column group, since
+		// these are values in that unit.
+		o.Span(centerCols, t.Unit, texttab.Center, texttab.LeftMargin(" │ "))
+
+		if i > 0 {
+			// All but the first column will have A/B
+			// comparisons.
+			//
+			// Separate center and delta column groups by
+			// 2 spaces.
+			o.Span(deltaCols, "vs base", texttab.Left, texttab.LeftMargin("  "))
+		}
+
+		// Make all of the interior columns in this column
+		// group shrink columns, leaving on the leftmost and
+		// rightmost to stretch.
+		for j := l + 1; j < o.CurCol(); j++ {
+			o.SetShrink(j, true)
+		}
+	}
+	o.Col(rEdge).Cell("", texttab.LeftMargin(" │"))
+
+	// Emit measurements.
+	unitClass := benchunit.ClassOf(t.Unit)
+	for _, row := range t.Rows {
+		o.Row()
+
+		// TODO: Should I put each row key value in a
+		// column? With the keys as headers?
+		o.Cell(row.StringValues())
+
+		// Get a common scalar across this row.
+		scalar := t.RowScaler(row, unitClass)
+
+		for exp, col := range t.Cols {
+			cell, ok := t.Cells[TableKey{row, col}]
+			if !ok {
+				continue
+			}
+
+			o.Col(startCol(exp))
+			o.Cell(scalar.Format(cell.Summary.Center), texttab.Right)
+			// Put ± in the margin so 1) the ±s line up,
+			// 2) the geomean value (which doesn't have ±)
+			// aligns with the summary column, 3) we can
+			// right align the range column.
+			o.Cell(cell.Summary.PctRangeString(), texttab.Right, texttab.LeftMargin(" ± "))
+			warn(cell.Sample.Warnings, cell.Summary.Warnings)
+			if exp > 0 && cell.Baseline != nil {
+				d := cell.Comparison.FormatDelta(cell.Baseline.Summary.Center, cell.Summary.Center)
+				// TODO: Color the delta for whether
+				// it's good or bad.
+				o.Cell(d, texttab.Right)
+				o.Cell("(" + cell.Comparison.String() + ")")
+				warn(cell.Comparison.Warnings)
+			}
+		}
+	}
+
+	// Emit summary row.
+	if len(t.Rows) > 1 {
+		o.Row()
+		o.Cell(t.SummaryLabel)
+		for exp, col := range t.Cols {
+			tsum, ok := t.Summary[col]
+			if !ok {
+				continue
+			}
+
+			if tsum.HasSummary {
+				o.Col(startCol(exp))
+				o.Cell(benchunit.Scale(tsum.Summary, unitClass), texttab.Right)
+			}
+			if exp > 0 {
+				o.Col(startCol(exp) + centerCols)
+				if tsum.HasRatio {
+					o.Cell(fmt.Sprintf("%+.2f%%", (tsum.Ratio-1)*100), texttab.Right)
+				} else {
+					o.Cell("?")
+				}
+			}
+
+			o.Col(startCol(exp+1) - 1)
+			warn(tsum.Warnings)
+		}
+	}
+
+	// Emit table.
+	if err := o.Format(w); err != nil {
+		return err
+	}
+
+	// Emit warnings.
+	if len(warningList) > 0 {
+		for i, msg := range warningList {
+			if _, err := fmt.Fprintf(w, "%s %s\n", superscript(i+1), msg); err != nil {
+				return err
+			}
+		}
+	}
+
+	return nil
+}
+
+var superDigits = []rune("⁰¹²³⁴⁵⁶⁷⁸⁹")
+
+func superscript(i int) string {
+	if i == 0 {
+		return string(superDigits[0])
+	}
+
+	var buf [20]rune
+	pos := len(buf)
+	for i > 0 && pos > 0 {
+		pos--
+		buf[pos] = superDigits[i%10]
+		i /= 10
+	}
+	return string(buf[pos:])
+}
+
+// ToCSV renders t to CSV format. Warnings are written in text format
+// to the "warnings" Writer, and prefixed with spreadsheet-style cell
+// references. These references assume the table begins on row
+// "startRow".
+func (t *Table) ToCSV(o *csv.Writer, startRow int, warnings io.Writer) (rowCount int) {
+	const labelCols = 1
+	const centerCols = 2 // <center> <CI>
+	const deltaCols = 2  // <P%> <(p=0.PPP n=N)>
+	startCol := func(exp int) int {
+		if exp == 0 {
+			// Baseline, so no delta.
+			return labelCols
+		}
+		// Center and delta columns.
+		l := labelCols + centerCols + (exp-1)*(centerCols+deltaCols)
+		return l
+	}
+	row := make([]string, startCol(len(t.Cols)))
+	row = row[:0]
+	clearTo := func(col int) {
+		for len(row) < col {
+			row = append(row, "")
+		}
+	}
+	emit := func() {
+		o.Write(row)
+		row = row[:0]
+		rowCount++
+	}
+	warn := func(msgs []error) {
+		// Construct a spreadsheet-style cell label.
+		colName := make([]byte, 10)
+		colNamePos := len(colName)
+		for x := len(row); x > 0; {
+			colNamePos--
+			colName[colNamePos] = 'A' + byte(x%26)
+			x /= 26
+		}
+		if colNamePos == len(colName) {
+			colNamePos--
+			colName[colNamePos] = 'A'
+		}
+		colName = colName[colNamePos:]
+		// Print warnings.
+		for _, msg := range msgs {
+			fmt.Fprintf(warnings, "%s%d: %s\n", colName, startRow+rowCount, msg)
+		}
+	}
+
+	// Emit column configurations header.
+	colFields := t.Cols[0].Projection().FlattenedFields()
+	for _, field := range colFields {
+		for exp, key := range t.Cols {
+			clearTo(startCol(exp))
+			row = append(row, key.Get(field))
+		}
+		clearTo(startCol(len(t.Cols)))
+		emit()
+	}
+
+	// Emit column headers.
+	for exp := range t.Cols {
+		clearTo(startCol(exp))
+		row = append(row, t.Unit, "CI")
+		if exp > 0 {
+			row = append(row, "vs base", "P")
+		}
+	}
+	emit()
+
+	// Emit table.
+	for _, rowKey := range t.Rows {
+		row = append(row, rowKey.StringValues())
+		for exp, colKey := range t.Cols {
+			cell, ok := t.Cells[TableKey{rowKey, colKey}]
+			if !ok {
+				continue
+			}
+
+			clearTo(startCol(exp))
+			warn(cell.Sample.Warnings)
+			warn(cell.Summary.Warnings)
+			row = append(row,
+				fmt.Sprint(cell.Summary.Center),
+				cell.Summary.PctRangeString(),
+			)
+			if exp > 0 && cell.Baseline != nil {
+				warn(cell.Comparison.Warnings)
+				row = append(row,
+					cell.Comparison.FormatDelta(cell.Baseline.Summary.Center, cell.Summary.Center),
+					cell.Comparison.String(),
+				)
+			}
+		}
+		emit()
+	}
+
+	// Emit summary row.
+	row = append(row, t.SummaryLabel)
+	for exp, key := range t.Cols {
+		tsum, ok := t.Summary[key]
+		if !ok {
+			continue
+		}
+
+		clearTo(startCol(exp))
+		warn(tsum.Warnings)
+		if tsum.HasSummary {
+			row = append(row, fmt.Sprint(tsum.Summary))
+		}
+		if exp > 0 {
+			clearTo(startCol(exp) + centerCols)
+			if tsum.HasRatio {
+				row = append(row, fmt.Sprintf("%+.2f%%", (tsum.Ratio-1)*100))
+			} else {
+				row = append(row, "?")
+			}
+		}
+	}
+	clearTo(startCol(len(t.Cols)))
+	emit()
+
+	return
+}

internal/texttab/table.go (0 → 7198)

diff --git a/internal/texttab/table.go b/internal/texttab/table.go
new file mode 100644
index 0000000..7bba817
--- /dev/null
+++ b/internal/texttab/table.go
@@ -0,0 +1,291 @@
+// Note(alexwlchan, 2026-11-04): This file was retrieved from
+// https://cs.opensource.google/go/x/perf/+/be2c69fb:cmd/benchstat/internal/texttab/table.go
+
+// Copyright 2020 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package texttab
+
+import (
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+	"unicode/utf8"
+)
+
+// Table does layout of text-based tables.
+//
+// Many of its methods return the textTable so callers can easily
+// chain them to build up many cells at once.
+type Table struct {
+	cells []textCell
+	cols  int
+
+	shrink []bool
+
+	curRow, curCol int
+}
+
+type textCell struct {
+	row, col, span int
+	value          string
+	leftMargin     string
+	alignment      align
+}
+
+type CellOption func(c *textCell)
+
+func LeftMargin(x string) CellOption {
+	return func(c *textCell) {
+		c.leftMargin = x
+	}
+}
+
+var (
+	Left   CellOption = func(c *textCell) { c.alignment = alignLeft }
+	Center            = func(c *textCell) { c.alignment = alignCenter }
+	Right             = func(c *textCell) { c.alignment = alignRight }
+)
+
+type align int
+
+const (
+	alignLeft align = iota
+	alignCenter
+	alignRight
+)
+
+func (a align) lpad(s string, w int) string {
+	switch a {
+	default:
+		return s
+	case alignCenter:
+		l := (w - utf8.RuneCountInString(s)) / 2
+		return fmt.Sprintf("%*s%s", l, "", s)
+	case alignRight:
+		return fmt.Sprintf("%*s", w, s)
+	}
+}
+
+// Row starts a new row in table t.
+func (t *Table) Row() *Table {
+	if len(t.cells) > 0 {
+		t.curRow++
+	}
+	t.curCol = 0
+	return t
+}
+
+// Col skips to column "col" in table t. Columns are numbered starting
+// at 0.
+func (t *Table) Col(col int) *Table {
+	if col < t.curCol {
+		panic(fmt.Sprintf("cannot move from column %d to earlier column %d", t.curCol, col))
+	}
+	t.curCol = col
+	return t
+}
+
+// CurCol returns the current column index.
+func (t *Table) CurCol() int {
+	return t.curCol
+}
+
+// Cell adds a single-column cell at the current row and column.
+func (t *Table) Cell(value string, opts ...CellOption) *Table {
+	return t.Span(1, value, opts...)
+}
+
+// Span adds a multi-column cell at the current row and column.
+func (t *Table) Span(cols int, value string, opts ...CellOption) *Table {
+	lMargin := " "
+	if t.curCol == 0 || len(value) == 0 {
+		// For the left-most column or empty cells, we default
+		// to no left margin.
+		lMargin = ""
+	}
+	t.cells = append(t.cells, textCell{t.curRow, t.curCol, cols, value, lMargin, alignLeft})
+	for _, o := range opts {
+		o(&t.cells[len(t.cells)-1])
+	}
+
+	t.curCol += cols
+	if t.curCol > t.cols {
+		t.cols = t.curCol
+	}
+
+	return t
+}
+
+// SetShrink marks a column as a "shrink" column, which will have
+// minimum width.
+func (t *Table) SetShrink(col int, shrink bool) {
+	for len(t.shrink) < col+1 {
+		t.shrink = append(t.shrink, false)
+	}
+	t.shrink[col] = shrink
+}
+
+// Format lays out table t and writes it to w.
+func (t *Table) Format(w io.Writer) error {
+	shrink := func(col int) bool {
+		if col < len(t.shrink) {
+			return t.shrink[col]
+		}
+		return false
+	}
+
+	// Collect max length margin for each column.
+	lmargin := make([]int, t.cols)
+	for _, cell := range t.cells {
+		lmargin[cell.col] = max(utf8.RuneCountInString(cell.leftMargin), lmargin[cell.col])
+	}
+
+	// Compute column widths, including their left margins.
+	ws := make([]int, t.cols)
+	// Consider cells in increasing span width.
+	sort.Slice(t.cells, func(i, j int) bool {
+		return t.cells[i].span < t.cells[j].span
+	})
+	var spanCols []int
+	for _, cell := range t.cells {
+		w := utf8.RuneCountInString(cell.value) + lmargin[cell.col]
+
+		if cell.span == 1 {
+			// Easy case.
+			ws[cell.col] = max(ws[cell.col], w)
+			continue
+		}
+
+		// This cell spans multiple columns. Is the total
+		// width of those columns already sufficient?
+		tw := 0
+		for col := cell.col; col < cell.col+cell.span; col++ {
+			tw += ws[col]
+		}
+		if tw >= w {
+			continue
+		}
+
+		// We need to expand columns. The goal is to expand
+		// them all to the necessary average, but some may
+		// already be wider than this average. Hence, we
+		// process columns from widest to narrowest,
+		// subtracting out the columns that are already wider
+		// than the target average (which in turn changes the
+		// target), and then distributing the remaining space
+		// among the narrower ones.
+		spanCols = spanCols[:0]
+		for col := cell.col; col < cell.col+cell.span; col++ {
+			if shrink(col) {
+				// We can't grow a shrink column, so
+				// account for its space, but don't
+				// add it to the columns to adjust.
+				w -= ws[col]
+			} else {
+				spanCols = append(spanCols, col)
+			}
+		}
+		// Process the wider columns first.
+		sort.Slice(spanCols, func(i, j int) bool {
+			return ws[spanCols[i]] > ws[spanCols[j]]
+		})
+		span := len(spanCols)
+		for _, col := range spanCols {
+			// What's the target average width at this
+			// point? Round up with span.
+			avg := (w + span - 1) / span
+			// Expand column if it isn't wide enough.
+			ws[col] = max(ws[col], avg)
+			// Subtract this column from the space needed.
+			// If the column was already wide enough, this
+			// will redistribute its excess across the
+			// smaller columns. We also do this if we
+			// expanded the column as a convenient way to
+			// spread out the integer rounding of avg.
+			w -= ws[col]
+			span--
+		}
+	}
+
+	// Convert column widths into starting offsets. The offset of
+	// column i is where i's left margin begins. The slice
+	// includes a final offset for the width of the table.
+	offs := make([]int, t.cols+1)
+	off := 0
+	for i, w := range ws {
+		offs[i] = off
+		off += w
+	}
+	offs[len(ws)] = off
+
+	const debugPrintColumns = false
+	if debugPrintColumns {
+		fmt.Println(ws)
+		pos := 0
+		for col, off := range offs {
+			fmt.Fprintf(w, "%*s", off-pos, "")
+			pos = off
+			for i := 0; i < lmargin[col]; i++ {
+				fmt.Fprintf(w, "|")
+				pos++
+			}
+		}
+		fmt.Fprint(w, "\n")
+	}
+
+	// Format the table. Put the cells back into top-to-bottom
+	// left-to-right order.
+	sort.Slice(t.cells, func(i, j int) bool {
+		if t.cells[i].row != t.cells[j].row {
+			return t.cells[i].row < t.cells[j].row
+		}
+		return t.cells[i].col < t.cells[j].col
+	})
+	row, off := 0, 0
+	for _, cell := range t.cells {
+		if strings.TrimSpace(cell.value) == "" && strings.TrimSpace(cell.leftMargin) == "" {
+			// Skip empty cells. This avoids printing
+			// unnecessary trailing spaces if cells appear
+			// at the end of a row.
+			continue
+		}
+
+		// Get to cell's row.
+		for cell.row > row {
+			if _, err := fmt.Fprintf(w, "\n"); err != nil {
+				return err
+			}
+			row++
+			off = 0
+		}
+
+		// Space to the cell's starting offset and print its
+		// left margin.
+		spaces := offs[cell.col] - off
+		if _, err := fmt.Fprintf(w, "%*s%*s", spaces, "", lmargin[cell.col], cell.leftMargin); err != nil {
+			return err
+		}
+		off += spaces + lmargin[cell.col]
+
+		// Compute total cell width, excluding the margin we
+		// just printed.
+		tw := offs[cell.col+cell.span] - offs[cell.col] - lmargin[cell.col]
+
+		// Print cell contents.
+		s := cell.alignment.lpad(cell.value, tw)
+		if _, err := fmt.Fprintf(w, "%s", s); err != nil {
+			return err
+		}
+		off += utf8.RuneCountInString(s)
+	}
+	if len(t.cells) > 0 {
+		if _, err := fmt.Fprintf(w, "\n"); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

internal/texttab/table_test.go (0 → 3071)

diff --git a/internal/texttab/table_test.go b/internal/texttab/table_test.go
new file mode 100644
index 0000000..d92598f
--- /dev/null
+++ b/internal/texttab/table_test.go
@@ -0,0 +1,121 @@
+// Note(alexwlchan, 2026-11-04): This file was retrieved from
+// https://cs.opensource.google/go/x/perf/+/be2c69fb:cmd/benchstat/internal/texttab/table_test.go
+
+// Copyright 2020 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package texttab
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestAlign(t *testing.T) {
+	check := func(s string, a align, w int, want string) {
+		t.Helper()
+		got := a.lpad(s, w)
+		if got != want {
+			t.Errorf("want %q, got %q", want, got)
+		}
+	}
+
+	check("abc", alignLeft, 10, "abc")
+	check("abc", alignCenter, 10, "   abc")
+	check("abc", alignCenter, 11, "    abc")
+	check("abc", alignRight, 10, "       abc")
+	check("☃", alignRight, 4, "   ☃")
+}
+
+func TestTable(t *testing.T) {
+	var tab Table
+	check := func(want string) {
+		t.Helper()
+		var gotBuf strings.Builder
+		tab.Format(&gotBuf)
+		got := gotBuf.String()
+		if want != got {
+			t.Errorf("want:\n%sgot:\n%s", want, got)
+		}
+		// Reset tab.
+		tab = Table{}
+	}
+
+	// Basic test.
+	tab.Row().Cell("a").Cell("b").Cell("c")
+	tab.Row().Cell("d").Cell("e").Cell("f")
+	check("a b c\nd e f\n")
+
+	// Basic cell padding. Also checks that we don't print
+	// unnecessary spaces at the ends of lines.
+	tab.Row().Cell("a").Cell("b").Cell("c")
+	tab.Row().Cell("long").Cell("e").Cell("long")
+	check("a    b c\nlong e long\n")
+
+	// Cell alignment.
+	tab.Row().Cell("a", Left).Cell("b", Center).Cell("c", Right)
+	tab.Row().Cell("xxx").Cell("xxx").Cell("xxx")
+	check("a    b    c\nxxx xxx xxx\n")
+
+	// Margins.
+	tab.Row().Cell("a").Cell("b", LeftMargin("  "))
+	tab.Row().Cell("c").Cell("d")
+	tab.Row().Cell("e").Cell("f", LeftMargin("|"))
+	check("a  b\nc  d\ne |f\n")
+
+	// Missing cell in the middle.
+	tab.Row().Cell("a").Col(2).Cell("c")
+	tab.Row().Cell("d").Cell("e").Cell("f")
+	check("a   c\nd e f\n")
+
+	// Missing cells at the end.
+	tab.Row().Cell("a")
+	tab.Row().Cell("d").Cell("e").Cell("f")
+	check("a\nd e f\n")
+
+	// Blank rows.
+	tab.Row().Cell("a")
+	tab.Row()
+	tab.Row()
+	tab.Row().Cell("b")
+	check("a\n\n\nb\n")
+
+	// Basic spans.
+	tab.Row().Cell("a").Cell("b")
+	tab.Row().Span(2, "abc")
+	check("a b\nabc\n")
+
+	// Spans expanding other cells.
+	tab.Row().Cell("a").Cell("b")
+	tab.Row().Span(2, "abcdefg")
+	check("a   b\nabcdefg\n")
+
+	// Other cells expanding spans.
+	tab.Row().Cell("abc").Cell("def")
+	tab.Row().Span(2, "a", Right)
+	check("abc def\n      a\n")
+
+	// Some cells are already large enough to complete the span.
+	tab.Row().Cell("a").Cell("def")
+	tab.Row().Span(2, "abdef", Right)
+	check("a def\nabdef\n")
+
+	// Larger cells are sufficient, but smaller cells need to be
+	// expanded.
+	tab.Row().Cell("a").Cell("def")
+	tab.Row().Span(2, "abcdef", Right)
+	check("a  def\nabcdef\n")
+
+	// Spans with margins.
+	tab.Row().Cell("a").Cell("b", LeftMargin("  ")).Cell("x")
+	tab.Row().Span(2, "a__b").Cell("x")
+	check("a  b x\na__b x\n")
+
+	// Shrink columns.
+	tab.Row().Span(2, "abcdef")
+	tab.Row().Cell("a").Cell("bc")
+	tab.Row().Cell("x").Cell("y")
+	tab.SetShrink(1, true)
+	check("abcdef\na   bc\nx   y\n")
+}