← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/revision.py

  • Committer: Patch Queue Manager
  • Date: 2011-09-22 14:12:18 UTC
  • mfrom: (6155.3.1 jam)
  • Revision ID: pqm@pqm.ubuntu.com-20110922141218-86s4uu6nqvourw4f
(jameinel) Cleanup comments bzrlib/smart/__init__.py (John A Meinel)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/revision.py
1
 
# Copyright (C) 2005, 2006 Canonical
 
1
# Copyright (C) 2005-2011 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
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
 
# TODO: Some kind of command-line display of revision properties: 
 
17
# TODO: Some kind of command-line display of revision properties:
18
18
# perhaps show them in log -v and allow them as options to the commit command.
19
19
 
20
20
 
21
 
import bzrlib.errors as errors
22
 
from bzrlib.graph import node_distances, select_farthest, all_descendants, Graph
 
21
from bzrlib.lazy_import import lazy_import
 
22
lazy_import(globals(), """
 
23
from bzrlib import bugtracker
 
24
""")
 
25
from bzrlib import (
 
26
    errors,
 
27
    symbol_versioning,
 
28
    )
23
29
from bzrlib.osutils import contains_whitespace
24
 
from bzrlib.progress import DummyProgress
25
 
from bzrlib.symbol_versioning import (deprecated_function,
26
 
        zero_eight,
27
 
        )
28
30
 
29
31
NULL_REVISION="null:"
 
32
CURRENT_REVISION="current:"
 
33
 
30
34
 
31
35
class Revision(object):
32
36
    """Single revision on a branch.
42
46
 
43
47
    properties
44
48
        Dictionary of revision properties.  These are attached to the
45
 
        revision as extra metadata.  The name must be a single 
 
49
        revision as extra metadata.  The name must be a single
46
50
        word; the value can be an arbitrary string.
47
51
    """
48
 
    
 
52
 
49
53
    def __init__(self, revision_id, properties=None, **args):
50
54
        self.revision_id = revision_id
51
 
        self.properties = properties or {}
52
 
        self._check_properties()
 
55
        if properties is None:
 
56
            self.properties = {}
 
57
        else:
 
58
            self.properties = properties
 
59
            self._check_properties()
 
60
        self.committer = None
53
61
        self.parent_ids = []
54
62
        self.parent_sha1s = []
55
63
        """Not used anymore - legacy from for 4."""
61
69
    def __eq__(self, other):
62
70
        if not isinstance(other, Revision):
63
71
            return False
64
 
        # FIXME: rbc 20050930 parent_ids are not being compared
65
72
        return (
66
73
                self.inventory_sha1 == other.inventory_sha1
67
74
                and self.revision_id == other.revision_id
69
76
                and self.message == other.message
70
77
                and self.timezone == other.timezone
71
78
                and self.committer == other.committer
72
 
                and self.properties == other.properties)
 
79
                and self.properties == other.properties
 
80
                and self.parent_ids == other.parent_ids)
73
81
 
74
82
    def __ne__(self, other):
75
83
        return not self.__eq__(other)
80
88
            if not isinstance(name, basestring) or contains_whitespace(name):
81
89
                raise ValueError("invalid property name %r" % name)
82
90
            if not isinstance(value, basestring):
83
 
                raise ValueError("invalid property value %r for %r" % 
84
 
                                 (name, value))
 
91
                raise ValueError("invalid property value %r for %r" %
 
92
                                 (value, name))
85
93
 
86
94
    def get_history(self, repository):
87
95
        """Return the canonical line-of-history for this revision.
104
112
 
105
113
    def get_summary(self):
106
114
        """Get the first line of the log message for this revision.
107
 
        """
108
 
        return self.message.split('\n', 1)[0]
109
 
 
110
 
 
111
 
def is_ancestor(revision_id, candidate_id, branch):
112
 
    """Return true if candidate_id is an ancestor of revision_id.
113
 
 
114
 
    A false negative will be returned if any intermediate descendent of
115
 
    candidate_id is not present in any of the revision_sources.
116
 
    
117
 
    revisions_source is an object supporting a get_revision operation that
