Extended Rugged example

Author: ben

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

@@ -69,13 +69,44 @@ tree = commit.tree
 As you can see, the code is much less cluttered.
 Firstly, Rugged uses exceptions; it can raise things like `ConfigError` or `ObjectError`  to signal error conditions.
 Secondly, there's no explicit freeing of resources, since Ruby is garbage-collected.
-Let's take a look at a slightly more complicated example:
+Let's take a look at a slightly more complicated example: crafting a commit from scratch
 
 [source,ruby]
 ----
-# TODO
+blob_id = repo.write("Blob contents", :blob) # <1>
+
+index = repo.index
+index.read_tree(repo.head.target.tree)
+index.add(:path => 'newfile.txt', :oid => blob_id) # <2>
+
+sig = {
+    :email => "[email protected]",
+    :name => "Bob User",
+    :time => Time.now,
+}
+
+commit_id = Rugged::Commit.create(repo,
+    :tree => index.write_tree(repo), # <3>
+    :author => sig,
+    :committer => sig, # <4>
+    :message => "Add newfile.txt", # <5>
+    :parents => repo.empty? ? [] : [ repo.head.target ].compact, # <6>
+    :update_ref => 'HEAD', # <7>
+)
+commit = repo.lookup(commit_id) # <8>
 ----
 
+<1> Create a new blob, which contains the contents of a new file.
+<2> Populate the index with the head commit's tree, and add the new file at the path `newfile.txt`.
+<3> This creates a new tree in the ODB, and uses it for the new commit.
+<4> We use the same signature for both the author and committer fields.
+<5> The commit message.
+<6> When creating a commit, you have to specify the new commit's parents.
+    This uses the tip of HEAD for the single parent.
+<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.
+
+
 ==== Advanced Functionality
 
 // TODO: backend, remote