tutorial: second chapter about changing a file

docs/tutorial/1-initial-commit.txt

@@ -58,7 +58,8 @@ job of the commit::
   >>> from time import time
   >>> commit = Commit()
   >>> commit.tree = tree.id
-  >>> commit.author = commit.committer = "Your Name <your.email@example.com>"
+  >>> author = "Your Name <your.email@example.com>"
+  >>> commit.author = commit.committer = author
   >>> commit.commit_time = commit.author_time = int(time())
   >>> tz = parse_timezone('-0200')
   >>> commit.commit_timezone = commit.author_timezone = tz

docs/tutorial/2-change_file.txt

@@ -0,0 +1,61 @@
+Changing a File and Commit it
+=============================
+
+Now we have a first commit, the next one will show a difference.
+
+As seen in the introduction, it's about making a path in a tree point to a
+new blob. The old blob will remain to compute the diff. The tree is altered
+and the new commit'task is to point to this new version.
+
+In the following examples, we assume we still have the ``repo`` and ``tree``
+object from the previous chapter.
+
+Let's first build the blob::
+
+  >>> spam = Blob.from_string("My new file content")
+  >>> spam.id
+  'fd2a0fa3ad828c5bda4b7badcbe522dc3b12af73'
+
+An alternative is to alter the previously constructed blob object::
+
+  >>> blob.data = "My new file content"
+  >>> blob.id
+  'fd2a0fa3ad828c5bda4b7badcbe522dc3b12af73'
+
+In any case, update the blob id known as "spam". You also have the
+opportunity of changing its mode::
+
+  >>> tree["spam"] = (0100644, spam.id)
+
+Now let's record the change::
+
+  >>> c2 = Commit()
+  >>> c2.tree = tree.id
+  >>> c2.parents = [commit.id]
+  >>> c2.author = c2.committer = author
+  >>> c2.commit_time = c2.author_time = int(time())
+  >>> c2.commit_timezone = c2.author_timezone = tz
+  >>> c2.encoding = "UTF-8"
+  >>> c2.message = 'Changing "spam"'
+
+In this new commit we record the changed tree id, and most important, the
+previous commit as the parent. Parents are actually a list because a commit
+may happen to have several parents after merging branches.
+
+Remain to record this whole new family::
+
+  >>> object_store.add_object(spam)
+  >>> object_store.add_object(tree)
+  >>> object_store.add_object(c2)
+
+You can already ask git to introspect this commit using ``git show`` and the
+value of ``commit.it`` as an argument. You'll see the difference will the
+previous blob recorded as "spam".
+
+You won't see it using git log because the head is still the previous
+commit. It's easy to remedy::
+
+  >>> repo.refs['refs/heads/master'] = commit.id
+
+Now all git tools will work as expected. Though don't forget that Dulwich is
+still open!

docs/tutorial/Makefile

@@ -1,4 +1,11 @@
+TXT=$(shell ls *.txt)
+
 ALL: index.html
 
-index.html: index.txt
-	rst2html.py $< $@
+index.html: $(TXT)
+	rst2html.py index.txt index.html
+
+clean:
+	rm -f index.html
+
+.PHONY: clean

docs/tutorial/index.txt

@@ -6,3 +6,4 @@ Dulwich Tutorial
 
 .. include:: 0-introduction.txt
 .. include:: 1-initial-commit.txt
+.. include:: 2-change_file.txt