← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/branch.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-08-20 05:20:56 UTC
  • mfrom: (5380.3.3 doc)
  • Revision ID: pqm@pqm.ubuntu.com-20100820052056-gwad7dz2otckrjax
(mbp) Start whatsnew for 2.3; update ppa developer docs (Martin Pool)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/branch.py
1
 
# Copyright (C) 2005, 2006, 2007, 2008, 2009 Canonical Ltd
 
1
# Copyright (C) 2005-2010 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
29
29
        errors,
30
30
        lockdir,
31
31
        lockable_files,
 
32
        remote,
32
33
        repository,
33
34
        revision as _mod_revision,
34
35
        rio,
46
47
    )
47
48
""")
48
49
 
49
 
from bzrlib.decorators import needs_read_lock, needs_write_lock
 
50
from bzrlib.decorators import needs_read_lock, needs_write_lock, only_raises
50
51
from bzrlib.hooks import HookPoint, Hooks
51
52
from bzrlib.inter import InterObject
 
53
from bzrlib.lock import _RelockDebugMixin, LogicalLockResult
52
54
from bzrlib import registry
53
55
from bzrlib.symbol_versioning import (
54
56
    deprecated_in,
62
64
BZR_BRANCH_FORMAT_6 = "Bazaar Branch Format 6 (bzr 0.15)\n"
63
65
 
64
66
 
65
 
# TODO: Maybe include checks for common corruption of newlines, etc?
66
 
 
67
 
# TODO: Some operations like log might retrieve the same revisions
68
 
# repeatedly to calculate deltas.  We could perhaps have a weakref
69
 
# cache in memory to make this faster.  In general anything can be
70
 
# cached in memory between lock and unlock operations. .. nb thats
71
 
# what the transaction identity map provides
72
 
 
73
 
 
74
 
######################################################################
75
 
# branch objects
76
 
 
77
 
class Branch(object):
 
67
class Branch(bzrdir.ControlComponent):
78
68
    """Branch holding a history of revisions.
79
69
 
80
 
    base
81
 
        Base directory/url of the branch.
 
70
    :ivar base:
 
71
        Base directory/url of the branch; using control_url and
 
72
        control_transport is more standardized.
82
73
 
83
74
    hooks: An instance of BranchHooks.
84
75
    """
86
77
    # - RBC 20060112
87
78
    base = None
88
79
 
 
80
    @property
 
81
    def control_transport(self):
 
82
        return self._transport
 
83
 
 
84
    @property
 
85
    def user_transport(self):
 
86
        return self.bzrdir.user_transport
 
87
 
89
88
    def __init__(self, *ignored, **ignored_too):
90
89
        self.tags = self._format.make_tags(self)
91
90
        self._revision_history_cache = None
106
105
        """Activate the branch/repository from url as a fallback repository."""
107
106
        repo = self._get_fallback_repository(url)
108
107
        if repo.has_same_location(self.repository):
109
 
            raise errors.UnstackableLocationError(self.base, url)
 
108
            raise errors.UnstackableLocationError(self.user_url, url)
110
109
        self.repository.add_fallback_repository(repo)
111
110
 
112
111
    def break_lock(self):
166
165
        """
167
166
        control = bzrdir.BzrDir.open(base, _unsupported,
168
167
                                     possible_transports=possible_transports)
169
 
        return control.open_branch(_unsupported)
 
168
        return control.open_branch(unsupported=_unsupported)
170
169
 
171
170
    @staticmethod
172
 
    def open_from_transport(transport, _unsupported=False):
 
171
    def open_from_transport(transport, name=None, _unsupported=False):
173
172
        """Open the branch rooted at transport"""
174
173
        control = bzrdir.BzrDir.open_from_transport(transport, _unsupported)
175
 
        return control.open_branch(_unsupported)
 
174
        return control.open_branch(name=name, unsupported=_unsupported)
176
175
 
177
176
    @staticmethod
178
177
    def open_containing(url, possible_transports=None):
199
198
        return self.supports_tags() and self.tags.get_tag_dict()
200
199
 
201
200
    def get_config(self):
 
201
        """Get a bzrlib.config.BranchConfig for this Branch.
 
202
 
 
203
        This can then be used to get and set configuration options for the
 
204
        branch.
 
205
 
 
206
        :return: A bzrlib.config.BranchConfig.
 
207
        """
202
208
        return BranchConfig(self)
203
209
 
204
210
    def _get_config(self):
216
222
    def _get_fallback_repository(self, url):
217
223
        """Get the repository we fallback to at url."""
218
224
        url = urlutils.join(self.base, url)
