doc/properties.txt

   1 This file documents how file and revision properties are used in
   2 cvs2svn.
   3
   4 cvs2svn allows arbitrary properties to be associated with CVSFile and
   5 CVSRevision instances.  These properties are combined to form the
   6 effective properties for each CVSRevision.  Properties set in a
   7 CVSRevision take precedence over properties set in the corresponding
   8 CVSFile.
   9
  10 These properties can be set very flexibly by FilePropertySetter and
  11 RevisionPropertySetter objects, which in turn can be implemented
  12 arbitrarily and set via the conversion configuration file.  Several
  13 types of PropertySetters are already provided, and examples of there
  14 use are shown in the example configuration files.  The properties are
  15 determined early in the conversion and are retained for the duration
  16 of the conversion.
  17
  18 CVSFile.properties holds properties that do not change for the life of
  19 the file; for example, whether keywords should be expanded in the file
  20 contents.
  21
  22 CVSRevision.properties holds properties that can vary from one file
  23 revision to another.  The only current example of a revision property
  24 is the cvs2svn:rev-num property.
  25
  26 Properties whose names start with underscore are reserved for the
  27 internal use of cvs2svn.
  28
  29 The properties can be used by backends for any purpose.  Currently,
  30 they are used for two purposes:
  31
  32 1. Passing RevisionReaders information about how a file revision's
  33    contents should be transformed before being written to the new VCS.
  34    Please note that this does not necessarily correspond to how the
  35    revision contents will look after being checked out of the new VCS;
  36    for example, Subversion requires keywords to be *unexpanded* in the
  37    dumpfile stream if Subversion is going to expand them.  These
  38    properties are:
  39
  40        _keyword_handling -- How should RCS keywords be handled?
  41
  42            'untouched' -- The keywords should be output exactly as
  43                they are found in the RCS file.
  44
  45            'collapsed' -- The keywords should be collapsed in the
  46                output; e.g., "$Author: jrandom $" -> "$Author$".
  47
  48            'expanded' -- The keywords should be expanded in the
  49                output; e.g., "$Author$" -> "$Author: jrandom $".
  50
  51            'deleted' -- To be implemented
  52
  53        _eol_fix -- Should end-of-line sequences be made uniform before
  54            committing to the target VCS?  If this property is set to a
  55            non-empty value, then every end-of-line character sequence
  56            ('\n', '\r\n', or '\r') is converted to the specified value
  57            (which should obviously be a valid end-of-line character
  58            sequence).
  59
  60 2. cvs2svn: Specifying Subversion versioned properties.  Any
  61    properties that do not start with an underscore are converted into
  62    Subversion versioned properties on the associated file.  By this
  63    mechanism, arbitrary Subversion properties can be set.  A number of
  64    PropertySetters are provided to set common Subversion properties
  65    such as svn:mime-type, svn:eol-style, svn:executable, and
  66    svn:keywords.  Other properties can be set via the
  67    AutoPropsPropertySetter or by implementing custom PropertySetters.
  68
  69