go-spew

go-spew is a small Go library for producing detailed, readable dumps of arbitrary in-memory data structures. Where the standard fmt package hides unexported fields, elides pointer chains, and doesn’t guard against cycles, go-spew walks every value with reflection, prints types and pointer addresses at every level, and safely detects circular references it has already visited.

It ships as both a standalone dumper (spew.Dump, spew.Sdump, spew.Fdump) and a set of drop-in wrappers around fmt’s Print/Printf family (spew.Printf, spew.Sprintf, spew.Errorf, and more) that substitute a custom Formatter for each argument. Configuration is centralized in a ConfigState struct, so indentation, depth limits, pointer-address visibility, and method-invocation behavior can be tuned globally or per call.

What You Get

• Dump/Fdump/Sdump functions for full multi-line, indented dumps with type and pointer information
• Printf/Sprintf/Fprintf-style wrappers that substitute go-spew formatting into any fmt call
• A ConfigState struct for tuning indent, MaxDepth, pointer visibility, and method invocation, globally or per instance
• Automatic circular-reference detection that prevents infinite recursion on self-referential structs
• Hexdump-style output for byte slices and arrays, matching hexdump -C

Common Use Cases

• Debugging nested structs, maps, and slices during local development
• Printing readable failure diffs in unit tests, often paired with testify
• Inspecting unexported struct fields without writing custom String() methods
• Diagnosing corrupted or unexpected data shapes in application log output
• Comparing two data structures visually when debugging serialization bugs

Under The Hood

Architecture go-spew is organized as a single flat package (spew) that separates the dumping engine (dump.go, dumpState) from the fmt-wrapper formatting layer (format.go, spew.go), sharing constant byte-slice literals and low-level value printers defined in common.go; a ConfigState struct in config.go centralizes every behavior tunable, and both entry points construct a fresh dumpState/formatState against it rather than mutating global state, so each call is independent and safe for concurrent use. Circular-reference detection is handled with a pointer-address-to-depth map threaded through the recursive dump() walker, and the unsafe-vs-safe split (bypass.go / bypasssafe.go) is resolved entirely at compile time via build tags, giving one clean call site (unsafeReflectValue) regardless of platform.

Tech Stack The package has zero third-party dependencies, relying only on Go’s standard library (reflect, unsafe, fmt, bytes, encoding/hex, regexp, sort, strconv, io, os). No go.mod is checked in, since the code predates Go modules; its own build-tag comments target compatibility back to go1.4, with special handling for environments where unsafe isn’t available, such as Google App Engine and GopherJS. CI (.travis.yml) runs gometalinter (gofmt, golint, vet, gosimple, unconvert) plus go test -race across Go 1.6 through tip, uploading coverage to Coveralls.

Code Quality The package ships nine test files whose combined size exceeds the implementation code, and the repo’s own test_coverage.txt documents effectively complete coverage of dump.go, format.go, and common.go; CI enforces this with race-detector runs, a coverage upload, and a linter gate that fails the build on any gofmt/golint/vet/gosimple deviation. Error handling is intentionally minimal, since this is a pure formatter with almost nothing that can fail; the one real risk, a panic inside a caller’s Stringer or error method, is explicitly caught with catchPanic/recover in common.go rather than left to propagate. Naming and structure follow idiomatic stdlib-style Go, with unexported byte-slice constants used in place of string literals to avoid allocation overhead.

What Makes It Unique go-spew’s defining technical choice is using the unsafe package to read reflect.Value’s private flag bits, bypassing Go’s visibility restrictions so it can print unexported struct fields and invoke pointer-receiver Stringer/error methods that reflection alone can’t reach. It pairs this with explicit pointer-address cycle detection so arbitrarily self-referential graphs never blow the stack, plus a hexdump-style renderer for byte slices. None of these ideas are unique in isolation, but the combination of safe unsafe-package use, full cycle safety, and a fmt-drop-in API made go-spew the de facto standard debug and test-diff dumper across the Go ecosystem, where it remains a near-ubiquitous transitive dependency despite little new capability being added in recent years.