README.md
1
2[](https://pkg.go.dev/github.com/go-git/go-git/v5) [](https://github.com/go-git/go-git/actions) [](https://goreportcard.com/report/github.com/go-git/go-git)
3
4*go-git* is a highly extensible git implementation library written in **pure Go**.
5
6It can be used to manipulate git repositories at low level *(plumbing)* or high level *(porcelain)*, through an idiomatic Go API. It also supports several types of storage, such as in-memory filesystems, or custom implementations, thanks to the [`Storer`](https://pkg.go.dev/github.com/go-git/go-git/v5/plumbing/storer) interface.
7
8It's being actively developed since 2015 and is being used extensively by [Keybase](https://keybase.io/blog/encrypted-git-for-everyone), [Gitea](https://gitea.io/en-us/) or [Pulumi](https://github.com/search?q=org%3Apulumi+go-git&type=Code), and by many other libraries and tools.
9
10Project Status
11--------------
12
13After the legal issues with the [`src-d`](https://github.com/src-d) organization, the lack of update for four months and the requirement to make a hard fork, the project is **now back to normality**.
14
15The project is currently actively maintained by individual contributors, including several of the original authors, but also backed by a new company, [gitsight](https://github.com/gitsight), where `go-git` is a critical component used at scale.
16
17
18Comparison with git
19-------------------
20
21*go-git* aims to be fully compatible with [git](https://github.com/git/git), all the *porcelain* operations are implemented to work exactly as *git* does.
22
23*git* is a humongous project with years of development by thousands of contributors, making it challenging for *go-git* to implement all the features. You can find a comparison of *go-git* vs *git* in the [compatibility documentation](COMPATIBILITY.md).
24
25
26Installation
27------------
28
29The recommended way to install *go-git* is:
30
31```go
32import "github.com/go-git/go-git/v5" // with go modules enabled (GO111MODULE=on or outside GOPATH)
33import "github.com/go-git/go-git" // with go modules disabled
34```
35
36
37Examples
38--------
39
40> Please note that the `CheckIfError` and `Info` functions used in the examples are from the [examples package](https://github.com/go-git/go-git/blob/master/_examples/common.go#L19) just to be used in the examples.
41
42
43### Basic example
44
45A basic example that mimics the standard `git clone` command
46
47```go
48// Clone the given repository to the given directory
49Info("git clone https://github.com/go-git/go-git")
50
51_, err := git.PlainClone("/tmp/foo", false, &git.CloneOptions{
52 URL: "https://github.com/go-git/go-git",
53 Progress: os.Stdout,
54})
55
56CheckIfError(err)
57```
58
59Outputs:
60```
61Counting objects: 4924, done.
62Compressing objects: 100% (1333/1333), done.
63Total 4924 (delta 530), reused 6 (delta 6), pack-reused 3533
64```
65
66### In-memory example
67
68Cloning a repository into memory and printing the history of HEAD, just like `git log` does
69
70
71```go
72// Clones the given repository in memory, creating the remote, the local
73// branches and fetching the objects, exactly as:
74Info("git clone https://github.com/go-git/go-billy")
75
76r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{
77 URL: "https://github.com/go-git/go-billy",
78})
79
80CheckIfError(err)
81
82// Gets the HEAD history from HEAD, just like this command:
83Info("git log")
84
85// ... retrieves the branch pointed by HEAD
86ref, err := r.Head()
87CheckIfError(err)
88
89
90// ... retrieves the commit history
91cIter, err := r.Log(&git.LogOptions{From: ref.Hash()})
92CheckIfError(err)
93
94// ... just iterates over the commits, printing it
95err = cIter.ForEach(func(c *object.Commit) error {
96 fmt.Println(c)
97 return nil
98})
99CheckIfError(err)
100```
101
102Outputs:
103```
104commit ded8054fd0c3994453e9c8aacaf48d118d42991e
105Author: Santiago M. Mola <santi@mola.io>
106Date: Sat Nov 12 21:18:41 2016 +0100
107
108 index: ReadFrom/WriteTo returns IndexReadError/IndexWriteError. (#9)
109
110commit df707095626f384ce2dc1a83b30f9a21d69b9dfc
111Author: Santiago M. Mola <santi@mola.io>
112Date: Fri Nov 11 13:23:22 2016 +0100
113
114 readwriter: fix bug when writing index. (#10)
115
116 When using ReadWriter on an existing siva file, absolute offset for
117 index entries was not being calculated correctly.
118...
119```
120
121You can find this [example](_examples/log/main.go) and many others in the [examples](_examples) folder.
122
123Contribute
124----------
125
126[Contributions](https://github.com/go-git/go-git/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) are more than welcome, if you are interested please take a look to
127our [Contributing Guidelines](CONTRIBUTING.md).
128
129License
130-------
131Apache License Version 2.0, see [LICENSE](LICENSE)
132
){kind=link}
){kind=link}
){kind=link}