cmds.py

   1 # Copyright (C) 2008 Canonical Ltd
   2 #
   3 # This program is free software; you can redistribute it and/or modify
   4 # it under the terms of the GNU General Public License as published by
   5 # the Free Software Foundation; either version 2 of the License, or
   6 # (at your option) any later version.
   7 #
   8 # This program is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 # GNU General Public License for more details.
  12 #
  13 # You should have received a copy of the GNU General Public License
  14 # along with this program; if not, write to the Free Software
  15 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  16
  17 """Fastimport/fastexport commands."""
  18
  19 from bzrlib import bzrdir
  20 from bzrlib.commands import Command
  21 from bzrlib.option import Option, ListOption, RegistryOption
  22
  23 from bzrlib.plugins.fastimport import load_fastimport
  24
  25
  26 def _run(source, processor_factory, verbose=False, user_map=None, **kwargs):
  27     """Create and run a processor.
  28
  29     :param source: a filename or '-' for standard input. If the
  30       filename ends in .gz, it will be opened as a gzip file and
  31       the stream will be implicitly uncompressed
  32     :param processor_factory: a callable for creating a processor
  33     :param user_map: if not None, the file containing the user map.
  34     """
  35     from fastimport import parser
  36     stream = _get_source_stream(source)
  37     user_mapper = _get_user_mapper(user_map)
  38     proc = processor_factory(verbose=verbose, **kwargs)
  39     p = parser.ImportParser(stream, verbose=verbose, user_mapper=user_mapper)
  40     return proc.process(p.iter_commands)
  41
  42
  43 def _get_source_stream(source):
  44     if source == '-':
  45         import sys
  46         from fastimport import helpers
  47         stream = helpers.binary_stream(sys.stdin)
  48     elif source.endswith('.gz'):
  49         import gzip
  50         stream = gzip.open(source, "rb")
  51     else:
  52         stream = open(source, "rb")
  53     return stream
  54
  55
  56 def _get_user_mapper(filename):
  57     import user_mapper
  58     if filename is None:
  59         return None
  60     f = open(filename)
  61     lines = f.readlines()
  62     f.close()
  63     return user_mapper.UserMapper(lines)
  64
  65
  66 class cmd_fast_import(Command):
  67     """Backend for fast Bazaar data importers.
  68
  69     This command reads a mixed command/data stream and creates
  70     branches in a Bazaar repository accordingly. The preferred
  71     recipe is::
  72
  73       bzr fast-import project.fi project.bzr
  74
  75     Numerous commands are provided for generating a fast-import file
  76     to use as input. These are named fast-export-from-xxx where xxx
  77     is one of cvs, darcs, git, hg, mtn, p4 or svn.
  78     To specify standard input as the input stream, use a
  79     source name of '-' (instead of project.fi). If the source name
  80     ends in '.gz', it is assumed to be compressed in gzip format.
  81
  82     project.bzr will be created if it doesn't exist. If it exists
  83     already, it should be empty or be an existing Bazaar repository
  84     or branch. If not specified, the current directory is assumed.
  85
  86     fast-import will intelligently select the format to use when
  87     creating a repository or branch. If you are running Bazaar 1.17
  88     up to Bazaar 2.0, the default format for Bazaar 2.x ("2a") is used.
  89     Otherwise, the current default format ("pack-0.92" for Bazaar 1.x)
  90     is used. If you wish to specify a custom format, use the `--format`
  91     option.
  92
  93      .. note::
  94
  95         To maintain backwards compatibility, fast-import lets you
  96         create the target repository or standalone branch yourself.
  97         It is recommended though that you let fast-import create
  98         these for you instead.
  99
 100     :Branch mapping rules:
 101
 102      Git reference names are mapped to Bazaar branch names as follows:
 103
 104      * refs/heads/foo is mapped to foo
 105      * refs/remotes/origin/foo is mapped to foo.remote
 106      * refs/tags/foo is mapped to foo.tag
 107      * */master is mapped to trunk, trunk.remote, etc.
 108      * */trunk is mapped to git-trunk, git-trunk.remote, etc.
 109
 110     :Branch creation rules:
 111
 112      When a shared repository is created or found at the destination,
 113      branches are created inside it. In the simple case of a single
 114      branch (refs/heads/master) inside the input file, the branch is
 115      project.bzr/trunk.
 116
 117      When a standalone branch is found at the destination, the trunk
 118      is imported there and warnings are output about any other branches
 119      found in the input file.
 120
 121      When a branch in a shared repository is found at the destination,
 122      that branch is made the trunk and other branches, if any, are
 123      created in sister directories.
 124
 125     :Working tree updates:
 126
 127      The working tree is generated for the trunk branch. If multiple
 128      branches are created, a message is output on completion explaining
 129      how to create the working trees for other branches.
 130
 131     :Custom exporters:
 132
 133      The fast-export-from-xxx commands typically call more advanced
 134      xxx-fast-export scripts. You are welcome to use the advanced
 135      scripts if you prefer.
 136
 137      If you wish to write a custom exporter for your project, see
 138      http://bazaar-vcs.org/BzrFastImport for the detailed protocol
 139      specification. In many cases, exporters can be written quite
 140      quickly using whatever scripting/programming language you like.
 141
 142     :User mapping:
 143
 144      Some source repositories store just the user name while Bazaar
 145      prefers a full email address. You can adjust user-ids while
 146      importing by using the --user-map option. The argument is a
 147      text file with lines in the format::
 148
 149        old-id = new-id
 150
 151      Blank lines and lines beginning with # are ignored.
 152      If old-id has the special value '@', then users without an
 153      email address will get one created by using the matching new-id
 154      as the domain, unless a more explicit address is given for them.
 155      For example, given the user-map of::
 156
 157        @ = example.com
 158        bill = William Jones <bill@example.com>
 159
 160      then user-ids are mapped as follows::
 161
 162       maria => maria <maria@example.com>
 163       bill => William Jones <bill@example.com>
 164
 165      .. note::
 166
 167         User mapping is supported by both the fast-import and
 168         fast-import-filter commands.
 169
 170     :Blob tracking:
 171
 172      As some exporters (like git-fast-export) reuse blob data across
 173      commits, fast-import makes two passes over the input file by
 174      default. In the first pass, it collects data about what blobs are
 175      used when, along with some other statistics (e.g. total number of
 176      commits). In the second pass, it generates the repository and
 177      branches.
 178
 179      .. note::
 180
 181         The initial pass isn't done if the --info option is used
 182         to explicitly pass in information about the input stream.
 183         It also isn't done if the source is standard input. In the
 184         latter case, memory consumption may be higher than otherwise
 185         because some blobs may be kept in memory longer than necessary.
 186
 187     :Restarting an import:
 188
 189      At checkpoints and on completion, the commit-id -> revision-id
 190      map is saved to a file called 'fastimport-id-map' in the control
 191      directory for the repository (e.g. .bzr/repository). If the import
 192      is interrupted or unexpectedly crashes, it can be started again
 193      and this file will be used to skip over already loaded revisions.
 194      As long as subsequent exports from the original source begin
 195      with exactly the same revisions, you can use this feature to
 196      maintain a mirror of a repository managed by a foreign tool.
 197      If and when Bazaar is used to manage the repository, this file
 198      can be safely deleted.
 199
 200     :Examples:
 201
 202      Import a Subversion repository into Bazaar::
 203
 204        bzr fast-export-from-svn /svn/repo/path project.fi
 205        bzr fast-import project.fi project.bzr
 206
 207      Import a CVS repository into Bazaar::
 208
 209        bzr fast-export-from-cvs /cvs/repo/path project.fi
 210        bzr fast-import project.fi project.bzr
 211
 212      Import a Git repository into Bazaar::
 213
 214        bzr fast-export-from-git /git/repo/path project.fi
 215        bzr fast-import project.fi project.bzr
 216
 217      Import a Mercurial repository into Bazaar::
 218
 219        bzr fast-export-from-hg /hg/repo/path project.fi
 220        bzr fast-import project.fi project.bzr
 221
 222      Import a Darcs repository into Bazaar::
 223
 224        bzr fast-export-from-darcs /darcs/repo/path project.fi
 225        bzr fast-import project.fi project.bzr
 226     """
 227     hidden = False
 228     _see_also = ['fast-export', 'fast-import-filter', 'fast-import-info']
 229     takes_args = ['source', 'destination?']
 230     takes_options = ['verbose',
 231                     Option('user-map', type=str,
 232                         help="Path to file containing a map of user-ids.",
 233                         ),
 234                     Option('info', type=str,
 235                         help="Path to file containing caching hints.",
 236                         ),
 237                     Option('trees',
 238                         help="Update all working trees, not just trunk's.",
 239                         ),
 240                     Option('count', type=int,
 241                         help="Import this many revisions then exit.",
 242                         ),
 243                     Option('checkpoint', type=int,
 244                         help="Checkpoint automatically every N revisions."
 245                              " The default is 10000.",
 246                         ),
 247                     Option('autopack', type=int,
 248                         help="Pack every N checkpoints. The default is 4.",
 249                         ),
 250                     Option('inv-cache', type=int,
 251                         help="Number of inventories to cache.",
 252                         ),
 253                     RegistryOption.from_kwargs('mode',
 254                         'The import algorithm to use.',
 255                         title='Import Algorithm',
 256                         default='Use the preferred algorithm (inventory deltas).',
 257                         classic="Use the original algorithm (mutable inventories).",
 258                         experimental="Enable experimental features.",
 259                         value_switches=True, enum_switch=False,
 260                         ),
 261                     Option('import-marks', type=str,
 262                         help="Import marks from file."
 263                         ),
 264                     Option('export-marks', type=str,
 265                         help="Export marks to file."
 266                         ),
 267                     RegistryOption('format',
 268                             help='Specify a format for the created repository. See'
 269                                  ' "bzr help formats" for details.',
 270                             lazy_registry=('bzrlib.bzrdir', 'format_registry'),
 271                             converter=lambda name: bzrdir.format_registry.make_bzrdir(name),
 272                             value_switches=False, title='Repository format'),
 273                      ]
 274     def run(self, source, destination='.', verbose=False, info=None,
 275         trees=False, count=-1, checkpoint=10000, autopack=4, inv_cache=-1,
 276         mode=None, import_marks=None, export_marks=None, format=None,
 277         user_map=None):
 278         load_fastimport()
 279         from bzrlib.plugins.fastimport.processors import generic_processor
 280         from bzrlib.plugins.fastimport.helpers import (
 281             open_destination_directory,
 282             )
 283         # If no format is given and the user is running a release
 284         # leading up to 2.0, select 2a for them. Otherwise, use
 285         # the default format.
 286         if format is None:
 287             import bzrlib
 288             bzr_version = bzrlib.version_info[0:2]
 289             if bzr_version in [(1,17), (1,18), (2,0)]:
 290                 format = bzrdir.format_registry.make_bzrdir('2a')
 291         control = open_destination_directory(destination, format=format)
 292
 293         # If an information file was given and the source isn't stdin,
 294         # generate the information by reading the source file as a first pass
 295         if info is None and source != '-':
 296             info = self._generate_info(source)
 297
 298         # Do the work
 299         if mode is None:
 300             mode = 'default'
 301         params = {
 302             'info': info,
 303             'trees': trees,
 304             'count': count,
 305             'checkpoint': checkpoint,
 306             'autopack': autopack,
 307             'inv-cache': inv_cache,
 308             'mode': mode,
 309             'import-marks': import_marks,
 310             'export-marks': export_marks,
 311             }
 312         return _run(source, generic_processor.GenericProcessor, control=control,
 313                 params=params, verbose=verbose, user_map=user_map)
 314
 315     def _generate_info(self, source):
 316         from cStringIO import StringIO
 317         from fastimport import parser
 318         from fastimport.processors import info_processor
 319         stream = _get_source_stream(source)
 320         output = StringIO()
 321         try:
 322             proc = info_processor.InfoProcessor(verbose=True, outf=output)
 323             p = parser.ImportParser(stream)
 324             return_code = proc.process(p.iter_commands)
 325             lines = output.getvalue().splitlines()
 326         finally:
 327             output.close()
 328             stream.seek(0)
 329         return lines
 330
 331
 332 class cmd_fast_import_filter(Command):
 333     """Filter a fast-import stream to include/exclude files & directories.
 334
 335     This command is useful for splitting a subdirectory or bunch of
 336     files out from a project to create a new project complete with history
 337     for just those files. It can also be used to create a new project
 338     repository that removes all references to files that should not have
 339     been committed, e.g. security-related information (like passwords),
 340     commercially sensitive material, files with an incompatible license or
 341     large binary files like CD images.
 342
 343     To specify standard input as the input stream, use a source name
 344     of '-'. If the source name ends in '.gz', it is assumed to be
 345     compressed in gzip format.
 346
 347     :File/directory filtering:
 348
 349      This is supported by the -i and -x options. Excludes take precedence
 350      over includes.
 351
 352      When filtering out a subdirectory (or file), the new stream uses the
 353      subdirectory (or subdirectory containing the file) as the root. As
 354      fast-import doesn't know in advance whether a path is a file or
 355      directory in the stream, you need to specify a trailing '/' on
 356      directories passed to the `--includes option`. If multiple files or
 357      directories are given, the new root is the deepest common directory.
 358
 359      Note: If a path has been renamed, take care to specify the *original*
 360      path name, not the final name that it ends up with.
 361
 362     :User mapping:
 363
 364      Some source repositories store just the user name while Bazaar
 365      prefers a full email address. You can adjust user-ids
 366      by using the --user-map option. The argument is a
 367      text file with lines in the format::
 368
 369        old-id = new-id
 370
 371      Blank lines and lines beginning with # are ignored.
 372      If old-id has the special value '@', then users without an
 373      email address will get one created by using the matching new-id
 374      as the domain, unless a more explicit address is given for them.
 375      For example, given the user-map of::
 376
 377        @ = example.com
 378        bill = William Jones <bill@example.com>
 379
 380      then user-ids are mapped as follows::
 381
 382       maria => maria <maria@example.com>
 383       bill => William Jones <bill@example.com>
 384
 385      .. note::
 386
 387         User mapping is supported by both the fast-import and
 388         fast-import-filter commands.
 389
 390     :Examples:
 391
 392      Create a new project from a library (note the trailing / on the
 393      directory name of the library)::
 394
 395        front-end | bzr fast-import-filter -i lib/xxx/ > xxx.fi
 396        bzr fast-import xxx.fi mylibrary.bzr
 397        (lib/xxx/foo is now foo)
 398
 399      Create a new repository without a sensitive file::
 400
 401        front-end | bzr fast-import-filter -x missile-codes.txt > clean.fi
 402        bzr fast-import clean.fi clean.bzr
 403     """
 404     hidden = False
 405     _see_also = ['fast-import']
 406     takes_args = ['source?']
 407     takes_options = ['verbose',
 408                     ListOption('include_paths', short_name='i', type=str,
 409                         help="Only include commits affecting these paths."
 410                              " Directories should have a trailing /."
 411                         ),
 412                     ListOption('exclude_paths', short_name='x', type=str,
 413                         help="Exclude these paths from commits."
 414                         ),
 415                     Option('user-map', type=str,
 416                         help="Path to file containing a map of user-ids.",
 417                         ),
 418                      ]
 419     encoding_type = 'exact'
 420     def run(self, source=None, verbose=False, include_paths=None,
 421         exclude_paths=None, user_map=None):
 422         load_fastimport()
 423         from fastimport.processors import filter_processor
 424         params = {
 425             'include_paths': include_paths,
 426             'exclude_paths': exclude_paths,
 427             }
 428         from fastimport import parser
 429         stream = _get_source_stream(source)
 430         user_mapper = _get_user_mapper(user_map)
 431         proc = filter_processor.FilterProcessor(params=params, verbose=verbose)
 432         p = parser.ImportParser(stream, verbose=verbose, user_mapper=user_mapper)
 433         return proc.process(p.iter_commands)
 434
 435
 436 class cmd_fast_import_info(Command):
 437     """Output information about a fast-import stream.
 438
 439     This command reads a fast-import stream and outputs
 440     statistics and interesting properties about what it finds.
 441     When run in verbose mode, the information is output as a
 442     configuration file that can be passed to fast-import to
 443     assist it in intelligently caching objects.
 444
 445     To specify standard input as the input stream, use a source name
 446     of '-'. If the source name ends in '.gz', it is assumed to be
 447     compressed in gzip format.
 448
 449     :Examples:
 450
 451      Display statistics about the import stream produced by front-end::
 452
 453       front-end | bzr fast-import-info -
 454
 455      Create a hints file for running fast-import on a large repository::
 456
 457        front-end | bzr fast-import-info -v - > front-end.cfg
 458     """
 459     hidden = False
 460     _see_also = ['fast-import']
 461     takes_args = ['source']
 462     takes_options = ['verbose']
 463     def run(self, source, verbose=False):
 464         load_fastimport()
 465         from fastimport.processors import info_processor
 466         return _run(source, info_processor.InfoProcessor, verbose=verbose)
 467
 468
 469 class cmd_fast_import_query(Command):
 470     """Query a fast-import stream displaying selected commands.
 471
 472     To specify standard input as the input stream, use a source name
 473     of '-'. If the source name ends in '.gz', it is assumed to be
 474     compressed in gzip format.
 475
 476     To specify a commit to display, give its mark using the
 477     --commit-mark option. The commit will be displayed with
 478     file-commands included but with inline blobs hidden.
 479
 480     To specify the commands to display, use the -C option one or
 481     more times. To specify just some fields for a command, use the
 482     syntax::
 483
 484       command=field1,...
 485
 486     By default, the nominated fields for the nominated commands
 487     are displayed tab separated. To see the information in
 488     a name:value format, use verbose mode.
 489
 490     Note: Binary fields (e.g. data for blobs) are masked out
 491     so it is generally safe to view the output in a terminal.
 492
 493     :Examples:
 494
 495      Show the commit with mark 429::
 496
 497       bzr fast-import-query xxx.fi -m429
 498
 499      Show all the fields of the reset and tag commands::
 500
 501       bzr fast-import-query xxx.fi -Creset -Ctag
 502
 503      Show the mark and merge fields of the commit commands::
 504
 505       bzr fast-import-query xxx.fi -Ccommit=mark,merge
 506     """
 507     hidden = True
 508     _see_also = ['fast-import', 'fast-import-filter']
 509     takes_args = ['source']
 510     takes_options = ['verbose',
 511                     Option('commit-mark', short_name='m', type=str,
 512                         help="Mark of the commit to display."
 513                         ),
 514                     ListOption('commands', short_name='C', type=str,
 515                         help="Display fields for these commands."
 516                         ),
 517                      ]
 518     def run(self, source, verbose=False, commands=None, commit_mark=None):
 519         load_fastimport()
 520         from fastimport.processors import query_processor
 521         from bzrlib.plugins.fastimport import helpers
 522         params = helpers.defines_to_dict(commands) or {}
 523         if commit_mark:
 524             params['commit-mark'] = commit_mark
 525         return _run(source, query_processor.QueryProcessor, params=params,
 526             verbose=verbose)
 527
 528
 529 class cmd_fast_export(Command):
 530     """Generate a fast-import stream from a Bazaar branch.
 531
 532     This program generates a stream from a Bazaar branch in fast-import
 533     format used by tools such as bzr fast-import, git-fast-import and
 534     hg-fast-import.
 535
 536     If no destination is given or the destination is '-', standard output
 537     is used. Otherwise, the destination is the name of a file. If the
 538     destination ends in '.gz', the output will be compressed into gzip
 539     format.
 540
 541     :Round-tripping:
 542
 543      Recent versions of the fast-import specification support features
 544      that allow effective round-tripping of many Bazaar branches. As
 545      such, fast-exporting a branch and fast-importing the data produced
 546      will create a new repository with equivalent history, i.e.
 547      "bzr log -v -p --include-merges --forward" on the old branch and
 548      new branch should produce similar, if not identical, results.
 549
 550      .. note::
 551
 552         Be aware that the new repository may appear to have similar history
 553         but internally it is quite different with new revision-ids and
 554         file-ids assigned. As a consequence, the ability to easily merge
 555         with branches based on the old repository is lost. Depending on your
 556         reasons for producing a new repository, this may or may not be an
 557         issue.
 558
 559     :Interoperability:
 560
 561      fast-export can use the following "extended features" to
 562      produce a richer data stream:
 563
 564      * *multiple-authors* - if a commit has multiple authors (as commonly
 565        occurs in pair-programming), all authors will be included in the
 566        output, not just the first author
 567
 568      * *commit-properties* - custom metadata per commit that Bazaar stores
 569        in revision properties (e.g. branch-nick and bugs fixed by this
 570        change) will be included in the output.
 571
 572      * *empty-directories* - directories, even the empty ones, will be
 573        included in the output.
 574
 575      To disable these features and produce output acceptable to git 1.6,
 576      use the --plain option. To enable these features, use --no-plain.
 577      Currently, --plain is the default but that will change in the near
 578      future once the feature names and definitions are formally agreed
 579      to by the broader fast-import developer community.
 580
 581     :Examples:
 582
 583      To produce data destined for import into Bazaar::
 584
 585        bzr fast-export --no-plain my-bzr-branch my.fi.gz
 586
 587      To produce data destined for Git 1.6::
 588
 589        bzr fast-export --plain my-bzr-branch my.fi
 590
 591      To import several unmerged but related branches into the same repository,
 592      use the --{export,import}-marks options, and specify a name for the git
 593      branch like this::
 594
 595        bzr fast-export --export-marks=marks.bzr project.dev |
 596               GIT_DIR=project/.git git-fast-import --export-marks=marks.git
 597
 598        bzr fast-export --import-marks=marks.bzr -b other project.other |
 599               GIT_DIR=project/.git git-fast-import --import-marks=marks.git
 600
 601      If you get a "Missing space after source" error from git-fast-import,
 602      see the top of the commands.py module for a work-around.
 603     """
 604     hidden = False
 605     _see_also = ['fast-import', 'fast-import-filter']
 606     takes_args = ['source', 'destination?']
 607     takes_options = ['verbose', 'revision',
 608                     Option('git-branch', short_name='b', type=str,
 609                         argname='FILE',
 610                         help='Name of the git branch to create (default=master).'
 611                         ),
 612                     Option('checkpoint', type=int, argname='N',
 613                         help="Checkpoint every N revisions (default=10000)."
 614                         ),
 615                     Option('marks', type=str, argname='FILE',
 616                         help="Import marks from and export marks to file."
 617                         ),
 618                     Option('import-marks', type=str, argname='FILE',
 619                         help="Import marks from file."
 620                         ),
 621                     Option('export-marks', type=str, argname='FILE',
 622                         help="Export marks to file."
 623                         ),
 624                     Option('plain',
 625                         help="Exclude metadata to maximise interoperability."
 626                         ),
 627                      ]
 628     encoding_type = 'exact'
 629     def run(self, source, destination=None, verbose=False,
 630         git_branch="master", checkpoint=10000, marks=None,
 631         import_marks=None, export_marks=None, revision=None,
 632         plain=True):
 633         load_fastimport()
 634         from bzrlib.plugins.fastimport import exporter
 635
 636         if marks:
 637             import_marks = export_marks = marks
 638         exporter = exporter.BzrFastExporter(source,
 639             destination=destination,
 640             git_branch=git_branch, checkpoint=checkpoint,
 641             import_marks_file=import_marks, export_marks_file=export_marks,
 642             revision=revision, verbose=verbose, plain_format=plain)
 643         return exporter.run()
 644
 645
 646 class cmd_fast_export_from_cvs(Command):
 647     """Generate a fast-import file from a CVS repository.
 648
 649     Destination is a dump file, typically named xxx.fi where xxx is
 650     the name of the project. If '-' is given, standard output is used.
 651
 652     cvs2svn 2.3 or later must be installed as its cvs2bzr script is used
 653     under the covers to do the export.
 654
 655     The source must be the path on your filesystem to the part of the
 656     repository you wish to convert. i.e. either that path or a parent
 657     directory must contain a CVSROOT subdirectory. The path may point to
 658     either the top of a repository or to a path within it. In the latter
 659     case, only that project within the repository will be converted.
 660
 661     .. note::
 662        Remote access to the repository is not sufficient - the path
 663        must point into a copy of the repository itself. See
 664        http://cvs2svn.tigris.org/faq.html#repoaccess for instructions
 665        on how to clone a remote CVS repository locally.
 666
 667     By default, the trunk, branches and tags are all exported. If you
 668     only want the trunk, use the `--trunk-only` option.
 669
 670     By default, filenames, log messages and author names are expected
 671     to be encoded in ascii. Use the `--encoding` option to specify an
 672     alternative. If multiple encodings are used, specify the option
 673     multiple times. For a list of valid encoding names, see
 674     http://docs.python.org/lib/standard-encodings.html.
 675
 676     Windows users need to install GNU sort and use the `--sort`
 677     option to specify its location. GNU sort can be downloaded from
 678     http://unxutils.sourceforge.net/.
 679     """
 680     hidden = False
 681     _see_also = ['fast-import', 'fast-import-filter']
 682     takes_args = ['source', 'destination']
 683     takes_options = ['verbose',
 684                     Option('trunk-only',
 685                         help="Export just the trunk, ignoring tags and branches."
 686                         ),
 687                     ListOption('encoding', type=str, argname='CODEC',
 688                         help="Encoding used for filenames, commit messages "
 689                              "and author names if not ascii."
 690                         ),
 691                     Option('sort', type=str, argname='PATH',
 692                         help="GNU sort program location if not on the path."
 693                         ),
 694                     ]
 695     encoding_type = 'exact'
 696     def run(self, source, destination, verbose=False, trunk_only=False,
 697         encoding=None, sort=None):
 698         load_fastimport()
 699         from bzrlib.plugins.fastimport.exporters import fast_export_from
 700         custom = []
 701         if trunk_only:
 702             custom.append("--trunk-only")
 703         if encoding:
 704             for enc in encoding:
 705                 custom.extend(['--encoding', enc])
 706         if sort:
 707             custom.extend(['--sort', sort])
 708         fast_export_from(source, destination, 'cvs', verbose, custom)
 709
 710
 711 class cmd_fast_export_from_darcs(Command):
 712     """Generate a fast-import file from a Darcs repository.
 713
 714     Destination is a dump file, typically named xxx.fi where xxx is
 715     the name of the project. If '-' is given, standard output is used.
 716
 717     Darcs 2.2 or later must be installed as various subcommands are
 718     used to access the source repository. The source may be a network
 719     URL but using a local URL is recommended for performance reasons.
 720     """
 721     hidden = False
 722     _see_also = ['fast-import', 'fast-import-filter']
 723     takes_args = ['source', 'destination']
 724     takes_options = ['verbose',
 725                     Option('encoding', type=str, argname='CODEC',
 726                         help="Encoding used for commit messages if not utf-8."
 727                         ),
 728                     ]
 729     encoding_type = 'exact'
 730     def run(self, source, destination, verbose=False, encoding=None):
 731         from bzrlib.plugins.fastimport.exporters import fast_export_from
 732         custom = None
 733         if encoding is not None:
 734             custom = ['--encoding', encoding]
 735         fast_export_from(source, destination, 'darcs', verbose, custom)
 736
 737
 738 class cmd_fast_export_from_hg(Command):
 739     """Generate a fast-import file from a Mercurial repository.
 740
 741     Destination is a dump file, typically named xxx.fi where xxx is
 742     the name of the project. If '-' is given, standard output is used.
 743
 744     Mercurial 1.2 or later must be installed as its libraries are used
 745     to access the source repository. Given the APIs currently used,
 746     the source repository must be a local file, not a network URL.
 747     """
 748     hidden = False
 749     _see_also = ['fast-import', 'fast-import-filter']
 750     takes_args = ['source', 'destination']
 751     takes_options = ['verbose']
 752     encoding_type = 'exact'
 753     def run(self, source, destination, verbose=False):
 754         load_fastimport()
 755         from bzrlib.plugins.fastimport.exporters import fast_export_from
 756         fast_export_from(source, destination, 'hg', verbose)
 757
 758
 759 class cmd_fast_export_from_git(Command):
 760     """Generate a fast-import file from a Git repository.
 761
 762     Destination is a dump file, typically named xxx.fi where xxx is
 763     the name of the project. If '-' is given, standard output is used.
 764
 765     Git 1.6 or later must be installed as the git fast-export
 766     subcommand is used under the covers to generate the stream.
 767     The source must be a local directory.
 768
 769     .. note::
 770
 771        Earlier versions of Git may also work fine but are
 772        likely to receive less active support if problems arise.
 773     """
 774     hidden = False
 775     _see_also = ['fast-import', 'fast-import-filter']
 776     takes_args = ['source', 'destination']
 777     takes_options = ['verbose']
 778     encoding_type = 'exact'
 779     def run(self, source, destination, verbose=False):
 780         load_fastimport()
 781         from bzrlib.plugins.fastimport.exporters import fast_export_from
 782         fast_export_from(source, destination, 'git', verbose)
 783
 784
 785 class cmd_fast_export_from_mtn(Command):
 786     """Generate a fast-import file from a Monotone repository.
 787
 788     Destination is a dump file, typically named xxx.fi where xxx is
 789     the name of the project. If '-' is given, standard output is used.
 790
 791     Monotone 0.43 or later must be installed as the mtn git_export
 792     subcommand is used under the covers to generate the stream.
 793     The source must be a local directory.
 794     """
 795     hidden = False
 796     _see_also = ['fast-import', 'fast-import-filter']
 797     takes_args = ['source', 'destination']
 798     takes_options = ['verbose']
 799     encoding_type = 'exact'
 800     def run(self, source, destination, verbose=False):
 801         load_fastimport()
 802         from bzrlib.plugins.fastimport.exporters import fast_export_from
 803         fast_export_from(source, destination, 'mtn', verbose)
 804
 805
 806 class cmd_fast_export_from_p4(Command):
 807     """Generate a fast-import file from a Perforce repository.
 808
 809     Source is a Perforce depot path, e.g., //depot/project
 810
 811     Destination is a dump file, typically named xxx.fi where xxx is
 812     the name of the project. If '-' is given, standard output is used.
 813
 814     bzrp4 must be installed as its p4_fast_export.py module is used under
 815     the covers to do the export.  bzrp4 can be downloaded from
 816     https://launchpad.net/bzrp4/.
 817
 818     The P4PORT environment variable must be set, and you must be logged
 819     into the Perforce server.
 820
 821     By default, only the HEAD changelist is exported.  To export all
 822     changelists, append '@all' to the source.  To export a revision range,
 823     append a comma-delimited pair of changelist numbers to the source,
 824     e.g., '100,200'.
 825     """
 826     hidden = False
 827     _see_also = ['fast-import', 'fast-import-filter']
 828     takes_args = ['source', 'destination']
 829     takes_options = []
 830     encoding_type = 'exact'
 831     def run(self, source, destination, verbose=False):
 832         load_fastimport()
 833         from bzrlib.plugins.fastimport.exporters import fast_export_from
 834         custom = []
 835         fast_export_from(source, destination, 'p4', verbose, custom)
 836
 837
 838 class cmd_fast_export_from_svn(Command):
 839     """Generate a fast-import file from a Subversion repository.
 840
 841     Destination is a dump file, typically named xxx.fi where xxx is
 842     the name of the project. If '-' is given, standard output is used.
 843
 844     Python-Subversion (Python bindings to the Subversion APIs)
 845     1.4 or later must be installed as this library is used to
 846     access the source repository. The source may be a network URL
 847     but using a local URL is recommended for performance reasons.
 848     """
 849     hidden = False
 850     _see_also = ['fast-import', 'fast-import-filter']
 851     takes_args = ['source', 'destination']
 852     takes_options = ['verbose',
 853                     Option('trunk-path', type=str, argname="STR",
 854                         help="Path in repo to /trunk.\n"
 855                               "May be `regex:/cvs/(trunk)/proj1/(.*)` in "
 856                               "which case the first group is used as the "
 857                               "branch name and the second group is used "
 858                               "to match files.",
 859                         ),
 860                     Option('branches-path', type=str, argname="STR",
 861                         help="Path in repo to /branches."
 862                         ),
 863                     Option('tags-path', type=str, argname="STR",
 864                         help="Path in repo to /tags."
 865                         ),
 866                     ]
 867     encoding_type = 'exact'
 868     def run(self, source, destination, verbose=False, trunk_path=None,
 869         branches_path=None, tags_path=None):
 870         load_fastimport()
 871         from bzrlib.plugins.fastimport.exporters import fast_export_from
 872         custom = []
 873         if trunk_path is not None:
 874             custom.extend(['--trunk-path', trunk_path])
 875         if branches_path is not None:
 876             custom.extend(['--branches-path', branches_path])
 877         if tags_path is not None:
 878             custom.extend(['--tags-path', tags_path])
 879         fast_export_from(source, destination, 'svn', verbose, custom)