diff

README

diff - unified text diffing in Go

This is a copy of the Go text diffing packages that the official Go language server gopls uses internally to generate unified diffs.

If you've previously tried to generate unified text diffs in Go (like the ones you see in Git and on GitHub), you may have found github.com/sergi/go-diff which is a Go port of Neil Fraser's google-diff-match-patch code - however it does not support unified diffs.

This is arguably one of the best (and most maintained) unified text diffing packages in Go as of at least 2020.

(All credit goes to the Go authors, I am merely re-publishing their work so others can use it.)

Example usage

Import the packages:

import (
    "github.com/pgavlin/diff"
    "github.com/pgavlin/diff/myers"
)

Assuming you want to diff a.txt and b.txt, whose contents are stored in aString and bString then:

edits := myers.ComputeEdits(span.URIFromPath("a.txt"), aString, bString)
diff := fmt.Sprint(diff.ToUnified("a.txt", "b.txt", aString, edits))

diff will be a string like:

--- a.txt
+++ b.txt
@@ -1,13 +1,28 @@
-foo
+bar

API compatability

We will publish a new major version anytime the API changes in a backwards-incompatible way. Because the upstream is not being developed with this being a public package in mind, API breakages may occur more often than in other Go packages (but you can always continue using the old version thanks to Go modules.)

Alternatives

• github.com/andreyvit/diff: Quick'n'easy string diffing functions for Golang based on github.com/sergi/go-diff.
• github.com/kylelemons/godebug/diff: implements a linewise diff algorithm (inactive).

Contributing

We will only accept changes made upstream, please send any contributions to the upstream instead! Compared to the upstream, only import paths will be modified (to be non-internal so they are importable.) The only thing we add here is this README.

License

See https://github.com/golang/tools/blob/master/LICENSE

Documentation

Overview

Package diff computes differences between text files or strings.

Index

• func Apply[S1, S2 text.String](src S1, edits []Edit[S2]) (S1, error)
• func ApplyTo[S text.String](dst io.Writer, src io.Reader, srcLen int, edits []Edit[S]) (int64, error)
• func SortEdits[S text.String](edits []Edit[S])
• func ToUnified[S text.String](oldLabel, newLabel string, content S, edits []Edit[S]) (string, error)
• func Unified[S text.String](oldLabel, newLabel string, old, new S) string
• type Edit
  • func Binary[S1, S2 text.String](before S1, after S2) []Edit[S2]
  • func Lines[S1, S2 text.String](before S1, after S2) []Edit[S2]
  • func Text[S1, S2 text.String](before S1, after S2) []Edit[S2]
  • func Validate[S text.String](srcLen int, edits []Edit[S]) ([]Edit[S], int, error)
  • func (e Edit[S]) String() string
• type OpKind
  • func (k OpKind) String() string

Functions

func Apply

func Apply[S1, S2 text.String](src S1, edits []Edit[S2]) (S1, error)

Apply applies a sequence of edits to the src buffer and returns the result. Edits are applied in order of start offset; edits with the same start offset are applied in they order they were provided.

Apply returns an error if any edit is out of bounds, or if any pair of edits is overlapping.

func ApplyTo

func ApplyTo[S text.String](dst io.Writer, src io.Reader, srcLen int, edits []Edit[S]) (int64, error)

ApplyTo applies a sequence of edits to the src Reader and writes the result to the dst Writer. Edits are applied in order of start offset; edits with the same start offset are applied in they order they were provided.

ApplyTo returns an error if any edit is out of bounds, or if any pair of edits is overlapping.

func SortEdits

func SortEdits[S text.String](edits []Edit[S])

SortEdits orders a slice of Edits by (start, end) offset. This ordering puts insertions (end = start) before deletions (end > start) at the same point, but uses a stable sort to preserve the order of multiple insertions at the same point. (Apply detects multiple deletions at the same point as an error.)

func ToUnified

func ToUnified[S text.String](oldLabel, newLabel string, content S, edits []Edit[S]) (string, error)

ToUnified applies the edits to content and returns a unified diff. The old and new labels are the names of the content and result files. It returns an error if the edits are inconsistent; see ApplyEdits.

func Unified

func Unified[S text.String](oldLabel, newLabel string, old, new S) string

Unified returns a unified diff of the old and new texts. The old and new labels are the names of the old and new files. If the texts are equal, it returns the empty string.

Types

type Edit

type Edit[S text.String] struct {
	Start, End int // byte offsets of the region to replace
	New        S
}

Edit represents a change to a section of a document. The text within the specified span should be replaced by the supplied new text.

func Binary

func Binary[S1, S2 text.String](before S1, after S2) []Edit[S2]

Binary computes the differences between two texts. The texts are treated as binary data. The resulting edits do not respect rune boundaries.

func Lines

func Lines[S1, S2 text.String](before S1, after S2) []Edit[S2]

Lines computes the line differences between two texts.

func Text

func Text[S1, S2 text.String](before S1, after S2) []Edit[S2]

Text computes the differences between two texts. The resulting edits respect rune boundaries.

func Validate

func Validate[S text.String](srcLen int, edits []Edit[S]) ([]Edit[S], int, error)

Validate checks that edits are consistent with src, and returns the size of the patched output. It may return a different slice.

func (Edit[S]) String

func (e Edit[S]) String() string

type OpKind

type OpKind int

OpKind is used to denote the type of operation a line represents. TODO(adonovan): hide this once the myers package no longer references it.

const (
	// Delete is the operation kind for a line that is present in the input
	// but not in the output.
	Delete OpKind = iota
	// Insert is the operation kind for a line that is new in the output.
	Insert
	// Equal is the operation kind for a line that is the same in the input and
	// output, often used to provide context around edited lines.
	Equal
)

func (OpKind) String

func (k OpKind) String() string

String returns a human readable representation of an OpKind. It is not intended for machine processing.