Libgit2 tweaks

Author: ben

book/B-embedding-git/sections/libgit2.asc

@@ -107,6 +107,7 @@ commit = repo.lookup(commit_id) # <8>
 <8> The return value is the SHA-1 hash of a new commit object, which you can then use to get a `Commit` object.
 
 The Ruby code is nice and clean, but since Libgit2 is doing the heavy lifting, this code will run pretty fast, too.
+If you're not a rubyist, we touch on some other bindings in <<_libgit2_bindings>>.
 
 
 ==== Advanced Functionality
@@ -117,7 +118,7 @@ Libgit2 allows custom backends for configuration, ref storage, and the object da
 
 Let's take a look at how this works.
 The code below is borrowed from the set of backend examples provided by the Libgit2 team (which can be found at https://github.com/libgit2/libgit2-backends[]).
-Here's how a custom backend for the object database is set up.
+Here's how a custom backend for the object database is set up:
 
 [source,c]
 ----
@@ -133,15 +134,15 @@ error = git_odb_backend_mine(&my_backend, /*…*/); // <3>
 error = git_odb_add_backendodb, my_backend, 1); // <4>
 ----
 
-_Note that error handling has been left out for this example. You should know better._
+_(Note that errors are captured, but not handled. We hope your code is better than ours.)_
 
 <1> Initialize an empty object database (ODB) ``frontend,'' which will act as a handle to the real ODB.
 <2> Construct a `git_repository` around the empty ODB.
 <3> Initialize a custom ODB backend.
 <4> Set the repository to use the custom backend for its ODB.
 
 But what is this `git_odb_backend_mine` thing?
-Well, that's your own backend, and you can do whatever you want in there, so long as you fill in the `git_odb_backend` structure properly.
+Well, that's your own ODB implementation, and you can do whatever you want in there, so long as you fill in the `git_odb_backend` structure properly.
 Here's what it _could_ look like:
 
 [source,c]
@@ -172,38 +173,41 @@ int git_odb_backend_mine(git_odb_backend **backend_out, /*…*/)
 }
 ----
 
-The `my_backend_struct` structure contains a `git_odb_backend` member first, which ensures that the memory layout is what the Libgit2 code expects it to be.
+The subtlest constraint here is that `my_backend_struct`'s first member must be a `git_odb_backend` structure; this ensures that the memory layout is what the Libgit2 code expects it to be.
 The rest of it is arbitrary; this structure can be as large or small as you need it to be.
+
 The initialization function allocates some memory for the structure, sets up the custom context, and then fills in the members of the `parent` structure that it supports.
 Take a look at the `include/git2/sys/odb_backend.h` file in the Libgit2 source for a complete set of call signatures; your particular use case will help determine which of these you'll want to support.
 
+[[_libgit2_bindings]]
 ==== Other Bindings
 
 Libgit2 has bindings for many languages.
-Here we show how to get the commit message from HEAD with a few of the more mature bindings pakages; there are many others, including C++, Go, Node.js, Erlang, and the JVM.
+Here we show a small example using a few of the more complete bindings pakages as of this writing; libraries exist for many other languages, including C++, Go, Node.js, Erlang, and the JVM, all in various stages of maturity.
 The official collection of bindings can be found by browsing the repositories at https://github.com/libgit2[].
+The code we'll write will return the commit message from the commit eventually pointed to by HEAD (sort of like `git log -1`).
 
 
 ===== LibGit2Sharp
 
 (((.NET)))(((C#)))(((Mono)))
 If you're writing a .NET or Mono application, LibGit2Sharp (https://github.com/libgit2/libgit2sharp[]) is what you're looking for.
 The bindings are written in C#, and great care has been taken to wrap the raw Libgit2 calls with native-feeling CLR APIs.
-Here's what it looks like to read HEAD's commit message:
+Here's what our example program looks like:
 
 [source,csharp]
 -----
 new Repository(@"C:\path\to\repo").Head.Tip.Message;
 -----
 
-For desktop Windows applications, there's a NuGet package that will help you get started quickly.
+For desktop Windows applications, there's even a NuGet package that will help you get started quickly.
 
 ===== objective-git
 
 (((Apple)))(((Objective-C)))(((Cocoa)))
 If your application is running on an Apple platform, you're likely using Objective-C as your implementation language.
 Objective-Git (https://github.com/libgit2/objective-git[]) is the name of the Libgit2 bindings for that environment.
-Again, here's how to read HEAD's commit message:
+The example program looks like this:
 
 [source,objc]
 -----
@@ -212,21 +216,25 @@ GTRepository *repo =
 NSString *msg = [[[repo headReferenceWithError:NULL] resolvedTarget] message];
 -----
 
+Objective-git is fully interoperable with Swift, so don't fear if you've left Objective-C behind.
+
 
 ===== pygit2
 
 (((Python)))
 The bindings for Libgit2 in Python are called Pygit2, and can be found at http://www.pygit2.org/[].
-As always, HEAD's commit message:
+Our example program:
 
 [source,python]
 ----
-pygit2.Repository("/path/to/repo").head.resolve().get_object().message
+pygit2.Repository("/path/to/repo") # open repository
+    .head.resolve()                # get a direct ref
+    .get_object().message          # get commit, read message
 ----
 
 
 ==== Further Reading
 
 Of course, a full treatment of Libgit2's capabilities is outside the scope of this book.
 If you want more information on Libgit2 itself, there's API documentation at https://libgit2.github.com/libgit2[], and a set of guides at https://libgit2.github.com/docs[].
-For the other bindings, check the README and tests; there are often small tutorials and pointers to further reading there.
+For the other bindings, check the bundled README and tests; there are often small tutorials and pointers to further reading there.