doc/revision-reader.txt

   1 This file contains a description of the RevisionRecorder /
   2 RevisionExcluder / RevisionReader mechanism.
   3
   4
   5 cvs2svn now includes hooks to make it possible to avoid having to
   6 invoke CVS or RCS zillions of times in OutputPass (which is otherwise
   7 the most expensive part of the conversion).  Here is a brief
   8 description of how the hooks work.
   9
  10 Each conversion requires an instance of RevisionReader, whose
  11 responsibility is to produce the text contents of CVS revisions on
  12 demand during OutputPass.  The RevisionReader can read the CVS
  13 revision contents directly out of the RCS files during OutputPass.
  14 But additional hooks support the construction of different kinds of
  15 RevisionReader that record the CVS file revisions' contents during
  16 CollectRevsPass then output the contents during OutputPass.  (Indeed,
  17 for non-SVN backends, OutputPass might not even require the file
  18 contents.)
  19
  20 The following two other types of classes can help the RevisionReader:
  21
  22     RevisionRecorder -- can record the CVS revisions' text during
  23         CollectRevsPass to avoid having to parse the RCS files again
  24         during OutputPass.
  25
  26     RevisionExcluder -- is informed during FilterSymbolsPass about CVS
  27         revisions that have been excluded from the conversion and will
  28         therefore not be needed during OutputPass.  This mechanism can
  29         be used to discard temporary data that will not be required.
  30
  31 The type of RevisionReader to be used for a run of cvs2svn can be set
  32 using --use-internal-co, --use-rcs, or --use-cvs, or via the --options
  33 file with a line like:
  34
  35     ctx.revision_recorder = MyRevisionRecorder()
  36     ctx.revision_excluder = MyRevisionExcluder()
  37     ctx.revision_reader = MyRevisionReader()
  38
  39 The following RevisionReaders are supplied with cvs2svn:
  40
  41     InternalRevisionReader -- an InternalRevisionRecorder records the
  42         revisions' delta text and their dependencies during
  43         CollectRevsPass; an InternalRevisionExcluder discards unneeded
  44         deltas in FilterSymbolsPass; an InternalRevisionReader
  45         reconstitutes the revisions' contents during OutputPass from
  46         the recorded data.  This is by far the fastest option, but it
  47         requires a substantial amount of temporary disk space for the
  48         duration of the conversion.
  49
  50     RCSRevisionReader -- uses RCS's "co" command to extract the
  51         revision text during OutputPass.  This is slower than
  52         InternalRevisionReader because "co" has to be executed very
  53         many times, but is better tested and does not require any
  54         temporary disk space.  RCSRevisionReader does not use a
  55         RevisionRecorder or RevisionExcluder.
  56
  57     CVSRevisionReader -- uses the "cvs" command to extract the
  58         revision text during OutputPass.  This is even slower than
  59         RCSRevisionReader, but it can handle a some CVS file quirks
  60         that stymy RCSRevisionReader (see the cvs2svn HTML
  61         documentation).  CVSRevisionReader does not use a
  62         RevisionRecorder or RevisionExcluder.
  63
  64
  65 It is possible to write your own RevisionReader if you would like to
  66 do things differently.  A RevisionRecorder, with callback methods that
  67 are invoked as the CVS files are parsed, can be used to collect
  68 information during CollectRevsPass.  For example,
  69 RevisionRecorder.record_text() is passed the log message and text
  70 (full text or delta) for each file revision.  The record_text() method
  71 is allowed to return an arbitrary token (for example, a content hash),
  72 and that token is stored into CVSRevision.revision_recorder_token and
  73 carried along by cvs2svn.
  74
  75 A RevisionExcluder, with callbacks that are invoked during
  76 FilterSymbolsPass, can be used to learn which CVS revisions will
  77 actually be needed by the conversion.  The RevisionExcluder has the
  78 opportunity to use this information to delete unneeded temporary data.
  79
  80 Later, when OutputPass requires the file contents, it calls
  81 RevisionReader.get_content_stream(), which is passed a CVSRevision
  82 instance and has to return a stream object that produces the file
  83 revision's contents.  The fancy RevisionReader could use the token to
  84 retrieve the pre-stored file contents without having to call CVS or
  85 RCS at all.
  86
  87