Add basic porcelain page in tutorial.

diff --git a/docs/tutorial/index.txt b/docs/tutorial/index.txt
index 79e914a3f49a76e5e66d45bea43688eef3ad7fa9..7d085a1f27c3776cea1ca27ee009618120443c2f 100644 (file)
--- a/docs/tutorial/index.txt
+++ b/docs/tutorial/index.txt
@@ -13,5 +13,6 @@ Tutorial
    object-store
    remote
    tag
+   porcelain
    conclusion
 

diff --git a/docs/tutorial/introduction.txt b/docs/tutorial/introduction.txt
index 184134d3c60af6a8a56b59a389474beca9c3e463..9fee9d8623797c57fb4734236d67365ee3702c54 100644 (file)
--- a/docs/tutorial/introduction.txt
+++ b/docs/tutorial/introduction.txt
@@ -10,7 +10,11 @@ The plumbing is the lower layer and it deals with the Git object database and th
 nitty gritty internals. The porcelain is roughly what you would expect to
 be exposed to as a user of the ``git`` command-like tool.
 
-Dulwich has a fairly complete plumbing implementation, and only a somewhat
-smaller porcelain implementation. The porcelain code lives in
-``dulwich.porcelain``. For the large part, this tutorial introduces you to the
-internal concepts of Git and the main plumbing parts of Dulwich.
+Dulwich has a fairly complete plumbing implementation, and a more recently
+added porcelain implementation. The porcelain code lives in
+``dulwich.porcelain``.
+
+
+For the large part, this tutorial introduces you to the internal concepts of
+Git and the main plumbing parts of Dulwich. The last chapter covers
+the porcelain.

diff --git a/docs/tutorial/porcelain.txt b/docs/tutorial/porcelain.txt
new file mode 100644 (file)
index 0000000..74d7048
--- /dev/null
+++ b/docs/tutorial/porcelain.txt
@@ -0,0 +1,34 @@
+Porcelain
+=========
+
+The ``porcelain'' is the higher level interface, built on top of the lower
+level implementation covered in previous chapters of this tutorial. The
+``dulwich.porcelain'' module in Dulwich is aimed to closely resemble
+the Git command-line API that you are familiar with.
+
+Basic concepts
+--------------
+The porcelain operations are implemented as top-level functions in the
+``dulwich.porcelain'' module. Most arguments can either be strings or
+more complex Dulwich objects; e.g. a repository argument will either take
+a string with a path to the repository or an instance of a ``Repo`` object.
+
+Initializing a new repository
+-----------------------------
+
+  >>> from dulwich import porcelain
+
+  >>> repo = porcelain.init("myrepo")
+
+Clone a repository
+------------------
+
+  >>> porcelain.clone("git://github.com/jelmer/dulwich", "dulwich-clone")
+
+Commit changes
+--------------
+
+  >>> r = porcelain.init("testrepo")
+  >>> open("testrepo/testfile", "w").write("data")
+  >>> porcelain.add(r, "testrepo/testfile")
+  >>> porcelain.commit(r, "A sample commit")