219
 
        a_bzrdir = bzrdir.BzrDir.open(url,
 
225
        a_branch = Branch.open(url,
220
226
            possible_transports=[self.bzrdir.root_transport])
221
 
        return a_bzrdir.open_branch().repository
 
227
        return a_branch.repository
222
228
 
223
229
    def _get_tags_bytes(self):
224
230
        """Get the bytes of a serialised tags dict.
240
246
        if not local and not config.has_explicit_nickname():
241
247
            try:
242
248
                master = self.get_master_branch(possible_transports)
 
249
                if master and self.user_url == master.user_url:
 
250
                    raise errors.RecursiveBind(self.user_url)
243
251
                if master is not None:
244
252
                    # return the master branch value
245
253
                    return master.nick
 
254
            except errors.RecursiveBind, e:
 
255
                raise e
246
256
            except errors.BzrError, e:
247
257
                # Silently fall back to local implicit nick if the master is
248
258
                # unavailable
285
295
        new_history.reverse()
286
296
        return new_history
287
297
 
288
 
    def lock_write(self):
 
298
    def lock_write(self, token=None):
 
299
        """Lock the branch for write operations.
 
300
 
 
301
        :param token: A token to permit reacquiring a previously held and
 
302
            preserved lock.
 
303
        :return: A BranchWriteLockResult.
 
304
        """
289
305
        raise NotImplementedError(self.lock_write)
290
306
 
291
307
    def lock_read(self):
 
308
        """Lock the branch for read operations.
 
309
 
 
310
        :return: A bzrlib.lock.LogicalLockResult.
 
311
        """
292
312
        raise NotImplementedError(self.lock_read)
293
313
 
294
314
    def unlock(self):
419
439
            * 'include' - the stop revision is the last item in the result
420
440
            * 'with-merges' - include the stop revision and all of its
421
441
              merged revisions in the result
 
442
            * 'with-merges-without-common-ancestry' - filter out revisions 
 
443
              that are in both ancestries
422
444
        :param direction: either 'reverse' or 'forward':
423
445
            * reverse means return the start_revision_id first, i.e.
424
446
              start at the most recent revision and go backwards in history
446
468
        # start_revision_id.
447
469
        if self._merge_sorted_revisions_cache is None:
448
470
            last_revision = self.last_revision()
449
 
            graph = self.repository.get_graph()
450
 
            parent_map = dict(((key, value) for key, value in
451
 
                     graph.iter_ancestry([last_revision]) if value is not None))
452
 
            revision_graph = repository._strip_NULL_ghosts(parent_map)
453
 
            revs = tsort.merge_sort(revision_graph, last_revision, None,
454
 
                generate_revno=True)
455
 
            # Drop the sequence # before caching
456
 
            self._merge_sorted_revisions_cache = [r[1:] for r in revs]
457
 
 
 
471
            known_graph = self.repository.get_known_graph_ancestry(
 
472
                [last_revision])
 
473
            self._merge_sorted_revisions_cache = known_graph.merge_sort(
 
474
                last_revision)
458
475
        filtered = self._filter_merge_sorted_revisions(
459
476
            self._merge_sorted_revisions_cache, start_revision_id,
460
477
            stop_revision_id, stop_rule)
 
478
        # Make sure we don't return revisions that are not part of the
 
479
        # start_revision_id ancestry.
 
480
        filtered = self._filter_start_non_ancestors(filtered)
461
481
        if direction == 'reverse':
462
482
            return filtered
463
483
        if direction == 'forward':
470
490
        """Iterate over an inclusive range of sorted revisions."""
471
491
        rev_iter = iter(merge_sorted_revisions)
472
492
        if start_revision_id is not None:
473
 
            for rev_id, depth, revno, end_of_merge in rev_iter:
 
493
            for node in rev_iter:
 
494
                rev_id = node.key[-1]
474
495
                if rev_id != start_revision_id:
475
496
                    continue
476
497
                else:
477
498
                    # The decision to include the start or not
478
499
                    # depends on the stop_rule if a stop is provided
479
 
                    rev_iter = chain(
480
 
                        iter([(rev_id, depth, revno, end_of_merge)]),
481
 
                        rev_iter)
 
500
                    # so pop this node back into the iterator
 
501
                    rev_iter = chain(iter([node]), rev_iter)
482
502
                    break
483
503
        if stop_revision_id is None:
484
 
            for rev_id, depth, revno, end_of_merge in rev_iter:
485
 
                yield rev_id, depth, revno, end_of_merge
 
504
            # Yield everything
 
505
            for node in rev_iter:
 
506
                rev_id = node.key[-1]
 
507
                yield (rev_id, node.merge_depth, node.revno,
 
508
                       node.end_of_merge)
486
509
        elif stop_rule == 'exclude':
487
 
            for rev_id, depth, revno, end_of_merge in rev_iter:
 
510
            for node in rev_iter:
 
511
                rev_id = node.key[-1]
488
512
                if rev_id == stop_revision_id:
489
513
                    return
490
 
                yield rev_id, depth, revno, end_of_merge
 
514
                yield (rev_id, node.merge_depth, node.revno,
 
515
                       node.end_of_merge)
491
516
        elif stop_rule == 'include':
492
 
            for rev_id, depth, revno, end_of_merge in rev_iter:
493
 
                yield rev_id, depth, revno, end_of_merge
 
517
            for node in rev_iter:
 
518
                rev_id = node.key[-1]
 
519
                yield (rev_id, node.merge_depth, node.revno,
 
520
                       node.end_of_merge)
494
521
                if rev_id == stop_revision_id:
495
522
                    return
 
523
        elif stop_rule == 'with-merges-without-common-ancestry':
 
524
            # We want to exclude all revisions that are already part of the
 
525
            # stop_revision_id ancestry.
 
526
            graph = self.repository.get_graph()
 
527
            ancestors = graph.find_unique_ancestors(start_revision_id,
 
528
                                                    [stop_revision_id])
 
529
            for node in rev_iter:
 
530
                rev_id = node.key[-1]
 
531
                if rev_id not in ancestors:
 
532
                    continue
 
533
                yield (rev_id, node.merge_depth, node.revno,
 
534
                       node.end_of_merge)
496
535
        elif stop_rule == 'with-merges':
497
536
            stop_rev = self.repository.get_revision(stop_revision_id)
498
537
            if stop_rev.parent_ids:
499
538
                left_parent = stop_rev.parent_ids[0]
500
539
            else:
501
540
                left_parent = _mod_revision.NULL_REVISION
502
 
            for rev_id, depth, revno, end_of_merge in rev_iter:
 
541
            # left_parent is the actual revision we want to stop logging at,
 
542
            # since we want to show the merged revisions after the stop_rev too
 
543
            reached_stop_revision_id = False
 
544
            revision_id_whitelist = []
 
545
            for node in rev_iter:
 
546
                rev_id = node.key[-1]
503
547
                if rev_id == left_parent:
 
548
                    # reached the left parent after the stop_revision
504
549
                    return
505
 
                yield rev_id, depth, revno, end_of_merge
 
550
                if (not reached_stop_revision_id or
 
551
                        rev_id in revision_id_whitelist):
 
552
                    yield (rev_id, node.merge_depth, node.revno,
 
553
                       node.end_of_merge)
 
554
                    if reached_stop_revision_id or rev_id == stop_revision_id:
 
555
                        # only do the merged revs of rev_id from now on
 
556
                        rev = self.repository.get_revision(rev_id)
 
557
                        if rev.parent_ids:
 
558
                            reached_stop_revision_id = True
 
559
                            revision_id_whitelist.extend(rev.parent_ids)
506
560
        else:
507
561
            raise ValueError('invalid stop_rule %r' % stop_rule)
508
562
 
 
563
    def _filter_start_non_ancestors(self, rev_iter):
 
564
        # If we started from a dotted revno, we want to consider it as a tip
 
565
        # and don't want to yield revisions that are not part of its
 
566
        # ancestry. Given the order guaranteed by the merge sort, we will see
 
567
        # uninteresting descendants of the first parent of our tip before the
 
568
        # tip itself.
 
569
        first = rev_iter.next()
 
570
        (rev_id, merge_depth, revno, end_of_merge) = first
 
571
        yield first
 
572
        if not merge_depth:
 
573
            # We start at a mainline revision so by definition, all others
 
574
            # revisions in rev_iter are ancestors
 
575
            for node in rev_iter:
 
576
                yield node
 
577
 
 
578
        clean = False
 
579
        whitelist = set()
 
580
        pmap = self.repository.get_parent_map([rev_id])
 
581
        parents = pmap.get(rev_id, [])
 
582
        if parents:
 
583
            whitelist.update(parents)
 
584
        else:
 
585
            # If there is no parents, there is nothing of interest left
 
586
 
 
587
            # FIXME: It's hard to test this scenario here as this code is never
 
588
            # called in that case. -- vila 20100322
 
589
            return
 
590
 
 
591
        for (rev_id, merge_depth, revno, end_of_merge) in rev_iter:
 
592
            if not clean:
 
593
                if rev_id in whitelist:
 
594
                    pmap = self.repository.get_parent_map([rev_id])
 
595
                    parents = pmap.get(rev_id, [])
 
596
                    whitelist.remove(rev_id)
 
597
                    whitelist.update(parents)
 
598
                    if merge_depth == 0:
 
599
                        # We've reached the mainline, there is nothing left to
 
600
                        # filter
 
601
                        clean = True
 
602
                else:
 
603
                    # A revision that is not part of the ancestry of our
 
604
                    # starting revision.
 
605
                    continue
 
606
            yield (rev_id, merge_depth, revno, end_of_merge)
 
607
 
509
608
    def leave_lock_in_place(self):
510
609
        """Tell this branch object not to release the physical lock when this
511
610
        object is unlocked.
528
627
        :param other: The branch to bind to
529
628
        :type other: Branch
530
629
        """
531
 
        raise errors.UpgradeRequired(self.base)
 
630
        raise errors.UpgradeRequired(self.user_url)
532
631
 
533
632
    def set_append_revisions_only(self, enabled):
534
633
        if not self._format.supports_set_append_revisions_only():
535
 
            raise errors.UpgradeRequired(self.base)
 
634
            raise errors.UpgradeRequired(self.user_url)
536
635
        if enabled:
537
636
            value = 'True'
538
637
        else:
586
685
    def get_old_bound_location(self):
587
686
        """Return the URL of the branch we used to be bound to
588
687
        """
589
 
        raise errors.UpgradeRequired(self.base)
 
688
        raise errors.UpgradeRequired(self.user_url)
590
689
 
591
690
    def get_commit_builder(self, parents, config=None, timestamp=None,
592
691
                           timezone=None, committer=None, revprops=None,
670
769
            stacking.
671
770
        """
672
771
        if not self._format.supports_stacking():
673
 
            raise errors.UnstackableBranchFormat(self._format, self.base)
 
772
            raise errors.UnstackableBranchFormat(self._format, self.user_url)
674
773
        # XXX: Changing from one fallback repository to another does not check
675
774
        # that all the data you need is present in the new fallback.
676
775
        # Possibly it should.
706
805
            if len(old_repository._fallback_repositories) != 1:
707
806
                raise AssertionError("can't cope with fallback repositories "
708
807
                    "of %r" % (self.repository,))
709
 
            # unlock it, including unlocking the fallback
 
808
            # Open the new repository object.
 
809
            # Repositories don't offer an interface to remove fallback
 
810
            # repositories today; take the conceptually simpler option and just
 
811
            # reopen it.  We reopen it starting from the URL so that we
 
812
            # get a separate connection for RemoteRepositories and can
 
813
            # stream from one of them to the other.  This does mean doing
 
814
            # separate SSH connection setup, but unstacking is not a
 
815
            # common operation so it's tolerable.
 
816
            new_bzrdir = bzrdir.BzrDir.open(self.bzrdir.root_transport.base)
 
817
            new_repository = new_bzrdir.find_repository()
 
818
            if new_repository._fallback_repositories:
 
819
                raise AssertionError("didn't expect %r to have "
 
820
                    "fallback_repositories"
 
821
                    % (self.repository,))
 
822
            # Replace self.repository with the new repository.
 
823
            # Do our best to transfer the lock state (i.e. lock-tokens and
 
824
            # lock count) of self.repository to the new repository.
 
825
            lock_token = old_repository.lock_write().repository_token
 
826
            self.repository = new_repository
 
827
            if isinstance(self, remote.RemoteBranch):
 
828
                # Remote branches can have a second reference to the old
 
829
                # repository that need to be replaced.
 
830
                if self._real_branch is not None:
 
831
                    self._real_branch.repository = new_repository
 
832
            self.repository.lock_write(token=lock_token)
 
833
            if lock_token is not None:
 
834
                old_repository.leave_lock_in_place()
710
835
            old_repository.unlock()
 
836
            if lock_token is not None:
 
837
                # XXX: self.repository.leave_lock_in_place() before this
 
838
                # function will not be preserved.  Fortunately that doesn't
 
839
                # affect the current default format (2a), and would be a
 
840
                # corner-case anyway.
 
841
                #  - Andrew Bennetts, 2010/06/30
 
842
                self.repository.dont_leave_lock_in_place()
 
843
            old_lock_count = 0
 
844
            while True:
 
845
                try:
 
846
                    old_repository.unlock()
 
847
                except errors.LockNotHeld:
 
848
                    break
 
849
                old_lock_count += 1
 
850
            if old_lock_count == 0:
 
851
                raise AssertionError(
 
852
                    'old_repository should have been locked at least once.')
 
853
            for i in range(old_lock_count-1):
 
854
                self.repository.lock_write()
 
855
            # Fetch from the old repository into the new.
711
856
            old_repository.lock_read()
712
857
            try:
713
 
                # Repositories don't offer an interface to remove fallback
714
 
                # repositories today; take the conceptually simpler option and just
715
 
                # reopen it.  We reopen it starting from the URL so that we
716
 
                # get a separate connection for RemoteRepositories and can
717
 
                # stream from one of them to the other.  This does mean doing
718
 
                # separate SSH connection setup, but unstacking is not a
719
 
                # common operation so it's tolerable.
720
 
                new_bzrdir = bzrdir.BzrDir.open(self.bzrdir.root_transport.base)
721
 
                new_repository = new_bzrdir.find_repository()
722
 
                self.repository = new_repository
723
 
                if self.repository._fallback_repositories:
724
 
                    raise AssertionError("didn't expect %r to have "
725
 
                        "fallback_repositories"
726
 
                        % (self.repository,))
727
 
                # this is not paired with an unlock because it's just restoring
728
 
                # the previous state; the lock's released when set_stacked_on_url
729
 
                # returns
730
 
                self.repository.lock_write()
731
858
                # XXX: If you unstack a branch while it has a working tree
732
859
                # with a pending merge, the pending-merged revisions will no
733
860
                # longer be present.  You can (probably) revert and remerge.
827
954
 
828
955
    def unbind(self):
829
956
        """Older format branches cannot bind or unbind."""
830
 
        raise errors.UpgradeRequired(self.base)
 
957
        raise errors.UpgradeRequired(self.user_url)
831
958
 
832
959
    def last_revision(self):
833
960
        """Return last revision id, or NULL_REVISION."""
874
1001
                raise errors.NoSuchRevision(self, stop_revision)
875
1002
        return other_history[self_len:stop_revision]
876
1003
 
877
 
    @needs_write_lock
878
1004
    def update_revisions(self, other, stop_revision=None, overwrite=False,
879
1005
                         graph=None):
880
1006
        """Pull in new perfect-fit revisions.
929
1055
            self._extend_partial_history(distance_from_last)
930
1056
        return self._partial_revision_history_cache[distance_from_last]
931
1057
 
932
 
    @needs_write_lock
933
1058
    def pull(self, source, overwrite=False, stop_revision=None,
934
1059
             possible_transports=None, *args, **kwargs):
935
1060
        """Mirror source into this branch.
993
1118
        try:
994
1119
            return urlutils.join(self.base[:-1], parent)
995
1120
        except errors.InvalidURLJoin, e:
996
 
            raise errors.InaccessibleParent(parent, self.base)
 
1121
            raise errors.InaccessibleParent(parent, self.user_url)
997
1122
 
998
1123
    def _get_parent_location(self):
999
1124
        raise NotImplementedError(self._get_parent_location)
1084
1209
        params = ChangeBranchTipParams(
1085
1210
            self, old_revno, new_revno, old_revid, new_revid)
1086
1211
        for hook in hooks:
1087
 
            try:
1088
 
                hook(params)
1089
 
            except errors.TipChangeRejected:
1090
 
                raise
1091
 
            except Exception:
1092
 
                exc_info = sys.exc_info()
1093
 
                hook_name = Branch.hooks.get_hook_name(hook)
1094
 
                raise errors.HookFailed(
1095
 
                    'pre_change_branch_tip', hook_name, exc_info)
 
1212
            hook(params)
1096
1213
 
1097
1214
    @needs_write_lock
1098
1215
    def update(self):
1147
1264
        revision_id: if not None, the revision history in the new branch will
1148
1265
                     be truncated to end with revision_id.
1149
1266
        """
 
1267
        if (repository_policy is not None and
 
1268
            repository_policy.requires_stacking()):
 
1269
            to_bzrdir._format.require_stacking(_skip_repo=True)
1150
1270
        result = to_bzrdir.create_branch()
1151
1271
        result.lock_write()
1152
1272
        try:
1183
1303
                revno = 1
1184
1304
        destination.set_last_revision_info(revno, revision_id)
1185
1305
 
1186
 
    @needs_read_lock
1187
1306
    def copy_content_into(self, destination, revision_id=None):
1188
1307
        """Copy the content of self into destination.
1189
1308
 
1190
1309
        revision_id: if not None, the revision history in the new branch will
1191
1310
                     be truncated to end with revision_id.
1192
1311
        """
1193
 
        self.update_references(destination)
1194
 
        self._synchronize_history(destination, revision_id)
1195
 
        try:
1196
 
            parent = self.get_parent()
1197
 
        except errors.InaccessibleParent, e:
1198
 
            mutter('parent was not accessible to copy: %s', e)
1199
 
        else:
1200
 
            if parent:
1201
 
                destination.set_parent(parent)
1202
 
        if self._push_should_merge_tags():
1203
 
            self.tags.merge_to(destination.tags)
 
1312
        return InterBranch.get(self, destination).copy_content_into(
 
1313
            revision_id=revision_id)
1204
1314
 
1205
1315
    def update_references(self, target):
1206
1316
        if not getattr(self._format, 'supports_reference_locations', False):
1274
1384
        """
1275
1385
        # XXX: Fix the bzrdir API to allow getting the branch back from the
1276
1386
        # clone call. Or something. 20090224 RBC/spiv.
 
1387
        # XXX: Should this perhaps clone colocated branches as well, 
 
1388
        # rather than just the default branch? 20100319 JRV
1277
1389
        if revision_id is None:
1278
1390
            revision_id = self.last_revision()
1279
 
        try:
1280
 
            dir_to = self.bzrdir.clone_on_transport(to_transport,
1281
 
                revision_id=revision_id, stacked_on=stacked_on,
1282
 
                create_prefix=create_prefix, use_existing_dir=use_existing_dir)
1283
 
        except errors.FileExists:
1284
 
            if not use_existing_dir:
1285
 
                raise
1286
 
        except errors.NoSuchFile:
1287
 
            if not create_prefix:
1288
 
                raise
 
1391
        dir_to = self.bzrdir.clone_on_transport(to_transport,
 
1392
            revision_id=revision_id, stacked_on=stacked_on,
 
1393
            create_prefix=create_prefix, use_existing_dir=use_existing_dir)
1289
1394
        return dir_to.open_branch()
1290
1395
 
1291
1396
    def create_checkout(self, to_location, revision_id=None,
1310
1415
        if lightweight:
1311
1416
            format = self._get_checkout_format()
1312
1417
            checkout = format.initialize_on_transport(t)
1313
 
            from_branch = BranchReferenceFormat().initialize(checkout, self)
 
1418
            from_branch = BranchReferenceFormat().initialize(checkout, 
 
1419
                target_branch=self)
1314
1420
        else:
1315
1421
            format = self._get_checkout_format()
1316
1422
            checkout_branch = bzrdir.BzrDir.create_branch_convenience(
1358
1464
    def supports_tags(self):
1359
1465
        return self._format.supports_tags()
1360
1466
 
 
1467
    def automatic_tag_name(self, revision_id):
 
1468
        """Try to automatically find the tag name for a revision.
 
1469
 
 
1470
        :param revision_id: Revision id of the revision.
 
1471
        :return: A tag name or None if no tag name could be determined.
 
1472
        """
 
1473
        for hook in Branch.hooks['automatic_tag_name']:
 
1474
            ret = hook(self, revision_id)
 
1475
            if ret is not None:
 
1476
                return ret
 
1477
        return None
 
1478
 
1361
1479
    def _check_if_descendant_or_diverged(self, revision_a, revision_b, graph,
1362
1480
                                         other_branch):
1363
1481
        """Ensure that revision_b is a descendant of revision_a.
1427
1545
        return not (self == other)
1428
1546
 
1429
1547
    @classmethod
1430
 
    def find_format(klass, a_bzrdir):
 
1548
    def find_format(klass, a_bzrdir, name=None):
1431
1549
        """Return the format for the branch object in a_bzrdir."""
1432
1550
        try:
1433
 
            transport = a_bzrdir.get_branch_transport(None)
1434
 
            format_string = transport.get("format").read()
1435
 
            return klass._formats[format_string]
 
1551
            transport = a_bzrdir.get_branch_transport(None, name=name)
 
1552
            format_string = transport.get_bytes("format")
 
1553
            format = klass._formats[format_string]
 
1554
            if isinstance(format, MetaDirBranchFormatFactory):
 
1555
                return format()
 
1556
            return format
1436
1557
        except errors.NoSuchFile:
1437
 
            raise errors.NotBranchError(path=transport.base)
 
1558
            raise errors.NotBranchError(path=transport.base, bzrdir=a_bzrdir)
1438
1559
        except KeyError:
1439
1560
            raise errors.UnknownFormatError(format=format_string, kind='branch')
1440
1561
 
1443
1564
        """Return the current default format."""
1444
1565
        return klass._default_format
1445
1566
 
1446
 
    def get_reference(self, a_bzrdir):
 
1567
    @classmethod
 
1568
    def get_formats(klass):
 
1569
        """Get all the known formats.
 
1570
 
 
1571
        Warning: This triggers a load of all lazy registered formats: do not
 
1572
        use except when that is desireed.
 
1573
        """
 
1574
        result = []
 
1575
        for fmt in klass._formats.values():
 
1576
            if isinstance(fmt, MetaDirBranchFormatFactory):
 
1577
                fmt = fmt()
 
1578
            result.append(fmt)
 
1579
        return result
 
1580
 
 
1581
    def get_reference(self, a_bzrdir, name=None):
1447
1582
        """Get the target reference of the branch in a_bzrdir.
1448
1583
 
1449
1584
        format probing must have been completed before calling
1451
1586
        in a_bzrdir is correct.
1452
1587
 
1453
1588
        :param a_bzrdir: The bzrdir to get the branch data from.
 
1589
        :param name: Name of the colocated branch to fetch
1454
1590
        :return: None if the branch is not a reference branch.
1455
1591
        """
1456
1592
        return None
1457
1593
 
1458
1594
    @classmethod
1459
 
    def set_reference(self, a_bzrdir, to_branch):
 
1595
    def set_reference(self, a_bzrdir, name, to_branch):
1460
1596
        """Set the target reference of the branch in a_bzrdir.
1461
1597
 
1462
1598
        format probing must have been completed before calling
1464
1600
        in a_bzrdir is correct.
1465
1601
 
1466
1602
        :param a_bzrdir: The bzrdir to set the branch reference for.
 
1603
        :param name: Name of colocated branch to set, None for default
1467
1604
        :param to_branch: branch that the checkout is to reference
1468
1605
        """
1469
1606
        raise NotImplementedError(self.set_reference)
1476
1613
        """Return the short format description for this format."""
1477
1614
        raise NotImplementedError(self.get_format_description)
1478
1615
 
1479
 
    def _initialize_helper(self, a_bzrdir, utf8_files, lock_type='metadir',
1480
 
                           set_format=True):
 
1616
    def _run_post_branch_init_hooks(self, a_bzrdir, name, branch):
 
1617
        hooks = Branch.hooks['post_branch_init']
 
1618
        if not hooks:
 
1619
            return
 
1620
        params = BranchInitHookParams(self, a_bzrdir, name, branch)
 
1621
        for hook in hooks:
 
1622
            hook(params)
 
1623
 
 
1624
    def _initialize_helper(self, a_bzrdir, utf8_files, name=None,
 
1625
                           lock_type='metadir', set_format=True):
1481
1626
        """Initialize a branch in a bzrdir, with specified files
1482
1627
 
1483
1628
        :param a_bzrdir: The bzrdir to initialize the branch in
1484
1629
        :param utf8_files: The files to create as a list of
1485
1630
            (filename, content) tuples
 
1631
        :param name: Name of colocated branch to create, if any
1486
1632
        :param set_format: If True, set the format with
1487
1633
            self.get_format_string.  (BzrBranch4 has its format set
1488
1634
            elsewhere)
1489
1635
        :return: a branch in this format
1490
1636
        """
1491
 
        mutter('creating branch %r in %s', self, a_bzrdir.transport.base)
1492
 
        branch_transport = a_bzrdir.get_branch_transport(self)
 
1637
        mutter('creating branch %r in %s', self, a_bzrdir.user_url)
 
1638
        branch_transport = a_bzrdir.get_branch_transport(self, name=name)
1493
1639
        lock_map = {
1494
1640
            'metadir': ('lock', lockdir.LockDir),
1495
1641
            'branch4': ('branch-lock', lockable_files.TransportLock),
1516
1662
        finally:
1517
1663
            if lock_taken:
1518
1664
                control_files.unlock()
1519
 
        return self.open(a_bzrdir, _found=True)
 
1665
        branch = self.open(a_bzrdir, name, _found=True)
 
1666
        self._run_post_branch_init_hooks(a_bzrdir, name, branch)
 
1667
        return branch
1520
1668
 
1521
 
    def initialize(self, a_bzrdir):
1522
 
        """Create a branch of this format in a_bzrdir."""
 
1669
    def initialize(self, a_bzrdir, name=None):
 
1670
        """Create a branch of this format in a_bzrdir.
 
1671
        
 
1672
        :param name: Name of the colocated branch to create.
 
1673
        """
1523
1674
        raise NotImplementedError(self.initialize)
1524
1675
 
1525
1676
    def is_supported(self):
1555
1706
        """
1556
1707
        raise NotImplementedError(self.network_name)
1557
1708
 
1558
 
    def open(self, a_bzrdir, _found=False, ignore_fallbacks=False):
 
1709
    def open(self, a_bzrdir, name=None, _found=False, ignore_fallbacks=False):
1559
1710
        """Return the branch object for a_bzrdir
1560
1711
 
1561
1712
        :param a_bzrdir: A BzrDir that contains a branch.
 
1713
        :param name: Name of colocated branch to open
1562
1714
        :param _found: a private parameter, do not use it. It is used to
1563
1715
            indicate if format probing has already be done.
1564
1716
        :param ignore_fallbacks: when set, no fallback branches will be opened
1568
1720
 
1569
1721
    @classmethod
1570
1722
    def register_format(klass, format):
1571
 
        """Register a metadir format."""
 
1723
        """Register a metadir format.
 
1724
        
 
1725
        See MetaDirBranchFormatFactory for the ability to register a format
 
1726
        without loading the code the format needs until it is actually used.
 
1727
        """
1572
1728
        klass._formats[format.get_format_string()] = format
1573
1729
        # Metadir formats have a network name of their format string, and get
1574
 
        # registered as class factories.
1575
 
        network_format_registry.register(format.get_format_string(), format.__class__)
 
1730
        # registered as factories.
 
1731
        if isinstance(format, MetaDirBranchFormatFactory):
 
1732
            network_format_registry.register(format.get_format_string(), format)
 
1733
        else:
 
1734
            network_format_registry.register(format.get_format_string(),
 
1735
                format.__class__)
1576
1736
 
1577
1737
    @classmethod
1578
1738
    def set_default_format(klass, format):
1598
1758
        return False  # by default
1599
1759
 
1600
1760
 
 
1761
class MetaDirBranchFormatFactory(registry._LazyObjectGetter):
 
1762
    """A factory for a BranchFormat object, permitting simple lazy registration.
 
1763
    
 
1764
    While none of the built in BranchFormats are lazy registered yet,
 
1765
    bzrlib.tests.test_branch.TestMetaDirBranchFormatFactory demonstrates how to
 
1766
    use it, and the bzr-loom plugin uses it as well (see
 
1767
    bzrlib.plugins.loom.formats).
 
1768
    """
 
1769
 
 
1770
    def __init__(self, format_string, module_name, member_name):
 
1771
        """Create a MetaDirBranchFormatFactory.
 
1772
 
 
1773
        :param format_string: The format string the format has.
 
1774
        :param module_name: Module to load the format class from.
 
1775
        :param member_name: Attribute name within the module for the format class.
 
1776
        """
 
1777
        registry._LazyObjectGetter.__init__(self, module_name, member_name)
 
1778
        self._format_string = format_string
 
1779
        
 
1780
    def get_format_string(self):
 
1781
        """See BranchFormat.get_format_string."""
 
1782
        return self._format_string
 
1783
 
 
1784
    def __call__(self):
 
1785
        """Used for network_format_registry support."""
 
1786
        return self.get_obj()()
 
1787
 
 
1788
 
1601
1789
class BranchHooks(Hooks):
1602
1790
    """A dictionary mapping hook name to a list of callables for branch hooks.
1603
1791
 
1672
1860
            "multiple hooks installed for transform_fallback_location, "
1673
1861
            "all are called with the url returned from the previous hook."
1674
1862
            "The order is however undefined.", (1, 9), None))
 
1863
        self.create_hook(HookPoint('automatic_tag_name',
 
1864
            "Called to determine an automatic tag name for a revision. "
 
1865
            "automatic_tag_name is called with (branch, revision_id) and "
 
1866
            "should return a tag name or None if no tag name could be "
 
1867
            "determined. The first non-None tag name returned will be used.",
 
1868
            (2, 2), None))
 
1869
        self.create_hook(HookPoint('post_branch_init',
 
1870
            "Called after new branch initialization completes. "
 
1871
            "post_branch_init is called with a "
 
1872
            "bzrlib.branch.BranchInitHookParams. "
 
1873
            "Note that init, branch and checkout (both heavyweight and "
 
1874
            "lightweight) will all trigger this hook.", (2, 2), None))
 
1875
        self.create_hook(HookPoint('post_switch',
 
1876
            "Called after a checkout switches branch. "
 
1877
            "post_switch is called with a "
 
1878
            "bzrlib.branch.SwitchHookParams.", (2, 2), None))
 
1879
 
1675
1880
 
1676
1881
 
1677
1882
# install the default hooks into the Branch class.
1716
1921
            self.old_revno, self.old_revid, self.new_revno, self.new_revid)
