~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/controldir.py

  • Committer: John Arbash Meinel
  • Date: 2005-09-29 21:13:03 UTC
  • mto: (1393.1.12)
  • mto: This revision was merged to the branch mainline in revision 1396.
  • Revision ID: john@arbash-meinel.com-20050929211303-7f1f9bf969d65dc3
All tests pass.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2010, 2011 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
 
 
17
 
"""ControlDir is the basic control directory class.
18
 
 
19
 
The ControlDir class is the base for the control directory used
20
 
by all bzr and foreign formats. For the ".bzr" implementation,
21
 
see bzrlib.bzrdir.BzrDir.
22
 
 
23
 
"""
24
 
 
25
 
from bzrlib.lazy_import import lazy_import
26
 
lazy_import(globals(), """
27
 
import textwrap
28
 
 
29
 
from bzrlib import (
30
 
    errors,
31
 
    revision as _mod_revision,
32
 
    transport as _mod_transport,
33
 
    ui,
34
 
    urlutils,
35
 
    )
36
 
from bzrlib.push import (
37
 
    PushResult,
38
 
    )
39
 
 
40
 
""")
41
 
 
42
 
from bzrlib import registry
43
 
 
44
 
 
45
 
class ControlComponent(object):
46
 
    """Abstract base class for control directory components.
47
 
 
48
 
    This provides interfaces that are common across controldirs,
49
 
    repositories, branches, and workingtree control directories.
50
 
 
51
 
    They all expose two urls and transports: the *user* URL is the
52
 
    one that stops above the control directory (eg .bzr) and that
53
 
    should normally be used in messages, and the *control* URL is
54
 
    under that in eg .bzr/checkout and is used to read the control
55
 
    files.
56
 
 
57
 
    This can be used as a mixin and is intended to fit with
58
 
    foreign formats.
59
 
    """
60
 
 
61
 
    @property
62
 
    def control_transport(self):
63
 
        raise NotImplementedError
64
 
 
65
 
    @property
66
 
    def control_url(self):
67
 
        return self.control_transport.base
68
 
 
69
 
    @property
70
 
    def user_transport(self):
71
 
        raise NotImplementedError
72
 
 
73
 
    @property
74
 
    def user_url(self):
75
 
        return self.user_transport.base
76
 
 
77
 
 
78
 
 
79
 
class ControlDir(ControlComponent):
80
 
    """A control directory.
81
 
 
82
 
    While this represents a generic control directory, there are a few
83
 
    features that are present in this interface that are currently only
84
 
    supported by one of its implementations, BzrDir.
85
 
 
86
 
    These features (bound branches, stacked branches) are currently only
87
 
    supported by Bazaar, but could be supported by other version control
88
 
    systems as well. Implementations are required to raise the appropriate
89
 
    exceptions when an operation is requested that is not supported.
90
 
 
91
 
    This also makes life easier for API users who can rely on the
92
 
    implementation always allowing a particular feature to be requested but
93
 
    raising an exception when it is not supported, rather than requiring the
94
 
    API users to check for magic attributes to see what features are supported.
95
 
    """
96
 
 
97
 
    def can_convert_format(self):
98
 
        """Return true if this controldir is one whose format we can convert
99
 
        from."""
100
 
        return True
101
 
 
102
 
    def list_branches(self):
103
 
        """Return a sequence of all branches local to this control directory.
104
 
 
105
 
        """
106
 
        try:
107
 
            return [self.open_branch()]
108
 
        except (errors.NotBranchError, errors.NoRepositoryPresent):
109
 
            return []
110
 
 
111
 
    def is_control_filename(self, filename):
112
 
        """True if filename is the name of a path which is reserved for
113
 
        controldirs.
114
 
 
115
 
        :param filename: A filename within the root transport of this
116
 
            controldir.
117
 
 
118
 
        This is true IF and ONLY IF the filename is part of the namespace reserved
119
 
        for bzr control dirs. Currently this is the '.bzr' directory in the root
120
 
        of the root_transport. it is expected that plugins will need to extend
121
 
        this in the future - for instance to make bzr talk with svn working
122
 
        trees.
123
 
        """
124
 
        raise NotImplementedError(self.is_control_filename)
125
 
 
126
 
    def needs_format_conversion(self, format=None):
127
 
        """Return true if this controldir needs convert_format run on it.
128
 
 
129
 
        For instance, if the repository format is out of date but the
130
 
        branch and working tree are not, this should return True.
131
 
 
132
 
        :param format: Optional parameter indicating a specific desired
133
 
                       format we plan to arrive at.
134
 
        """
135
 
        raise NotImplementedError(self.needs_format_conversion)
136
 
 
137
 
    def create_repository(self, shared=False):
138
 
        """Create a new repository in this control directory.
139
 
 
140
 
        :param shared: If a shared repository should be created
141
 
        :return: The newly created repository
142
 
        """
143
 
        raise NotImplementedError(self.create_repository)
144
 
 
145
 
    def destroy_repository(self):
146
 
        """Destroy the repository in this ControlDir."""
147
 
        raise NotImplementedError(self.destroy_repository)
148
 
 
149
 
    def create_branch(self, name=None, repository=None):
