ODB backends part I

Author: ben

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

@@ -106,10 +106,41 @@ commit = repo.lookup(commit_id) # <8>
 <7> Rugged (and Libgit2) can optionally update a reference when making a commit.
 <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 pretty clean, but since Libgit2 is doing the heavy lifting, this code will run pretty fast, too.
+
 
 ==== Advanced Functionality
 
-// TODO: backend, remote
+Libgit2 has a couple of capabilities that are outside the scope of core Git.
+One example is pluggability: Libgit2 allows you to provide custom ``backends'' for several types of operation, so you can store things in a different way than stock Git does.
+Libgit2 allows custom backends for configuration, ref storage, and the object database, among other things.
+
+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.
+
+[source,c]
+----
+git_odb *odb;
+int error = git_odb_new(&odb); // <1>
+
+git_repository *repo;
+error = git_repository_wrap_odb(&repo, odb); // <2>
+
+git_odb_backend *my_backend;
+error = git_odb_backend_mine(&my_backend, repo, …); // <3>
+
+error = git_odb_add_backendodb, my_backend, 1); // <4>
+----
+
+_Note that error handling has been elided for this example. You should know better._
+
+<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.
+
+// TODO
 
 ==== What Libgit2 Can't Do