1717
1922
 
1718
1923
 
 
1924
class BranchInitHookParams(object):
 
1925
    """Object holding parameters passed to *_branch_init hooks.
 
1926
 
 
1927
    There are 4 fields that hooks may wish to access:
 
1928
 
 
1929
    :ivar format: the branch format
 
1930
    :ivar bzrdir: the BzrDir where the branch will be/has been initialized
 
1931
    :ivar name: name of colocated branch, if any (or None)
 
1932
    :ivar branch: the branch created
 
1933
 
 
1934
    Note that for lightweight checkouts, the bzrdir and format fields refer to
 
1935
    the checkout, hence they are different from the corresponding fields in
 
1936
    branch, which refer to the original branch.
 
1937
    """
 
1938
 
 
1939
    def __init__(self, format, a_bzrdir, name, branch):
 
1940
        """Create a group of BranchInitHook parameters.
 
1941
 
 
1942
        :param format: the branch format
 
1943
        :param a_bzrdir: the BzrDir where the branch will be/has been
 
1944
            initialized
 
1945
        :param name: name of colocated branch, if any (or None)
 
1946
        :param branch: the branch created
 
1947
 
 
1948
        Note that for lightweight checkouts, the bzrdir and format fields refer
 
1949
        to the checkout, hence they are different from the corresponding fields
 
1950
        in branch, which refer to the original branch.
 
1951
        """
 
