by r3labs

r3labs / diff

A library for diffing golang structures

194 Stars 29 Forks Last release: Not found Mozilla Public License 2.0 84 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Diff PkgGoDev Go Report Card Build Status

A library for diffing golang structures and values.

Utilizing field tags and reflection, it is able to compare two structures of the same type and create a changelog of all modified values. The produced changelog can easily be serialized to json.

NOTE: All active development now takes place on the v2 branch.


For version 2:

go get github.com/r3labs/diff/v2

Changelog Format

When diffing two structures using

, a changelog will be produced. Any detected changes will populate the changelog array with a Change type:
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

Given the example below, we are diffing two slices where the third element has been removed:

from := []int{1, 2, 3, 4}
to := []int{1, 2, 4}

changelog, _ := diff.Diff(from, to)

The resultant changelog should contain one change:

    Type: "delete",
    Path: ["2"],
    From: 3,
    To:   nil,

Supported Types

A diffable value can be/contain any of the following types:

| Type | Supported | |--------------|-----------| | struct | ✔ | | slice | ✔ | | string | ✔ | | int | ✔ | | bool | ✔ | | map | ✔ | | pointer | ✔ | | custom types | ✔ |

Please see the docs for more supported types, options and features.


In order for struct fields to be compared, they must be tagged with a given name. All tag values are prefixed with

. i.e.

| Tag | Usage | |--------------|------------------------------------| |

| Excludes a value from being diffed | |
| If you need to compare arrays by a matching identifier and not based on order, you can specify the
tag. If an identifiable element is found in both the from and to structures, they will be directly compared. i.e.
diff:"name, identifier"
| |
| Will omit this struct field from diffing. When using
these values will be added to the returned changelog. It's usecase is for when we have nothing to compare a struct to and want to show all of its relevant values. |


Basic Example

Diffing a basic set of values can be accomplished using the diff functions. Any items that specify a "diff" tag using a name will be compared.

import "github.com/r3labs/diff"

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)


In this example, the output generated in the changelog will indicate that the third element with a value of '3' was removed from items. When marshalling the changelog to json, the output will look like:

        "type": "delete",
        "path": ["items", "2"],
        "from": 3,
        "to": null

Options and Configuration

You can create a new instance of a differ that allows options to be set.

import "github.com/r3labs/diff"

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},

d, err := diff.NewDiffer(diff.SliceOrdering(true))
if err != nil {

changelog, err := d.Diff(a, b)


Supported options are:

ensures that the ordering of items in a slice is taken into account

Running Tests

make test


Please read through our contributing guidelines. Included are directions for opening issues, coding standards, and notes on development.

Moreover, if your pull request contains patches or features, you must include relevant unit tests.


For transparency into our release cycle and in striving to maintain backward compatibility, this project is maintained under the Semantic Versioning guidelines.

Copyright and License

Code and documentation copyright since 2015 r3labs.io authors.

Code released under the Mozilla Public License Version 2.0.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.