gotextdiff

README

gotextdiff - 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/hexops/gotextdiff"
    "github.com/hexops/gotextdiff/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(gotextdiff.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 gotextdiff supports a pluggable diff algorithm.

Index

• func ApplyEdits(before string, edits []TextEdit) string
• func SortTextEdits(d []TextEdit)
• type ComputeEdits
• type Hunk
• type Line
• type OpKind
  • func (k OpKind) String() string
• type TextEdit
  • func LineEdits(before string, edits []TextEdit) []TextEdit
• type Unified
  • func ToUnified(from, to string, content string, edits []TextEdit) Unified
  • func (u Unified) Format(f fmt.State, r rune)

Functions

func ApplyEdits

func ApplyEdits(before string, edits []TextEdit) string

ApplyEdits applies the set of edits to the before and returns the resulting content. It may panic or produce garbage if the edits are not valid for the provided before content.

func SortTextEdits

func SortTextEdits(d []TextEdit)

SortTextEdits attempts to order all edits by their starting points. The sort is stable so that edits with the same starting point will not be reordered.

Types

type ComputeEdits

type ComputeEdits func(uri span.URI, before, after string) []TextEdit

ComputeEdits is the type for a function that produces a set of edits that convert from the before content to the after content.

type Hunk

type Hunk struct {
	// The line in the original source where the hunk starts.
	FromLine int
	// The line in the original source where the hunk finishes.
	ToLine int
	// The set of line based edits to apply.
	Lines []Line
}

Hunk represents a contiguous set of line edits to apply.

type Line

type Line struct {
	// Kind is the type of line this represents, deletion, insertion or copy.
	Kind OpKind
	// Content is the content of this line.
	// For deletion it is the line being removed, for all others it is the line
	// to put in the output.
	Content string
}

Line represents a single line operation to apply as part of a Hunk.

type OpKind

type OpKind int

OpKind is used to denote the type of operation a line represents.

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.

type TextEdit

type TextEdit struct {
	Span    span.Span
	NewText string
}

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

func LineEdits

func LineEdits(before string, edits []TextEdit) []TextEdit

LineEdits takes a set of edits and expands and merges them as necessary to ensure that there are only full line edits left when it is done.

type Unified

type Unified struct {
	// From is the name of the original file.
	From string
	// To is the name of the modified file.
	To string
	// Hunks is the set of edit hunks needed to transform the file content.
	Hunks []*Hunk
}

Unified represents a set of edits as a unified diff.

func ToUnified

func ToUnified(from, to string, content string, edits []TextEdit) Unified

ToUnified takes a file contents and a sequence of edits, and calculates a unified diff that represents those edits.

func (Unified) Format

func (u Unified) Format(f fmt.State, r rune)

Format converts a unified diff to the standard textual form for that diff. The output of this function can be passed to tools like patch.