118
 
    behaves like Branch's.
119
 
    """
120
 
    return candidate_id in branch.repository.get_ancestry(revision_id)
 
115
 
 
116
        Return an empty string if message is None.
 
117
        """
 
118
        if self.message:
 
119
            return self.message.lstrip().split('\n', 1)[0]
 
120
        else:
 
121
            return ''
 
122
 
 
123
    def get_apparent_authors(self):
 
124
        """Return the apparent authors of this revision.
 
125
 
 
126
        If the revision properties contain the names of the authors,
 
127
        return them. Otherwise return the committer name.
 
128
 
 
129
        The return value will be a list containing at least one element.
 
130
        """
 
131
        authors = self.properties.get('authors', None)
 
132
        if authors is None:
 
133
            author = self.properties.get('author', self.committer)
 
134
            if author is None:
 
135
                return []
 
136
            return [author]
 
137
        else:
 
138
            return authors.split("\n")
 
139
 
 
140
    def iter_bugs(self):
 
141
        """Iterate over the bugs associated with this revision."""
 
142
        bug_property = self.properties.get('bugs', None)
 
143
        if bug_property is None:
 
144
            return
 
145
        for line in bug_property.splitlines():
 
146
            try:
 
147
                url, status = line.split(None, 2)
 
148
            except ValueError:
 
149
                raise errors.InvalidLineInBugsProperty(line)
 
150
            if status not in bugtracker.ALLOWED_BUG_STATUSES:
 
151
                raise errors.InvalidBugStatus(status)
 
152
            yield url, status
121
153
 
122
154
 
123
155
def iter_ancestors(revision_id, revision_source, only_present=False):
132
164
                revision = revision_source.get_revision(ancestor)
133
165
            except errors.NoSuchRevision, e:
134
166
                if e.revision == revision_id:
135
 
                    raise 
 
167
                    raise
136
168
                else:
137
169
                    continue
138
170
            if only_present:
146
178
    """Return the ancestors of a revision present in a branch.
147
179
 
148
180
    It's possible that a branch won't have the complete ancestry of
149
 
    one of its revisions.  
 
181
    one of its revisions.
150
182
 
151
183
    """
152
184
    found_ancestors = {}
153
185
    anc_iter = enumerate(iter_ancestors(revision_id, revision_source,
154
186
                         only_present=True))
155
187
    for anc_order, (anc_id, anc_distance) in anc_iter:
156
 
        if not found_ancestors.has_key(anc_id):
 
188
        if anc_id not in found_ancestors:
157
189
            found_ancestors[anc_id] = (anc_order, anc_distance)
158
190
    return found_ancestors
159
 
    
 
191
 
160
192
 
161
193
def __get_closest(intersection):
162
194
    intersection.sort()
163
 
    matches = [] 
 
195
    matches = []
164
196
    for entry in intersection:
165
197
        if entry[0] == intersection[0][0]:
166
198
            matches.append(entry[2])
167
199
    return matches
168
200
 
169
201
 
170
 
def revision_graph(revision, revision_source):
171
 
    """Produce a graph of the ancestry of the specified revision.
172
 
    
173
 
    :return: root, ancestors map, descendants map
 
202
def is_reserved_id(revision_id):
 
203
    """Determine whether a revision id is reserved
 
204
 
 
205
    :return: True if the revision is reserved, False otherwise