150
 
        """Create a branch in this ControlDir.
151
 
 
152
 
        :param name: Name of the colocated branch to create, None for
153
 
            the default branch.
154
 
 
155
 
        The controldirs format will control what branch format is created.
156
 
        For more control see BranchFormatXX.create(a_controldir).
157
 
        """
158
 
        raise NotImplementedError(self.create_branch)
159
 
 
160
 
    def destroy_branch(self, name=None):
161
 
        """Destroy a branch in this ControlDir.
162
 
 
163
 
        :param name: Name of the branch to destroy, None for the default 
164
 
            branch.
165
 
        """
166
 
        raise NotImplementedError(self.destroy_branch)
167
 
 
168
 
    def create_workingtree(self, revision_id=None, from_branch=None,
169
 
        accelerator_tree=None, hardlink=False):
170
 
        """Create a working tree at this ControlDir.
171
 
 
172
 
        :param revision_id: create it as of this revision id.
173
 
        :param from_branch: override controldir branch 
174
 
            (for lightweight checkouts)
175
 
        :param accelerator_tree: A tree which can be used for retrieving file
176
 
            contents more quickly than the revision tree, i.e. a workingtree.
177
 
            The revision tree will be used for cases where accelerator_tree's
178
 
            content is different.
179
 
        """
180
 
        raise NotImplementedError(self.create_workingtree)
181
 
 
182
 
    def destroy_workingtree(self):
183
 
        """Destroy the working tree at this ControlDir.
184
 
 
185
 
        Formats that do not support this may raise UnsupportedOperation.
186
 
        """
187
 
        raise NotImplementedError(self.destroy_workingtree)
188
 
 
189
 
    def destroy_workingtree_metadata(self):
190
 
        """Destroy the control files for the working tree at this ControlDir.
191
 
 
192
 
        The contents of working tree files are not affected.
193
 
        Formats that do not support this may raise UnsupportedOperation.
194
 
        """
195
 
        raise NotImplementedError(self.destroy_workingtree_metadata)
196
 
 
197
 
    def find_branch_format(self, name=None):
198
 
        """Find the branch 'format' for this bzrdir.
199
 
 
200
 
        This might be a synthetic object for e.g. RemoteBranch and SVN.
201
 
        """
202
 
        raise NotImplementedError(self.find_branch_format)
203
 
 
204
 
    def get_branch_reference(self, name=None):
205
 
        """Return the referenced URL for the branch in this controldir.
206
 
 
207
 
        :param name: Optional colocated branch name
208
 
        :raises NotBranchError: If there is no Branch.
209
 
        :raises NoColocatedBranchSupport: If a branch name was specified
210
 
            but colocated branches are not supported.
211
 
        :return: The URL the branch in this controldir references if it is a
212
 
            reference branch, or None for regular branches.
213
 
        """
214
 
        if name is not None:
215
 
            raise errors.NoColocatedBranchSupport(self)
216
 
        return None
217
 
 
218
 
    def open_branch(self, name=None, unsupported=False,
219
 
                    ignore_fallbacks=False):
220
 
        """Open the branch object at this ControlDir if one is present.
221
 
 
222
 
        If unsupported is True, then no longer supported branch formats can
223
 
        still be opened.
224
 
 
225
 
        TODO: static convenience version of this?
226
 
        """
227
 
        raise NotImplementedError(self.open_branch)
228
 
 
229
 
    def open_repository(self, _unsupported=False):
230
 
        """Open the repository object at this ControlDir if one is present.
231
 
 
232
 
        This will not follow the Branch object pointer - it's strictly a direct
233
 
        open facility. Most client code should use open_branch().repository to
234
 
        get at a repository.
235
 
 
236
 
        :param _unsupported: a private parameter, not part of the api.
237
 
 
238
 
        TODO: static convenience version of this?
239
 
        """
240
 
        raise NotImplementedError(self.open_repository)
241
 
 
242
 
    def find_repository(self):
243
 
        """Find the repository that should be used.
244
 
 
245
 
        This does not require a branch as we use it to find the repo for
246
 
        new branches as well as to hook existing branches up to their
247
 
        repository.
248
 
        """
249
 
        raise NotImplementedError(self.find_repository)
250
 
 
251
 
    def open_workingtree(self, _unsupported=False,
252
 
                         recommend_upgrade=True, from_branch=None):
253
 
        """Open the workingtree object at this ControlDir if one is present.
254
 
 
255
 
        :param recommend_upgrade: Optional keyword parameter, when True (the
256
 
            default), emit through the ui module a recommendation that the user
257
 
            upgrade the working tree when the workingtree being opened is old
258
 
            (but still fully supported).
259
 
        :param from_branch: override controldir branch (for lightweight
260
 
            checkouts)
261
 
        """
262
 
        raise NotImplementedError(self.open_workingtree)
263
 
 
264
 
    def has_branch(self, name=None):
265
 
        """Tell if this controldir contains a branch.
266
 
 
267
 
        Note: if you're going to open the branch, you should just go ahead
268
 
        and try, and not ask permission first.  (This method just opens the
269
 
        branch and discards it, and that's somewhat expensive.)
270
 
        """
271
 
        try:
272
 
            self.open_branch(name)
273
 
            return True
274
 
        except errors.NotBranchError:
275
 
            return False
276
 
 
277
 
    def _get_selected_branch(self):
