Merge pull request #999 from bzz/embedding/add-dulwich

Add Dulwich to Appendinx B: embedding

Author: ben

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

@@ -15,3 +15,6 @@ 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[]
+
+include::book/B-embedding-git/sections/dulwich.asc[]
+

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

@@ -0,0 +1,44 @@
+=== Dulwich
+
+(((Dulwich)))((("Python")))
+There is also a pure-Python Git implementation - Dulwich.
+The project is hosted under https://www.dulwich.io/
+It aims to provide an interface to git repositories (both local and remote) that doesn't call out to git directly but instead uses pure Python.
+It has an optional C extensions though, that significantly improve the performance.
+
+Dulwich follows git design and separate two basic levels of API: plumbing and porcelain.
+
+Here is an example of using the lower level API to access the commit message of the last commit:
+
+[source, python]
+-----
+from dulwich.repo import Repo
+r = Repo('.')
+r.head()
+# '57fbe010446356833a6ad1600059d80b1e731e15'
+
+c = r[r.head()]
+c
+# <Commit 015fc1267258458901a94d228e39f0a378370466>
+
+c.message
+# 'Add note about encoding.\n'
+-----
+
+To print a commit log using high-level porcelain API, one can use:
+
+[source, python]
+-----
+from dulwich import porcelain
+porcelain.log('.', max_entries=1)
+
+#commit: 57fbe010446356833a6ad1600059d80b1e731e15
+#Author: Jelmer Vernooij <[email protected]>
+#Date:   Sat Apr 29 2017 23:57:34 +0000
+-----
+
+
+==== Further Reading
+ 
+ * The official API documentation is available at https://www.dulwich.io/apidocs/dulwich.html[]
+ * Official tutorial at https://www.dulwich.io/docs/tutorial[] has many examples of how to do specific tasks with Dulwich