r3labs/diff

When you call diff.Diff(from, to), the library returns a changelog containing Change objects. Each object describes a specific modification:

• Type: The nature of the change (create, update, or delete).
• Path: A slice of strings representing the traversal path (field names or array indices) to the changed value.
• From: The original value in the from structure.
• To: The new value detected in the to structure.

type Change struct {
	Type string      // The type of change detected; can be one of create, update or delete
	Path []string    // The path of the detected change; will contain any field name or array index that was part of the traversal
	From interface{} // The original value that was present in the "from" structure
	To   interface{} // The new value that was detected as a change in the "to" structure
}

To use the latest version of the library, install it using go get:

go get github.com/r3labs/diff/v3

The ComparativeList type is used to store indexed comparisons between two sets of values. It maintains a mapping of keys to Comparative objects, where each Comparative object holds a pointer to a reflect.Value for both side A and side B. This is useful when you need to track differences across keyed collections.

To use it, initialize a list with NewComparativeList() and populate it using the addA and addB methods. Note that addA and addB are internal methods used to build the comparison state for a specific key k.

// Initialize a new list
cl := diff.NewComparativeList()

// Note: addA and addB are used internally to associate 
// reflect.Values with specific keys.
// cl.addA(key, &valA)
// cl.addB(key, &valB)

A DiffError is a specialized error type used throughout the library. It provides a structured way to report errors with context:

• Message: The primary error description.
• Count: An integer representing the number of causes appended to the error chain.
• Next: The underlying error being wrapped.

When calling .Error(), the output follows the format: <message> (cause count <count>) <cause_error_string>.

A Change object represents a single mutation. It contains the following fields:

• Type: A string indicating the nature of the change (CREATE, UPDATE, or DELETE).
• Path: A []string representing the breadcrumb path to the changed element.
• From: The value before the change.
• To: The value after the change.
• parent: The parent object of the change (internal/optional).

For struct fields to be included in a diff, they must be tagged with diff:"name". All tag values are prefixed with diff.

Supported tag options:

• -: Excludes the value from being diffed.
• identifier: Used for comparing arrays by a matching identifier instead of order. Example: diff:"name, identifier".
• immutable: Omits the field from diffing, but includes it in the changelog when using diff.StructValues() (useful for showing full state when comparing against nil).
• nocreate: Tells the patch function to skip elements that would otherwise require allocation.
• omitunequal: Instructs the patcher to selectively ignore values that are not a 100% match to the 'from' value in the changelog.

Use diff.Diff(a, b) to compare two structures. Only fields with a diff tag will be compared.

import "github.com/r3labs/diff/v3"

type Order struct {
    ID    string `diff:"id"`
    Items []int  `diff:"items"`
}

func main() {
    a := Order{
        ID: "1234",
        Items: []int{1, 2, 3, 4},
    }

    b := Order{
        ID: "1234",
        Items: []int{1, 2, 4},
    }

    changelog, err := diff.Diff(a, b)
    // changelog will indicate the third element (index 2) was deleted
}

The library provides mechanisms to apply a changelog to a target instance.

• diff.Patch(changelog, target): A "best effort" operation that applies changes from the changelog to the target pointer. It returns a patchlog which can be used to check for errors encountered during the process.
• diff.Merge(from, to, target): A convenience function that performs both the diff (between from and to) and the patch (applying the result to target) in one step.

Note: Patch does not fail immediately; use patchlog.ErrorCount() to inspect how many issues occurred.

// Patching an existing instance
changelog, _ := diff.Diff(a, b)
patchlog := diff.Patch(changelog, &c)
fmt.Printf("Encountered %d errors while patching", patchlog.ErrorCount())

// Merging in one step
// a: from, b: to, c: target
patchlog, err := diff.Merge(a, b, &c)

Call NewComparativeList() to create a new instance of ComparativeList. This initializes the underlying map and the keys slice required to track indexed comparisons.

cl := diff.NewComparativeList()

To handle specific types or logic differently (e.g., custom equality for a specific struct), implement the ValueDiffer interface. This allows you to intercept the diffing process before the built-in functions are called.

Methods to implement:

• Match(a, b reflect.Value) bool: Returns true if this differ should handle the given values.
• Diff(dt DiffType, df DiffFunc, cl *Changelog, path []string, a, b reflect.Value, parent interface{}) error: The logic for performing the diff and adding to the changelog.
• InsertParentDiffer(dfunc func(path []string, a, b reflect.Value, p interface{}) error): Used to provide a function for inserting parent context.