278
 
        """Return the name of the branch selected by the user.
279
 
 
280
 
        :return: Name of the branch selected by the user, or None.
281
 
        """
282
 
        branch = self.root_transport.get_segment_parameters().get("branch")
283
 
        if branch is not None:
284
 
            branch = urlutils.unescape(branch)
285
 
        return branch
286
 
 
287
 
    def has_workingtree(self):
288
 
        """Tell if this controldir contains a working tree.
289
 
 
290
 
        This will still raise an exception if the controldir has a workingtree
291
 
        that is remote & inaccessible.
292
 
 
293
 
        Note: if you're going to open the working tree, you should just go ahead
294
 
        and try, and not ask permission first.  (This method just opens the
295
 
        workingtree and discards it, and that's somewhat expensive.)
296
 
        """
297
 
        try:
298
 
            self.open_workingtree(recommend_upgrade=False)
299
 
            return True
300
 
        except errors.NoWorkingTree:
301
 
            return False
302
 
 
303
 
    def cloning_metadir(self, require_stacking=False):
304
 
        """Produce a metadir suitable for cloning or sprouting with.
305
 
 
306
 
        These operations may produce workingtrees (yes, even though they're
307
 
        "cloning" something that doesn't have a tree), so a viable workingtree
308
 
        format must be selected.
309
 
 
310
 
        :require_stacking: If True, non-stackable formats will be upgraded
311
 
            to similar stackable formats.
312
 
        :returns: a ControlDirFormat with all component formats either set
313
 
            appropriately or set to None if that component should not be
314
 
            created.
315
 
        """
316
 
        raise NotImplementedError(self.cloning_metadir)
317
 
 
318
 
    def checkout_metadir(self):
319
 
        """Produce a metadir suitable for checkouts of this controldir."""
320
 
        return self.cloning_metadir()
321
 
 
322
 
    def sprout(self, url, revision_id=None, force_new_repo=False,
323
 
               recurse='down', possible_transports=None,
324
 
               accelerator_tree=None, hardlink=False, stacked=False,
325
 
               source_branch=None, create_tree_if_local=True):
326
 
        """Create a copy of this controldir prepared for use as a new line of
327
 
        development.
328
 
 
329
 
        If url's last component does not exist, it will be created.
330
 
 
331
 
        Attributes related to the identity of the source branch like
332
 
        branch nickname will be cleaned, a working tree is created
333
 
        whether one existed before or not; and a local branch is always
334
 
        created.
335
 
 
336
 
        :param revision_id: if revision_id is not None, then the clone
337
 
            operation may tune itself to download less data.
338
 
        :param accelerator_tree: A tree which can be used for retrieving file
339
 
            contents more quickly than the revision tree, i.e. a workingtree.
340
 
            The revision tree will be used for cases where accelerator_tree's
341
 
            content is different.
342
 
        :param hardlink: If true, hard-link files from accelerator_tree,
343
 
            where possible.
344
 
        :param stacked: If true, create a stacked branch referring to the
345
 
            location of this control directory.
346
 
        :param create_tree_if_local: If true, a working-tree will be created
347
 
            when working locally.
348
 
        """
349
 
        raise NotImplementedError(self.sprout)
350
 
 
351
 
    def push_branch(self, source, revision_id=None, overwrite=False, 
352
 
        remember=False, create_prefix=False):
353
 
        """Push the source branch into this ControlDir."""
354
 
        br_to = None
355
 
        # If we can open a branch, use its direct repository, otherwise see
356
 
        # if there is a repository without a branch.
357
 
        try:
358
 
            br_to = self.open_branch()
359
 
        except errors.NotBranchError:
360
 
            # Didn't find a branch, can we find a repository?
361
 
            repository_to = self.find_repository()
362
 
        else:
363
 
            # Found a branch, so we must have found a repository
364
 
            repository_to = br_to.repository
365
 
 
366
 
        push_result = PushResult()
367
 
        push_result.source_branch = source
368
 
        if br_to is None:
369
 
            # We have a repository but no branch, copy the revisions, and then
370
 
            # create a branch.
371
 
            if revision_id is None:
372
 
                # No revision supplied by the user, default to the branch
373
 
                # revision
374
 
                revision_id = source.last_revision()
375
 
            repository_to.fetch(source.repository, revision_id=revision_id)
376
 
            br_to = source.clone(self, revision_id=revision_id)
377
 
            if source.get_push_location() is None or remember:
378
 
                source.set_push_location(br_to.base)
379
 
            push_result.stacked_on = None
380
 
            push_result.branch_push_result = None
381
 
            push_result.old_revno = None
382
 
            push_result.old_revid = _mod_revision.NULL_REVISION
383
 
            push_result.target_branch = br_to
384
 
            push_result.master_branch = None
385
 
            push_result.workingtree_updated = False
386
 
        else:
387
 
            # We have successfully opened the branch, remember if necessary:
388
 
            if source.get_push_location() is None or remember:
389
 
                source.set_push_location(br_to.base)
390
 
            try:
391
 
                tree_to = self.open_workingtree()
392
 
            except errors.NotLocalUrl:
393
 
                push_result.branch_push_result = source.push(br_to, 
394
 
                    overwrite, stop_revision=revision_id)