174
206
    """
175
 
    revision_source.lock_read()
176
 
    try:
177
 
        return _revision_graph(revision, revision_source)
178
 
    finally:
179
 
        revision_source.unlock()
180
 
 
181
 
 
182
 
def _revision_graph(revision, revision_source):
183
 
    """See revision_graph."""
184
 
    from bzrlib.tsort import topo_sort
185
 
    graph = revision_source.get_revision_graph(revision)
186
 
    # mark all no-parent revisions as being NULL_REVISION parentage.
187
 
    for node, parents in graph.items():
188
 
        if len(parents) == 0:
189
 
            graph[node] = [NULL_REVISION]
190
 
    # add NULL_REVISION to the graph
191
 
    graph[NULL_REVISION] = []
192
 
 
193
 
    # pick a root. If there are multiple roots
194
 
    # this could pick a random one.
195
 
    topo_order = topo_sort(graph.items())
196
 
    root = topo_order[0]
197
 
 
198
 
    ancestors = {}
199
 
    descendants = {}
200
 
 
201
 
    # map the descendants of the graph.
202
 
    # and setup our set based return graph.
203
 
    for node in graph.keys():
204
 
        descendants[node] = {}
205
 
    for node, parents in graph.items():
206
 
        for parent in parents:
207
 
            descendants[parent][node] = 1
208
 
        ancestors[node] = set(parents)
209
 
 
210
 
    assert root not in descendants[root]
211
 
    assert root not in ancestors[root]
212
 
    return root, ancestors, descendants
213
 
 
214
 
 
215
 
def combined_graph(revision_a, revision_b, revision_source):
216
 
    """Produce a combined ancestry graph.
