godump

godump is a developer-friendly, zero-dependency debug dumper for Go. It provides pretty, colorized terminal output of your structs, slices, maps, and more - complete with cyclic reference detection and control character escaping. Inspired by Symfony's VarDumper which is used in Laravel's tools like dump() and dd().

Terminal Output Example (Kitchen Sink)

HTML Output Example

godump.Diff(a,b) Output Example

Feature Comparison: godump vs go-spew vs pp

If you'd like to suggest improvements or additional comparisons, feel free to open an issue or PR.

Installation

go get github.com/goforj/godump

Basic Usage

View Full Runnable Example →

type User struct { Name string }
godump.Dump(User{Name: "Alice"})
// #main.User {
//    +Name => "Alice" #string
// }	

Extended Usage (Snippets)

godump.DumpStr(v)     // return as string
godump.DumpHTML(v)    // return HTML output
godump.DumpJSON(v)    // print JSON directly
godump.Fdump(w, v)    // write to io.Writer
godump.Dd(v)          // dump + exit
godump.Diff(a, b)     // diff two values
godump.DiffStr(a, b)  // diff two values as string
godump.DiffHTML(a, b) // diff two values as HTML

Diff Usage

View Diff Example →

type User struct {
    Name string
}
before := User{Name: "Alice"}
after := User{Name: "Bob"}
godump.Diff(before, after)
//   #main.User {
// -   +Name => "Alice" #string
// +   +Name => "Bob" #string
//   }

View Diff Extended Example →

Builder Options Usage

godump aims for simple usage with sensible defaults out of the box, but also provides a flexible builder-style API for customization.

If you want to heavily customize the dumper behavior, you can create a Dumper instance with specific options:

View Full Runnable Example →

godump.NewDumper(
    godump.WithMaxDepth(15),           // default: 15
    godump.WithMaxItems(100),          // default: 100
    godump.WithMaxStringLen(100000),   // default: 100000
    godump.WithWriter(os.Stdout),      // default: os.Stdout
    godump.WithSkipStackFrames(10),    // default: 10
    godump.WithDisableStringer(false), // default: false
    godump.WithoutColor(),             // default: false
).Dump(v)

Contributing

Ensure that all tests pass, and you run ./docs/generate.sh to update the API index in the README before submitting a PR.

Ensure all public functions have documentation blocks with examples, as these are used to generate runnable examples and the API index.

Runnable Examples Directory

Every function has a corresponding runnable example under ./examples.

These examples are generated directly from the documentation blocks of each function, ensuring the docs and code never drift. These are the same examples you see here in the README and GoDoc.

An automated test executes every example to verify it builds and runs successfully.

This guarantees all examples are valid, up-to-date, and remain functional as the API evolves.

<#dump // main.go:26

#main.User

  +Name => "Alice"
  -secret  => "..."

↩︎ &1

  0 => "value"
  a => 1

"Line1\nLine2\tDone"

API Index

Builder

NewDumper

NewDumper creates a new Dumper with the given options applied. Defaults are used for any setting not overridden.

v := map[string]int{"a": 1}
d := godump.NewDumper(
	godump.WithMaxDepth(10),
	godump.WithWriter(os.Stdout),
)
d.Dump(v)
// #map[string]int {
//   a => 1 #int
// }

Diff

Diff

Diff prints a diff between two values to stdout.

Example: print diff

a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
godump.Diff(a, b)
// <#diff // path:line
// - #map[string]int {
// -   a => 1 #int
// - }
// + #map[string]int {
// +   a => 2 #int
// + }

Example: print diff with a custom dumper

d := godump.NewDumper()
a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
d.Diff(a, b)
// <#diff // path:line
// - #map[string]int {
// -   a => 1 #int
// - }
// + #map[string]int {
// +   a => 2 #int
// + }

DiffHTML

DiffHTML returns an HTML diff between two values.

Example: HTML diff

a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
html := godump.DiffHTML(a, b)
_ = html
// (html diff)

Example: HTML diff with a custom dumper

d := godump.NewDumper()
a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
html := d.DiffHTML(a, b)
_ = html
// (html diff)

DiffStr

