Merge pull request #998 from bzz/embedding/add-go-git

Add go-git to Appendinx B: embedding

Author: ben

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[]

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[].