diff --git a/B-embedding-git-in-your-applications.asc b/B-embedding-git-in-your-applications.asc index 5a59a81c4..3a3b70c08 100644 --- a/B-embedding-git-in-your-applications.asc +++ b/B-embedding-git-in-your-applications.asc @@ -5,10 +5,13 @@ If your application is for developers, chances are good that it could benefit from integration with source control. Even non-developer applications, such as document editors, could potentially benefit from version-control features, and Git's model works very well for many different scenarios. -If you need to integrate Git with your application, you have essentially three choices: spawning a shell and using the Git command-line tool; Libgit2; and JGit. +If you need to integrate Git with your application, you have essentially two options: spawn a shell and call the `git` command-line program, or embed a Git library into your application. +Here we'll cover command-line integration and several of the most popular embeddable Git libraries. include::book/B-embedding-git/sections/command-line.asc[] include::book/B-embedding-git/sections/libgit2.asc[] include::book/B-embedding-git/sections/jgit.asc[] + +include::book/B-embedding-git/sections/go-git.asc[] diff --git a/book/B-embedding-git/sections/go-git.asc b/book/B-embedding-git/sections/go-git.asc new file mode 100644 index 000000000..bb6e6ccf7 --- /dev/null +++ b/book/B-embedding-git/sections/go-git.asc @@ -0,0 +1,85 @@ +=== go-git + +(((go-git)))((("Go"))) +In case you want to integrate Git into a service written in Golang, there also is a pure Go library implementation. +This implementation does not have any native dependencies and thus is not prone to manual memory managemen errors. +It is also transparent for the standard Golang performance analysis tooling like CPU, Memory profilers, race detector, etc. + +go-git is focused on extensibility, compatibility and supports most of the plumbing APIs, which is documented at https://github.com/src-d/go-git/blob/master/COMPATIBILITY.md[]. + +Here is a basic example of using Go APIs: + +[source, go] +----- +import "gopkg.in/src-d/go-git.v4" + +r, err := git.PlainClone("/tmp/foo", false, &git.CloneOptions{ + URL: "https://github.com/src-d/go-git", + Progress: os.Stdout, +}) +----- + +As soon as you have a `Repository` instance, you can access information and perform mutations on it: + + +[source, go] +----- +// retrieves the branch pointed by HEAD +ref, err := r.Head() + +// get the commit object, pointed by ref +commit, err := r.CommitObject(ref.Hash()) + +// retrieves the commit history +history, err := commit.History() + +// iterates over the commits and print each +for _, c := range history { + fmt.Println(c) +} +----- + + +==== Advanced Functionality + +go-git has few notable advanced features, one of which is a pluggable storage system, which is similar to Libgit2 backends. +The default implementation is in-memory storage, which is very fast. + +[source, go] +----- +r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{ + URL: "https://github.com/src-d/go-git", +}) +----- + +Pluggable storage provides many interesting options. For instance, https://github.com/src-d/go-git/tree/master/_examples/storage[] allows you to store references, objects, and configuration in an Aerospike database. + +Another feature is a flexible filesystem abstraction. +Using https://godoc.org/github.com/src-d/go-billy#Filesystem[] it is easy to store all the files in different way i.e by packing all of them to a single archive on disk or by keeping them all in-memory. + +Another advanced use-case includes a fine-tunable HTTP client, such as the one found at https://github.com/src-d/go-git/blob/master/_examples/custom_http/main.go[]. + +[source, go] +----- +customClient := &http.Client{ + Transport: &http.Transport{ // accept any certificate (might be useful for testing) + TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, + }, + Timeout: 15 * time.Second, // 15 second timeout + CheckRedirect: func(req *http.Request, via []*http.Request) error { + return http.ErrUseLastResponse // don't follow redirect + }, +} + +// Override http(s) default protocol to use our custom client +client.InstallProtocol("https", githttp.NewClient(customClient)) + +// Clone repository using the new client if the protocol is https:// +r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{URL: url}) +----- + + +==== Further Reading + +A full treatment of go-git's capabilities is outside the scope of this book. +If you want more information on go-git, there's API documentation at https://godoc.org/gopkg.in/src-d/go-git.v4[], and a set of usage examples at https://github.com/src-d/go-git/tree/master/_examples[].