Rev 2818: Introduce tree/directory distinction. in file:///v/home/vila/src/experimental/hashtrees/

[Vincent Ladeuil]

At file:///v/home/vila/src/experimental/hashtrees/

------------------------------------------------------------
revno: 2818
revision-id: v.ladeuil+lp at free.fr-20070913093745-xfx3f56n1ojxw95t
parent: pqm at pqm.ubuntu.com-20070912222627-zvqit350mf6gvrbh
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: hashtrees
timestamp: Thu 2007-09-13 11:37:45 +0200
message:
  Introduce tree/directory distinction.
modified:
  doc/developers/directory-fingerprints.txt directoryfingerprint-20070731033348-okmllh4b5srdtlk2-1
-------------- next part --------------
=== modified file 'doc/developers/directory-fingerprints.txt'
--- a/doc/developers/directory-fingerprints.txt	2007-07-31 03:38:18 +0000
+++ b/doc/developers/directory-fingerprints.txt	2007-09-13 09:37:45 +0000
@@ -6,12 +6,12 @@
 Introduction
 ------------
 
-The basic idea is that for a directory in a tree (committed or otherwise), we
-will have a single scalar value.  If these values are the same, the contents of
-the subtree under that directory are necessarily the same.  
+The basic idea is that a tree (committed or otherwise), we will have a single
+scalar value representing the content.  If these values are different for two
+trees, the contents of the two trees are necessarily different.
 
 This is intended to help with these use cases, by allowing them to quickly skip
-over directories with no relevant changes, and to detect when a directory has
+over subtrees with no relevant changes, and to detect when a tree content has
 changed:
 
 * diff/status (both local trees and historical trees)
@@ -21,6 +21,39 @@
 * commit
 
 
+Definitions
+-----------
+
+Tree content
+~~~~~~~~~~~~
+
+A tree content differs from a directory by defining some attributes that
+reflects the content of the whole tree instead of the content of the directory
+itself.
+
+For example the last modified attribute of a directory will be the date and
+time when a file was added, deleted or renamed in this directory. By contrast,
+the last modified attribute of a tree will be when a file was added, deleted,
+renamed or *modified* in the associated directory or any subtree.
+
+We focused on a attribute representing the whole tree content in this
+specification but handling a last modified attribute may be a nice property for
+GUIs like tortoisebzr.
+
+Note: Such attributes have little chance to handled by file systems because
+mounted file systems forbids updates of such attributes above the mount point.
+
+A tree content is :
+- list of the names of files and directories contained,
+- for each file the content of the file itself,
+- for each directory the corresponding tree content.
+
+The hash of a tree content is then calculated from:
+- list of the names of files and directories contained,
+- for each file the hash of its content,
+- for each directory the corresponding hash of the tree content.
+
+
 Use-case oriented APIs
 ----------------------
 
@@ -49,7 +82,7 @@
 ~~~~~~~
 
 Log is interested in two operations: finding the revisions that touched
-anything inside a directory, and getting the differences between 
+anything inside a tree, and getting the differences between 
 consecutive revisions (possibly filtered to a directory)::
 
   find_touching_revisions(branch, file_id) # should be on Branch?