1952
        self.format = format
 
1953
        self.bzrdir = a_bzrdir
 
1954
        self.name = name
 
1955
        self.branch = branch
 
1956
 
 
1957
    def __eq__(self, other):
 
1958
        return self.__dict__ == other.__dict__
 
1959
 
 
1960
    def __repr__(self):
 
1961
        return "<%s of %s>" % (self.__class__.__name__, self.branch)
 
1962
 
 
1963
 
 
1964
class SwitchHookParams(object):
 
1965
    """Object holding parameters passed to *_switch hooks.
 
1966
 
 
1967
    There are 4 fields that hooks may wish to access:
 
1968
 
 
1969
    :ivar control_dir: BzrDir of the checkout to change
 
1970
    :ivar to_branch: branch that the checkout is to reference
 
1971
    :ivar force: skip the check for local commits in a heavy checkout
 
1972
    :ivar revision_id: revision ID to switch to (or None)
 
1973
    """
 
1974
 
 
1975
    def __init__(self, control_dir, to_branch, force, revision_id):
 
1976
        """Create a group of SwitchHook parameters.
 
1977
 
 
1978
        :param control_dir: BzrDir of the checkout to change
 
1979
        :param to_branch: branch that the checkout is to reference
 
1980
        :param force: skip the check for local commits in a heavy checkout
 
1981
        :param revision_id: revision ID to switch to (or None)
 
1982
        """
 
