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
```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`](./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
| Group | Functions |
|------:|-----------|
| **Builder** | [NewDumper](#newdumper) |
| **Diff** | [Diff](#diff) · [DiffHTML](#diffhtml) · [DiffStr](#diffstr) |
| **Dump** | [Dd](#dd) · [Dump](#dump) · [DumpStr](#dumpstr) · [Fdump](#fdump) |
| **HTML** | [DumpHTML](#dumphtml) |
| **JSON** | [DumpJSON](#dumpjson) · [DumpJSONStr](#dumpjsonstr) |
| **Options** | [WithDisableStringer](#withdisablestringer) · [WithExcludeFields](#withexcludefields) · [WithFieldMatchMode](#withfieldmatchmode) · [WithMaxDepth](#withmaxdepth) · [WithMaxItems](#withmaxitems) · [WithMaxStringLen](#withmaxstringlen) · [WithOnlyFields](#withonlyfields) · [WithRedactFields](#withredactfields) · [WithRedactMatchMode](#withredactmatchmode) · [WithRedactSensitive](#withredactsensitive) · [WithSkipStackFrames](#withskipstackframes) · [WithWriter](#withwriter) · [WithoutColor](#withoutcolor) · [WithoutHeader](#withoutheader) |
## 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