DiffStr returns a string diff between two values.

Example: diff string

a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
out := godump.DiffStr(a, b)
_ = out
// <#diff // path:line
// - #map[string]int {
// -   a => 1 #int
// - }
// + #map[string]int {
// +   a => 2 #int
// + }

Example: diff string with a custom dumper

d := godump.NewDumper()
a := map[string]int{"a": 1}
b := map[string]int{"a": 2}
out := d.DiffStr(a, b)
_ = out
// <#diff // path:line
// - #map[string]int {
// -   a => 1 #int
// - }
// + #map[string]int {
// +   a => 2 #int
// + }

Dump

Dd

Dd is a debug function that prints the values and exits the program.

Example: dump and exit

v := map[string]int{"a": 1}
godump.Dd(v)
// #map[string]int {
//   a => 1 #int
// }

Example: dump and exit with a custom dumper

d := godump.NewDumper()
v := map[string]int{"a": 1}
d.Dd(v)
// #map[string]int {
//   a => 1 #int
// }

Dump

Dump prints the values to stdout with colorized output.

Example: print to stdout

v := map[string]int{"a": 1}
godump.Dump(v)
// #map[string]int {
//   a => 1 #int
// }

Example: print with a custom dumper

d := godump.NewDumper()
v := map[string]int{"a": 1}
d.Dump(v)
// #map[string]int {
//   a => 1 #int
// }

DumpStr

DumpStr returns a string representation of the values with colorized output.

Example: get a string dump

v := map[string]int{"a": 1}
out := godump.DumpStr(v)
godump.Dump(out)
// "#map[string]int {\n  a => 1 #int\n}" #string

Example: get a string dump with a custom dumper

d := godump.NewDumper()
v := map[string]int{"a": 1}
out := d.DumpStr(v)
_ = out
// "#map[string]int {\n  a => 1 #int\n}" #string

Fdump

Fdump writes the formatted dump of values to the given io.Writer.

var b strings.Builder
v := map[string]int{"a": 1}
godump.Fdump(&b, v)
// outputs to strings builder

HTML

DumpHTML

DumpHTML dumps the values as HTML with colorized output.

Example: dump HTML

v := map[string]int{"a": 1}
html := godump.DumpHTML(v)
_ = html
// (html output)

Example: dump HTML with a custom dumper

d := godump.NewDumper()
v := map[string]int{"a": 1}
html := d.DumpHTML(v)
_ = html
fmt.Println(html)
// (html output)

JSON

DumpJSON

DumpJSON prints a pretty-printed JSON string to the configured writer.

Example: print JSON

v := map[string]int{"a": 1}
d := godump.NewDumper()
d.DumpJSON(v)
// {
//   "a": 1
// }

Example: print JSON

v := map[string]int{"a": 1}
godump.DumpJSON(v)
// {
//   "a": 1
// }

DumpJSONStr

DumpJSONStr pretty-prints values as JSON and returns it as a string.

Example: dump JSON string

v := map[string]int{"a": 1}
d := godump.NewDumper()
out := d.DumpJSONStr(v)
_ = out
// {"a":1}

Example: JSON string

v := map[string]int{"a": 1}
out := godump.DumpJSONStr(v)
_ = out
// {"a":1}

Options

WithDisableStringer

WithDisableStringer disables using the fmt.Stringer output. When enabled, the underlying type is rendered instead of String().

// Default: false
v := time.Duration(3)
d := godump.NewDumper(godump.WithDisableStringer(true))
d.Dump(v)
// 3 #time.Duration

WithExcludeFields

WithExcludeFields omits struct fields that match the provided names.

// Default: none
type User struct {
	ID       int
	Email    string
	Password string
}
d := godump.NewDumper(
	godump.WithExcludeFields("Password"),
)
d.Dump(User{ID: 1, Email: "user@example.com", Password: "secret"})
// #godump.User {
//   +ID    => 1 #int
//   +Email => "user@example.com" #string
// }

WithFieldMatchMode

WithFieldMatchMode sets how field names are matched for WithExcludeFields.

