GoForjUnreleased
Support this libraryStar on GitHub

godump logo – Go pretty printer and Laravel-style dump/dd debugging tool

Go ReferenceLicense: MITGo TestGo versionLatest tagTestsMentioned in Awesome Go

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)
Terminal output example kitchen sink

HTML Output Example
HTML output example

godump.Diff(a,b) Output Example
Diff output example

Feature Comparison: godump vs go-spew vs pp {#feature-comparison:-godump-vs-go-spew-vs-pp} ​

Featuregodumpgo-spewpp
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 ​

bash
go get github.com/goforj/godump

Basic Usage ​

View Full Runnable Example →

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

Extended Usage (Snippets) ​

go
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 →

go
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 →

go
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 ​

go
<#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 ​

go
#main.User
  • Fully qualified struct name with its package path.

Visibility Markers ​

go
  +Name => "Alice"
  -secret  => "..."
  • + → Exported (public) field
  • - → Unexported (private) field (accessed reflectively)

Cyclic References ​

If a pointer has already been printed:

go
↩︎ &1
  • Prevents infinite loops in circular structures
  • References point back to earlier object instances

Slices and Maps ​

go
  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 ​

go
"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 ​

GroupFunctions
BuilderNewDumper
DiffDiff · DiffHTML · DiffStr
DumpDd · Dump · DumpStr · Fdump
HTMLDumpHTML
JSONDumpJSON · DumpJSONStr
OptionsWithDisableStringer · WithExcludeFields · WithFieldMatchMode · WithMaxDepth · WithMaxItems · WithMaxStringLen · WithOnlyFields · WithRedactFields · WithRedactMatchMode · WithRedactSensitive · WithRedactTags · WithSkipStackFrames · WithWriter · WithoutColor · WithoutHeader · WithoutTypes

Builder ​

NewDumper ​

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

go
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

go
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

go
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

go
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

go
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

go
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

go
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

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

Example: dump and exit with a custom dumper

go
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

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

Example: print with a custom dumper

go
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

go
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

go
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.

go
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

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

Example: dump HTML with a custom dumper

go
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

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

Example: print JSON

go
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

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

Example: JSON string

go
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().

go
// 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.

go
// 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.

go
// 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.

go
// 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.

go
// 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.

go
// 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.

go
// 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.

go
// 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.

go
// 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.

go
// 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
// }

WithRedactTags ​

WithRedactTags redacts struct fields whose selected tag values equal "-". With no keys, or with "*", it checks all tag keys. Calls accumulate selected keys. Matching is case-sensitive and does not treat "-,omitempty" as "-". It applies as text, HTML, and diff output traverse nested and embedded structs. JSON helpers retain encoding/json behavior. Structs rendered through fmt.Stringer are not traversed; use WithDisableStringer(true) to inspect their fields instead.

go
type User struct {
	Name string
	Credential string `json:"-"`
}
d := godump.NewDumper(godump.WithRedactTags("json"), godump.WithoutHeader())
d.Dump(User{Name: "Alice", Credential: "secret"})
// #godump.User {
//   +Name       => "Alice" #string
//   +Credential => <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.

go
// 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.

go
// 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.

go
// 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.

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

WithoutTypes ​

WithoutTypes omits type annotations while preserving value colors and structure. It applies to text, HTML, and diff output. JSON output is unchanged.

go
type User struct {
	Name string
}
d := godump.NewDumper(godump.WithoutTypes(), godump.WithoutHeader())
d.Dump(User{Name: "Alice"})
// {
//   +Name => "Alice"
// }

Development ​

Use make test for the root module, make vet for static checks, and make modernize-check to check for supported modernization opportunities. The examples directory is a separate Go module and can be tested from that directory when changed.