217
 
    Return graph root, ancestors map, descendants map, set of common nodes"""
218
 
    root, ancestors, descendants = revision_graph(
219
 
        revision_a, revision_source)
220
 
    root_b, ancestors_b, descendants_b = revision_graph(
221
 
        revision_b, revision_source)
222
 
    if root != root_b:
223
 
        raise errors.NoCommonRoot(revision_a, revision_b)
224
 
    common = set()
225
 
    for node, node_anc in ancestors_b.iteritems():
226
 
        if node in ancestors:
227
 
            common.add(node)
228
 
        else:
229
 
            ancestors[node] = set()
230
 
        ancestors[node].update(node_anc)
231
 
    for node, node_dec in descendants_b.iteritems():
232
 
        if node not in descendants:
233
 
            descendants[node] = {}
234
 
        descendants[node].update(node_dec)
235
 
    return root, ancestors, descendants, common
236
 
 
237
 
 
238
 
def common_ancestor(revision_a, revision_b, revision_source, 
239
 
                    pb=DummyProgress()):
240
 
    if None in (revision_a, revision_b):
241
 
        return None
242
 
    if NULL_REVISION in (revision_a, revision_b):
 
207
    return isinstance(revision_id, basestring) and revision_id.endswith(':')
 
208
 
 
209
 
 
210
def check_not_reserved_id(revision_id):
 
211
    """Raise ReservedId if the supplied revision_id is reserved"""
 
212
    if is_reserved_id(revision_id):
 
213
        raise errors.ReservedId(revision_id)
 
214
 
 
215
 
 
216
def ensure_null(revision_id):
 
217
    """Ensure only NULL_REVISION is used to represent the null revision"""
 
218
    if revision_id is None:
 
219
        symbol_versioning.warn('NULL_REVISION should be used for the null'
 
220
            ' revision instead of None, as of bzr 0.91.',
 
221
            DeprecationWarning, stacklevel=2)
243
222
        return NULL_REVISION
244
 
    # trivial optimisation
245
 
    if revision_a == revision_b:
246
 
        return revision_a
247
 
    try:
248
 
        try:
249
 
            pb.update('Picking ancestor', 1, 3)
250
 
            graph = revision_source.get_revision_graph_with_ghosts(
251
 
                [revision_a, revision_b])
252
 
            # convert to a NULL_REVISION based graph.
253
 
            ancestors = graph.get_ancestors()
254
 
            descendants = graph.get_descendants()
255
 
            common = set(graph.get_ancestry(revision_a)).intersection(
256
 
                     set(graph.get_ancestry(revision_b)))
257
 
            descendants[NULL_REVISION] = {}
258
 
            ancestors[NULL_REVISION] = []
259
 
            for root in graph.roots:
260
 
                descendants[NULL_REVISION][root] = 1
261
 
                ancestors[root].append(NULL_REVISION)
262
 
            for ghost in graph.ghosts:
263
 
                # ghosts act as roots for the purpose of finding 
264
 
                # the longest paths from the root: any ghost *might*
265
 
                # be directly attached to the root, so we treat them
266
 
                # as being such.
267
 
                # ghost now descends from NULL
268
 
                descendants[NULL_REVISION][ghost] = 1
269
 
                # that is it has an ancestor of NULL
270
 
                ancestors[ghost] = [NULL_REVISION]
271
 
                # ghost is common if any of ghosts descendants are common:
272
 
                for ghost_descendant in descendants[ghost]:
273
 
                    if ghost_descendant in common:
274
 
                        common.add(ghost)
275
 
                
276
 
            root = NULL_REVISION
277
 
            common.add(NULL_REVISION)
278
 
        except errors.NoCommonRoot:
279
 
            raise errors.NoCommonAncestor(revision_a, revision_b)
280
 
            
281
 
        pb.update('Picking ancestor', 2, 3)
282
 
        distances = node_distances (descendants, ancestors, root)
283
 
        pb.update('Picking ancestor', 3, 2)
284
 
        farthest = select_farthest(distances, common)
285
 
        if farthest is None or farthest == NULL_REVISION:
286
 
            raise errors.NoCommonAncestor(revision_a, revision_b)
287
 
    finally:
288
 
        pb.clear()
289
 
    return farthest
290
 
 
291
 
 
292
 
class MultipleRevisionSources(object):
293
 
    """Proxy that looks in multiple branches for revisions."""
294
 
    def __init__(self, *args):
295
 
        object.__init__(self)
296
 
        assert len(args) != 0
297
 
        self._revision_sources = args
298
 
 
299
 
    def revision_parents(self, revision_id):
300
 
        for source in self._revision_sources:
301
 
            try:
302
 
                return source.revision_parents(revision_id)
303
 
            except (errors.WeaveRevisionNotPresent, errors.NoSuchRevision), e:
304
 
                pass
305
 
        raise e
306
 
 
307
 
    def get_revision(self, revision_id):
308
 
        for source in self._revision_sources:
309
 
            try:
310
 
                return source.get_revision(revision_id)
311
 
            except errors.NoSuchRevision, e:
312
 
                pass
313
 
        raise e
314
 
 
315
 
    def get_revision_graph(self, revision_id):
316
 
        # we could probe incrementally until the pending
317
 
        # ghosts list stop growing, but its cheaper for now
318
 
        # to just ask for the complete graph for each repository.
319
 
        graphs = []
320
 
        for source in self._revision_sources:
321
 
            ghost_graph = source.get_revision_graph_with_ghosts()
322
 
            graphs.append(ghost_graph)
323
 
        absent = 0
324
 
        for graph in graphs:
325
 
            if not revision_id in graph.get_ancestors():
326
 
                absent += 1
327
 
        if absent == len(graphs):
328
 
            raise errors.NoSuchRevision(self._revision_sources[0], revision_id)
329
 
 
330
 
        # combine the graphs
331
 
        result = {}
332
 
        pending = set([revision_id])
333
 
        def find_parents(node_id):
334
 
            """find the parents for node_id."""
335
 
            for graph in graphs:
336
 
                ancestors = graph.get_ancestors()
337
 
                try:
338
 
                    return ancestors[node_id]
339
 
                except KeyError:
340
 
                    pass
341
 
            raise errors.NoSuchRevision(self._revision_sources[0], node_id)
342
 
        while len(pending):
343
 
            # all the graphs should have identical parent lists
344
 
            node_id = pending.pop()
345
 
            try:
346
 
                result[node_id] = find_parents(node_id)
347
 
                for parent_node in result[node_id]:
348
 
                    if not parent_node in result:
349
 
                        pending.add(parent_node)
350
 
            except errors.NoSuchRevision:
351
 
                # ghost, ignore it.
352
 
                pass
353
 
        return result
354
 
 
355
 
    def get_revision_graph_with_ghosts(self, revision_ids):
356
 
        # query all the sources for their entire graphs 
357
 
        # and then build a combined graph for just
358
 
        # revision_ids.
359
 
        graphs = []
360
 
        for source in self._revision_sources:
361
 
            ghost_graph = source.get_revision_graph_with_ghosts()
362
 
            graphs.append(ghost_graph.get_ancestors())
363
 
        for revision_id in revision_ids:
364
 
            absent = 0
365
 
            for graph in graphs:
366
 
                    if not revision_id in graph:
367
 
                        absent += 1
368
 
            if absent == len(graphs):
369
 
                raise errors.NoSuchRevision(self._revision_sources[0],
370
 
                                            revision_id)
371
 
 
372
 
        # combine the graphs
373
 
        result = Graph()
374
 
        pending = set(revision_ids)
375
 
        done = set()
376
 
        def find_parents(node_id):
377
 
            """find the parents for node_id."""
378
 
            for graph in graphs:
379
 
                try:
380
 
                    return graph[node_id]
381
 
                except KeyError:
382
 
                    pass
383
 
            raise errors.NoSuchRevision(self._revision_sources[0], node_id)
384
 
        while len(pending):
385
 
            # all the graphs should have identical parent lists
386
 
            node_id = pending.pop()
387
 
            try:
388
 
                parents = find_parents(node_id)
389
 
                for parent_node in parents:
390
 
                    # queued or done? 
391
 
                    if (parent_node not in pending and
392
 
                        parent_node not in done):
393
 
                        # no, queue
394
 
                        pending.add(parent_node)
395
 
                result.add_node(node_id, parents)
396
 
                done.add(node_id)
397
 
            except errors.NoSuchRevision:
398
 
                # ghost
399
 
                result.add_ghost(node_id)
400
 
                continue
401
 
        return result
402
 
 
403
 
    def lock_read(self):
404
 
        for source in self._revision_sources:
405
 
            source.lock_read()
406
 
 
407
 
    def unlock(self):
408
 
        for source in self._revision_sources:
409
 
            source.unlock()
410
 
 
411
 
 
412
 
@deprecated_function(zero_eight)
413
 
def get_intervening_revisions(ancestor_id, rev_id, rev_source,
414
 
                              revision_history=None):
415
 
    """Find the longest line of descent from maybe_ancestor to revision.