// Default: FieldMatchExact
type User struct {
	UserID int
}
d := godump.NewDumper(
	godump.WithExcludeFields("id"),
	godump.WithFieldMatchMode(godump.FieldMatchContains),
)
d.Dump(User{UserID: 10})
// #godump.User {
// }

WithMaxDepth

WithMaxDepth limits how deep the structure will be dumped. Param n must be 0 or greater or this will be ignored, and default MaxDepth will be 15.

// Default: 15
v := map[string]map[string]int{"a": {"b": 1}}
d := godump.NewDumper(godump.WithMaxDepth(1))
d.Dump(v)
// #map[string]map[string]int {
//   a => #map[string]int {
//     b => 1 #int
//   }
// }

WithMaxItems

WithMaxItems limits how many items from an array, slice, or map can be printed. Param n must be 0 or greater or this will be ignored, and default MaxItems will be 100.

// Default: 100
v := []int{1, 2, 3}
d := godump.NewDumper(godump.WithMaxItems(2))
d.Dump(v)
// #[]int [
//   0 => 1 #int
//   1 => 2 #int
//   ... (truncated)
// ]

WithMaxStringLen

WithMaxStringLen limits how long printed strings can be. Param n must be 0 or greater or this will be ignored, and default MaxStringLen will be 100000.

// Default: 100000
v := "hello world"
d := godump.NewDumper(godump.WithMaxStringLen(5))
d.Dump(v)
// "hello…" #string

WithOnlyFields

WithOnlyFields limits struct output to fields that match the provided names.

// Default: none
type User struct {
	ID       int
	Email    string
	Password string
}
d := godump.NewDumper(
	godump.WithOnlyFields("ID", "Email"),
)
d.Dump(User{ID: 1, Email: "user@example.com", Password: "secret"})
// #godump.User {
//   +ID    => 1 #int
//   +Email => "user@example.com" #string
// }

WithRedactFields

WithRedactFields replaces matching struct fields with a redacted placeholder.

// Default: none
type User struct {
	ID       int
	Password string
}
d := godump.NewDumper(
	godump.WithRedactFields("Password"),
)
d.Dump(User{ID: 1, Password: "secret"})
// #godump.User {
//   +ID       => 1 #int
//   +Password => <redacted> #string
// }

WithRedactMatchMode

WithRedactMatchMode sets how field names are matched for WithRedactFields.

// Default: FieldMatchExact
type User struct {
	APIKey string
}
d := godump.NewDumper(
	godump.WithRedactFields("key"),
	godump.WithRedactMatchMode(godump.FieldMatchContains),
)
d.Dump(User{APIKey: "abc"})
// #godump.User {
//   +APIKey => <redacted> #string
// }

WithRedactSensitive

WithRedactSensitive enables default redaction for common sensitive fields.

// Default: disabled
type User struct {
	Password string
	Token    string
}
d := godump.NewDumper(
	godump.WithRedactSensitive(),
)
d.Dump(User{Password: "secret", Token: "abc"})
// #godump.User {
//   +Password => <redacted> #string
//   +Token    => <redacted> #string
// }

WithSkipStackFrames

WithSkipStackFrames skips additional stack frames for header reporting. This is useful when godump is wrapped and the actual call site is deeper.

// Default: 0
v := map[string]int{"a": 1}
d := godump.NewDumper(godump.WithSkipStackFrames(2))
d.Dump(v)
// <#dump // ../../../../usr/local/go/src/runtime/asm_arm64.s:1223
// #map[string]int {
//   a => 1 #int
// }

WithWriter

WithWriter routes output to the provided writer.

// Default: stdout
var b strings.Builder
v := map[string]int{"a": 1}
d := godump.NewDumper(godump.WithWriter(&b))
d.Dump(v)
// #map[string]int {
//   a => 1 #int
// }

WithoutColor

WithoutColor disables colorized output for the dumper.

// Default: false
v := map[string]int{"a": 1}
d := godump.NewDumper(godump.WithoutColor())
d.Dump(v)
// (prints without color)
// #map[string]int {
//   a => 1 #int
// }

WithoutHeader

WithoutHeader disables printing the source location header.

// Default: false
d := godump.NewDumper(godump.WithoutHeader())
d.Dump("hello")
// "hello" #string