From f2cc7f3f53b57cd803863a14ab87c9674f98a8ea Mon Sep 17 00:00:00 2001 From: Alexander Bezzubov Date: Mon, 30 Oct 2017 22:27:59 +0100 Subject: [PATCH 1/5] Add go-git to Appendinx B: embedding Signed-off-by: Alexander Bezzubov --- B-embedding-git-in-your-applications.asc | 8 ++- book/B-embedding-git/sections/go-git.asc | 84 ++++++++++++++++++++++++ 2 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 book/B-embedding-git/sections/go-git.asc diff --git a/B-embedding-git-in-your-applications.asc b/B-embedding-git-in-your-applications.asc index 5a59a81c4..f1f776f59 100644 --- a/B-embedding-git-in-your-applications.asc +++ b/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[] 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..f62a23970 --- /dev/null +++ b/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[]. From f349f99d08bfe4a3dc7cb72b6833d2cefe7f4883 Mon Sep 17 00:00:00 2001 From: Alexander Bezzubov Date: Wed, 7 Mar 2018 14:40:33 +0100 Subject: [PATCH 2/5] Rewording introduction to embedding options Signed-off-by: Alexander Bezzubov --- B-embedding-git-in-your-applications.asc | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/B-embedding-git-in-your-applications.asc b/B-embedding-git-in-your-applications.asc index f1f776f59..3a3b70c08 100644 --- a/B-embedding-git-in-your-applications.asc +++ b/B-embedding-git-in-your-applications.asc @@ -5,11 +5,8 @@ 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 next options: - - spawning a shell and using the Git command-line tool; - - Libgit2; - - JGit; - - go-git. +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[] From 3a33938b30cb893be03132d84e02f1b0f6f5a02b Mon Sep 17 00:00:00 2001 From: Alexander Bezzubov Date: Wed, 7 Mar 2018 14:45:32 +0100 Subject: [PATCH 3/5] Fix typos :man_facepalming: Signed-off-by: Alexander Bezzubov --- book/B-embedding-git/sections/go-git.asc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/B-embedding-git/sections/go-git.asc b/book/B-embedding-git/sections/go-git.asc index f62a23970..25c257353 100644 --- a/book/B-embedding-git/sections/go-git.asc +++ b/book/B-embedding-git/sections/go-git.asc @@ -1,9 +1,9 @@ === 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. +In case you want to integrate Git into a service written in Golang, there also is a pure Go library implementation. 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[] +go-git is focused on extensibility, compatibility and supports most of the plumbing APIs, which is documented https://github.com/src-d/go-git/blob/master/COMPATIBILITY.md[] Here is a basic example of using Go APIs @@ -40,7 +40,7 @@ for _, c := range history { ==== 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. +go-git has few notable advanced features, one of which is a pluggable storage system, similar to Libgit2 backends, with a default implementation of in-memory storage. [source, go] ----- @@ -49,9 +49,9 @@ r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{ }) ----- -That way all operations over the repository become bazingly fast as they never hit the disk. +That way all operations over the repository become blazingly 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. +Other storage implementations 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. From c79efb596ff029311aac9c56c8103b628d652f93 Mon Sep 17 00:00:00 2001 From: Alexander Bezzubov Date: Wed, 7 Mar 2018 14:48:04 +0100 Subject: [PATCH 4/5] Re-formating to single-sentence-per-source-line Signed-off-by: Alexander Bezzubov --- book/B-embedding-git/sections/go-git.asc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/B-embedding-git/sections/go-git.asc b/book/B-embedding-git/sections/go-git.asc index 25c257353..6418d200d 100644 --- a/book/B-embedding-git/sections/go-git.asc +++ b/book/B-embedding-git/sections/go-git.asc @@ -1,7 +1,8 @@ === 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. 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. +In case you want to integrate Git into a service written in Golang, there also is a pure Go library implementation. +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, which is documented https://github.com/src-d/go-git/blob/master/COMPATIBILITY.md[] From d9a13967e2db91d612b341e54596e6f46b2b7292 Mon Sep 17 00:00:00 2001 From: Alexander Bezzubov Date: Wed, 7 Mar 2018 15:24:13 +0100 Subject: [PATCH 5/5] Apply reviewer's feedback Signed-off-by: Alexander Bezzubov --- book/B-embedding-git/sections/go-git.asc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/book/B-embedding-git/sections/go-git.asc b/book/B-embedding-git/sections/go-git.asc index 6418d200d..bb6e6ccf7 100644 --- a/book/B-embedding-git/sections/go-git.asc +++ b/book/B-embedding-git/sections/go-git.asc @@ -2,11 +2,12 @@ (((go-git)))((("Go"))) In case you want to integrate Git into a service written in Golang, there also is a pure Go library implementation. -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. +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 https://github.com/src-d/go-git/blob/master/COMPATIBILITY.md[] +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 +Here is a basic example of using Go APIs: [source, go] ----- @@ -18,7 +19,7 @@ r, err := git.PlainClone("/tmp/foo", false, &git.CloneOptions{ }) ----- -As soon as you have a `Repository` instance, +As soon as you have a `Repository` instance, you can access information and perform mutations on it: [source, go] @@ -41,7 +42,8 @@ for _, c := range history { ==== Advanced Functionality -go-git has few notable advanced features, one of which is a pluggable storage system, similar to Libgit2 backends, with a default implementation of in-memory storage. +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] ----- @@ -50,14 +52,12 @@ r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{ }) ----- -That way all operations over the repository become blazingly fast as they never hit the disk. - -Other storage implementations 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. +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 https://github.com/src-d/go-git/blob/master/_examples/custom_http/main.go[] +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] -----