416
 
    Revision history is followed where possible.
417
 
 
418
 
    If ancestor_id == rev_id, list will be empty.
419
 
    Otherwise, rev_id will be the last entry.  ancestor_id will never appear.
420
 
    If ancestor_id is not an ancestor, NotAncestor will be thrown
421
 
    """
422
 
    root, ancestors, descendants = revision_graph(rev_id, rev_source)
423
 
    if len(descendants) == 0:
424
 
        raise errors.NoSuchRevision(rev_source, rev_id)
425
 
    if ancestor_id not in descendants:
426
 
        rev_source.get_revision(ancestor_id)
427
 
        raise errors.NotAncestor(rev_id, ancestor_id)
428
 
    root_descendants = all_descendants(descendants, ancestor_id)
429
 
    root_descendants.add(ancestor_id)
430
 
    if rev_id not in root_descendants:
431
 
        raise errors.NotAncestor(rev_id, ancestor_id)
432
 
    distances = node_distances(descendants, ancestors, ancestor_id,
433
 
                               root_descendants=root_descendants)
434
 
 
435
 
    def best_ancestor(rev_id):
436
 
        best = None
437
 
        for anc_id in ancestors[rev_id]:
438
 
            try:
439
 
                distance = distances[anc_id]
440
 
            except KeyError:
441
 
                continue
442
 
            if revision_history is not None and anc_id in revision_history:
443
 
                return anc_id
444
 
            elif best is None or distance > best[1]:
445
 
                best = (anc_id, distance)
446
 
        return best[0]
447
 
 
448
 
    next = rev_id
449
 
    path = []
450
 
    while next != ancestor_id:
451
 
        path.append(next)
452
 
        next = best_ancestor(next)
453
 
    path.reverse()
454
 
    return path
 
223
    else:
 
224
        return revision_id
 
225
 
 
226
 
 
227
def is_null(revision_id):
 
228
    if revision_id is None:
 
229
        symbol_versioning.warn('NULL_REVISION should be used for the null'
 
230
            ' revision instead of None, as of bzr 0.90.',
 
231
            DeprecationWarning, stacklevel=2)
 
232
    return revision_id in (None, NULL_REVISION)