~bzr-pqm/bzr/bzr.dev

# Copyright (C) 2005-2011 Canonical Ltd

#

# This program is free software; you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation; either version 2 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program; if not, write to the Free Software

# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

from cStringIO import StringIO

from bzrlib.lazy_import import lazy_import

lazy_import(globals(), """

import itertools

from bzrlib import (

        bzrdir,

        cache_utf8,

        cleanup,

        config as _mod_config,

        debug,

        errors,

        fetch,

        graph as _mod_graph,

        lockdir,

        lockable_files,

        remote,

        repository,

        revision as _mod_revision,

        rio,

        tag as _mod_tag,

        transport,

        ui,

        urlutils,

        )

from bzrlib.i18n import gettext, ngettext

""")

from bzrlib import (

    controldir,

    )

from bzrlib.decorators import (

    needs_read_lock,

    needs_write_lock,

    only_raises,

    )

from bzrlib.hooks import Hooks

from bzrlib.inter import InterObject

from bzrlib.lock import _RelockDebugMixin, LogicalLockResult

from bzrlib import registry

from bzrlib.symbol_versioning import (

    deprecated_in,

    deprecated_method,

    )

from bzrlib.trace import mutter, mutter_callsite, note, is_quiet

class Branch(controldir.ControlComponent):

    """Branch holding a history of revisions.

    :ivar base:

        Base directory/url of the branch; using control_url and

        control_transport is more standardized.

    :ivar hooks: An instance of BranchHooks.

    :ivar _master_branch_cache: cached result of get_master_branch, see

        _clear_cached_state.

    """

    # this is really an instance variable - FIXME move it there

    # - RBC 20060112

    base = None

    @property

    def control_transport(self):

        return self._transport

    @property

    def user_transport(self):

        return self.bzrdir.user_transport

    def __init__(self, *ignored, **ignored_too):

        self.tags = self._format.make_tags(self)

        self._revision_history_cache = None

        self._revision_id_to_revno_cache = None

        self._partial_revision_id_to_revno_cache = {}

        self._partial_revision_history_cache = []

        self._tags_bytes = None

        self._last_revision_info_cache = None

        self._master_branch_cache = None

        self._merge_sorted_revisions_cache = None

        self._open_hook()

        hooks = Branch.hooks['open']

        for hook in hooks:

            hook(self)

    def _open_hook(self):

        """Called by init to allow simpler extension of the base class."""

    def _activate_fallback_location(self, url):

        """Activate the branch/repository from url as a fallback repository."""

        for existing_fallback_repo in self.repository._fallback_repositories:

            if existing_fallback_repo.user_url == url:

                # This fallback is already configured.  This probably only

                # happens because BzrDir.sprout is a horrible mess.  To avoid

                # confusing _unstack we don't add this a second time.

                mutter('duplicate activation of fallback %r on %r', url, self)

                return

        repo = self._get_fallback_repository(url)

        if repo.has_same_location(self.repository):

            raise errors.UnstackableLocationError(self.user_url, url)

        self.repository.add_fallback_repository(repo)

    def break_lock(self):

        """Break a lock if one is present from another instance.

        Uses the ui factory to ask for confirmation if the lock may be from

        an active process.

        This will probe the repository for its lock as well.

        """

        self.control_files.break_lock()

        self.repository.break_lock()

        master = self.get_master_branch()

        if master is not None:

            master.break_lock()

    def _check_stackable_repo(self):

        if not self.repository._format.supports_external_lookups:

            raise errors.UnstackableRepositoryFormat(self.repository._format,

                self.repository.base)

    def _extend_partial_history(self, stop_index=None, stop_revision=None):

        """Extend the partial history to include a given index

        If a stop_index is supplied, stop when that index has been reached.

        If a stop_revision is supplied, stop when that revision is

        encountered.  Otherwise, stop when the beginning of history is

        reached.

        :param stop_index: The index which should be present.  When it is

            present, history extension will stop.

        :param stop_revision: The revision id which should be present.  When

            it is encountered, history extension will stop.

        """

        if len(self._partial_revision_history_cache) == 0:

            self._partial_revision_history_cache = [self.last_revision()]

        repository._iter_for_revno(

            self.repository, self._partial_revision_history_cache,

            stop_index=stop_index, stop_revision=stop_revision)

        if self._partial_revision_history_cache[-1] == _mod_revision.NULL_REVISION:

            self._partial_revision_history_cache.pop()

    def _get_check_refs(self):

        """Get the references needed for check().

        See bzrlib.check.

        """

        revid = self.last_revision()

        return [('revision-existence', revid), ('lefthand-distance', revid)]

    @staticmethod

    def open(base, _unsupported=False, possible_transports=None):

        """Open the branch rooted at base.

        For instance, if the branch is at URL/.bzr/branch,

        Branch.open(URL) -> a Branch instance.

        """

        control = bzrdir.BzrDir.open(base, _unsupported,

                                     possible_transports=possible_transports)

        return control.open_branch(unsupported=_unsupported)

    @staticmethod

    def open_from_transport(transport, name=None, _unsupported=False):

        """Open the branch rooted at transport"""

        control = bzrdir.BzrDir.open_from_transport(transport, _unsupported)

        return control.open_branch(name=name, unsupported=_unsupported)

    @staticmethod

    def open_containing(url, possible_transports=None):

        """Open an existing branch which contains url.

        This probes for a branch at url, and searches upwards from there.

        Basically we keep looking up until we find the control directory or

        run into the root.  If there isn't one, raises NotBranchError.

        If there is one and it is either an unrecognised format or an unsupported

        format, UnknownFormatError or UnsupportedFormatError are raised.

        If there is one, it is returned, along with the unused portion of url.

        """

        control, relpath = bzrdir.BzrDir.open_containing(url,

                                                         possible_transports)

        return control.open_branch(), relpath

    def _push_should_merge_tags(self):

        """Should _basic_push merge this branch's tags into the target?

        The default implementation returns False if this branch has no tags,

        and True the rest of the time.  Subclasses may override this.

        """

        return self.supports_tags() and self.tags.get_tag_dict()

    def get_config(self):

        """Get a bzrlib.config.BranchConfig for this Branch.

        This can then be used to get and set configuration options for the

        branch.

        :return: A bzrlib.config.BranchConfig.

        """

        return _mod_config.BranchConfig(self)

    def get_config_stack(self):

        """Get a bzrlib.config.BranchStack for this Branch.

        This can then be used to get and set configuration options for the

        branch.

        :return: A bzrlib.config.BranchStack.

        """

        return _mod_config.BranchStack(self)

    def _get_config(self):

        """Get the concrete config for just the config in this branch.

        This is not intended for client use; see Branch.get_config for the

        public API.

        Added in 1.14.

        :return: An object supporting get_option and set_option.

        """

        raise NotImplementedError(self._get_config)

    def _get_fallback_repository(self, url):

        """Get the repository we fallback to at url."""

        url = urlutils.join(self.base, url)

        a_branch = Branch.open(url,

            possible_transports=[self.bzrdir.root_transport])

        return a_branch.repository

    @needs_read_lock

    def _get_tags_bytes(self):

        """Get the bytes of a serialised tags dict.

        Note that not all branches support tags, nor do all use the same tags

        logic: this method is specific to BasicTags. Other tag implementations

        may use the same method name and behave differently, safely, because

        of the double-dispatch via

        format.make_tags->tags_instance->get_tags_dict.

        :return: The bytes of the tags file.

        :seealso: Branch._set_tags_bytes.

        """

        if self._tags_bytes is None:

            self._tags_bytes = self._transport.get_bytes('tags')

        return self._tags_bytes

    def _get_nick(self, local=False, possible_transports=None):

        config = self.get_config()

        # explicit overrides master, but don't look for master if local is True

        if not local and not config.has_explicit_nickname():

            try:

                master = self.get_master_branch(possible_transports)

                if master and self.user_url == master.user_url:

                    raise errors.RecursiveBind(self.user_url)

                if master is not None:

                    # return the master branch value

                    return master.nick

            except errors.RecursiveBind, e:

                raise e

            except errors.BzrError, e:

                # Silently fall back to local implicit nick if the master is

                # unavailable

                mutter("Could not connect to bound branch, "

                    "falling back to local nick.\n " + str(e))

        return config.get_nickname()

    def _set_nick(self, nick):

        self.get_config().set_user_option('nickname', nick, warn_masked=True)

    nick = property(_get_nick, _set_nick)

    def is_locked(self):

        raise NotImplementedError(self.is_locked)

    def _lefthand_history(self, revision_id, last_rev=None,

                          other_branch=None):

        if 'evil' in debug.debug_flags:

            mutter_callsite(4, "_lefthand_history scales with history.")

        # stop_revision must be a descendant of last_revision

        graph = self.repository.get_graph()

        if last_rev is not None:

            if not graph.is_ancestor(last_rev, revision_id):

                # our previous tip is not merged into stop_revision

                raise errors.DivergedBranches(self, other_branch)

        # make a new revision history from the graph

        parents_map = graph.get_parent_map([revision_id])

        if revision_id not in parents_map:

            raise errors.NoSuchRevision(self, revision_id)

        current_rev_id = revision_id

        new_history = []

        check_not_reserved_id = _mod_revision.check_not_reserved_id

        # Do not include ghosts or graph origin in revision_history

        while (current_rev_id in parents_map and

               len(parents_map[current_rev_id]) > 0):

            check_not_reserved_id(current_rev_id)

            new_history.append(current_rev_id)

            current_rev_id = parents_map[current_rev_id][0]

            parents_map = graph.get_parent_map([current_rev_id])

        new_history.reverse()

        return new_history

    def lock_write(self, token=None):

        """Lock the branch for write operations.

        :param token: A token to permit reacquiring a previously held and

            preserved lock.

        :return: A BranchWriteLockResult.

        """

        raise NotImplementedError(self.lock_write)

    def lock_read(self):

        """Lock the branch for read operations.

        :return: A bzrlib.lock.LogicalLockResult.

        """

        raise NotImplementedError(self.lock_read)

    def unlock(self):

        raise NotImplementedError(self.unlock)

    def peek_lock_mode(self):

        """Return lock mode for the Branch: 'r', 'w' or None"""

        raise NotImplementedError(self.peek_lock_mode)

    def get_physical_lock_status(self):

        raise NotImplementedError(self.get_physical_lock_status)

    @needs_read_lock

    def dotted_revno_to_revision_id(self, revno, _cache_reverse=False):

        """Return the revision_id for a dotted revno.

        :param revno: a tuple like (1,) or (1,1,2)

        :param _cache_reverse: a private parameter enabling storage

           of the reverse mapping in a top level cache. (This should

           only be done in selective circumstances as we want to

           avoid having the mapping cached multiple times.)

        :return: the revision_id

        :raises errors.NoSuchRevision: if the revno doesn't exist

        """

        rev_id = self._do_dotted_revno_to_revision_id(revno)

        if _cache_reverse:

            self._partial_revision_id_to_revno_cache[rev_id] = revno

        return rev_id

    def _do_dotted_revno_to_revision_id(self, revno):

        """Worker function for dotted_revno_to_revision_id.

        Subclasses should override this if they wish to

        provide a more efficient implementation.

        """

        if len(revno) == 1:

            return self.get_rev_id(revno[0])

        revision_id_to_revno = self.get_revision_id_to_revno_map()

        revision_ids = [revision_id for revision_id, this_revno

                        in revision_id_to_revno.iteritems()

                        if revno == this_revno]

        if len(revision_ids) == 1:

            return revision_ids[0]

        else:

            revno_str = '.'.join(map(str, revno))

            raise errors.NoSuchRevision(self, revno_str)

    @needs_read_lock

    def revision_id_to_dotted_revno(self, revision_id):

        """Given a revision id, return its dotted revno.

        :return: a tuple like (1,) or (400,1,3).

        """

        return self._do_revision_id_to_dotted_revno(revision_id)

    def _do_revision_id_to_dotted_revno(self, revision_id):

        """Worker function for revision_id_to_revno."""

        # Try the caches if they are loaded

        result = self._partial_revision_id_to_revno_cache.get(revision_id)

        if result is not None:

            return result

        if self._revision_id_to_revno_cache:

            result = self._revision_id_to_revno_cache.get(revision_id)

            if result is None:

                raise errors.NoSuchRevision(self, revision_id)

        # Try the mainline as it's optimised

        try:

            revno = self.revision_id_to_revno(revision_id)

            return (revno,)

        except errors.NoSuchRevision:

            # We need to load and use the full revno map after all

            result = self.get_revision_id_to_revno_map().get(revision_id)

            if result is None:

                raise errors.NoSuchRevision(self, revision_id)

        return result

    @needs_read_lock

    def get_revision_id_to_revno_map(self):

        """Return the revision_id => dotted revno map.

        This will be regenerated on demand, but will be cached.

        :return: A dictionary mapping revision_id => dotted revno.

            This dictionary should not be modified by the caller.

        """

        if self._revision_id_to_revno_cache is not None:

            mapping = self._revision_id_to_revno_cache

        else:

            mapping = self._gen_revno_map()

            self._cache_revision_id_to_revno(mapping)

        # TODO: jam 20070417 Since this is being cached, should we be returning

        #       a copy?

        # I would rather not, and instead just declare that users should not

        # modify the return value.

        return mapping

    def _gen_revno_map(self):

        """Create a new mapping from revision ids to dotted revnos.

        Dotted revnos are generated based on the current tip in the revision

        history.

        This is the worker function for get_revision_id_to_revno_map, which

        just caches the return value.

        :return: A dictionary mapping revision_id => dotted revno.

        """

        revision_id_to_revno = dict((rev_id, revno)

            for rev_id, depth, revno, end_of_merge

             in self.iter_merge_sorted_revisions())

        return revision_id_to_revno

    @needs_read_lock

    def iter_merge_sorted_revisions(self, start_revision_id=None,

            stop_revision_id=None, stop_rule='exclude', direction='reverse'):

        """Walk the revisions for a branch in merge sorted order.

        Merge sorted order is the output from a merge-aware,

        topological sort, i.e. all parents come before their

        children going forward; the opposite for reverse.

        :param start_revision_id: the revision_id to begin walking from.

            If None, the branch tip is used.

        :param stop_revision_id: the revision_id to terminate the walk

            after. If None, the rest of history is included.

        :param stop_rule: if stop_revision_id is not None, the precise rule

            to use for termination:

            * 'exclude' - leave the stop revision out of the result (default)

            * 'include' - the stop revision is the last item in the result

            * 'with-merges' - include the stop revision and all of its

              merged revisions in the result

            * 'with-merges-without-common-ancestry' - filter out revisions 

              that are in both ancestries

        :param direction: either 'reverse' or 'forward':

            * reverse means return the start_revision_id first, i.e.

              start at the most recent revision and go backwards in history

            * forward returns tuples in the opposite order to reverse.

              Note in particular that forward does *not* do any intelligent

              ordering w.r.t. depth as some clients of this API may like.

              (If required, that ought to be done at higher layers.)

        :return: an iterator over (revision_id, depth, revno, end_of_merge)

            tuples where:

            * revision_id: the unique id of the revision

            * depth: How many levels of merging deep this node has been

              found.

            * revno_sequence: This field provides a sequence of

              revision numbers for all revisions. The format is:

              (REVNO, BRANCHNUM, BRANCHREVNO). BRANCHNUM is the number of the

              branch that the revno is on. From left to right the REVNO numbers

              are the sequence numbers within that branch of the revision.

            * end_of_merge: When True the next node (earlier in history) is

              part of a different merge.

        """

        # Note: depth and revno values are in the context of the branch so

        # we need the full graph to get stable numbers, regardless of the

        # start_revision_id.

        if self._merge_sorted_revisions_cache is None:

            last_revision = self.last_revision()

            known_graph = self.repository.get_known_graph_ancestry(

                [last_revision])

            self._merge_sorted_revisions_cache = known_graph.merge_sort(

                last_revision)

        filtered = self._filter_merge_sorted_revisions(

            self._merge_sorted_revisions_cache, start_revision_id,

            stop_revision_id, stop_rule)

        # Make sure we don't return revisions that are not part of the

        # start_revision_id ancestry.

        filtered = self._filter_start_non_ancestors(filtered)

        if direction == 'reverse':

            return filtered

        if direction == 'forward':

            return reversed(list(filtered))

        else:

            raise ValueError('invalid direction %r' % direction)

    def _filter_merge_sorted_revisions(self, merge_sorted_revisions,

        start_revision_id, stop_revision_id, stop_rule):

        """Iterate over an inclusive range of sorted revisions."""

        rev_iter = iter(merge_sorted_revisions)

        if start_revision_id is not None:

            for node in rev_iter:

                rev_id = node.key

                if rev_id != start_revision_id:

                    continue

                else:

                    # The decision to include the start or not

                    # depends on the stop_rule if a stop is provided

                    # so pop this node back into the iterator

                    rev_iter = itertools.chain(iter([node]), rev_iter)

                    break

        if stop_revision_id is None:

            # Yield everything

            for node in rev_iter:

                rev_id = node.key

                yield (rev_id, node.merge_depth, node.revno,

                       node.end_of_merge)

        elif stop_rule == 'exclude':

            for node in rev_iter:

                rev_id = node.key

                if rev_id == stop_revision_id:

                    return

                yield (rev_id, node.merge_depth, node.revno,

                       node.end_of_merge)

        elif stop_rule == 'include':

            for node in rev_iter:

                rev_id = node.key

                yield (rev_id, node.merge_depth, node.revno,

                       node.end_of_merge)

                if rev_id == stop_revision_id:

                    return

        elif stop_rule == 'with-merges-without-common-ancestry':

            # We want to exclude all revisions that are already part of the

            # stop_revision_id ancestry.

            graph = self.repository.get_graph()

            ancestors = graph.find_unique_ancestors(start_revision_id,

                                                    [stop_revision_id])

            for node in rev_iter:

                rev_id = node.key

                if rev_id not in ancestors:

                    continue

                yield (rev_id, node.merge_depth, node.revno,

                       node.end_of_merge)

        elif stop_rule == 'with-merges':

            stop_rev = self.repository.get_revision(stop_revision_id)

            if stop_rev.parent_ids:

                left_parent = stop_rev.parent_ids[0]

            else:

                left_parent = _mod_revision.NULL_REVISION

            # left_parent is the actual revision we want to stop logging at,

            # since we want to show the merged revisions after the stop_rev too

            reached_stop_revision_id = False

            revision_id_whitelist = []

            for node in rev_iter:

                rev_id = node.key

                if rev_id == left_parent:

                    # reached the left parent after the stop_revision

                    return

                if (not reached_stop_revision_id or

                        rev_id in revision_id_whitelist):

                    yield (rev_id, node.merge_depth, node.revno,

                       node.end_of_merge)

                    if reached_stop_revision_id or rev_id == stop_revision_id:

                        # only do the merged revs of rev_id from now on

                        rev = self.repository.get_revision(rev_id)

                        if rev.parent_ids:

                            reached_stop_revision_id = True

                            revision_id_whitelist.extend(rev.parent_ids)

        else:

            raise ValueError('invalid stop_rule %r' % stop_rule)

    def _filter_start_non_ancestors(self, rev_iter):

        # If we started from a dotted revno, we want to consider it as a tip

        # and don't want to yield revisions that are not part of its

        # ancestry. Given the order guaranteed by the merge sort, we will see

        # uninteresting descendants of the first parent of our tip before the

        # tip itself.

        first = rev_iter.next()

        (rev_id, merge_depth, revno, end_of_merge) = first

        yield first

        if not merge_depth:

            # We start at a mainline revision so by definition, all others

            # revisions in rev_iter are ancestors

            for node in rev_iter:

                yield node

        clean = False

        whitelist = set()

        pmap = self.repository.get_parent_map([rev_id])

        parents = pmap.get(rev_id, [])

        if parents:

            whitelist.update(parents)

        else:

            # If there is no parents, there is nothing of interest left

            # FIXME: It's hard to test this scenario here as this code is never

            # called in that case. -- vila 20100322

            return

        for (rev_id, merge_depth, revno, end_of_merge) in rev_iter:

            if not clean:

                if rev_id in whitelist:

                    pmap = self.repository.get_parent_map([rev_id])

                    parents = pmap.get(rev_id, [])

                    whitelist.remove(rev_id)

                    whitelist.update(parents)

                    if merge_depth == 0:

                        # We've reached the mainline, there is nothing left to

                        # filter

                        clean = True

                else:

                    # A revision that is not part of the ancestry of our

                    # starting revision.

                    continue

            yield (rev_id, merge_depth, revno, end_of_merge)

    def leave_lock_in_place(self):

        """Tell this branch object not to release the physical lock when this

        object is unlocked.

        If lock_write doesn't return a token, then this method is not supported.

        """

        self.control_files.leave_in_place()

    def dont_leave_lock_in_place(self):

        """Tell this branch object to release the physical lock when this

        object is unlocked, even if it didn't originally acquire it.

        If lock_write doesn't return a token, then this method is not supported.

        """

        self.control_files.dont_leave_in_place()

    def bind(self, other):

        """Bind the local branch the other branch.

        :param other: The branch to bind to

        :type other: Branch

        """

        raise errors.UpgradeRequired(self.user_url)

    def get_append_revisions_only(self):

        """Whether it is only possible to append revisions to the history.

        """

        if not self._format.supports_set_append_revisions_only():

            return False

        return self.get_config(

            ).get_user_option_as_bool('append_revisions_only')

    def set_append_revisions_only(self, enabled):

        if not self._format.supports_set_append_revisions_only():

            raise errors.UpgradeRequired(self.user_url)

        if enabled:

            value = 'True'

        else:

            value = 'False'

        self.get_config().set_user_option('append_revisions_only', value,

            warn_masked=True)

    def set_reference_info(self, file_id, tree_path, branch_location):

        """Set the branch location to use for a tree reference."""

        raise errors.UnsupportedOperation(self.set_reference_info, self)

    def get_reference_info(self, file_id):

        """Get the tree_path and branch_location for a tree reference."""

        raise errors.UnsupportedOperation(self.get_reference_info, self)

    @needs_write_lock

    def fetch(self, from_branch, last_revision=None, limit=None):

        """Copy revisions from from_branch into this branch.

        :param from_branch: Where to copy from.

        :param last_revision: What revision to stop at (None for at the end

                              of the branch.

        :param limit: Optional rough limit of revisions to fetch

        :return: None