395
 
                push_result.workingtree_updated = False
396
 
            except errors.NoWorkingTree:
397
 
                push_result.branch_push_result = source.push(br_to,
398
 
                    overwrite, stop_revision=revision_id)
399
 
                push_result.workingtree_updated = None # Not applicable
400
 
            else:
401
 
                tree_to.lock_write()
402
 
                try:
403
 
                    push_result.branch_push_result = source.push(
404
 
                        tree_to.branch, overwrite, stop_revision=revision_id)
405
 
                    tree_to.update()
406
 
                finally:
407
 
                    tree_to.unlock()
408
 
                push_result.workingtree_updated = True
409
 
            push_result.old_revno = push_result.branch_push_result.old_revno
410
 
            push_result.old_revid = push_result.branch_push_result.old_revid
411
 
            push_result.target_branch = \
412
 
                push_result.branch_push_result.target_branch
413
 
        return push_result
414
 
 
415
 
    def _get_tree_branch(self, name=None):
416
 
        """Return the branch and tree, if any, for this bzrdir.
417
 
 
418
 
        :param name: Name of colocated branch to open.
419
 
 
420
 
        Return None for tree if not present or inaccessible.
421
 
        Raise NotBranchError if no branch is present.
422
 
        :return: (tree, branch)
423
 
        """
424
 
        try:
425
 
            tree = self.open_workingtree()
426
 
        except (errors.NoWorkingTree, errors.NotLocalUrl):
427
 
            tree = None
428
 
            branch = self.open_branch(name=name)
429
 
        else:
430
 
            if name is not None:
431
 
                branch = self.open_branch(name=name)
432
 
            else:
433
 
                branch = tree.branch
434
 
        return tree, branch
435
 
 
436
 
    def get_config(self):
437
 
        """Get configuration for this ControlDir."""
438
 
        raise NotImplementedError(self.get_config)
439
 
 
440
 
    def check_conversion_target(self, target_format):
441
 
        """Check that a bzrdir as a whole can be converted to a new format."""
442
 
        raise NotImplementedError(self.check_conversion_target)
443
 
 
444
 
    def clone(self, url, revision_id=None, force_new_repo=False,
445
 
              preserve_stacking=False):
446
 
        """Clone this bzrdir and its contents to url verbatim.
447
 
 
448
 
        :param url: The url create the clone at.  If url's last component does
449
 
            not exist, it will be created.
450
 
        :param revision_id: The tip revision-id to use for any branch or
451
 
            working tree.  If not None, then the clone operation may tune
452
 
            itself to download less data.
453
 
        :param force_new_repo: Do not use a shared repository for the target
454
 
                               even if one is available.
455
 
        :param preserve_stacking: When cloning a stacked branch, stack the
456
 
            new branch on top of the other branch's stacked-on branch.
457
 
        """
458
 
        return self.clone_on_transport(_mod_transport.get_transport(url),
459
 
                                       revision_id=revision_id,
460
 
                                       force_new_repo=force_new_repo,
461
 
                                       preserve_stacking=preserve_stacking)
462
 
 
463
 
    def clone_on_transport(self, transport, revision_id=None,
464
 
        force_new_repo=False, preserve_stacking=False, stacked_on=None,
465
 
        create_prefix=False, use_existing_dir=True, no_tree=False):
466
 
        """Clone this bzrdir and its contents to transport verbatim.
467
 
 
468
 
        :param transport: The transport for the location to produce the clone
469
 
            at.  If the target directory does not exist, it will be created.
470
 
        :param revision_id: The tip revision-id to use for any branch or
471
 
            working tree.  If not None, then the clone operation may tune
472
 
            itself to download less data.
473
 
        :param force_new_repo: Do not use a shared repository for the target,
474
 
                               even if one is available.
475
 
        :param preserve_stacking: When cloning a stacked branch, stack the
476
 
            new branch on top of the other branch's stacked-on branch.
477
 
        :param create_prefix: Create any missing directories leading up to
478
 
            to_transport.
479
 
        :param use_existing_dir: Use an existing directory if one exists.
480
 
        :param no_tree: If set to true prevents creation of a working tree.
481
 
        """
482
 
        raise NotImplementedError(self.clone_on_transport)
483
 
 
484
 
 
485
 
class ControlComponentFormat(object):
486
 
    """A component that can live inside of a .bzr meta directory."""
487
 
 
488
 
    upgrade_recommended = False
489
 
 
490
 
    def get_format_string(self):
491
 
        """Return the format of this format, if usable in meta directories."""
492
 
        raise NotImplementedError(self.get_format_string)
493
 
 
494
 
    def get_format_description(self):
495
 
        """Return the short description for this format."""
496
 
        raise NotImplementedError(self.get_format_description)
497
 
 
498
 
    def is_supported(self):
499
 
        """Is this format supported?
500
 
 
501
 
        Supported formats must be initializable and openable.
502
 
        Unsupported formats may not support initialization or committing or
503
 
        some other features depending on the reason for not being supported.
504
 
        """
505
 
        return True
506
 
 
507
 
    def check_support_status(self, allow_unsupported, recommend_upgrade=True,
508
 
        basedir=None):
