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 == '-' or source is None:
  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,
 313                 bzrdir=control, params=params, verbose=verbose,
 314                 user_map=user_map)
 315
 316     def _generate_info(self, source):
 317         from cStringIO import StringIO
 318         from fastimport import parser
 319         from fastimport.processors import info_processor
 320         stream = _get_source_stream(source)
 321         output = StringIO()
 322         try:
 323             proc = info_processor.InfoProcessor(verbose=True, outf=output)
 324             p = parser.ImportParser(stream)
 325             return_code = proc.process(p.iter_commands)
 326             lines = output.getvalue().splitlines()
 327         finally:
 328             output.close()
 329             stream.seek(0)
 330         return lines
 331
 332
 333 class cmd_fast_import_filter(Command):
 334     """Filter a fast-import stream to include/exclude files & directories.
 335
 336     This command is useful for splitting a subdirectory or bunch of
 337     files out from a project to create a new project complete with history
 338     for just those files. It can also be used to create a new project
 339     repository that removes all references to files that should not have
 340     been committed, e.g. security-related information (like passwords),
 341     commercially sensitive material, files with an incompatible license or
 342     large binary files like CD images.
 343
 344     To specify standard input as the input stream, use a source name
 345     of '-'. If the source name ends in '.gz', it is assumed to be
 346     compressed in gzip format.
 347
 348     :File/directory filtering:
 349
 350      This is supported by the -i and -x options. Excludes take precedence
 351      over includes.
 352
 353      When filtering out a subdirectory (or file), the new stream uses the
 354      subdirectory (or subdirectory containing the file) as the root. As
 355      fast-import doesn't know in advance whether a path is a file or
 356      directory in the stream, you need to specify a trailing '/' on
 357      directories passed to the `--includes option`. If multiple files or
 358      directories are given, the new root is the deepest common directory.
 359
 360      Note: If a path has been renamed, take care to specify the *original*
 361      path name, not the final name that it ends up with.
 362
 363     :User mapping:
 364
 365      Some source repositories store just the user name while Bazaar
 366      prefers a full email address. You can adjust user-ids
 367      by using the --user-map option. The argument is a
 368      text file with lines in the format::
 369
 370        old-id = new-id
 371
 372      Blank lines and lines beginning with # are ignored.
 373      If old-id has the special value '@', then users without an
 374      email address will get one created by using the matching new-id
 375      as the domain, unless a more explicit address is given for them.
 376      For example, given the user-map of::
 377
 378        @ = example.com
 379        bill = William Jones <bill@example.com>
 380
 381      then user-ids are mapped as follows::
 382
 383       maria => maria <maria@example.com>
 384       bill => William Jones <bill@example.com>
 385
 386      .. note::
 387
 388         User mapping is supported by both the fast-import and
 389         fast-import-filter commands.
 390
 391     :Examples:
 392
 393      Create a new project from a library (note the trailing / on the
 394      directory name of the library)::
 395
 396        front-end | bzr fast-import-filter -i lib/xxx/ > xxx.fi
 397        bzr fast-import xxx.fi mylibrary.bzr
 398        (lib/xxx/foo is now foo)
 399
 400      Create a new repository without a sensitive file::
 401
 402        front-end | bzr fast-import-filter -x missile-codes.txt > clean.fi
 403        bzr fast-import clean.fi clean.bzr
 404     """
 405     hidden = False
 406     _see_also = ['fast-import']
 407     takes_args = ['source?']
 408     takes_options = ['verbose',
 409                     ListOption('include_paths', short_name='i', type=str,
 410                         help="Only include commits affecting these paths."
 411                              " Directories should have a trailing /."
 412                         ),
 413                     ListOption('exclude_paths', short_name='x', type=str,
 414                         help="Exclude these paths from commits."
 415                         ),
 416                     Option('user-map', type=str,
 417                         help="Path to file containing a map of user-ids.",
 418                         ),
 419                      ]
 420     encoding_type = 'exact'
 421     def run(self, source=None, verbose=False, include_paths=None,
 422         exclude_paths=None, user_map=None):
 423         load_fastimport()
 424         from fastimport.processors import filter_processor
 425         params = {
 426             'include_paths': include_paths,
 427             'exclude_paths': exclude_paths,
 428             }
 429         from fastimport import parser
 430         stream = _get_source_stream(source)
 431         user_mapper = _get_user_mapper(user_map)
 432         proc = filter_processor.FilterProcessor(params=params, verbose=verbose)
 433         p = parser.ImportParser(stream, verbose=verbose, user_mapper=user_mapper)
 434         return proc.process(p.iter_commands)
 435
 436
 437 class cmd_fast_import_info(Command):
 438     """Output information about a fast-import stream.
 439
 440     This command reads a fast-import stream and outputs
 441     statistics and interesting properties about what it finds.
 442     When run in verbose mode, the information is output as a
 443     configuration file that can be passed to fast-import to
 444     assist it in intelligently caching objects.
 445
 446     To specify standard input as the input stream, use a source name
 447     of '-'. If the source name ends in '.gz', it is assumed to be
 448     compressed in gzip format.
 449
 450     :Examples:
 451
 452      Display statistics about the import stream produced by front-end::
 453
 454       front-end | bzr fast-import-info -
 455
 456      Create a hints file for running fast-import on a large repository::
 457
 458        front-end | bzr fast-import-info -v - > front-end.cfg
 459     """
 460     hidden = False
 461     _see_also = ['fast-import']
 462     takes_args = ['source']
 463     takes_options = ['verbose']
 464     def run(self, source, verbose=False):
 465         load_fastimport()
 466         from fastimport.processors import info_processor
 467         return _run(source, info_processor.InfoProcessor, verbose=verbose)
 468
 469
 470 class cmd_fast_import_query(Command):
 471     """Query a fast-import stream displaying selected commands.
 472
 473     To specify standard input as the input stream, use a source name
 474     of '-'. If the source name ends in '.gz', it is assumed to be
 475     compressed in gzip format.
 476
 477     To specify a commit to display, give its mark using the
 478     --commit-mark option. The commit will be displayed with
 479     file-commands included but with inline blobs hidden.
 480
 481     To specify the commands to display, use the -C option one or
 482     more times. To specify just some fields for a command, use the
 483     syntax::
 484
 485       command=field1,...
 486
 487     By default, the nominated fields for the nominated commands
 488     are displayed tab separated. To see the information in
 489     a name:value format, use verbose mode.
 490
 491     Note: Binary fields (e.g. data for blobs) are masked out
 492     so it is generally safe to view the output in a terminal.
 493
 494     :Examples:
 495
 496      Show the commit with mark 429::
 497
 498       bzr fast-import-query xxx.fi -m429
 499
 500      Show all the fields of the reset and tag commands::
 501
 502       bzr fast-import-query xxx.fi -Creset -Ctag
 503
 504      Show the mark and merge fields of the commit commands::
 505
 506       bzr fast-import-query xxx.fi -Ccommit=mark,merge
 507     """
 508     hidden = True
 509     _see_also = ['fast-import', 'fast-import-filter']
 510     takes_args = ['source']
 511     takes_options = ['verbose',
 512                     Option('commit-mark', short_name='m', type=str,
 513                         help="Mark of the commit to display."
 514                         ),
 515                     ListOption('commands', short_name='C', type=str,
 516                         help="Display fields for these commands."
 517                         ),
 518                      ]
 519     def run(self, source, verbose=False, commands=None, commit_mark=None):
 520         load_fastimport()
 521         from fastimport.processors import query_processor
 522         from bzrlib.plugins.fastimport import helpers
 523         params = helpers.defines_to_dict(commands) or {}
 524         if commit_mark:
 525             params['commit-mark'] = commit_mark
 526         return _run(source, query_processor.QueryProcessor, params=params,
 527             verbose=verbose)
 528
 529
 530 class cmd_fast_export(Command):
 531     """Generate a fast-import stream from a Bazaar branch.
 532
 533     This program generates a stream from a Bazaar branch in fast-import
 534     format used by tools such as bzr fast-import, git-fast-import and
 535     hg-fast-import.
 536
 537     If no destination is given or the destination is '-', standard output
 538     is used. Otherwise, the destination is the name of a file. If the
 539     destination ends in '.gz', the output will be compressed into gzip
 540     format.
 541
 542     :Round-tripping:
 543
 544      Recent versions of the fast-import specification support features
 545      that allow effective round-tripping of many Bazaar branches. As
 546      such, fast-exporting a branch and fast-importing the data produced
 547      will create a new repository with equivalent history, i.e.
 548      "bzr log -v -p --include-merges --forward" on the old branch and
 549      new branch should produce similar, if not identical, results.
 550
 551      .. note::
 552
 553         Be aware that the new repository may appear to have similar history
 554         but internally it is quite different with new revision-ids and
 555         file-ids assigned. As a consequence, the ability to easily merge
 556         with branches based on the old repository is lost. Depending on your
 557         reasons for producing a new repository, this may or may not be an
 558         issue.
 559
 560     :Interoperability:
 561
 562      fast-export can use the following "extended features" to
 563      produce a richer data stream:
 564
 565      * *multiple-authors* - if a commit has multiple authors (as commonly
 566        occurs in pair-programming), all authors will be included in the
 567        output, not just the first author
 568
 569      * *commit-properties* - custom metadata per commit that Bazaar stores
 570        in revision properties (e.g. branch-nick and bugs fixed by this
 571        change) will be included in the output.
 572
 573      * *empty-directories* - directories, even the empty ones, will be
 574        included in the output.
 575
 576      To disable these features and produce output acceptable to git 1.6,
 577      use the --plain option. To enable these features, use --no-plain.
 578      Currently, --plain is the default but that will change in the near
 579      future once the feature names and definitions are formally agreed
 580      to by the broader fast-import developer community.
 581
 582     :Examples:
 583
 584      To produce data destined for import into Bazaar::
 585
 586        bzr fast-export --no-plain my-bzr-branch my.fi.gz
 587
 588      To produce data destined for Git 1.6::
 589
 590        bzr fast-export --plain my-bzr-branch my.fi
 591
 592      To import several unmerged but related branches into the same repository,
 593      use the --{export,import}-marks options, and specify a name for the git
 594      branch like this::
 595
 596        bzr fast-export --export-marks=marks.bzr project.dev |
 597               GIT_DIR=project/.git git-fast-import --export-marks=marks.git
 598
 599        bzr fast-export --import-marks=marks.bzr -b other project.other |
 600               GIT_DIR=project/.git git-fast-import --import-marks=marks.git
 601
 602      If you get a "Missing space after source" error from git-fast-import,
 603      see the top of the commands.py module for a work-around.
 604     """
 605     hidden = False
 606     _see_also = ['fast-import', 'fast-import-filter']
 607     takes_args = ['source', 'destination?']
 608     takes_options = ['verbose', 'revision',
 609                     Option('git-branch', short_name='b', type=str,
 610                         argname='FILE',
 611                         help='Name of the git branch to create (default=master).'
 612                         ),
 613                     Option('checkpoint', type=int, argname='N',
 614                         help="Checkpoint every N revisions (default=10000)."
 615                         ),
 616                     Option('marks', type=str, argname='FILE',
 617                         help="Import marks from and export marks to file."
 618                         ),
 619                     Option('import-marks', type=str, argname='FILE',
 620                         help="Import marks from file."
 621                         ),
 622                     Option('export-marks', type=str, argname='FILE',
 623                         help="Export marks to file."
 624                         ),
 625                     Option('plain',
 626                         help="Exclude metadata to maximise interoperability."
 627                         ),
 628                      ]
 629     encoding_type = 'exact'
 630     def run(self, source, destination=None, verbose=False,
 631         git_branch="master", checkpoint=10000, marks=None,
 632         import_marks=None, export_marks=None, revision=None,
 633         plain=True):
 634         load_fastimport()
 635         from bzrlib.plugins.fastimport import exporter
 636
 637         if marks:
 638             import_marks = export_marks = marks
 639         exporter = exporter.BzrFastExporter(source,
 640             destination=destination,
 641             git_branch=git_branch, checkpoint=checkpoint,
 642             import_marks_file=import_marks, export_marks_file=export_marks,
 643             revision=revision, verbose=verbose, plain_format=plain)
 644         return exporter.run()
 645
 646
 647 class cmd_fast_export_from_cvs(Command):
 648     """Generate a fast-import file from a CVS repository.
 649
 650     Destination is a dump file, typically named xxx.fi where xxx is
 651     the name of the project. If '-' is given, standard output is used.
 652
 653     cvs2svn 2.3 or later must be installed as its cvs2bzr script is used
 654     under the covers to do the export.
 655
 656     The source must be the path on your filesystem to the part of the
 657     repository you wish to convert. i.e. either that path or a parent
 658     directory must contain a CVSROOT subdirectory. The path may point to
 659     either the top of a repository or to a path within it. In the latter
 660     case, only that project within the repository will be converted.
 661
 662     .. note::
 663        Remote access to the repository is not sufficient - the path
 664        must point into a copy of the repository itself. See
 665        http://cvs2svn.tigris.org/faq.html#repoaccess for instructions
 666        on how to clone a remote CVS repository locally.
 667
 668     By default, the trunk, branches and tags are all exported. If you
 669     only want the trunk, use the `--trunk-only` option.
 670
 671     By default, filenames, log messages and author names are expected
 672     to be encoded in ascii. Use the `--encoding` option to specify an
 673     alternative. If multiple encodings are used, specify the option
 674     multiple times. For a list of valid encoding names, see
 675     http://docs.python.org/lib/standard-encodings.html.
 676
 677     Windows users need to install GNU sort and use the `--sort`
 678     option to specify its location. GNU sort can be downloaded from
 679     http://unxutils.sourceforge.net/.
 680     """
 681     hidden = False
 682     _see_also = ['fast-import', 'fast-import-filter']
 683     takes_args = ['source', 'destination']
 684     takes_options = ['verbose',
 685                     Option('trunk-only',
 686                         help="Export just the trunk, ignoring tags and branches."
 687                         ),
 688                     ListOption('encoding', type=str, argname='CODEC',
 689                         help="Encoding used for filenames, commit messages "
 690                              "and author names if not ascii."
 691                         ),
 692                     Option('sort', type=str, argname='PATH',
 693                         help="GNU sort program location if not on the path."
 694                         ),
 695                     ]
 696     encoding_type = 'exact'
 697     def run(self, source, destination, verbose=False, trunk_only=False,
 698         encoding=None, sort=None):
 699         load_fastimport()
 700         from bzrlib.plugins.fastimport.exporters import fast_export_from
 701         custom = []
 702         if trunk_only:
 703             custom.append("--trunk-only")
 704         if encoding:
 705             for enc in encoding:
 706                 custom.extend(['--encoding', enc])
 707         if sort:
 708             custom.extend(['--sort', sort])
 709         fast_export_from(source, destination, 'cvs', verbose, custom)
 710
 711
 712 class cmd_fast_export_from_darcs(Command):
 713     """Generate a fast-import file from a Darcs repository.
 714
 715     Destination is a dump file, typically named xxx.fi where xxx is
 716     the name of the project. If '-' is given, standard output is used.
 717
 718     Darcs 2.2 or later must be installed as various subcommands are
 719     used to access the source repository. The source may be a network
 720     URL but using a local URL is recommended for performance reasons.
 721     """
 722     hidden = False
 723     _see_also = ['fast-import', 'fast-import-filter']
 724     takes_args = ['source', 'destination']
 725     takes_options = ['verbose',
 726                     Option('encoding', type=str, argname='CODEC',
 727                         help="Encoding used for commit messages if not utf-8."
 728                         ),
 729                     ]
 730     encoding_type = 'exact'
 731     def run(self, source, destination, verbose=False, encoding=None):
 732         from bzrlib.plugins.fastimport.exporters import fast_export_from
 733         custom = None
 734         if encoding is not None:
 735             custom = ['--encoding', encoding]
 736         fast_export_from(source, destination, 'darcs', verbose, custom)
 737
 738
 739 class cmd_fast_export_from_hg(Command):
 740     """Generate a fast-import file from a Mercurial repository.
 741
 742     Destination is a dump file, typically named xxx.fi where xxx is
 743     the name of the project. If '-' is given, standard output is used.
 744
 745     Mercurial 1.2 or later must be installed as its libraries are used
 746     to access the source repository. Given the APIs currently used,
 747     the source repository must be a local file, not a network URL.
 748     """
 749     hidden = False
 750     _see_also = ['fast-import', 'fast-import-filter']
 751     takes_args = ['source', 'destination']
 752     takes_options = ['verbose']
 753     encoding_type = 'exact'
 754     def run(self, source, destination, verbose=False):
 755         load_fastimport()
 756         from bzrlib.plugins.fastimport.exporters import fast_export_from
 757         fast_export_from(source, destination, 'hg', verbose)
 758
 759
 760 class cmd_fast_export_from_git(Command):
 761     """Generate a fast-import file from a Git repository.
 762
 763     Destination is a dump file, typically named xxx.fi where xxx is
 764     the name of the project. If '-' is given, standard output is used.
 765
 766     Git 1.6 or later must be installed as the git fast-export
 767     subcommand is used under the covers to generate the stream.
 768     The source must be a local directory.
 769
 770     .. note::
 771
 772        Earlier versions of Git may also work fine but are
 773        likely to receive less active support if problems arise.
 774     """
 775     hidden = False
 776     _see_also = ['fast-import', 'fast-import-filter']
 777     takes_args = ['source', 'destination']
 778     takes_options = ['verbose']
 779     encoding_type = 'exact'
 780     def run(self, source, destination, verbose=False):
 781         load_fastimport()
 782         from bzrlib.plugins.fastimport.exporters import fast_export_from
 783         fast_export_from(source, destination, 'git', verbose)
 784
 785
 786 class cmd_fast_export_from_mtn(Command):
 787     """Generate a fast-import file from a Monotone repository.
 788
 789     Destination is a dump file, typically named xxx.fi where xxx is
 790     the name of the project. If '-' is given, standard output is used.
 791
 792     Monotone 0.43 or later must be installed as the mtn git_export
 793     subcommand is used under the covers to generate the stream.
 794     The source must be a local directory.
 795     """
 796     hidden = False
 797     _see_also = ['fast-import', 'fast-import-filter']
 798     takes_args = ['source', 'destination']
 799     takes_options = ['verbose']
 800     encoding_type = 'exact'
 801     def run(self, source, destination, verbose=False):
 802         load_fastimport()
 803         from bzrlib.plugins.fastimport.exporters import fast_export_from
 804         fast_export_from(source, destination, 'mtn', verbose)
 805
 806
 807 class cmd_fast_export_from_p4(Command):
 808     """Generate a fast-import file from a Perforce repository.
 809
 810     Source is a Perforce depot path, e.g., //depot/project
 811
 812     Destination is a dump file, typically named xxx.fi where xxx is
 813     the name of the project. If '-' is given, standard output is used.
 814
 815     bzrp4 must be installed as its p4_fast_export.py module is used under
 816     the covers to do the export.  bzrp4 can be downloaded from
 817     https://launchpad.net/bzrp4/.
 818
 819     The P4PORT environment variable must be set, and you must be logged
 820     into the Perforce server.
 821
 822     By default, only the HEAD changelist is exported.  To export all
 823     changelists, append '@all' to the source.  To export a revision range,
 824     append a comma-delimited pair of changelist numbers to the source,
 825     e.g., '100,200'.
 826     """
 827     hidden = False
 828     _see_also = ['fast-import', 'fast-import-filter']
 829     takes_args = ['source', 'destination']
 830     takes_options = []
 831     encoding_type = 'exact'
 832     def run(self, source, destination, verbose=False):
 833         load_fastimport()
 834         from bzrlib.plugins.fastimport.exporters import fast_export_from
 835         custom = []
 836         fast_export_from(source, destination, 'p4', verbose, custom)
 837
 838
 839 class cmd_fast_export_from_svn(Command):
 840     """Generate a fast-import file from a Subversion repository.
 841
 842     Destination is a dump file, typically named xxx.fi where xxx is
 843     the name of the project. If '-' is given, standard output is used.
 844
 845     Python-Subversion (Python bindings to the Subversion APIs)
 846     1.4 or later must be installed as this library is used to
 847     access the source repository. The source may be a network URL
 848     but using a local URL is recommended for performance reasons.
 849     """
 850     hidden = False
 851     _see_also = ['fast-import', 'fast-import-filter']
 852     takes_args = ['source', 'destination']
 853     takes_options = ['verbose',
 854                     Option('trunk-path', type=str, argname="STR",
 855                         help="Path in repo to /trunk.\n"
 856                               "May be `regex:/cvs/(trunk)/proj1/(.*)` in "
 857                               "which case the first group is used as the "
 858                               "branch name and the second group is used "
 859                               "to match files.",
 860                         ),
 861                     ]
 862     encoding_type = 'exact'
 863     def run(self, source, destination, verbose=False, trunk_path=None):
 864         load_fastimport()
 865         from bzrlib.plugins.fastimport.exporters import fast_export_from
 866         custom = []
 867         if trunk_path is not None:
 868             custom.extend(['--trunk-path', trunk_path])
 869         fast_export_from(source, destination, 'svn', verbose, custom)