Add go-git to Appendinx B: embedding

Signed-off-by: Alexander Bezzubov <[email protected]>

Author: bzz

B-embedding-git-in-your-applications.asc

@@ -5,10 +5,16 @@
 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 next options: 
+ - spawning a shell and using the Git command-line tool; 
+ - Libgit2; 
+ - JGit;
+ - go-git.
 
 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,84 @@
+=== 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 implmentation. In contrast to using a Libgit2 bindings, this implementation does not have any native dependencies, not prone to memory management errors and is transparent for 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, wich is documented 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, 
+
+
+[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 wich is a pluggable storage system, similar to Libgit2 backends, with a default implementation of in-memory storage.
+
+[source, go]
+-----
+r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{
+    URL: "https://github.com/src-d/go-git",
+})
+-----
+
+That way all operations over the repository become bazingly fast as they never hit the disk.
+
+Other storage implementaions include ability to store references, objects and configuration in a database i.e https://github.com/src-d/go-git/tree/master/_examples/storage[] an Aerospike.
+
+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 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[].