509
 
        """Give an error or warning on old formats.
510
 
 
511
 
        :param allow_unsupported: If true, allow opening
512
 
            formats that are strongly deprecated, and which may
513
 
            have limited functionality.
514
 
 
515
 
        :param recommend_upgrade: If true (default), warn
516
 
            the user through the ui object that they may wish
517
 
            to upgrade the object.
518
 
        """
519
 
        if not allow_unsupported and not self.is_supported():
520
 
            # see open_downlevel to open legacy branches.
521
 
            raise errors.UnsupportedFormatError(format=self)
522
 
        if recommend_upgrade and self.upgrade_recommended:
523
 
            ui.ui_factory.recommend_upgrade(
524
 
                self.get_format_description(), basedir)
525
 
 
526
 
 
527
 
class ControlComponentFormatRegistry(registry.FormatRegistry):
528
 
    """A registry for control components (branch, workingtree, repository)."""
529
 
 
530
 
    def __init__(self, other_registry=None):
531
 
        super(ControlComponentFormatRegistry, self).__init__(other_registry)
532
 
        self._extra_formats = []
533
 
 
534
 
    def register(self, format):
535
 
        """Register a new format."""
536
 
        super(ControlComponentFormatRegistry, self).register(
537
 
            format.get_format_string(), format)
538
 
 
539
 
    def remove(self, format):
540
 
        """Remove a registered format."""
541
 
        super(ControlComponentFormatRegistry, self).remove(
542
 
            format.get_format_string())
543
 
 
544
 
    def register_extra(self, format):
545
 
        """Register a format that can not be used in a metadir.
546
 
 
547
 
        This is mainly useful to allow custom repository formats, such as older
548
 
        Bazaar formats and foreign formats, to be tested.
549
 
        """
550
 
        self._extra_formats.append(registry._ObjectGetter(format))
551
 
 
552
 
    def remove_extra(self, format):
553
 
        """Remove an extra format.
554
 
        """
555
 
        self._extra_formats.remove(registry._ObjectGetter(format))
556
 
 
557
 
    def register_extra_lazy(self, module_name, member_name):
558
 
        """Register a format lazily.
559
 
        """
560
 
        self._extra_formats.append(
561
 
            registry._LazyObjectGetter(module_name, member_name))
562
 
 
563
 
    def _get_extra(self):
564
 
        """Return all "extra" formats, not usable in meta directories."""
565
 
        result = []
566
 
        for getter in self._extra_formats:
567
 
            f = getter.get_obj()
568
 
            if callable(f):
569
 
                f = f()
570
 
            result.append(f)
571
 
        return result
572
 
 
573
 
    def _get_all(self):
574
 
        """Return all formats, even those not usable in metadirs.
575
 
        """
576
 
        result = []
577
 
        for name in self.keys():
578
 
            fmt = self.get(name)
579
 
            if callable(fmt):
580
 
                fmt = fmt()
581
 
            result.append(fmt)
582
 
        return result + self._get_extra()
583
 
 
584
 
    def _get_all_modules(self):
585
 
        """Return a set of the modules providing objects."""
586
 
        modules = set()
587
 
        for name in self.keys():
588
 
            modules.add(self._get_module(name))
589
 
        for getter in self._extra_formats:
590
 
            modules.add(getter.get_module())
591
 
        return modules
592
 
 
593
 
 
594
 
class Converter(object):
595
 
    """Converts a disk format object from one format to another."""
596
 
 
597
 
    def convert(self, to_convert, pb):
598
 
        """Perform the conversion of to_convert, giving feedback via pb.
599
 
 
600
 
        :param to_convert: The disk object to convert.
601
 
        :param pb: a progress bar to use for progress information.
602
 
        """
603
 
 
604
 
    def step(self, message):
605
 
        """Update the pb by a step."""
606
 
        self.count +=1
607
 
        self.pb.update(message, self.count, self.total)
608
 
 
609
 
 
610
 
class ControlDirFormat(object):
611
 
    """An encapsulation of the initialization and open routines for a format.
612
 
 
613
 
    Formats provide three things:
614
 
     * An initialization routine,
615
 
     * a format string,
616
 
     * an open routine.
617
 
 
618
 
    Formats are placed in a dict by their format string for reference
619
 
    during controldir opening. These should be subclasses of ControlDirFormat
620
 
    for consistency.
621
 
 
622
 
    Once a format is deprecated, just deprecate the initialize and open
623
 
    methods on the format class. Do not deprecate the object, as the
624
 
    object will be created every system load.
625
 
 
626
 
    :cvar colocated_branches: Whether this formats supports colocated branches.
627
 
    :cvar supports_workingtrees: This control directory can co-exist with a
628
 
        working tree.
629
 
    """
630
 
 
631
 
    _default_format = None
632
 
    """The default format used for new control directories."""
633
 
 
634
 
    _server_probers = []
635
 
    """The registered server format probers, e.g. RemoteBzrProber.
636
 
 
637
 
    This is a list of Prober-derived classes.
638
 
    """
639
 
 
640
 
    _probers = []
641
 
    """The registered format probers, e.g. BzrProber.
642
 
 
643
 
    This is a list of Prober-derived classes.
644
 
    """
645
 
 
646
 
    colocated_branches = False
647
 
    """Whether co-located branches are supported for this control dir format.
648
 
    """
649
 
 
650
 
    supports_workingtrees = True