1983
        self.control_dir = control_dir
 
1984
        self.to_branch = to_branch
 
1985
        self.force = force
 
1986
        self.revision_id = revision_id
 
1987
 
 
1988
    def __eq__(self, other):
 
1989
        return self.__dict__ == other.__dict__
 
1990
 
 
1991
    def __repr__(self):
 
1992
        return "<%s for %s to (%s, %s)>" % (self.__class__.__name__,
 
1993
            self.control_dir, self.to_branch,
 
1994
            self.revision_id)
 
1995
 
 
1996
 
1719
1997
class BzrBranchFormat4(BranchFormat):
1720
1998
    """Bzr branch format 4.
1721
1999
 
1728
2006
        """See BranchFormat.get_format_description()."""
1729
2007
        return "Branch format 4"
1730
2008
 
1731
 
    def initialize(self, a_bzrdir):
 
2009
    def initialize(self, a_bzrdir, name=None):
1732
2010
        """Create a branch of this format in a_bzrdir."""
1733
2011
        utf8_files = [('revision-history', ''),
1734
2012
                      ('branch-name', ''),
1735
2013
                      ]
1736
 
        return self._initialize_helper(a_bzrdir, utf8_files,
 
2014
        return self._initialize_helper(a_bzrdir, utf8_files, name=name,
1737
2015
                                       lock_type='branch4', set_format=False)
1738
2016
 
1739
2017
    def __init__(self):
1744
2022
        """The network name for this format is the control dirs disk label."""
1745
2023
        return self._matchingbzrdir.get_format_string()
1746
2024
 
1747
 
    def open(self, a_bzrdir, _found=False, ignore_fallbacks=False):
 
2025
    def open(self, a_bzrdir, name=None, _found=False, ignore_fallbacks=False):
1748
2026
        """See BranchFormat.open()."""
1749
2027
        if not _found:
1750
2028
            # we are being called directly and must probe.
1752
2030
        return BzrBranch(_format=self,
1753
2031
                         _control_files=a_bzrdir._control_files,
1754
2032
                         a_bzrdir=a_bzrdir,
 
2033
                         name=name,
1755
2034
                         _repository=a_bzrdir.open_repository())
1756
2035
 
1757
2036
    def __str__(self):
1772
2051
        """
1773
2052
        return self.get_format_string()
1774
2053
 
1775
 
    def open(self, a_bzrdir, _found=False, ignore_fallbacks=False):
 
2054
    def open(self, a_bzrdir, name=None, _found=False, ignore_fallbacks=False):
1776
2055
        """See BranchFormat.open()."""
1777
2056
        if not _found:
1778
 
            format = BranchFormat.find_format(a_bzrdir)
 
2057
            format = BranchFormat.find_format(a_bzrdir, name=name)
1779
2058
            if format.__class__ != self.__class__:
1780
2059
                raise AssertionError("wrong format %r found for %r" %
1781
2060
                    (format, self))
 
2061
        transport = a_bzrdir.get_branch_transport(None, name=name)
1782
2062
        try:
1783
 
            transport = a_bzrdir.get_branch_transport(None)
1784
2063
            control_files = lockable_files.LockableFiles(transport, 'lock',
1785
2064
                                                         lockdir.LockDir)
1786
2065
            return self._branch_class()(_format=self,
1787
2066
                              _control_files=control_files,
 
2067
                              name=name,
1788
2068
                              a_bzrdir=a_bzrdir,
1789
2069
                              _repository=a_bzrdir.find_repository(),
1790
2070
                              ignore_fallbacks=ignore_fallbacks)
1791
2071
        except errors.NoSuchFile:
1792
 
            raise errors.NotBranchError(path=transport.base)
 
2072
            raise errors.NotBranchError(path=transport.base, bzrdir=a_bzrdir)
1793
2073
 
1794
2074
    def __init__(self):
1795
2075
        super(BranchFormatMetadir, self).__init__()
1824
2104
        """See BranchFormat.get_format_description()."""
1825
2105
        return "Branch format 5"
1826
2106
 
1827
 
    def initialize(self, a_bzrdir):
 
2107
    def initialize(self, a_bzrdir, name=None):
1828
2108
        """Create a branch of this format in a_bzrdir."""
1829
2109
        utf8_files = [('revision-history', ''),
1830
2110
                      ('branch-name', ''),
1831
2111
                      ]
1832
 
        return self._initialize_helper(a_bzrdir, utf8_files)
 
2112
        return self._initialize_helper(a_bzrdir, utf8_files, name)
1833
2113
 
1834
2114
    def supports_tags(self):
1835
2115
        return False
1857
2137
        """See BranchFormat.get_format_description()."""
1858
2138
        return "Branch format 6"
1859
2139
 
1860
 
    def initialize(self, a_bzrdir):
 
2140
    def initialize(self, a_bzrdir, name=None):
1861
2141
        """Create a branch of this format in a_bzrdir."""
1862
2142
        utf8_files = [('last-revision', '0 null:\n'),
1863
2143
                      ('branch.conf', ''),
1864
2144
                      ('tags', ''),
1865
2145
                      ]
1866
 
        return self._initialize_helper(a_bzrdir, utf8_files)
 
2146
        return self._initialize_helper(a_bzrdir, utf8_files, name)
1867
2147
 
1868
2148
    def make_tags(self, branch):
1869
2149
        """See bzrlib.branch.BranchFormat.make_tags()."""
1887
2167
        """See BranchFormat.get_format_description()."""
1888
2168
        return "Branch format 8"
1889
2169
 
1890
 
    def initialize(self, a_bzrdir):
 
2170
    def initialize(self, a_bzrdir, name=None):
1891
2171
        """Create a branch of this format in a_bzrdir."""
1892
2172
        utf8_files = [('last-revision', '0 null:\n'),
1893
2173
                      ('branch.conf', ''),
1894
2174
                      ('tags', ''),
1895
2175
                      ('references', '')
1896
2176
                      ]
1897
 
        return self._initialize_helper(a_bzrdir, utf8_files)
 
2177
        return self._initialize_helper(a_bzrdir, utf8_files, name)
1898
2178
 
1899
2179
    def __init__(self):
1900
2180
        super(BzrBranchFormat8, self).__init__()
1923
2203
    This format was introduced in bzr 1.6.
