Rev 3154: Add documentation about the inventory system. in http://people.ubuntu.com/~robertc/baz2.0/inventory.journalled

[Robert Collins]

At http://people.ubuntu.com/~robertc/baz2.0/inventory.journalled

------------------------------------------------------------
revno: 3154
revision-id:robertc at robertcollins.net-20080103014016-7o8mxov3jxx0tuwo
parent: robertc at robertcollins.net-20080103012146-1hy9jrj8zgld3raf
committer: Robert Collins <robertc at robertcollins.net>
branch nick: inventory.journalled
timestamp: Thu 2008-01-03 12:40:16 +1100
message:
  Add documentation about the inventory system.
added:
  doc/developers/inventory.txt   inventory.txt-20080103013957-opkrhxy6lmywmx4i-1
modified:
  doc/developers/index.txt       index.txt-20070508041241-qznziunkg0nffhiw-1
=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt	2007-12-05 18:58:49 +0000
+++ b/doc/developers/index.txt	2008-01-03 01:40:16 +0000
@@ -33,6 +33,8 @@
 
 * `Network protocol <network-protocol.html>`_ |--| Custom network protocol.
 
+* `Inventories <inventory.html>`_ |--| Tree shape abstraction.
+
 Data formats
 ============
 

=== added file 'doc/developers/inventory.txt'
--- a/doc/developers/inventory.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/inventory.txt	2008-01-03 01:40:16 +0000
@@ -0,0 +1,47 @@
+===========
+Inventories
+===========
+
+.. contents::
+
+Overview
+========
+
+Inventories provide an abstraction for talking about the shape of a tree.
+Generally only tree object implementors should be concerned about inventories.
+
+In memory inventories
+=====================
+
+In memory inventories are often used in diff and status operations between
+trees. We are working to reduce the number of times this occurs with 'full
+tree' inventory objects, and instead use more custom tailored data structures
+that allow operations on only a small amount of data regardless of the size of
+the tree.
+
+
+Serialization
+=============
+
+There are several variants of serialised tree shape in use by bzr. To date
+these have been mostly xml based, though plugins have offered non-xml versions.
+
+dirstate
+--------
+
+The dirstate file in a working tree includes many different tree shapes - one
+for the working tree and one for each parent tree, interleaved to allow
+efficient diff and status operations.
+
+xml
+---
+
+All the xml serialized forms write to and read from a single byte string, whose
+hash is then the inventory validator for the commit object.
+
+journalled
+----------
+
+The in development journalled inventory serializer generates a single byte
+string during serialization, but may require many byte strings to deserialize,
+and these are discovered recursively.