651
 
    """Whether working trees can exist in control directories of this format.
652
 
    """
653
 
 
654
 
    fixed_components = False
655
 
    """Whether components can not change format independent of the control dir.
656
 
    """
657
 
 
658
 
    upgrade_recommended = False
659
 
    """Whether an upgrade from this format is recommended."""
660
 
 
661
 
    def get_format_description(self):
662
 
        """Return the short description for this format."""
663
 
        raise NotImplementedError(self.get_format_description)
664
 
 
665
 
    def get_converter(self, format=None):
666
 
        """Return the converter to use to convert controldirs needing converts.
667
 
 
668
 
        This returns a bzrlib.controldir.Converter object.
669
 
 
670
 
        This should return the best upgrader to step this format towards the
671
 
        current default format. In the case of plugins we can/should provide
672
 
        some means for them to extend the range of returnable converters.
673
 
 
674
 
        :param format: Optional format to override the default format of the
675
 
                       library.
676
 
        """
677
 
        raise NotImplementedError(self.get_converter)
678
 
 
679
 
    def is_supported(self):
680
 
        """Is this format supported?
681
 
 
682
 
        Supported formats must be initializable and openable.
683
 
        Unsupported formats may not support initialization or committing or
684
 
        some other features depending on the reason for not being supported.
685
 
        """
686
 
        return True
687
 
 
688
 
    def check_support_status(self, allow_unsupported, recommend_upgrade=True,
689
 
        basedir=None):
690
 
        """Give an error or warning on old formats.
691
 
 
692
 
        :param allow_unsupported: If true, allow opening
693
 
            formats that are strongly deprecated, and which may
694
 
            have limited functionality.
695
 
 
696
 
        :param recommend_upgrade: If true (default), warn
697
 
            the user through the ui object that they may wish
698
 
            to upgrade the object.
699
 
        """
700
 
        if not allow_unsupported and not self.is_supported():
701
 
            # see open_downlevel to open legacy branches.
702
 
            raise errors.UnsupportedFormatError(format=self)
703
 
        if recommend_upgrade and self.upgrade_recommended:
704
 
            ui.ui_factory.recommend_upgrade(
705
 
                self.get_format_description(), basedir)
706
 
 
707
 
    def same_model(self, target_format):
708
 
        return (self.repository_format.rich_root_data ==
709
 
            target_format.rich_root_data)
710
 
 
711
 
    @classmethod
712
 
    def register_format(klass, format):
713
 
        """Register a format that does not use '.bzr' for its control dir.
714
 
 
715
 
        """
716
 
        raise errors.BzrError("ControlDirFormat.register_format() has been "
717
 
            "removed in Bazaar 2.4. Please upgrade your plugins.")
718
 
 
719
 
    @classmethod
720
 
    def register_prober(klass, prober):
721
 
        """Register a prober that can look for a control dir.
722
 
 
723
 
        """
724
 
        klass._probers.append(prober)
725
 
 
726
 
    @classmethod
727
 
    def unregister_prober(klass, prober):
728
 
        """Unregister a prober.
729
 
 
730
 
        """
731
 
        klass._probers.remove(prober)
732
 
 
733
 
    @classmethod
734
 
    def register_server_prober(klass, prober):
735
 
        """Register a control format prober for client-server environments.
736
 
 
737
 
        These probers will be used before ones registered with
738
 
        register_prober.  This gives implementations that decide to the
739
 
        chance to grab it before anything looks at the contents of the format
740
 
        file.
741
 
        """
742
 
        klass._server_probers.append(prober)
743
 
 
744
 
    def __str__(self):
745
 
        # Trim the newline
746
 
        return self.get_format_description().rstrip()
747
 
 
748
 
    @classmethod
749
 
    def known_formats(klass):
750
 
        """Return all the known formats.
751
 
        """
752
 
        result = set()
753
 
        for prober_kls in klass._probers + klass._server_probers:
754
 
            result.update(prober_kls.known_formats())
755
 
        return result
756
 
 
757
 
    @classmethod
758
 
    def find_format(klass, transport, _server_formats=True):
759
 
        """Return the format present at transport."""
760
 
        if _server_formats:
761
 
            _probers = klass._server_probers + klass._probers
762
 
        else:
763
 
            _probers = klass._probers
764
 
        for prober_kls in _probers:
765
 
            prober = prober_kls()
766
 
            try:
767
 
                return prober.probe_transport(transport)
768
 
            except errors.NotBranchError:
769
 
                # this format does not find a control dir here.
770
 
                pass
771
 
        raise errors.NotBranchError(path=transport.base)
772
 
 
773
 
    def initialize(self, url, possible_transports=None):
774
 
        """Create a control dir at this url and return an opened copy.
775
 
 
776
 
        While not deprecated, this method is very specific and its use will
777
 
        lead to many round trips to setup a working environment. See
778
 
        initialize_on_transport_ex for a [nearly] all-in-one method.
779
 
 
780
 
        Subclasses should typically override initialize_on_transport
781
 
        instead of this method.
782
 
        """
783
 
        return self.initialize_on_transport(
784
 
            _mod_transport.get_transport(url, possible_transports))
785
 
 
786
 
    def initialize_on_transport(self, transport):