1924
2204
    """
1925
2205
 
1926
 
    def initialize(self, a_bzrdir):
 
2206
    def initialize(self, a_bzrdir, name=None):
1927
2207
        """Create a branch of this format in a_bzrdir."""
1928
2208
        utf8_files = [('last-revision', '0 null:\n'),
1929
2209
                      ('branch.conf', ''),
1930
2210
                      ('tags', ''),
1931
2211
                      ]
1932
 
        return self._initialize_helper(a_bzrdir, utf8_files)
 
2212
        return self._initialize_helper(a_bzrdir, utf8_files, name)
1933
2213
 
1934
2214
    def _branch_class(self):
1935
2215
        return BzrBranch7
1967
2247
        """See BranchFormat.get_format_description()."""
1968
2248
        return "Checkout reference format 1"
1969
2249
 
1970
 
    def get_reference(self, a_bzrdir):
 
2250
    def get_reference(self, a_bzrdir, name=None):
1971
2251
        """See BranchFormat.get_reference()."""
1972
 
        transport = a_bzrdir.get_branch_transport(None)
1973
 
        return transport.get('location').read()
 
2252
        transport = a_bzrdir.get_branch_transport(None, name=name)
 
2253
        return transport.get_bytes('location')
1974
2254
 
1975
 
    def set_reference(self, a_bzrdir, to_branch):
 
2255
    def set_reference(self, a_bzrdir, name, to_branch):
1976
2256
        """See BranchFormat.set_reference()."""
1977
 
        transport = a_bzrdir.get_branch_transport(None)
 
2257
        transport = a_bzrdir.get_branch_transport(None, name=name)
1978
2258
        location = transport.put_bytes('location', to_branch.base)
1979
2259
 
1980
 
    def initialize(self, a_bzrdir, target_branch=None):
 
2260
    def initialize(self, a_bzrdir, name=None, target_branch=None):
1981
2261
        """Create a branch of this format in a_bzrdir."""
1982
2262
        if target_branch is None:
1983
2263
            # this format does not implement branch itself, thus the implicit
1984
2264
            # creation contract must see it as uninitializable
1985
2265
            raise errors.UninitializableFormat(self)
1986
 
        mutter('creating branch reference in %s', a_bzrdir.transport.base)
1987
 
        branch_transport = a_bzrdir.get_branch_transport(self)
 
2266
        mutter('creating branch reference in %s', a_bzrdir.user_url)
 
2267
        branch_transport = a_bzrdir.get_branch_transport(self, name=name)
1988
2268
        branch_transport.put_bytes('location',
1989
 
            target_branch.bzrdir.root_transport.base)
 
2269
            target_branch.bzrdir.user_url)
1990
2270
        branch_transport.put_bytes('format', self.get_format_string())
1991
 
        return self.open(
1992
 
            a_bzrdir, _found=True,
 
2271
        branch = self.open(
 
2272
            a_bzrdir, name, _found=True,
1993
2273
            possible_transports=[target_branch.bzrdir.root_transport])
 
2274
        self._run_post_branch_init_hooks(a_bzrdir, name, branch)
 
2275
        return branch
1994
2276
 
1995
2277
    def __init__(self):
1996
2278
        super(BranchReferenceFormat, self).__init__()
2002
2284
        def clone(to_bzrdir, revision_id=None,
2003
2285
            repository_policy=None):
2004
2286
            """See Branch.clone()."""
2005
 
            return format.initialize(to_bzrdir, a_branch)
 
2287
            return format.initialize(to_bzrdir, target_branch=a_branch)
2006
2288
            # cannot obey revision_id limits when cloning a reference ...
2007
2289
            # FIXME RBC 20060210 either nuke revision_id for clone, or
2008
2290
            # emit some sort of warning/error to the caller ?!
2009
2291
        return clone
2010
2292
 
2011
 
    def open(self, a_bzrdir, _found=False, location=None,
 
2293
    def open(self, a_bzrdir, name=None, _found=False, location=None,
2012
2294
             possible_transports=None, ignore_fallbacks=False):
2013
2295
        """Return the branch that the branch reference in a_bzrdir points at.
2014
2296
 
2015
2297
        :param a_bzrdir: A BzrDir that contains a branch.
 
2298
        :param name: Name of colocated branch to open, if any
2016
2299
        :param _found: a private parameter, do not use it. It is used to
2017
2300
            indicate if format probing has already be done.
2018
2301
        :param ignore_fallbacks: when set, no fallback branches will be opened
2023
2306
        :param possible_transports: An optional reusable transports list.
2024
2307
        """
2025
2308
        if not _found:
2026
 
            format = BranchFormat.find_format(a_bzrdir)
 
2309
            format = BranchFormat.find_format(a_bzrdir, name=name)
2027
2310
            if format.__class__ != self.__class__:
2028
2311
                raise AssertionError("wrong format %r found for %r" %
2029
2312
                    (format, self))
2030
2313
        if location is None:
2031
 
            location = self.get_reference(a_bzrdir)
 
2314
            location = self.get_reference(a_bzrdir, name)
2032
2315
        real_bzrdir = bzrdir.BzrDir.open(
2033
2316
            location, possible_transports=possible_transports)
2034
 
        result = real_bzrdir.open_branch(ignore_fallbacks=ignore_fallbacks)
 
2317
        result = real_bzrdir.open_branch(name=name, 
 
2318
            ignore_fallbacks=ignore_fallbacks)
2035
2319
        # this changes the behaviour of result.clone to create a new reference
2036
2320
        # rather than a copy of the content of the branch.
2037
2321
        # I did not use a proxy object because that needs much more extensive
2064
2348
BranchFormat.register_format(__format6)
2065
2349
BranchFormat.register_format(__format7)
2066
2350
BranchFormat.register_format(__format8)
2067
 
BranchFormat.set_default_format(__format6)
 
2351
BranchFormat.set_default_format(__format7)
2068
2352
_legacy_formats = [BzrBranchFormat4(),
2069
2353
    ]
2070
2354
network_format_registry.register(
2071
2355
    _legacy_formats[0].network_name(), _legacy_formats[0].__class__)
2072
2356
 
2073
2357
 
2074
 
class BzrBranch(Branch):
 
2358
class BranchWriteLockResult(LogicalLockResult):
 
2359
    """The result of write locking a branch.
 
2360
 
 
2361
    :ivar branch_token: The token obtained from the underlying branch lock, or
 
2362
        None.
 
2363
    :ivar unlock: A callable which will unlock the lock.
 
2364
    """
 
2365
 
 
2366
    def __init__(self, unlock, branch_token):
 
2367
        LogicalLockResult.__init__(self, unlock)
 
2368
        self.branch_token = branch_token
 
2369
 
 
2370
    def __repr__(self):
 
2371
        return "BranchWriteLockResult(%s, %s)" % (self.branch_token,
 
2372
            self.unlock)
 
2373
 
 
2374
 
 
2375
class BzrBranch(Branch, _RelockDebugMixin):
2075
2376
    """A branch stored in the actual filesystem.
2076
2377
 
2077
2378
    Note that it's "local" in the context of the filesystem; it doesn't
2083
2384
    :ivar repository: Repository for this branch.
2084
2385
    :ivar base: The url of the base directory for this branch; the one
2085
2386
        containing the .bzr directory.
 
2387
    :ivar name: Optional colocated branch name as it exists in the control
 
2388
        directory.
2086
2389
    """
2087
2390
 
2088
2391
    def __init__(self, _format=None,
2089
 
                 _control_files=None, a_bzrdir=None, _repository=None,
2090
 
                 ignore_fallbacks=False):
 
2392
                 _control_files=None, a_bzrdir=None, name=None,
 
2393
                 _repository=None, ignore_fallbacks=False):
2091
2394
        """Create new branch object at a particular location."""
2092
2395
        if a_bzrdir is None:
2093
2396
            raise ValueError('a_bzrdir must be supplied')
2094
2397
        else:
2095
2398
            self.bzrdir = a_bzrdir
2096
2399
        self._base = self.bzrdir.transport.clone('..').base
 
2400
        self.name = name
2097
2401
        # XXX: We should be able to just do
2098
2402
        #   self.base = self.bzrdir.root_transport.base
2099
2403
        # but this does not quite work yet -- mbp 20080522
2106
2410
        Branch.__init__(self)
2107
2411
 
2108
2412
    def __str__(self):
2109
 
        return '%s(%r)' % (self.__class__.__name__, self.base)
 
2413
        if self.name is None:
 
2414
            return '%s(%s)' % (self.__class__.__name__, self.user_url)
 
2415
        else:
 
2416
            return '%s(%s,%s)' % (self.__class__.__name__, self.user_url,
 
2417
                self.name)
2110
2418
 
2111
2419
    __repr__ = __str__
2112
2420
 
2123
2431
        return self.control_files.is_locked()
2124
2432
 
2125
2433
    def lock_write(self, token=None):
 
2434
        """Lock the branch for write operations.
 
2435
 
 
2436
        :param token: A token to permit reacquiring a previously held and
 
2437
            preserved lock.
 
2438
        :return: A BranchWriteLockResult.
 
2439
        """
 
2440
        if not self.is_locked():
 
2441
            self._note_lock('w')
2126
2442
        # All-in-one needs to always unlock/lock.
2127
2443
        repo_control = getattr(self.repository, 'control_files', None)
2128
2444
        if self.control_files == repo_control or not self.is_locked():
 
2445
            self.repository._warn_if_deprecated(self)
2129
2446
            self.repository.lock_write()
2130
2447
            took_lock = True
2131
2448
        else:
2132
2449
            took_lock = False
2133
2450
        try:
2134
 
            return self.control_files.lock_write(token=token)
 
2451
            return BranchWriteLockResult(self.unlock,
 
2452
                self.control_files.lock_write(token=token))
2135
2453
        except:
2136
2454
            if took_lock:
2137
2455
                self.repository.unlock()
2138
2456
            raise
2139
2457
 
2140
2458
    def lock_read(self):
 
2459
        """Lock the branch for read operations.
 
2460
 
 
2461
        :return: A bzrlib.lock.LogicalLockResult.
 
2462
        """
 
2463
        if not self.is_locked():
 
2464
            self._note_lock('r')
2141
2465
        # All-in-one needs to always unlock/lock.
2142
2466
        repo_control = getattr(self.repository, 'control_files', None)
2143
2467
        if self.control_files == repo_control or not self.is_locked():
 
2468
            self.repository._warn_if_deprecated(self)
2144
2469
            self.repository.lock_read()
2145
2470
            took_lock = True
2146
2471
        else:
2147
2472
            took_lock = False
2148
2473
        try:
2149
2474
            self.control_files.lock_read()
 
2475
            return LogicalLockResult(self.unlock)
2150
2476
        except:
2151
2477
            if took_lock:
2152
2478
                self.repository.unlock()
2153
2479
            raise
2154
2480
 
 
2481
    @only_raises(errors.LockNotHeld, errors.LockBroken)
2155
2482
    def unlock(self):
2156
2483
        try:
2157
2484
            self.control_files.unlock()
2320
2647
        return result
2321
2648
 
2322
2649
    def get_stacked_on_url(self):
2323
 
        raise errors.UnstackableBranchFormat(self._format, self.base)
 
2650
        raise errors.UnstackableBranchFormat(self._format, self.user_url)
2324
2651
 
2325
2652
    def set_push_location(self, location):
2326
2653
        """See Branch.set_push_location."""
2516
2843
        if _mod_revision.is_null(last_revision):
2517
2844
            return
2518
2845
        if last_revision not in self._lefthand_history(revision_id):
2519
 
            raise errors.AppendRevisionsOnlyViolation(self.base)
 
2846
            raise errors.AppendRevisionsOnlyViolation(self.user_url)
2520
2847
 
2521
2848
    def _gen_revision_history(self):
2522
2849
        """Generate the revision history from last revision
