1 # (Be in -*- mode: python; coding: utf-8 -*- mode.)
3 # ====================================================================
4 # Copyright (c) 2006-2008 CollabNet. All rights reserved.
6 # This software is licensed as described in the file COPYING, which
7 # you should have received as part of this distribution. The terms
8 # are also available at http://subversion.tigris.org/license-1.html.
9 # If newer versions of this license are posted there, you may use a
10 # newer version instead, at your option.
12 # This software consists of voluntary contributions made by many
13 # individuals. For exact contribution history, see the revision
14 # history and logs, available at http://cvs2svn.tigris.org/.
15 # ====================================================================
17 # #####################
18 # ## PLEASE READ ME! ##
19 # #####################
21 # This is a template for an options file that can be used to configure
22 # cvs2svn to convert to git rather than to Subversion. See
23 # www/cvs2git.html and www/cvs2svn.html for general information, and
24 # see the comments in this file for information about what options are
25 # available and how they can be set.
27 # The program that is run to convert from CVS to git is called
28 # cvs2git. Run it with the --options option, passing it this file as
31 # cvs2git --options=cvs2git-example.options
33 # The output of cvs2git is a blob file and a dump file that can be
34 # loaded into git using the "git fast-import" command. Please read
35 # www/cvs2git.html for more information.
37 # Many options do not have defaults, so it is easier to copy this file
38 # and modify what you need rather than creating a new options file
39 # from scratch. This file is in Python syntax, but you don't need to
40 # know Python to modify it. But if you *do* know Python, then you
41 # will be happy to know that you can use arbitary Python constructs to
42 # do fancy configuration tricks.
44 # But please be aware of the following:
46 # * In many places, leading whitespace is significant in Python (it is
47 # used instead of curly braces to group statements together).
48 # Therefore, if you don't know what you are doing, it is best to
49 # leave the whitespace as it is.
51 # * In normal strings, Python treats a backslash ("\") as an escape
52 # character. Therefore, if you want to specify a string that
53 # contains a backslash, you need either to escape the backslash with
54 # another backslash ("\\"), or use a "raw string", as in one if the
55 # following equivalent examples:
57 # ctx.sort_executable = 'c:\\windows\\system32\\sort.exe'
58 # ctx.sort_executable = r'c:\windows\system32\sort.exe'
60 # See http://docs.python.org/tutorial/introduction.html#strings for
63 # Two identifiers will have been defined before this file is executed,
64 # and can be used freely within this file:
66 # ctx -- a Ctx object (see cvs2svn_lib/context.py), which holds
67 # many configuration options
69 # run_options -- an instance of the GitRunOptions class (see
70 # cvs2svn_lib/git_run_options.py), which holds some variables
71 # governing how cvs2git is run
74 # Import some modules that are used in setting the options:
77 from cvs2svn_lib import config
78 from cvs2svn_lib import changeset_database
79 from cvs2svn_lib.common import CVSTextDecoder
80 from cvs2svn_lib.log import Log
81 from cvs2svn_lib.project import Project
82 from cvs2svn_lib.git_revision_recorder import GitRevisionRecorder
83 from cvs2svn_lib.git_output_option import GitRevisionMarkWriter
84 from cvs2svn_lib.git_output_option import GitOutputOption
85 from cvs2svn_lib.revision_manager import NullRevisionRecorder
86 from cvs2svn_lib.revision_manager import NullRevisionExcluder
87 from cvs2svn_lib.fulltext_revision_recorder \
88 import SimpleFulltextRevisionRecorderAdapter
89 from cvs2svn_lib.rcs_revision_manager import RCSRevisionReader
90 from cvs2svn_lib.cvs_revision_manager import CVSRevisionReader
91 from cvs2svn_lib.checkout_internal import InternalRevisionRecorder
92 from cvs2svn_lib.checkout_internal import InternalRevisionExcluder
93 from cvs2svn_lib.checkout_internal import InternalRevisionReader
94 from cvs2svn_lib.symbol_strategy import AllBranchRule
95 from cvs2svn_lib.symbol_strategy import AllTagRule
96 from cvs2svn_lib.symbol_strategy import BranchIfCommitsRule
97 from cvs2svn_lib.symbol_strategy import ExcludeRegexpStrategyRule
98 from cvs2svn_lib.symbol_strategy import ForceBranchRegexpStrategyRule
99 from cvs2svn_lib.symbol_strategy import ForceTagRegexpStrategyRule
100 from cvs2svn_lib.symbol_strategy import ExcludeTrivialImportBranchRule
101 from cvs2svn_lib.symbol_strategy import ExcludeVendorBranchRule
102 from cvs2svn_lib.symbol_strategy import HeuristicStrategyRule
103 from cvs2svn_lib.symbol_strategy import UnambiguousUsageRule
104 from cvs2svn_lib.symbol_strategy import HeuristicPreferredParentRule
105 from cvs2svn_lib.symbol_strategy import SymbolHintsFileRule
106 from cvs2svn_lib.symbol_transform import ReplaceSubstringsSymbolTransform
107 from cvs2svn_lib.symbol_transform import RegexpSymbolTransform
108 from cvs2svn_lib.symbol_transform import IgnoreSymbolTransform
109 from cvs2svn_lib.symbol_transform import NormalizePathsSymbolTransform
110 from cvs2svn_lib.property_setters import AutoPropsPropertySetter
111 from cvs2svn_lib.property_setters import CVSBinaryFileDefaultMimeTypeSetter
112 from cvs2svn_lib.property_setters import CVSBinaryFileEOLStyleSetter
113 from cvs2svn_lib.property_setters import CVSRevisionNumberSetter
114 from cvs2svn_lib.property_setters import DefaultEOLStyleSetter
115 from cvs2svn_lib.property_setters import EOLStyleFromMimeTypeSetter
116 from cvs2svn_lib.property_setters import ExecutablePropertySetter
117 from cvs2svn_lib.property_setters import KeywordsPropertySetter
118 from cvs2svn_lib.property_setters import MimeMapper
119 from cvs2svn_lib.property_setters import SVNBinaryFileKeywordsPropertySetter
121 # To choose the level of logging output, uncomment one of the
123 #Log().log_level = Log.WARN
124 #Log().log_level = Log.QUIET
125 Log().log_level = Log.NORMAL
126 #Log().log_level = Log.VERBOSE
127 #Log().log_level = Log.DEBUG
130 # During CollectRevsPass, cvs2git records the contents of file
131 # revisions into a "blob" file in git-fast-import format. This option
132 # configures that process:
133 ctx.revision_recorder = SimpleFulltextRevisionRecorderAdapter(
134 # The following option specifies how the revision contents of the RCS
135 # files should be read.
137 # RCSRevisionReader uses RCS's "co" program to extract the revision
138 # contents of the RCS files during CollectRevsPass. The constructor
139 # argument specifies how to invoke the "co" executable.
141 # CVSRevisionReader uses the "cvs" program to extract the revision
142 # contents out of the RCS files during OutputPass. This option is
143 # considerably slower than RCSRevisionReader because "cvs" is
144 # considerably slower than "co". However, it works in some situations
145 # where RCSRevisionReader fails; see the HTML documentation of the
146 # "--use-cvs" option for details. The constructor argument specifies
147 # how to invoke the "co" executable.
149 # Uncomment one of the two following lines:
150 #RCSRevisionReader(co_executable=r'co'),
151 CVSRevisionReader(cvs_executable=r'cvs'),
153 # The file in which to write the git-fast-import stream that
154 # contains the file revision contents:
155 GitRevisionRecorder('cvs2svn-tmp/git-blob.dat'),
158 # cvs2git does not need to keep track of what revisions will be
159 # excluded, so leave this option unchanged:
160 ctx.revision_excluder = NullRevisionExcluder()
162 # cvs2git doesn't need a revision reader because OutputPass only
163 # refers to blobs that were output during CollectRevsPass, so leave
164 # this option set to None.
165 ctx.revision_reader = None
167 # Set the name (and optionally the path) of some other executables
168 # required by cvs2svn:
169 ctx.sort_executable = r'sort'
171 # Change the following line to True if the conversion should only
172 # include the trunk of the repository (i.e., all branches and tags
173 # should be omitted from the conversion):
174 ctx.trunk_only = False
176 # How to convert CVS author names, log messages, and filenames to
177 # unicode. The first argument to CVSTextDecoder is a list of encoders
178 # that are tried in order in 'strict' mode until one of them succeeds.
179 # If none of those succeeds, then fallback_encoder (if it is
180 # specified) is used in lossy 'replace' mode. Setting a fallback
181 # encoder ensures that the encoder always succeeds, but it can cause
183 ctx.cvs_author_decoder = CVSTextDecoder(
189 #fallback_encoding='ascii'
191 ctx.cvs_log_decoder = CVSTextDecoder(
197 #fallback_encoding='ascii'
199 # You might want to be especially strict when converting filenames to
200 # unicode (e.g., maybe not specify a fallback_encoding).
201 ctx.cvs_filename_decoder = CVSTextDecoder(
207 #fallback_encoding='ascii'
210 # Template for the commit message to be used for initial project
212 ctx.initial_project_commit_message = (
213 'Standard project directories initialized by cvs2svn.'
216 # Template for the commit message to be used for post commits, in
217 # which modifications to a vendor branch are copied back to trunk.
218 # This message can use '%(revnum)d' to include the SVN revision number
219 # of the revision that included the change to the vendor branch
220 # (admittedly rather pointless in a cvs2git conversion).
221 ctx.post_commit_message = (
222 'This commit was generated by cvs2svn to track changes on a CVS '
226 # Template for the commit message to be used for commits in which
227 # symbols are created. This message can use '%(symbol_type)d' to
228 # include the type of the symbol ('branch' or 'tag') or
229 # '%(symbol_name)' to include the name of the symbol.
230 ctx.symbol_commit_message = (
231 "This commit was manufactured by cvs2svn to create %(symbol_type)s "
235 # Some CVS clients for MacOS store resource fork data into CVS along
236 # with the file contents itself by wrapping it all up in a container
237 # format called "AppleSingle". Subversion currently does not support
238 # MacOS resource forks. Nevertheless, sometimes the resource fork
239 # information is not necessary and can be discarded. Set the
240 # following option to True if you would like cvs2svn to identify files
241 # whose contents are encoded in AppleSingle format, and discard all
242 # but the data fork for such files before committing them to
243 # Subversion. (Please note that AppleSingle contents are identified
244 # by the AppleSingle magic number as the first four bytes of the file.
245 # This check is not failproof, so only set this option if you think
247 ctx.decode_apple_single = False
249 # This option can be set to the name of a filename to which are stored
250 # statistics and conversion decisions about the CVS symbols.
251 ctx.symbol_info_filename = None
252 #ctx.symbol_info_filename = 'symbol-info.txt'
254 # cvs2svn uses "symbol strategy rules" to help decide how to handle
255 # CVS symbols. The rules in a project's symbol_strategy_rules are
256 # applied in order, and each rule is allowed to modify the symbol.
257 # The result (after each of the rules has been applied) is used for
260 # 1. A CVS symbol might be used as a tag in one file and as a branch
261 # in another file. cvs2svn has to decide whether to convert such a
262 # symbol as a tag or as a branch. cvs2svn uses a series of
263 # heuristic rules to decide how to convert a symbol. The user can
264 # override the default rules for specific symbols or symbols
265 # matching regular expressions.
267 # 2. cvs2svn is also capable of excluding symbols from the conversion
268 # (provided no other symbols depend on them.
270 # 3. CVS does not record unambiguously the line of development from
271 # which a symbol sprouted. cvs2svn uses a heuristic to choose a
272 # symbol's "preferred parents".
274 # The standard branch/tag/exclude StrategyRules do not change a symbol
275 # that has already been processed by an earlier rule, so in effect the
276 # first matching rule is the one that is used.
278 global_symbol_strategy_rules = [
279 # It is possible to specify manually exactly how symbols should be
280 # converted and what line of development should be used as the
281 # preferred parent. To do so, create a file containing the symbol
282 # hints and enable the following option.
284 # The format of the hints file is described in the documentation
285 # for the --symbol-hints command-line option. The file output by
286 # the --write-symbol-info (i.e., ctx.symbol_info_filename) option
287 # is in the same format. The simplest way to use this option is
288 # to run the conversion through CollateSymbolsPass with
289 # --write-symbol-info option, copy the symbol info and edit it to
290 # create a hints file, then re-start the conversion at
291 # CollateSymbolsPass with this option enabled.
292 #SymbolHintsFileRule('symbol-hints.txt'),
294 # To force all symbols matching a regular expression to be
295 # converted as branches, add rules like the following:
296 #ForceBranchRegexpStrategyRule(r'branch.*'),
298 # To force all symbols matching a regular expression to be
299 # converted as tags, add rules like the following:
300 #ForceTagRegexpStrategyRule(r'tag.*'),
302 # To force all symbols matching a regular expression to be
303 # excluded from the conversion, add rules like the following:
304 #ExcludeRegexpStrategyRule(r'unknown-.*'),
306 # Sometimes people use "cvs import" to get their own source code
307 # into CVS. This practice creates a vendor branch 1.1.1 and
308 # imports the code onto the vendor branch as 1.1.1.1, then copies
309 # the same content to the trunk as version 1.1. Normally, such
310 # vendor branches are useless and they complicate the SVN history
311 # unnecessarily. The following rule excludes any branches that
312 # only existed as a vendor branch with a single import (leaving
313 # only the 1.1 revision). If you want to retain such branches,
314 # comment out the following line. (Please note that this rule
315 # does not exclude vendor *tags*, as they are not so easy to
317 ExcludeTrivialImportBranchRule(),
319 # To exclude all vendor branches (branches that had "cvs import"s
320 # on them bug no other kinds of commits), uncomment the following
322 #ExcludeVendorBranchRule(),
324 # Usually you want this rule, to convert unambiguous symbols
325 # (symbols that were only ever used as tags or only ever used as
326 # branches in CVS) the same way they were used in CVS:
327 UnambiguousUsageRule(),
329 # If there was ever a commit on a symbol, then it cannot be
330 # converted as a tag. This rule causes all such symbols to be
331 # converted as branches. If you would like to resolve such
332 # ambiguities manually, comment out the following line:
333 BranchIfCommitsRule(),
335 # Last in the list can be a catch-all rule that is used for
336 # symbols that were not matched by any of the more specific rules
337 # above. (Assuming that BranchIfCommitsRule() was included above,
338 # then the symbols that are still indeterminate at this point can
339 # sensibly be converted as branches or tags.) Include at most one
340 # of these lines. If none of these catch-all rules are included,
341 # then the presence of any ambiguous symbols (that haven't been
342 # disambiguated above) is an error:
344 # Convert ambiguous symbols based on whether they were used more
345 # often as branches or as tags:
346 HeuristicStrategyRule(),
347 # Convert all ambiguous symbols as branches:
349 # Convert all ambiguous symbols as tags:
352 # The last rule is here to choose the preferred parent of branches
353 # and tags, that is, the line of development from which the symbol
355 HeuristicPreferredParentRule(),
358 # Specify a username to be used for commits for which CVS doesn't
359 # record the original author (for example, the creation of a branch).
360 # This should be a simple (unix-style) username, but it can be
361 # translated into a git-style name by the author_transforms map.
362 ctx.username = 'cvs2svn'
364 # ctx.svn_property_setters contains a list of rules used to set the
365 # svn properties on files in the converted archive. For each file,
366 # the rules are tried one by one. Any rule can add or suppress one or
367 # more svn properties. Typically the rules will not overwrite
368 # properties set by a previous rule (though they are free to do so).
370 # Obviously, SVN properties per se are not interesting for a cvs2git
371 # conversion, but some of these properties have side-effects that do
372 # affect the git output. FIXME: Document this in more detail.
373 ctx.svn_property_setters.extend([
374 # To read auto-props rules from a file, uncomment the following line
375 # and specify a filename. The boolean argument specifies whether
376 # case should be ignored when matching filenames to the filename
377 # patterns found in the auto-props file:
378 #AutoPropsPropertySetter(
379 # r'/home/username/.subversion/config',
383 # To read mime types from a file, uncomment the following line and
384 # specify a filename:
385 #MimeMapper(r'/etc/mime.types'),
387 # Omit the svn:eol-style property from any files that are listed
388 # as binary (i.e., mode '-kb') in CVS:
389 CVSBinaryFileEOLStyleSetter(),
391 # If the file is binary and its svn:mime-type property is not yet
392 # set, set svn:mime-type to 'application/octet-stream'.
393 CVSBinaryFileDefaultMimeTypeSetter(),
395 # To try to determine the eol-style from the mime type, uncomment
396 # the following line:
397 #EOLStyleFromMimeTypeSetter(),
399 # Choose one of the following lines to set the default
400 # svn:eol-style if none of the above rules applied. The argument
401 # is the svn:eol-style that should be applied, or None if no
402 # svn:eol-style should be set (i.e., the file should be treated as
405 # The default is to treat all files as binary unless one of the
406 # previous rules has determined otherwise, because this is the
407 # safest approach. However, if you have been diligent about
408 # marking binary files with -kb in CVS and/or you have used the
409 # above rules to definitely mark binary files as binary, then you
410 # might prefer to use 'native' as the default, as it is usually
411 # the most convenient setting for text files. Other possible
412 # options: 'CRLF', 'CR', 'LF'.
413 DefaultEOLStyleSetter(None),
414 #DefaultEOLStyleSetter('native'),
416 # Prevent svn:keywords from being set on files that have
417 # svn:eol-style unset.
418 SVNBinaryFileKeywordsPropertySetter(),
420 # If svn:keywords has not been set yet, set it based on the file's
422 KeywordsPropertySetter(config.SVN_KEYWORDS_VALUE),
424 # Set the svn:executable flag on any files that are marked in CVS as
426 ExecutablePropertySetter(),
430 # The directory to use for temporary files:
431 ctx.tmpdir = r'cvs2svn-tmp'
433 # To skip the cleanup of temporary files, uncomment the following
435 #ctx.skip_cleanup = True
438 # In CVS, it is perfectly possible to make a single commit that
439 # affects more than one project or more than one branch of a single
440 # project. Subversion also allows such commits. Therefore, by
441 # default, when cvs2svn sees what looks like a cross-project or
442 # cross-branch CVS commit, it converts it into a
443 # cross-project/cross-branch Subversion commit.
445 # However, other tools and SCMs have trouble representing
446 # cross-project or cross-branch commits. (For example, Trac's Revtree
447 # plugin, http://www.trac-hacks.org/wiki/RevtreePlugin is confused by
448 # such commits.) Therefore, we provide the following two options to
449 # allow cross-project/cross-branch commits to be suppressed.
451 # cvs2git only supports single-project conversions (multiple-project
452 # conversions wouldn't really make sense for git anyway). So this
453 # option must be set to False:
454 ctx.cross_project_commits = False
456 # git itself doesn't allow commits that affect more than one branch,
457 # so this option must be set to False:
458 ctx.cross_branch_commits = False
460 # cvs2git does not yet handle translating .cvsignore files into
461 # .git/info/exclude content, so by default, the .cvsignore files are included inthe conversion output. If you would like to omit the .cvsignore files from the output, set this option to False:
462 ctx.keep_cvsignore = True
464 # By default, it is a fatal error for a CVS ",v" file to appear both
465 # inside and outside of an "Attic" subdirectory (this should never
466 # happen, but frequently occurs due to botched repository
467 # administration). If you would like to retain both versions of such
468 # files, change the following option to True, and the attic version of
469 # the file will be written to a subdirectory called "Attic" in the
471 ctx.retain_conflicting_attic_files = False
473 # CVS uses unix login names as author names whereas git requires
474 # author names to be of the form "foo <bar>". The default is to set
475 # the git author to "cvsauthor <cvsauthor>". author_transforms can be
476 # used to map cvsauthor names (e.g., "jrandom") to a true name and
477 # email address (e.g., "J. Random <jrandom@example.com>" for the
478 # example shown). All values should be either 16-bit strings (i.e.,
479 # with "u" as a prefix) or 8-bit strings in the utf-8 encoding.
480 # Please substitute your own project's usernames here to use with the
481 # author_transforms option of GitOutputOption below.
483 'jrandom' : ('J. Random', 'jrandom@example.com'),
484 'mhagger' : ('Michael Haggerty', 'mhagger@alum.mit.edu'),
485 'brane' : (u'Branko Čibej', 'brane@xbc.nu'),
486 'ringstrom' : ('Tobias Ringström', 'tobias@ringstrom.mine.nu'),
487 'dionisos' : (u'Erik Hülsmann', 'e.huelsmann@gmx.net'),
489 # This one will be used for commits for which CVS doesn't record
490 # the original author, as explained above.
491 'cvs2svn' : ('cvs2svn', 'admin@example.com'),
494 # This is the main option that causes cvs2svn to output to git rather
496 ctx.output_option = GitOutputOption(
497 # The file in which to write the git-fast-import stream that
498 # contains the changesets and branch/tag information:
499 'cvs2svn-tmp/git-dump.dat',
501 # The blobs will be written via the revision recorder, so in
502 # OutputPass we only have to emit references to the blob marks:
503 GitRevisionMarkWriter(),
505 # This option can be set to an integer to limit the number of
506 # revisions that are merged with the main parent in any commit.
507 # For git output, this can be set to None (unlimited), though due
508 # to the limitations of other tools you might want to set it to a
509 # smaller number (e.g., 16). For Mercurial output, this should be
514 # Optional map from CVS author names to git author names:
515 author_transforms=author_transforms,
518 # Change this option to True to turn on profiling of cvs2svn (for
519 # debugging purposes):
520 run_options.profiling = False
523 # Should CVSItem -> Changeset database files be memory mapped? In
524 # some tests, using memory mapping speeded up the overall conversion
525 # by about 5%. But this option can cause the conversion to fail with
526 # an out of memory error if the conversion computer runs out of
527 # virtual address space (e.g., when running a very large conversion on
528 # a 32-bit operating system). Therefore it is disabled by default.
529 # Uncomment the following line to allow these database files to be
531 #changeset_database.use_mmap_for_cvs_item_to_changeset_table = True
533 # Now set the project to be converted to git. cvs2git only supports
534 # single-project conversions, so this method must only be called
536 run_options.set_project(
537 # The filesystem path to the part of the CVS repository (*not* a
538 # CVS working copy) that should be converted. This may be a
539 # subdirectory (i.e., a module) within a larger CVS repository.
540 r'test-data/main-cvsrepos',
542 # A list of symbol transformations that can be used to rename
543 # symbols in this project.
545 # Use IgnoreSymbolTransforms like the following to completely
546 # ignore symbols matching a regular expression when parsing
547 # the CVS repository, for example to avoid warnings about
548 # branches with two names and to choose the preferred name.
549 # It is *not* recommended to use this instead of
550 # ExcludeRegexpStrategyRule; though more efficient,
551 # IgnoreSymbolTransforms are less flexible and don't exclude
552 # branches correctly. The argument is a Python-style regular
553 # expression that has to match the *whole* CVS symbol name:
554 #IgnoreSymbolTransform(r'nightly-build-tag-.*')
556 # RegexpSymbolTransforms transform symbols textually using a
557 # regular expression. The first argument is a Python regular
558 # expression pattern and the second is a replacement pattern.
559 # The pattern is matched against each symbol name. If it
560 # matches the whole symbol name, then the symbol name is
561 # replaced with the corresponding replacement text. The
562 # replacement can include substitution patterns (e.g., r'\1'
563 # or r'\g<name>'). Typically you will want to use raw strings
564 # (strings with a preceding 'r', like shown in the examples)
565 # for the regexp and its replacement to avoid backslash
566 # substitution within those strings.
567 #RegexpSymbolTransform(r'release-(\d+)_(\d+)',
569 #RegexpSymbolTransform(r'release-(\d+)_(\d+)_(\d+)',
570 # r'release-\1.\2.\3'),
572 # Simple 1:1 character replacements can also be done. The
573 # following transform, which converts backslashes into forward
574 # slashes, should usually be included:
575 ReplaceSubstringsSymbolTransform('\\','/'),
577 # This last rule eliminates leading, trailing, and repeated
578 # slashes within the output symbol names:
579 NormalizePathsSymbolTransform(),
582 # See the definition of global_symbol_strategy_rules above for a
583 # description of this option:
584 symbol_strategy_rules=global_symbol_strategy_rules,