Reference
Every command, flag, format and limit in Abbreviatory v0.2.0. For a first run, the quick start is shorter. The same reference is in the code repository as docs/reference.md.
Commands
| Command | What it does |
|---|---|
abbreviatory reduce [flags] [file] |
Reduce a file, or standard input, and print the report |
abbreviatory run [flags] -- CMD |
Run a command, reduce what it prints, compare with its last run, exit with its status |
abbreviatory history [KEY] |
List the run histories, or the runs of one |
abbreviatory expand [-store dir] REF |
Print the original bytes a reference stands for |
abbreviatory prune [-older 168h] [-max-size 500MB] |
Remove old stored originals |
abbreviatory formats |
List the input formats |
abbreviatory version |
Print the version |
Exit codes: run exits with the command’s own status (127 if the command isn’t found). Otherwise 0 when it worked, 1 when the work failed (unreadable input, a budget too small, a reference not in the store), 2 for a usage mistake.
Flags for reduce and run
| Flag | Default | What it does |
|---|---|---|
-budget N |
4096 | Most bytes of output. At least 512 |
-preserve LIST |
errors,failures,warnings | What is always shown or referenced. Empty for nothing |
-keep REGEX |
Also keep lines matching this. Repeatable | |
-format NAME |
auto | auto, test-output, logs, json, or one of the formats below |
-json |
off | Print a JSON object with the counts and the report |
-no-store |
off | Don’t keep the original. The report then has no references |
-key NAME |
Keep a run history under NAME and report what changed. run names one after the project and the command |
|
-full |
off | With a history, the whole report even when nothing changed |
-no-history |
off | run only: keep no history |
-store DIR |
cache directory | Where originals and histories are kept. Also $ABBREVIATORY_STORE |
Formats
| Name | What it reads |
|---|---|
gotest-json |
go test -json: one record per test, with its output; build failures and tests that never finished too |
gotest |
Plain and -v go test output, subtests, panics, build errors |
pytest |
pytest, verbose or not: FAILURES and ERRORS sections matched to the short summary, the warnings summary, the final count |
junit |
JUnit XML reports, one record per testcase |
logs |
Anything that is text: levels, stack traces, Python tracebacks, Go panics |
json |
One JSON document, shown as a valid JSON outline |
The level of a log line comes from upper-case words near its start (ERROR, WARN, FATAL, CRITICAL and others), level= and JSON level fields, bracketed levels, glog prefixes, compiler style error: and warning:, and the first line of a panic or traceback.
The Report
[abbreviatory] <format>, <lines> (<size>), ref <ID>
<counts>
FAILED (n):
- <test> [ref ID:gN]
<the failure message>
ERRORS (<kinds>, <lines>):
- x<count> <the first line of the group> [ref ID:gN]
MATCHED --keep (...):
WARNINGS (...):
OTHER (...):
not shown: <what was left out> [ref ID:<kind>]
How the budget is spent: the header, the counts and the “not shown” lines are set aside first. Then every failure, error, keep-rule match and warning gets its one line. Then detail lines are shared out in rounds (2 each, then 6, 16 and 40), so every failure shows some of its message before any shows all of it. Other groups fill what’s left, most frequent first.
If even the header and the counts don’t fit, reduce fails and says how many bytes it needs. When an input is so small that showing it whole is no longer than reducing it, it’s shown whole.
References
A reference is ID:selector. The ID is a hash of the input, so the same input always gets the same ID.
| Selector | Expands to |
|---|---|
| none | The whole input |
gN |
The original lines of group N |
fail, error, warn, info, pass, skip |
Every line of that kind |
keep |
Every line a -keep rule matched |
L10 or L10-40 |
Those input lines |
/items/3 |
For JSON: that value, as it is in the input |
errors |
For JSON: every error field with its value |
Lines come back byte for byte, in input order.
Run History
With a history, each run is compared with the one before it. A failed test is known by its name. Anything else, a log error or a failed build, is known by its text with numbers and IDs aside.
| In the report | Meaning |
|---|---|
| new | failing now, not in the last run |
| fixed (logs: gone) | failing in the last run, passing now |
| not run | a test failing in the last run that was skipped or didn’t run this time |
| still failing (logs: recurring) | failing in both, marked with how many runs in a row |
| flaky (logs: intermittent) | changed between passing and failing 3 or more times in the last 10 runs |
New failures come first in the report, marked (new). Fixed ones carry a reference into the run where they last failed. When the same failures are there as last time, the report is one line, unless you pass -full. A history keeps the last 50 runs and is removed after 90 days unused.
Limits in v0.2.0
- Known formats only. Free prose, or a log format it doesn’t recognise, is reduced only by folding repeats and finding level words.
- Numbers don’t count for grouping. Two errors that differ only in a number, a port or a status code are one group. The first is shown, and the count says how many.
- Some inputs are read whole. JSON documents and JUnit reports are read in one piece, up to 256 MB. Logs and test output stream with no size limit.
- References need the stored original. With
-no-store, or after pruning, they can’t be expanded. - Plain go test and pytest only name failures. Without
-v, a failing test that disappears counts as fixed, even if it was deleted or skipped. - History tracks failures and errors only. Warnings and keep-rule matches aren’t compared. A log error whose wording changes counts as new.
- CI needs the store kept between runs. CI machines start empty, so cache the store directory, or every run is run 1.
- No service yet. An HTTP service and an MCP server are planned for v0.3.