~bzr-pqm/bzr/bzr.dev

# Copyright (C) 2005, 2006, 2007, 2008, 2009 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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

import sys

from bzrlib.lazy_import import lazy_import

lazy_import(globals(), """

from itertools import chain

from bzrlib import (

        bzrdir,

        cache_utf8,

        config as _mod_config,

        debug,

        errors,

        lockdir,

        lockable_files,

        repository,

        revision as _mod_revision,

        symbol_versioning,

        transport,

        tsort,

        ui,

        urlutils,

        )

from bzrlib.config import BranchConfig

from bzrlib.repofmt.pack_repo import RepositoryFormatKnitPack5RichRoot

from bzrlib.tag import (

    BasicTags,

    DisabledTags,

    )

""")

from bzrlib.decorators import needs_read_lock, needs_write_lock

from bzrlib.hooks import HookPoint, Hooks

from bzrlib.inter import InterObject

from bzrlib import registry

from bzrlib.symbol_versioning import (

    deprecated_in,

    deprecated_method,

    )

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

BZR_BRANCH_FORMAT_4 = "Bazaar-NG branch, format 0.0.4\n"

BZR_BRANCH_FORMAT_5 = "Bazaar-NG branch, format 5\n"

BZR_BRANCH_FORMAT_6 = "Bazaar Branch Format 6 (bzr 0.15)\n"

# TODO: Maybe include checks for common corruption of newlines, etc?

# TODO: Some operations like log might retrieve the same revisions

# repeatedly to calculate deltas.  We could perhaps have a weakref

# cache in memory to make this faster.  In general anything can be

# cached in memory between lock and unlock operations. .. nb thats

# what the transaction identity map provides

######################################################################

# branch objects

