1# µDiff
2
3<p>
4<a href="https://github.com/aymanbagabas/go-udiff/releases"><img src="https://img.shields.io/github/release/aymanbagabas/go-udiff.svg" alt="Latest Release"></a>
5<a href="https://pkg.go.dev/github.com/aymanbagabas/go-udiff?tab=doc"><img src="https://godoc.org/github.com/golang/gddo?status.svg" alt="Go Docs"></a>
6<a href="https://github.com/aymanbagabas/go-udiff/actions"><img src="https://github.com/aymanbagabas/go-udiff/workflows/build/badge.svg" alt="Build Status"></a>
7<a href="https://goreportcard.com/report/github.com/aymanbagabas/go-udiff"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/aymanbagabas/go-udiff"></a>
8</p>
9
10Micro diff (µDiff) is a Go library that implements the
11[Myers'](http://www.xmailserver.org/diff2.pdf) diffing algorithm. It aims to
12provide a minimal API to compute and apply diffs with zero dependencies. It
13also supports generating diffs in the [Unified Format](https://www.gnu.org/software/diffutils/manual/html_node/Unified-Format.html).
14If you are looking for a way to parse unified diffs, check out
15[sourcegraph/go-diff](https://github.com/sourcegraph/go-diff).
16
17This is merely a copy of the [Golang tools internal diff package](https://github.com/golang/tools/tree/master/internal/diff)
18with a few modifications to export package symbols. All credit goes to the [Go authors](https://go.dev/AUTHORS).
19
20## Usage
21
22You can import the package using the following command:
23
24```bash
25go get github.com/aymanbagabas/go-udiff
26```
27
28## Examples
29
30Generate a unified diff for strings `a` and `b` with the default number of
31context lines (3). Use `udiff.ToUnified` to specify the number of context
32lines.
33
34```go
35package main
36
37import (
38 "fmt"
39
40 "github.com/aymanbagabas/go-udiff"
41)
42
43func main() {
44 a := "Hello, world!\n"
45 b := "Hello, Go!\nSay hi to µDiff"
46 unified := udiff.Unified("a.txt", "b.txt", a, b)
47 fmt.Println(unified)
48}
49```
50
51```
52--- a.txt
53+++ b.txt
54@@ -1 +1,2 @@
55-Hello, world!
56+Hello, Go!
57+Say hi to µDiff
58\ No newline at end of file
59```
60
61Apply changes to a string.
62
63```go
64package main
65
66import (
67 "fmt"
68
69 "github.com/aymanbagabas/go-udiff"
70)
71
72func main() {
73 a := "Hello, world!\n"
74 b := "Hello, Go!\nSay hi to µDiff"
75
76 edits := udiff.Strings(a, b)
77 final, err := udiff.Apply(a, edits)
78 if err != nil {
79 panic(err)
80 }
81
82 fmt.Println(final)
83}
84```
85
86```
87Hello, Go!
88Say hi to µDiff
89```
90
91To get a line-by-line diff and edits:
92
93```go
94package main
95
96import (
97 "fmt"
98
99 "github.com/aymanbagabas/go-udiff"
100)
101
102func main() {
103 a := "Hello, world!\n"
104 b := "Hello, Go!\nSay hi to µDiff"
105
106 edits := udiff.Strings(a, b)
107 d, err := udiff.ToUnifiedDiff("a.txt", "b.txt", a, edits, udiff.DefaultContextLines)
108 if err != nil {
109 panic(err)
110 }
111
112 for _, h := range d.Hunks {
113 fmt.Printf("hunk: -%d, +%d\n", h.FromLine, h.ToLine)
114 for _, l := range h.Lines {
115 fmt.Printf("%s %q\n", l.Kind, l.Content)
116 }
117 }
118}
119```
120
121```
122hunk: -1, +1
123delete "Hello, world!\n"
124insert "Hello, Go!\n"
125insert "Say hi to µDiff"
126```
127
128## Alternatives
129
130- [sergi/go-diff](https://github.com/sergi/go-diff) No longer reliable. See [#123](https://github.com/sergi/go-diff/issues/123) and [#141](https://github.com/sergi/go-diff/pull/141).
131- [hexops/gotextdiff](https://github.com/hexops/gotextdiff) Takes the same approach but looks like the project is abandoned.
132- [sourcegraph/go-diff](https://github.com/sourcegraph/go-diff) It doesn't compute diffs. Great package for parsing and printing unified diffs.
133
134## Contributing
135
136Please send any contributions [upstream](https://github.com/golang/tools). Pull
137requests made against [the upstream diff package](https://github.com/golang/tools/tree/master/internal/diff)
138are welcome.
139
140## License
141
142[BSD 3-Clause](./LICENSE-BSD) and [MIT](./LICENSE-MIT).