787
 
        """Initialize a new controldir in the base directory of a Transport."""
788
 
        raise NotImplementedError(self.initialize_on_transport)
789
 
 
790
 
    def initialize_on_transport_ex(self, transport, use_existing_dir=False,
791
 
        create_prefix=False, force_new_repo=False, stacked_on=None,
792
 
        stack_on_pwd=None, repo_format_name=None, make_working_trees=None,
793
 
        shared_repo=False, vfs_only=False):
794
 
        """Create this format on transport.
795
 
 
796
 
        The directory to initialize will be created.
797
 
 
798
 
        :param force_new_repo: Do not use a shared repository for the target,
799
 
                               even if one is available.
800
 
        :param create_prefix: Create any missing directories leading up to
801
 
            to_transport.
802
 
        :param use_existing_dir: Use an existing directory if one exists.
803
 
        :param stacked_on: A url to stack any created branch on, None to follow
804
 
            any target stacking policy.
805
 
        :param stack_on_pwd: If stack_on is relative, the location it is
806
 
            relative to.
807
 
        :param repo_format_name: If non-None, a repository will be
808
 
            made-or-found. Should none be found, or if force_new_repo is True
809
 
            the repo_format_name is used to select the format of repository to
810
 
            create.
811
 
        :param make_working_trees: Control the setting of make_working_trees
812
 
            for a new shared repository when one is made. None to use whatever
813
 
            default the format has.
814
 
        :param shared_repo: Control whether made repositories are shared or
815
 
            not.
816
 
        :param vfs_only: If True do not attempt to use a smart server
817
 
        :return: repo, controldir, require_stacking, repository_policy. repo is
818
 
            None if none was created or found, controldir is always valid.
819
 
            require_stacking is the result of examining the stacked_on
820
 
            parameter and any stacking policy found for the target.
821
 
        """
822
 
        raise NotImplementedError(self.initialize_on_transport_ex)
823
 
 
824
 
    def network_name(self):
825
 
        """A simple byte string uniquely identifying this format for RPC calls.
826
 
 
827
 
        Bzr control formats use this disk format string to identify the format
828
 
        over the wire. Its possible that other control formats have more
829
 
        complex detection requirements, so we permit them to use any unique and
830
 
        immutable string they desire.
831
 
        """
832
 
        raise NotImplementedError(self.network_name)
833
 
 
834
 
    def open(self, transport, _found=False):
835
 
        """Return an instance of this format for the dir transport points at.
836
 
        """
837
 
        raise NotImplementedError(self.open)
838
 
 
839
 
    @classmethod
840
 
    def _set_default_format(klass, format):
841
 
        """Set default format (for testing behavior of defaults only)"""
842
 
        klass._default_format = format
843
 
 
844
 
    @classmethod
845
 
    def get_default_format(klass):
846
 
        """Return the current default format."""
847
 
        return klass._default_format
848
 
 
849
 
 
850
 
class Prober(object):
851
 
    """Abstract class that can be used to detect a particular kind of
852
 
    control directory.
853
 
 
854
 
    At the moment this just contains a single method to probe a particular
855
 
    transport, but it may be extended in the future to e.g. avoid
856
 
    multiple levels of probing for Subversion repositories.
857
 
 
858
 
    See BzrProber and RemoteBzrProber in bzrlib.bzrdir for the
859
 
    probers that detect .bzr/ directories and Bazaar smart servers,
860
 
    respectively.
861
 
 
862
 
    Probers should be registered using the register_server_prober or
863
 
    register_prober methods on ControlDirFormat.
864
 
    """
865
 
 
866
 
    def probe_transport(self, transport):
867
 
        """Return the controldir style format present in a directory.
868
 
 
869
 
        :raise UnknownFormatError: If a control dir was found but is
870
 
            in an unknown format.
871
 
        :raise NotBranchError: If no control directory was found.
872
 
        :return: A ControlDirFormat instance.
873
 
        """
874
 
        raise NotImplementedError(self.probe_transport)
875
 
 
876
 
    @classmethod
877
 
    def known_formats(cls):
878
 
        """Return the control dir formats known by this prober.
879
 
 
880
 
        Multiple probers can return the same formats, so this should
881
 
        return a set.
882
 
 
883
 
        :return: A set of known formats.
884
 
        """
885
 
        raise NotImplementedError(cls.known_formats)
886
 
 
887
 
 
888
 
class ControlDirFormatInfo(object):
889
 
 
890
 
    def __init__(self, native, deprecated, hidden, experimental):
891
 
        self.deprecated = deprecated
892
 
        self.native = native
893
 
        self.hidden = hidden
894
 
        self.experimental = experimental
895
 
 
896
 
 
897
 
class ControlDirFormatRegistry(registry.Registry):
898
 
    """Registry of user-selectable ControlDir subformats.
899
 
 
900
 
    Differs from ControlDirFormat._formats in that it provides sub-formats,
901
 
    e.g. BzrDirMeta1 with weave repository.  Also, it's more user-oriented.
902
 
    """
903
 
 
904
 
    def __init__(self):
905
 
        """Create a ControlDirFormatRegistry."""
906
 
        self._aliases = set()
907
 
        self._registration_order = list()
908
 
        super(ControlDirFormatRegistry, self).__init__()