class Branch(object):

    """Branch holding a history of revisions.

    base

        Base directory/url of the branch.

    hooks: An instance of BranchHooks.

    """

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

    # - RBC 20060112

    base = None

    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._last_revision_info_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 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()

    @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)

    @staticmethod

    def open_from_transport(transport, _unsupported=False):

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

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

        return control.open_branch(_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):

        return BranchConfig(self)

    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.

        """

        return self._transport.get_bytes('tags')

    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 is not None:

                    # return the master branch value

                    return master.nick

            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):

        raise NotImplementedError(self.lock_write)

    def lock_read(self):

        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

        :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()

            graph = self.repository.get_graph()

            parent_map = dict(((key, value) for key, value in

                     graph.iter_ancestry([last_revision]) if value is not None))

            revision_graph = repository._strip_NULL_ghosts(parent_map)

            revs = tsort.merge_sort(revision_graph, last_revision, None,

                generate_revno=True)

            # Drop the sequence # before caching

            self._merge_sorted_revisions_cache = [r[1:] for r in revs]

        filtered = self._filter_merge_sorted_revisions(

            self._merge_sorted_revisions_cache, start_revision_id,

            stop_revision_id, stop_rule)

        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 rev_id, depth, revno, end_of_merge in rev_iter:

                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

                    rev_iter = chain(

                        iter([(rev_id, depth, revno, end_of_merge)]),

                        rev_iter)

                    break

        if stop_revision_id is None:

            for rev_id, depth, revno, end_of_merge in rev_iter:

                yield rev_id, depth, revno, end_of_merge

        elif stop_rule == 'exclude':

            for rev_id, depth, revno, end_of_merge in rev_iter:

                if rev_id == stop_revision_id:

                    return

                yield rev_id, depth, revno, end_of_merge

        elif stop_rule == 'include':

            for rev_id, depth, revno, end_of_merge in rev_iter:

                yield rev_id, depth, revno, end_of_merge

                if rev_id == stop_revision_id:

                    return

        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

            for rev_id, depth, revno, end_of_merge in rev_iter:

                if rev_id == left_parent:

                    return

                yield rev_id, depth, revno, end_of_merge

        else:

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

    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.base)

    @needs_write_lock

    def fetch(self, from_branch, last_revision=None, pb=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 pb: An optional progress bar to use.

        :return: None

        """

        if self.base == from_branch.base:

            return (0, [])

        if pb is not None:

            symbol_versioning.warn(

                symbol_versioning.deprecated_in((1, 14, 0))

                % "pb parameter to fetch()")

        from_branch.lock_read()

        try:

            if last_revision is None:

                last_revision = from_branch.last_revision()

                last_revision = _mod_revision.ensure_null(last_revision)

            return self.repository.fetch(from_branch.repository,

                                         revision_id=last_revision,

                                         pb=pb)

        finally:

            from_branch.unlock()

    def get_bound_location(self):

        """Return the URL of the branch we are bound to.

        Older format branches cannot bind, please be sure to use a metadir

        branch.

        """

        return None

    def get_old_bound_location(self):

        """Return the URL of the branch we used to be bound to

        """

        raise errors.UpgradeRequired(self.base)

    def get_commit_builder(self, parents, config=None, timestamp=None,

                           timezone=None, committer=None, revprops=None,

                           revision_id=None):

        """Obtain a CommitBuilder for this branch.

        :param parents: Revision ids of the parents of the new revision.

        :param config: Optional configuration to use.

        :param timestamp: Optional timestamp recorded for commit.

        :param timezone: Optional timezone for timestamp.

        :param committer: Optional committer to set for commit.

        :param revprops: Optional dictionary of revision properties.

        :param revision_id: Optional revision id.

        """

        if config is None:

            config = self.get_config()

        return self.repository.get_commit_builder(self, parents, config,

            timestamp, timezone, committer, revprops, revision_id)

    def get_master_branch(self, possible_transports=None):

        """Return the branch we are bound to.

        :return: Either a Branch, or None

        """

        return None

    def get_revision_delta(self, revno):

        """Return the delta for one revision.

        The delta is relative to its mainline predecessor, or the

        empty tree for revision 1.

        """

        rh = self.revision_history()

        if not (1 <= revno <= len(rh)):

            raise errors.InvalidRevisionNumber(revno)

        return self.repository.get_revision_delta(rh[revno-1])

    def get_stacked_on_url(self):

        """Get the URL this branch is stacked against.

        :raises NotStacked: If the branch is not stacked.

        :raises UnstackableBranchFormat: If the branch does not support

            stacking.

        """

        raise NotImplementedError(self.get_stacked_on_url)

    def print_file(self, file, revision_id):

        """Print `file` to stdout."""

        raise NotImplementedError(self.print_file)

    def set_revision_history(self, rev_history):

        raise NotImplementedError(self.set_revision_history)

    def set_stacked_on_url(self, url):

        """Set the URL this branch is stacked against.

        :raises UnstackableBranchFormat: If the branch does not support

            stacking.

        :raises UnstackableRepositoryFormat: If the repository does not support

            stacking.

        """

        raise NotImplementedError(self.set_stacked_on_url)

    def _set_tags_bytes(self, bytes):

        """Mirror method for _get_tags_bytes.

        :seealso: Branch._get_tags_bytes.

        """

        return _run_with_write_locked_target(self, self._transport.put_bytes,

            'tags', bytes)

    def _cache_revision_history(self, rev_history):

        """Set the cached revision history to rev_history.

        The revision_history method will use this cache to avoid regenerating

        the revision history.

        This API is semi-public; it only for use by subclasses, all other code

        should consider it to be private.

        """

        self._revision_history_cache = rev_history

    def _cache_revision_id_to_revno(self, revision_id_to_revno):

        """Set the cached revision_id => revno map to revision_id_to_revno.

        This API is semi-public; it only for use by subclasses, all other code

        should consider it to be private.

        """

        self._revision_id_to_revno_cache = revision_id_to_revno

    def _clear_cached_state(self):

        """Clear any cached data on this branch, e.g. cached revision history.

        This means the next call to revision_history will need to call

        _gen_revision_history.

        This API is semi-public; it only for use by subclasses, all other code

        should consider it to be private.

        """

        self._revision_history_cache = None

        self._revision_id_to_revno_cache = None

        self._last_revision_info_cache = None

        self._merge_sorted_revisions_cache = None

    def _gen_revision_history(self):

        """Return sequence of revision hashes on to this branch.

        Unlike revision_history, this method always regenerates or rereads the

        revision history, i.e. it does not cache the result, so repeated calls

        may be expensive.

        Concrete subclasses should override this instead of revision_history so

        that subclasses do not need to deal with caching logic.

        This API is semi-public; it only for use by subclasses, all other code

        should consider it to be private.

        """

        raise NotImplementedError(self._gen_revision_history)

    @needs_read_lock

    def revision_history(self):

        """Return sequence of revision ids on this branch.

        This method will cache the revision history for as long as it is safe to

        do so.

        """

        if 'evil' in debug.debug_flags:

            mutter_callsite(3, "revision_history scales with history.")

        if self._revision_history_cache is not None:

            history = self._revision_history_cache

        else:

            history = self._gen_revision_history()

            self._cache_revision_history(history)

        return list(history)

    def revno(self):

        """Return current revision number for this branch.

        That is equivalent to the number of revisions committed to

        this branch.

        """

        return self.last_revision_info()[0]

    def unbind(self):

        """Older format branches cannot bind or unbind."""

        raise errors.UpgradeRequired(self.base)

    def set_append_revisions_only(self, enabled):

        """Older format branches are never restricted to append-only"""

        raise errors.UpgradeRequired(self.base)

    def last_revision(self):

        """Return last revision id, or NULL_REVISION."""

        return self.last_revision_info()[1]

    @needs_read_lock

    def last_revision_info(self):

        """Return information about the last revision.

        :return: A tuple (revno, revision_id).

        """

        if self._last_revision_info_cache is None:

            self._last_revision_info_cache = self._last_revision_info()

        return self._last_revision_info_cache

    def _last_revision_info(self):

        rh = self.revision_history()

        revno = len(rh)

        if revno:

            return (revno, rh[-1])

        else:

            return (0, _mod_revision.NULL_REVISION)

    @deprecated_method(deprecated_in((1, 6, 0)))

    def missing_revisions(self, other, stop_revision=None):

        """Return a list of new revisions that would perfectly fit.

        If self and other have not diverged, return a list of the revisions

        present in other, but missing from self.

        """

        self_history = self.revision_history()

        self_len = len(self_history)

        other_history = other.revision_history()

        other_len = len(other_history)

        common_index = min(self_len, other_len) -1

        if common_index >= 0 and \

            self_history[common_index] != other_history[common_index]:

            raise errors.DivergedBranches(self, other)

        if stop_revision is None:

            stop_revision = other_len

        else:

            if stop_revision > other_len:

                raise errors.NoSuchRevision(self, stop_revision)