Update README regarding metadata support.

Signed-off-by: Rob Browning <rlb@defaultvalue.org>
Reviewed-by: Zoran Zaric <zz@zoranzaric.de>

diff --git a/DESIGN b/DESIGN
index dfe30f36062ffbf8cc2fb623792ef1b87271cf8a..70e440dd174d70f8e5b43c2f5ec316c21184f218 100644 (file)
--- a/DESIGN
+++ b/DESIGN
@@ -371,32 +371,31 @@ Detailed Metadata
 -----------------
 
 So that's the basic structure of a bup repository, which is also a git
-repository.  There's one more thing we have to deal with in bup: filesystem
-metadata.  git repositories are really only intended to store file contents
-with a small bit of extra information, like symlink support and
-differentiating between executable and non-executable files.  For the rest,
-we'll have to store it some other way.
+repository.  There's just one more thing we have to deal with:
+filesystem metadata.  Git repositories are really only intended to
+store file contents with a small bit of extra information, like
+symlink targets and and executable bits, so we have to store the rest
+some other way.
 
-As of this writing, bup's support for metadata is... pretty much
-nonexistent.  People are working on it.  But the plan goes like this:
+Bup stores more complete metadata in the VFS in a file named .bupm in
+each tree.  This file contains one entry for each file in the tree
+object, sorted in the same order as the tree.  The first .bupm entry
+is for the directory itself, i.e. ".", and its name is the empty
+string, "".
 
- - Each git tree will contain a file called .bupmeta.
- 
- - .bupmeta contains an entry for every entry in the tree object, sorted in
-   the same order as in the tree.
- 
- - the .bupmeta entry lists information like modification times, attributes,
-   file ownership, and so on for each file in the tree.
-   
- - for backward compatibility with pre-metadata versions of bup (and git,
-   for that matter) the .bupmeta file for each tree is optional, and if it's
-   missing, files will be assumed to have default permissions.
-   
- The nice thing about this design is that you can walk through each file in
- a tree just by opening the tree and the .bupmeta contents, and iterating
- through both at the same time.
- 
- Trust us, it'll be awesome.  
+Each .bupm entry contains a variable length sequence of records
+containing the metadata for the corresponding path.  Each record
+records one type of metadata.  Current types include a common record
+type (containing the normal stat information), a symlink target type,
+a POSIX1e ACL type, etc.  See metadata.py for the complete list.
+
+The .bupm file is optional, and when it's missing, bup will behave as
+it did before the addition of metadata, and restore files using the
+tree information.
+
+The nice thing about this design is that you can walk through each
+file in a tree just by opening the tree and the .bupmeta contents, and
+iterating through both at the same time.
 
 
 Filesystem Interaction
@@ -605,3 +604,7 @@ things to note:
 We hope you'll enjoy bup.  Looking forward to your patches!
 
 -- apenwarr and the rest of the bup team
+
+Local Variables:
+mode: text
+End:

diff --git a/README.md b/README.md
index b3a937e6514e70d58f1257876d80bde11cf1fd5f..3f9c2410a6198ae9328aeb918b44b31a2de66b18 100644 (file)
--- a/README.md
+++ b/README.md
@@ -300,10 +300,16 @@ Things that are stupid for now but which we'll fix later
 Help with any of these problems, or others, is very welcome.  Join the
 mailing list (see below) if you'd like to help.
 
- - 'bup save' and 'bup restore' don't know about file metadata.
+ - 'bup save' and 'bup restore' have immature metadata support.
  
-    That means we aren't saving file attributes, mtimes, ownership, hard
-    links, MacOS resource forks, etc.  Clearly this needs to be improved.
+    On the plus side, they actually do have support now, but it's new,
+    and not remotely as well tested as tar/rsync/whatever's.  If you'd
+    like to help test, please do; something like 'rsync -niaHAX src/
+    restore/' may be useful on that front.
+
+    In addition, at the moment, if any strip or graft-style options
+    are specified to 'bup save', then no metadata will be written for
+    the root directory.  That's obviously less than ideal.
 
  - 'bup index' is slower than it should be.