909
 
 
910
 
    def aliases(self):
911
 
        """Return a set of the format names which are aliases."""
912
 
        return frozenset(self._aliases)
913
 
 
914
 
    def register(self, key, factory, help, native=True, deprecated=False,
915
 
                 hidden=False, experimental=False, alias=False):
916
 
        """Register a ControlDirFormat factory.
917
 
 
918
 
        The factory must be a callable that takes one parameter: the key.
919
 
        It must produce an instance of the ControlDirFormat when called.
920
 
 
921
 
        This function mainly exists to prevent the info object from being
922
 
        supplied directly.
923
 
        """
924
 
        registry.Registry.register(self, key, factory, help,
925
 
            ControlDirFormatInfo(native, deprecated, hidden, experimental))
926
 
        if alias:
927
 
            self._aliases.add(key)
928
 
        self._registration_order.append(key)
929
 
 
930
 
    def register_lazy(self, key, module_name, member_name, help, native=True,
931
 
        deprecated=False, hidden=False, experimental=False, alias=False):
932
 
        registry.Registry.register_lazy(self, key, module_name, member_name,
933
 
            help, ControlDirFormatInfo(native, deprecated, hidden, experimental))
934
 
        if alias:
935
 
            self._aliases.add(key)
936
 
        self._registration_order.append(key)
937
 
 
938
 
    def set_default(self, key):
939
 
        """Set the 'default' key to be a clone of the supplied key.
940
 
 
941
 
        This method must be called once and only once.
942
 
        """
943
 
        registry.Registry.register(self, 'default', self.get(key),
944
 
            self.get_help(key), info=self.get_info(key))
945
 
        self._aliases.add('default')
946
 
 
947
 
    def set_default_repository(self, key):
948
 
        """Set the FormatRegistry default and Repository default.
949
 
 
950
 
        This is a transitional method while Repository.set_default_format
951
 
        is deprecated.
952
 
        """
953
 
        if 'default' in self:
954
 
            self.remove('default')
955
 
        self.set_default(key)
956
 
        format = self.get('default')()
957
 
 
958
 
    def make_bzrdir(self, key):
959
 
        return self.get(key)()
960
 
 
961
 
    def help_topic(self, topic):
962
 
        output = ""
963
 
        default_realkey = None
964
 
        default_help = self.get_help('default')
965
 
        help_pairs = []
966
 
        for key in self._registration_order:
967
 
            if key == 'default':
968
 
                continue
969
 
            help = self.get_help(key)
970
 
            if help == default_help:
971
 
                default_realkey = key
972
 
            else:
973
 
                help_pairs.append((key, help))
974
 
 
975
 
        def wrapped(key, help, info):
976
 
            if info.native:
977
 
                help = '(native) ' + help
978
 
            return ':%s:\n%s\n\n' % (key,
979
 
                textwrap.fill(help, initial_indent='    ',
980
 
                    subsequent_indent='    ',
981
 
                    break_long_words=False))
982
 
        if default_realkey is not None:
983
 
            output += wrapped(default_realkey, '(default) %s' % default_help,
984
 
                              self.get_info('default'))
985
 
        deprecated_pairs = []
986
 
        experimental_pairs = []
987
 
        for key, help in help_pairs:
988
 
            info = self.get_info(key)
989
 
            if info.hidden:
990
 
                continue
991
 
            elif info.deprecated:
992
 
                deprecated_pairs.append((key, help))
993
 
            elif info.experimental:
994
 
                experimental_pairs.append((key, help))
995
 
            else:
996
 
                output += wrapped(key, help, info)
997
 
        output += "\nSee :doc:`formats-help` for more about storage formats."
998
 
        other_output = ""
999
 
        if len(experimental_pairs) > 0:
1000
 
            other_output += "Experimental formats are shown below.\n\n"
1001
 
            for key, help in experimental_pairs:
1002
 
                info = self.get_info(key)
1003
 
                other_output += wrapped(key, help, info)
1004
 
        else:
1005
 
            other_output += \
1006
 
                "No experimental formats are available.\n\n"
1007
 
        if len(deprecated_pairs) > 0:
1008
 
            other_output += "\nDeprecated formats are shown below.\n\n"
1009
 
            for key, help in deprecated_pairs:
1010
 
                info = self.get_info(key)
1011
 
                other_output += wrapped(key, help, info)
1012
 
        else:
1013
 
            other_output += \
1014
 
                "\nNo deprecated formats are available.\n\n"
1015
 
        other_output += \
1016
 
                "\nSee :doc:`formats-help` for more about storage formats."
1017
 
 
1018
 
        if topic == 'other-formats':
1019
 
            return other_output
1020
 
        else:
1021
 
            return output
1022
 
 
1023
 
 
1024
 
# Please register new formats after old formats so that formats
1025
 
# appear in chronological order and format descriptions can build
1026
 
# on previous ones.
1027
 
format_registry = ControlDirFormatRegistry()
1028
 
 
1029
 
network_format_registry = registry.FormatRegistry()
1030
 
"""Registry of formats indexed by their network name.
1031
 
 
1032
 
The network name for a ControlDirFormat is an identifier that can be used when
1033
 
referring to formats with smart server operations. See
1034
 
ControlDirFormat.network_name() for more detail.
1035
 
"""