2622
2949
        if branch_location is None:
2623
2950
            return Branch.reference_parent(self, file_id, path,
2624
2951
                                           possible_transports)
2625
 
        branch_location = urlutils.join(self.base, branch_location)
 
2952
        branch_location = urlutils.join(self.user_url, branch_location)
2626
2953
        return Branch.open(branch_location,
2627
2954
                           possible_transports=possible_transports)
2628
2955
 
2674
3001
        return stacked_url
2675
3002
 
2676
3003
    def _get_append_revisions_only(self):
2677
 
        value = self.get_config().get_user_option('append_revisions_only')
2678
 
        return value == 'True'
 
3004
        return self.get_config(
 
3005
            ).get_user_option_as_bool('append_revisions_only')
2679
3006
 
2680
3007
    @needs_write_lock
2681
3008
    def generate_revision_history(self, revision_id, last_rev=None,
2743
3070
    """
2744
3071
 
2745
3072
    def get_stacked_on_url(self):
2746
 
        raise errors.UnstackableBranchFormat(self._format, self.base)
 
3073
        raise errors.UnstackableBranchFormat(self._format, self.user_url)
2747
3074
 
2748
3075
 
2749
3076
######################################################################
2836
3163
        :param verbose: Requests more detailed display of what was checked,
2837
3164
            if any.
2838
3165
        """
2839
 
        note('checked branch %s format %s', self.branch.base,
 
3166
        note('checked branch %s format %s', self.branch.user_url,
2840
3167
            self.branch._format)
2841
3168
        for error in self.errors:
2842
3169
            note('found error:%s', error)
2937
3264
    _optimisers = []
2938
3265
    """The available optimised InterBranch types."""
2939
3266
 
2940
 
    @staticmethod
2941
 
    def _get_branch_formats_to_test():
2942
 
        """Return a tuple with the Branch formats to use when testing."""
2943
 
        raise NotImplementedError(InterBranch._get_branch_formats_to_test)
 
3267
    @classmethod
 
3268
    def _get_branch_formats_to_test(klass):
 
3269
        """Return an iterable of format tuples for testing.
 
3270
        
 
3271
        :return: An iterable of (from_format, to_format) to use when testing
 
3272
            this InterBranch class. Each InterBranch class should define this
 
3273
            method itself.
 
3274
        """
 
3275
        raise NotImplementedError(klass._get_branch_formats_to_test)
2944
3276
 
 
3277
    @needs_write_lock
2945
3278
    def pull(self, overwrite=False, stop_revision=None,
2946
3279
             possible_transports=None, local=False):
2947
3280
        """Mirror source into target branch.
2952
3285
        """
2953
3286
        raise NotImplementedError(self.pull)
2954
3287
 
 
3288
    @needs_write_lock
2955
3289
    def update_revisions(self, stop_revision=None, overwrite=False,
2956
3290
                         graph=None):
2957
3291
        """Pull in new perfect-fit revisions.
2965
3299
        """
2966
3300
        raise NotImplementedError(self.update_revisions)
2967
3301
 
 
3302
    @needs_write_lock
2968
3303
    def push(self, overwrite=False, stop_revision=None,
2969
3304
             _override_hook_source_branch=None):
2970
3305
        """Mirror the source branch into the target branch.
2973
3308
        """
2974
3309
        raise NotImplementedError(self.push)
2975
3310
 
 
3311
    @needs_write_lock
 
3312
    def copy_content_into(self, revision_id=None):
 
3313
        """Copy the content of source into target
 
3314
 
 
3315
        revision_id: if not None, the revision history in the new branch will
 
3316
                     be truncated to end with revision_id.
 
3317
        """
 
3318
        raise NotImplementedError(self.copy_content_into)
 
3319
 
2976
3320
 
2977
3321
class GenericInterBranch(InterBranch):
2978
 
    """InterBranch implementation that uses public Branch functions.
2979
 
    """
2980
 
 
2981
 
    @staticmethod
2982
 
    def _get_branch_formats_to_test():
2983
 
        return BranchFormat._default_format, BranchFormat._default_format
2984
 
 
 
3322
    """InterBranch implementation that uses public Branch functions."""
 
3323
 
 
3324
    @classmethod
 
3325
    def is_compatible(klass, source, target):
 
3326
        # GenericBranch uses the public API, so always compatible
 
3327
        return True
 
3328
 
 
3329
    @classmethod
 
3330
    def _get_branch_formats_to_test(klass):
 
3331
        return [(BranchFormat._default_format, BranchFormat._default_format)]
 
3332
 
 
3333
    @classmethod
 
3334
    def unwrap_format(klass, format):
 
3335
        if isinstance(format, remote.RemoteBranchFormat):
 
3336
            format._ensure_real()
 
3337
            return format._custom_format
 
3338
        return format                                                                                                  
 
3339
 
 
3340
    @needs_write_lock
 
3341
    def copy_content_into(self, revision_id=None):
 
3342
        """Copy the content of source into target
 
3343
 
 
3344
        revision_id: if not None, the revision history in the new branch will
 
3345
                     be truncated to end with revision_id.
 
3346
        """
 
3347
        self.source.update_references(self.target)
 
3348
        self.source._synchronize_history(self.target, revision_id)
 
3349
        try:
 
3350
            parent = self.source.get_parent()
 
3351
        except errors.InaccessibleParent, e:
 
3352
            mutter('parent was not accessible to copy: %s', e)
 
3353
        else:
 
3354
            if parent:
 
3355
                self.target.set_parent(parent)
 
3356
        if self.source._push_should_merge_tags():
 
3357
            self.source.tags.merge_to(self.target.tags)
 
3358
 
 
3359
    @needs_write_lock
2985
3360
    def update_revisions(self, stop_revision=None, overwrite=False,
2986
3361
        graph=None):
2987
3362
        """See InterBranch.update_revisions()."""
2988
 
        self.source.lock_read()
2989
 
        try:
2990
 
            other_revno, other_last_revision = self.source.last_revision_info()
2991
 
            stop_revno = None # unknown
2992
 
            if stop_revision is None:
2993
 
                stop_revision = other_last_revision
2994
 
                if _mod_revision.is_null(stop_revision):
2995
 
                    # if there are no commits, we're done.
2996
 
                    return
2997
 
                stop_revno = other_revno
2998
 
 
2999
 
            # what's the current last revision, before we fetch [and change it
3000
 
            # possibly]
3001
 
            last_rev = _mod_revision.ensure_null(self.target.last_revision())
3002
 
            # we fetch here so that we don't process data twice in the common
3003
 
            # case of having something to pull, and so that the check for
3004
 
            # already merged can operate on the just fetched graph, which will
3005
 
            # be cached in memory.
3006
 
            self.target.fetch(self.source, stop_revision)
3007
 
            # Check to see if one is an ancestor of the other
3008
 
            if not overwrite:
3009
 
                if graph is None:
3010
 
                    graph = self.target.repository.get_graph()
3011
 
                if self.target._check_if_descendant_or_diverged(
3012
 
                        stop_revision, last_rev, graph, self.source):
3013
 
                    # stop_revision is a descendant of last_rev, but we aren't
3014
 
                    # overwriting, so we're done.
3015
 
                    return
3016
 
            if stop_revno is None:
3017
 
                if graph is None:
3018
 
                    graph = self.target.repository.get_graph()
3019
 
                this_revno, this_last_revision = \
3020
 
                        self.target.last_revision_info()
3021
 
                stop_revno = graph.find_distance_to_null(stop_revision,
3022
 
                                [(other_last_revision, other_revno),
3023
 
                                 (this_last_revision, this_revno)])
3024
 
            self.target.set_last_revision_info(stop_revno, stop_revision)
3025
 
        finally:
3026
 
            self.source.unlock()
3027
 
 
 
3363
        other_revno, other_last_revision = self.source.last_revision_info()
 
3364
        stop_revno = None # unknown
 
3365
        if stop_revision is None:
 
3366
            stop_revision = other_last_revision
 
3367
            if _mod_revision.is_null(stop_revision):
 
3368
                # if there are no commits, we're done.
 
3369
                return
 
3370
            stop_revno = other_revno
 
3371
 
 
3372
        # what's the current last revision, before we fetch [and change it
 
3373
        # possibly]
 
3374
        last_rev = _mod_revision.ensure_null(self.target.last_revision())
 
3375
        # we fetch here so that we don't process data twice in the common
 
3376
        # case of having something to pull, and so that the check for
 
3377
        # already merged can operate on the just fetched graph, which will
 
3378
        # be cached in memory.
 
3379
        self.target.fetch(self.source, stop_revision)
 
3380
        # Check to see if one is an ancestor of the other
 
3381
        if not overwrite:
 
3382
            if graph is None:
 
3383
                graph = self.target.repository.get_graph()
 
3384
            if self.target._check_if_descendant_or_diverged(
 
3385
                    stop_revision, last_rev, graph, self.source):
 
3386
                # stop_revision is a descendant of last_rev, but we aren't
 
3387
                # overwriting, so we're done.
 
3388
                return
 
3389
        if stop_revno is None:
 
3390
            if graph is None:
 
3391
                graph = self.target.repository.get_graph()
 
3392
            this_revno, this_last_revision = \
 
3393
                    self.target.last_revision_info()
 
3394
            stop_revno = graph.find_distance_to_null(stop_revision,
 
3395
                            [(other_last_revision, other_revno),
 
3396
                             (this_last_revision, this_revno)])
 
3397
        self.target.set_last_revision_info(stop_revno, stop_revision)
 
3398
 
 
3399
    @needs_write_lock
3028
3400
    def pull(self, overwrite=False, stop_revision=None,
3029
 
             possible_transports=None, _hook_master=None, run_hooks=True,
 
3401
             possible_transports=None, run_hooks=True,
3030
3402
             _override_hook_target=None, local=False):
3031
 
        """See Branch.pull.
 
3403
        """Pull from source into self, updating my master if any.
3032
3404
 
3033
 
        :param _hook_master: Private parameter - set the branch to
3034
 
            be supplied as the master to pull hooks.
3035
3405
        :param run_hooks: Private parameter - if false, this branch
3036
3406
            is being called because it's the master of the primary branch,
3037
3407
            so it should not run its hooks.
3038
 
        :param _override_hook_target: Private parameter - set the branch to be
3039
 
            supplied as the target_branch to pull hooks.
3040
 
        :param local: Only update the local branch, and not the bound branch.
3041
3408
        """
3042
 
        # This type of branch can't be bound.
3043
 
        if local:
 
3409
        bound_location = self.target.get_bound_location()
 
3410
        if local and not bound_location:
3044
3411
            raise errors.LocalRequiresBoundBranch()
3045
 
        result = PullResult()
3046
 
        result.source_branch = self.source
3047
 
        if _override_hook_target is None:
3048
 
            result.target_branch = self.target
3049
 
        else:
3050
 
            result.target_branch = _override_hook_target
3051
 
        self.source.lock_read()
 
3412
        master_branch = None
 
3413
        if not local and bound_location and self.source.user_url != bound_location:
 
3414
            # not pulling from master, so we need to update master.
 
3415
            master_branch = self.target.get_master_branch(possible_transports)
 
3416
            master_branch.lock_write()
3052
3417
        try:
3053
 
            # We assume that during 'pull' the target repository is closer than
3054
 
            # the source one.
3055
 
            self.source.update_references(self.target)
3056
 
            graph = self.target.repository.get_graph(self.source.repository)
3057
 
            # TODO: Branch formats should have a flag that indicates 
3058
 
            # that revno's are expensive, and pull() should honor that flag.
3059
 
            # -- JRV20090506
3060
 
            result.old_revno, result.old_revid = \
3061
 
                self.target.last_revision_info()
3062
 
            self.target.update_revisions(self.source, stop_revision,
3063
 
                overwrite=overwrite, graph=graph)
3064
 
            # TODO: The old revid should be specified when merging tags, 
3065
 
            # so a tags implementation that versions tags can only 
3066
 
            # pull in the most recent changes. -- JRV20090506
3067
 
            result.tag_conflicts = self.source.tags.merge_to(self.target.tags,
3068
 
                overwrite)
3069
 
            result.new_revno, result.new_revid = self.target.last_revision_info()
3070
 
            if _hook_master:
3071
 
                result.master_branch = _hook_master
3072
 
                result.local_branch = result.target_branch
3073
 
            else:
3074
 
                result.master_branch = result.target_branch
3075
 
                result.local_branch = None
3076
 
            if run_hooks:
3077
 
                for hook in Branch.hooks['post_pull']:
3078
 
                    hook(result)
 
3418
            if master_branch:
 
3419
                # pull from source into master.
 
3420
                master_branch.pull(self.source, overwrite, stop_revision,
 
3421
                    run_hooks=False)
 
3422
            return self._pull(overwrite,
 
3423
                stop_revision, _hook_master=master_branch,
 
3424
                run_hooks=run_hooks,
 
3425
                _override_hook_target=_override_hook_target)
3079
3426
        finally:
3080
 
            self.source.unlock()
3081
 
        return result
 
3427
            if master_branch:
 
3428
                master_branch.unlock()
3082
3429
 
3083
3430
    def push(self, overwrite=False, stop_revision=None,
3084
3431
             _override_hook_source_branch=None):
3146
3493
            _run_hooks()
3147
3494
            return result
3148
3495
 
3149
 
    @classmethod
3150
 
    def is_compatible(self, source, target):
3151
 
        # GenericBranch uses the public API, so always compatible
3152
 
        return True
3153
 
 
3154
 
 
3155
 
class InterToBranch5(GenericInterBranch):
3156
 
 
3157
 
    @staticmethod
3158
 
    def _get_branch_formats_to_test():
3159
 
        return BranchFormat._default_format, BzrBranchFormat5()
3160
 
 
3161
 
    def pull(self, overwrite=False, stop_revision=None,
3162
 
             possible_transports=None, run_hooks=True,
 
3496
    def _pull(self, overwrite=False, stop_revision=None,
 
3497
             possible_transports=None, _hook_master=None, run_hooks=True,
3163
3498
             _override_hook_target=None, local=False):
3164
 
        """Pull from source into self, updating my master if any.
3165
 
 
 
3499
        """See Branch.pull.
 
3500
 
 
3501
        This function is the core worker, used by GenericInterBranch.pull to
 
3502
        avoid duplication when pulling source->master and source->local.
 
3503
 
 
3504
        :param _hook_master: Private parameter - set the branch to
 
3505
            be supplied as the master to pull hooks.
3166
3506
        :param run_hooks: Private parameter - if false, this branch
3167
3507
            is being called because it's the master of the primary branch,
3168
3508
            so it should not run its hooks.
 
3509
        :param _override_hook_target: Private parameter - set the branch to be
 
3510
            supplied as the target_branch to pull hooks.
 
3511
        :param local: Only update the local branch, and not the bound branch.
3169
3512
        """
3170
 
        bound_location = self.target.get_bound_location()
3171
 
        if local and not bound_location:
 
3513
        # This type of branch can't be bound.
 
3514
        if local:
3172
3515
            raise errors.LocalRequiresBoundBranch()
3173
 
        master_branch = None
3174
 
        if not local and bound_location and self.source.base != bound_location:
3175
 
            # not pulling from master, so we need to update master.
3176
 
            master_branch = self.target.get_master_branch(possible_transports)
3177
 
            master_branch.lock_write()
 
3516
        result = PullResult()
 
3517
        result.source_branch = self.source
 
3518
        if _override_hook_target is None:
 
3519
            result.target_branch = self.target
 
3520
        else:
 
3521
            result.target_branch = _override_hook_target
 
3522
        self.source.lock_read()
3178
3523
        try:
3179
 
            if master_branch:
3180
 
                # pull from source into master.
3181
 
                master_branch.pull(self.source, overwrite, stop_revision,
3182
 
                    run_hooks=False)
3183
 
            return super(InterToBranch5, self).pull(overwrite,
3184
 
                stop_revision, _hook_master=master_branch,
3185
 
                run_hooks=run_hooks,
3186
 
                _override_hook_target=_override_hook_target)
 
3524
            # We assume that during 'pull' the target repository is closer than
 
3525
            # the source one.
 
3526
            self.source.update_references(self.target)
 
3527
            graph = self.target.repository.get_graph(self.source.repository)
 
3528
            # TODO: Branch formats should have a flag that indicates 
 
3529
            # that revno's are expensive, and pull() should honor that flag.
 
3530
            # -- JRV20090506
 
3531
            result.old_revno, result.old_revid = \
 
3532
                self.target.last_revision_info()
 
3533
            self.target.update_revisions(self.source, stop_revision,
 
3534
                overwrite=overwrite, graph=graph)
 
3535
            # TODO: The old revid should be specified when merging tags, 
 
3536
            # so a tags implementation that versions tags can only 
 
3537
            # pull in the most recent changes. -- JRV20090506
 
3538
            result.tag_conflicts = self.source.tags.merge_to(self.target.tags,
 
3539
                overwrite)
 
3540
            result.new_revno, result.new_revid = self.target.last_revision_info()
 
3541
            if _hook_master:
 
3542
                result.master_branch = _hook_master
 
3543
                result.local_branch = result.target_branch
 
3544
            else:
 
3545
                result.master_branch = result.target_branch
 
3546
                result.local_branch = None
 
3547
            if run_hooks:
 
3548
                for hook in Branch.hooks['post_pull']:
 
3549
                    hook(result)
3187
3550
        finally:
3188
 
            if master_branch:
3189
 
                master_branch.unlock()
 
3551
            self.source.unlock()
 
3552
        return result
3190
3553
 
3191
3554
 
3192
3555
InterBranch.register_optimiser(GenericInterBranch)
3193
 
InterBranch.register_optimiser(InterToBranch5)