Rev 4646: (mbp) developer documentation about content filtering in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

Canonical.com Patch Queue Manager pqm at pqm.ubuntu.com
Tue Aug 25 08:08:59 BST 2009


At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 4646 [merge]
revision-id: pqm at pqm.ubuntu.com-20090825070858-ufxhp9f3bjofawd9
parent: pqm at pqm.ubuntu.com-20090825050405-9g097zqrev5ownl5
parent: mbp at sourcefrog.net-20090825055114-g9l36dtwem4bww49
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Tue 2009-08-25 08:08:58 +0100
message:
  (mbp) developer documentation about content filtering
added:
  doc/developers/content-filtering.txt contentfiltering.txt-20090825034801-16mynkm76jpmi4tp-1
modified:
  NEWS                           NEWS-20050323055033-4e00b5db738777ff
  doc/developers/index.txt       index.txt-20070508041241-qznziunkg0nffhiw-1
=== modified file 'NEWS'
--- a/NEWS	2009-08-24 22:32:53 +0000
+++ b/NEWS	2009-08-25 07:08:58 +0000
@@ -61,6 +61,9 @@
 Documentation
 *************
 
+* New developer documentation for content filtering.
+  (Martin Pool)
+
 API Changes
 ***********
 

=== added file 'doc/developers/content-filtering.txt'
--- a/doc/developers/content-filtering.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/content-filtering.txt	2009-08-25 05:50:50 +0000
@@ -0,0 +1,147 @@
+*****************
+Content Filtering
+*****************
+
+Content filtering is the feature by which Bazaar can do line-ending
+conversion or keyword expansion so that the files that appear in the
+working tree are not precisely the same as the files stored in the
+repository.
+
+This document describes the implementation; see the user guide for how to
+use it.
+
+
+We distinguish between the *canonical form* which is stored in the
+repository and the *convenient form* which is stored in the working tree.
+The convenient form will for example use OS-local newline conventions or
+have keywords expanded, and the canonical form will not.  We use these
+names rather than eg "filtered" and "unfiltered" because filters are
+applied when both reading and writing so those names might cause
+confusion.
+
+Content filtering is only active on working trees that support it, which
+is format 2a and later.
+
+Content filtering is configured by rules that match file patterns.
+
+Filters
+*******
+
+Filters come in pairs: a read filter (reading convenient->canonical) and
+a write filter.  There is no requirement that they be symmetric or that
+they be deterministic from the input, though in general both these
+properties will be true.  Filters are allowed to change the size of the
+content, and things like line-ending conversion commonly will.
+
+Filters are fed a sequence of byte chunks (so that they don't have to
+hold the whole file in memory).  There is no guarantee that the chunks
+will be aligned with line endings.  Write filters are passed a context
+object through which they can obtain some information about eg which
+file they're working on.  (See ``bzrlib.filters`` docstring.)
+
+These are at the moment strictly *content* filters: they can't make
+changes to the tree like changing the execute bit, file types, or
+adding/removing entries.
+
+Conventions
+***********
+
+bzrlib interfaces that aren't explicitly specified to deal with the
+convenient form should return the canonical form.  Whenever we have the
+SHA1 hash of a file, it's the hash of the canonical form.
+
+
+Dirstate interactions
+*********************
+
+The dirstate file should store, in the column for the working copy, the cached
+hash and size of the canonical form, and the packed stat fingerprint for
+which that cache is valid.  This implies that the stored size will
+in general be different to the size in the packed stat.  (However, it
+may not always do this correctly - see
+<https://bugs.edge.launchpad.net/bzr/+bug/418439>.)
+
+The dirstate is given a SHA1Provider instance by its tree.  This class
+can calculate the (canonical) hash and size given a filename.  This
+provides a hook by which the working tree can make sure that when the
+dirstate needs to get the hash of the file, it takes the filters into
+account.
+
+
+User interface
+**************
+
+Most commands that deal with the text of files present the
+canonical form.  Some have options to choose.
+
+
+Performance considerations
+**************************
+
+Content filters can have serious performance implications.  For example,
+getting the size of (the canonical form of) a file is easy and fast when
+there are no content filters: we simply stat it.  However, when there
+are filters that might change the size of the file, determining the
+length of the canonical form requires reading in and filtering the whole
+file.
+
+Formats from 1.14 onwards support content filtering, so having fast
+paths for the case where content filtering is not possible is not
+generally worthwhile.  In fact, they're probably harmful by causing
+extra edges in test coverage and performance.
+
+We need to have things be fast even when filters are in use and then
+possibly do a bit less work when there are no filters configured.
+
+
+Future ideas and open issues
+****************************
+
+* We might benefit from having filters declare some of their properties
+  statically, for example that they're deterministic or can round-trip
+  or won't change the length of the file.  However, common cases like
+  crlf conversion are not guaranteed to round-trip and may change the
+  length, so perhaps adding separate cases will just complicate the code
+  and tests.  So overall this does not seem worthwhile.
+
+* In a future workingtree format, it might be better not to separately
+  store the working-copy hash and size, but rather just a stat fingerprint
+  at which point it was known to have the same canonical form as the 
+  basis tree.
+
+* It may be worthwhile to have a virtual Tree-like object that does
+  filtering, so there's a clean separation of filtering from the on-disk
+  state and the meaning of any object is clear.  This would have some
+  risk of bugs where either code holds the wrong object, or their state
+  becomes inconsistent.
+
+  This would be useful in allowing you to get a filtered view of a
+  historical tree, eg to export it or diff it.  At the moment export
+  needs to have its own code to do the filtering.
+
+  The convenient-form tree would talk to disk, and the convenient-form
+  tree would sit on top of that and be used by most other bzr code.
+
+  If we do this, we'd need to handle the fact that the on-disk tree,
+  which generally deals with all of the IO and generally works entirely
+  in convenient form, would also need to be told the canonical hash to
+  store in the dirstate.  This can perhaps be handled by the
+  SHA1Provider or a similar hook.
+
+* Content filtering at the moment is a bit specific to on-disk trees:
+  for instance ``SHA1Provider`` goes directly to disk, but it seems like
+  this is not necessary.
+
+
+See also
+********
+
+* http://bazaar-vcs.org/LineEndings
+
+* http://bazaar-vcs.org/LineEndings/Roadmap
+
+* `Developer Documentation <index.html>`_
+
+* ``bzrlib.filters``
+
+.. vim: ft=rst tw=72

=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt	2009-08-12 08:03:11 +0000
+++ b/doc/developers/index.txt	2009-08-25 03:48:12 +0000
@@ -126,6 +126,8 @@
 * `Computing last_modified values <last-modified.html>`_ for inventory
   entries
 
+* `Content filtering <content-filtering.html>`_
+
 * `LCA Tree Merging <lca_tree_merging.html>`_ |--| Merging tree-shape when
   there is not a single unique ancestor (criss-cross merge).
 




More information about the bazaar-commits mailing list