GitHub - goforj/godump: A minimal, developer-friendly pretty-printer and debug dumper for Go structs, inspired by Laravel’s dump() and Symfony’s VarDumper.

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`

Feature	godump	go-spew	pp
Zero dependencies	✓	-	-
Colorized terminal output	✓	✓	✓
HTML output	✓	-	-
JSON output helpers (`DumpJSON`, `DumpJSONStr`)	✓	-	-
Diff output helpers (`Diff`, `DiffStr`)	✓	-	-
Diff HTML output (`DiffHTML`)	✓	-	-
Dump to `io.Writer`	✓	✓	✓
Shows file + line number of dump call	✓	-	-
Cyclic reference detection	✓	~	-
Handles unexported struct fields	✓	✓	✓
Visibility markers (`+` / `-`)	✓	-	-
Max depth control	✓	-	-
Max items (slice/map truncation)	✓	-	-
Max string length truncation	✓	-	-
Dump & Die (`dd()` equivalent)	✓	-	-
Control character escaping	✓	~	~
Supports structs, maps, slices, pointers, interfaces	✓	✓	✓
Pretty type name rendering (`#package.Type`)	✓	-	-
Builder-style configuration API	✓	-	-
Test-friendly string output (`DumpStr`, `DiffStr`, `DumpJSONStr`)	✓	✓	✓
HTML / Web UI debugging support	✓	-	-

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.

📘 How to Read the Output

godump output is designed for clarity and traceability. Here's how to interpret its structure:

Location Header

<#dump // main.go:26

The first line shows the file and line number where godump.Dump() was invoked.
Helpful for finding where the dump happened during debugging.

Type Names

#main.User

Fully qualified struct name with its package path.

Visibility Markers

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

+ → Exported (public) field
- → Unexported (private) field (accessed reflectively)

Cyclic References

If a pointer has already been printed:

↩︎ &1

Prevents infinite loops in circular structures
References point back to earlier object instances

Slices and Maps

  0 => "value"
  a => 1

Array/slice indices and map keys are shown with => formatting and indentation
Slices and maps are truncated if maxItems is exceeded

Escaped Characters

"Line1\nLine2\tDone"

Control characters like \n, \t, \r, etc. are safely escaped
Strings are truncated after maxStringLen runes

Supported Types

✅ Structs (exported & unexported)
✅ Pointers, interfaces
✅ Maps, slices, arrays
✅ Channels, functions
✅ time.Time (nicely formatted)

API Index

Group	Functions
Builder	NewDumper
Diff	Diff DiffHTML DiffStr
Dump	Dd Dump DumpStr Fdump
HTML	DumpHTML
JSON	DumpJSON DumpJSONStr
Options	WithDisableStringer WithExcludeFields WithFieldMatchMode WithMaxDepth WithMaxItems WithMaxStringLen WithOnlyFields WithRedactFields WithRedactMatchMode WithRedactSensitive WithSkipStackFrames WithWriter WithoutColor WithoutHeader

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 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: "[email protected]", Password: "secret"})
// #godump.User {
//   +ID    => 1 #int
//   +Email => "[email protected]" #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: "[email protected]", Password: "secret"})
// #godump.User {
//   +ID    => 1 #int
//   +Email => "[email protected]" #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

Name		Name	Last commit message	Last commit date
Latest commit History 84 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
.gitignore		.gitignore
.golangci.yml		.golangci.yml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
diff.go		diff.go
diff_test.go		diff_test.go
example_compile_test.go		example_compile_test.go
go.mod		go.mod
go.sum		go.sum
godump.go		godump.go
godump_test.go		godump_test.go

License

goforj/godump

Folders and files

Latest commit

History

Repository files navigation

Feature Comparison: godump vs go-spew vs pp

Installation

Basic Usage

Extended Usage (Snippets)

Diff Usage

Builder Options Usage

Contributing

Runnable Examples Directory

Location Header

Type Names

Visibility Markers

Cyclic References

Slices and Maps

Escaped Characters

Supported Types

API Index

Builder

NewDumper

Diff

Diff

DiffHTML

DiffStr

Dump

Dd

Dump

DumpStr

Fdump

HTML

DumpHTML

JSON

DumpJSON

DumpJSONStr

Options

WithDisableStringer

WithExcludeFields

WithFieldMatchMode

WithMaxDepth

WithMaxItems

WithMaxStringLen

WithOnlyFields

WithRedactFields

WithRedactMatchMode

WithRedactSensitive

WithSkipStackFrames

WithWriter

WithoutColor

WithoutHeader

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors 13

Languages

Feature Comparison: `godump` vs `go-spew` vs `pp`

Packages