~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/tree.py

  • Committer: Alexander Belchenko
  • Date: 2006-08-01 18:27:42 UTC
  • mto: (1711.2.111 jam-integration)
  • mto: This revision was merged to the branch mainline in revision 1906.
  • Revision ID: bialix@ukr.net-20060801182742-b28d2edf7eea75d1
English

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2005-2011 Canonical Ltd
 
1
# Copyright (C) 2005 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
16
 
17
17
"""Tree classes, representing directory at point in time.
18
18
"""
19
19
 
20
20
import os
21
 
 
22
 
from bzrlib.lazy_import import lazy_import
23
 
lazy_import(globals(), """
24
 
import collections
25
 
 
26
 
from bzrlib import (
27
 
    conflicts as _mod_conflicts,
28
 
    debug,
29
 
    delta,
30
 
    errors,
31
 
    filters,
32
 
    inventory,
33
 
    osutils,
34
 
    revision as _mod_revision,
35
 
    rules,
36
 
    trace,
37
 
    )
38
 
""")
39
 
 
 
21
from cStringIO import StringIO
 
22
from warnings import warn
 
23
 
 
24
import bzrlib
 
25
from bzrlib import delta
40
26
from bzrlib.decorators import needs_read_lock
 
27
from bzrlib.errors import BzrError, BzrCheckError
 
28
from bzrlib import errors
 
29
from bzrlib.inventory import Inventory
41
30
from bzrlib.inter import InterObject
42
 
from bzrlib.symbol_versioning import (
43
 
    deprecated_in,
44
 
    deprecated_method,
45
 
    )
 
31
from bzrlib.osutils import fingerprint_file
 
32
import bzrlib.revision
 
33
from bzrlib.trace import mutter, note
46
34
 
47
35
 
48
36
class Tree(object):
49
37
    """Abstract file tree.
50
38
 
51
39
    There are several subclasses:
52
 
 
 
40
    
53
41
    * `WorkingTree` exists as files on disk editable by the user.
54
42
 
55
43
    * `RevisionTree` is a tree as recorded at some point in the past.
56
44
 
 
45
    Trees contain an `Inventory` object, and also know how to retrieve
 
46
    file texts mentioned in the inventory, either from a working
 
47
    directory or from a store.
 
48
 
 
49
    It is possible for trees to contain files that are not described
 
50
    in their inventory or vice versa; for this use `filenames()`.
 
51
 
57
52
    Trees can be compared, etc, regardless of whether they are working
58
53
    trees or versioned trees.
59
54
    """
60
 
 
 
55
    
61
56
    def changes_from(self, other, want_unchanged=False, specific_files=None,
62
 
        extra_trees=None, require_versioned=False, include_root=False,
63
 
        want_unversioned=False):
 
57
        extra_trees=None, require_versioned=False):
64
58
        """Return a TreeDelta of the changes from other to this tree.
65
59
 
66
60
        :param other: A tree to compare with.
75
69
        :param require_versioned: An optional boolean (defaults to False). When
76
70
            supplied and True all the 'specific_files' must be versioned, or
77
71
            a PathsNotVersionedError will be thrown.
78
 
        :param want_unversioned: Scan for unversioned paths.
79
72
 
80
 
        The comparison will be performed by an InterTree object looked up on
 
73
        The comparison will be performed by an InterTree object looked up on 
81
74
        self and other.
82
75
        """
83
76
        # Martin observes that Tree.changes_from returns a TreeDelta and this
88
81
            specific_files=specific_files,
89
82
            extra_trees=extra_trees,
90
83
            require_versioned=require_versioned,
91
 
            include_root=include_root,
92
 
            want_unversioned=want_unversioned,
93
84
            )
94
 
 
95
 
    def iter_changes(self, from_tree, include_unchanged=False,
96
 
                     specific_files=None, pb=None, extra_trees=None,
97
 
                     require_versioned=True, want_unversioned=False):
98
 
        """See InterTree.iter_changes"""
99
 
        intertree = InterTree.get(from_tree, self)
100
 
        return intertree.iter_changes(include_unchanged, specific_files, pb,
101
 
            extra_trees, require_versioned, want_unversioned=want_unversioned)
102
 
 
 
85
    
103
86
    def conflicts(self):
104
87
        """Get a list of the conflicts in the tree.
105
88
 
106
89
        Each conflict is an instance of bzrlib.conflicts.Conflict.
107
90
        """
108
 
        return _mod_conflicts.ConflictList()
109
 
 
110
 
    def extras(self):
111
 
        """For trees that can have unversioned files, return all such paths."""
112
91
        return []
113
92
 
114
93
    def get_parent_ids(self):
115
 
        """Get the parent ids for this tree.
 
94
        """Get the parent ids for this tree. 
116
95
 
117
96
        :return: a list of parent ids. [] is returned to indicate
118
97
        a tree with no parents.
119
98
        :raises: BzrError if the parents are not known.
120
99
        """
121
100
        raise NotImplementedError(self.get_parent_ids)
122
 
 
 
101
    
123
102
    def has_filename(self, filename):
124
103
        """True if the tree has given filename."""
125
 
        raise NotImplementedError(self.has_filename)
 
104
        raise NotImplementedError()
126
105
 
127
106
    def has_id(self, file_id):
128
 
        raise NotImplementedError(self.has_id)
 
107
        return self.inventory.has_id(file_id)
129
108
 
130
 
    @deprecated_method(deprecated_in((2, 4, 0)))
131
 
    def __contains__(self, file_id):
132
 
        return self.has_id(file_id)
 
109
    __contains__ = has_id
133
110
 
134
111
    def has_or_had_id(self, file_id):
135
 
        raise NotImplementedError(self.has_or_had_id)
136
 
 
137
 
    def is_ignored(self, filename):
138
 
        """Check whether the filename is ignored by this tree.
139
 
 
140
 
        :param filename: The relative filename within the tree.
141
 
        :return: True if the filename is ignored.
142
 
        """
143
 
        return False
144
 
 
145
 
    def all_file_ids(self):
146
 
        """Iterate through all file ids, including ids for missing files."""
147
 
        raise NotImplementedError(self.all_file_ids)
 
112
        if file_id == self.inventory.root.file_id:
 
113
            return True
 
114
        return self.inventory.has_id(file_id)
 
115
 
 
116
    def __iter__(self):
 
117
        return iter(self.inventory)
148
118
 
149
119
    def id2path(self, file_id):
150
 
        """Return the path for a file id.
151
 
 
152
 
        :raises NoSuchId:
153
 
        """
154
 
        raise NotImplementedError(self.id2path)
155
 
 
156
 
    def iter_entries_by_dir(self, specific_file_ids=None, yield_parents=False):
 
120
        return self.inventory.id2path(file_id)
 
121
 
 
122
    def iter_entries_by_dir(self):
157
123
        """Walk the tree in 'by_dir' order.
158
124
 
159
 
        This will yield each entry in the tree as a (path, entry) tuple.
160
 
        The order that they are yielded is:
161
 
 
162
 
        Directories are walked in a depth-first lexicographical order,
163
 
        however, whenever a directory is reached, all of its direct child
164
 
        nodes are yielded in  lexicographical order before yielding the
165
 
        grandchildren.
166
 
 
167
 
        For example, in the tree::
168
 
 
169
 
           a/
170
 
             b/
171
 
               c
172
 
             d/
173
 
               e
174
 
           f/
175
 
             g
176
 
 
177
 
        The yield order (ignoring root) would be::
178
 
 
179
 
          a, f, a/b, a/d, a/b/c, a/d/e, f/g
180
 
 
181
 
        :param yield_parents: If True, yield the parents from the root leading
182
 
            down to specific_file_ids that have been requested. This has no
183
 
            impact if specific_file_ids is None.
184
 
        """
185
 
        raise NotImplementedError(self.iter_entries_by_dir)
186
 
 
187
 
    def list_files(self, include_root=False, from_dir=None, recursive=True):
188
 
        """List all files in this tree.
189
 
 
190
 
        :param include_root: Whether to include the entry for the tree root
191
 
        :param from_dir: Directory under which to list files
192
 
        :param recursive: Whether to list files recursively
193
 
        :return: iterator over tuples of (path, versioned, kind, file_id,
194
 
            inventory entry)
195
 
        """
196
 
        raise NotImplementedError(self.list_files)
197
 
 
198
 
    def iter_references(self):
199
 
        if self.supports_tree_reference():
200
 
            for path, entry in self.iter_entries_by_dir():
201
 
                if entry.kind == 'tree-reference':
202
 
                    yield path, entry.file_id
 
125
        This will yield each entry in the tree as a (path, entry) tuple. The
 
126
        order that they are yielded is: the contents of a directory are 
 
127
        preceeded by the parent of a directory, and all the contents of a 
 
128
        directory are grouped together.
 
129
        """
 
130
        return self.inventory.iter_entries_by_dir()
203
131
 
204
132
    def kind(self, file_id):
205
 
        raise NotImplementedError("Tree subclass %s must implement kind"
206
 
            % self.__class__.__name__)
207
 
 
208
 
    def stored_kind(self, file_id):
209
 
        """File kind stored for this file_id.
210
 
 
211
 
        May not match kind on disk for working trees.  Always available
212
 
        for versioned files, even when the file itself is missing.
213
 
        """
214
 
        return self.kind(file_id)
215
 
 
216
 
    def path_content_summary(self, path):
217
 
        """Get a summary of the information about path.
218
 
 
219
 
        All the attributes returned are for the canonical form, not the
220
 
        convenient form (if content filters are in use.)
221
 
 
222
 
        :param path: A relative path within the tree.
223
 
        :return: A tuple containing kind, size, exec, sha1-or-link.
224
 
            Kind is always present (see tree.kind()).
225
 
            size is present if kind is file and the size of the 
226
 
                canonical form can be cheaply determined, None otherwise.
227
 
            exec is None unless kind is file and the platform supports the 'x'
228
 
                bit.
229
 
            sha1-or-link is the link target if kind is symlink, or the sha1 if
230
 
                it can be obtained without reading the file.
231
 
        """
232
 
        raise NotImplementedError(self.path_content_summary)
233
 
 
234
 
    def get_reference_revision(self, file_id, path=None):
235
 
        raise NotImplementedError("Tree subclass %s must implement "
236
 
                                  "get_reference_revision"
237
 
            % self.__class__.__name__)
238
 
 
239
 
    def _comparison_data(self, entry, path):
240
 
        """Return a tuple of kind, executable, stat_value for a file.
241
 
 
242
 
        entry may be None if there is no inventory entry for the file, but
243
 
        path must always be supplied.
244
 
 
245
 
        kind is None if there is no file present (even if an inventory id is
246
 
        present).  executable is False for non-file entries.
247
 
        """
248
 
        raise NotImplementedError(self._comparison_data)
249
 
 
250
 
    def _file_size(self, entry, stat_value):
251
 
        raise NotImplementedError(self._file_size)
252
 
 
253
 
    def get_file(self, file_id, path=None):
254
 
        """Return a file object for the file file_id in the tree.
255
 
 
256
 
        If both file_id and path are defined, it is implementation defined as
257
 
        to which one is used.
258
 
        """
259
 
        raise NotImplementedError(self.get_file)
260
 
 
261
 
    def get_file_with_stat(self, file_id, path=None):
262
 
        """Get a file handle and stat object for file_id.
263
 
 
264
 
        The default implementation returns (self.get_file, None) for backwards
265
 
        compatibility.
266
 
 
267
 
        :param file_id: The file id to read.
268
 
        :param path: The path of the file, if it is known.
269
 
        :return: A tuple (file_handle, stat_value_or_None). If the tree has
270
 
            no stat facility, or need for a stat cache feedback during commit,
271
 
            it may return None for the second element of the tuple.
272
 
        """
273
 
        return (self.get_file(file_id, path), None)
274
 
 
275
 
    def get_file_text(self, file_id, path=None):
276
 
        """Return the byte content of a file.
277
 
 
278
 
        :param file_id: The file_id of the file.
279
 
        :param path: The path of the file.
280
 
 
281
 
        If both file_id and path are supplied, an implementation may use
282
 
        either one.
283
 
 
284
 
        :returns: A single byte string for the whole file.
285
 
        """
286
 
        my_file = self.get_file(file_id, path)
287
 
        try:
288
 
            return my_file.read()
289
 
        finally:
290
 
            my_file.close()
291
 
 
292
 
    def get_file_lines(self, file_id, path=None):
293
 
        """Return the content of a file, as lines.
294
 
 
295
 
        :param file_id: The file_id of the file.
296
 
        :param path: The path of the file.
297
 
 
298
 
        If both file_id and path are supplied, an implementation may use
299
 
        either one.
300
 
        """
301
 
        return osutils.split_lines(self.get_file_text(file_id, path))
302
 
 
303
 
    def get_file_sha1(self, file_id, path=None, stat_value=None):
304
 
        """Return the SHA1 file for a file.
305
 
 
306
 
        :param file_id: The handle for this file.
307
 
        :param path: The path that this file can be found at.
308
 
            These must point to the same object.
309
 
        :param stat_value: Optional stat value for the object
310
 
        """
311
 
        raise NotImplementedError(self.get_file_sha1)
312
 
 
313
 
    def get_file_mtime(self, file_id, path=None):
314
 
        """Return the modification time for a file.
315
 
 
316
 
        :param file_id: The handle for this file.
317
 
        :param path: The path that this file can be found at.
318
 
            These must point to the same object.
319
 
        """
320
 
        raise NotImplementedError(self.get_file_mtime)
321
 
 
322
 
    def get_file_size(self, file_id):
323
 
        """Return the size of a file in bytes.
324
 
 
325
 
        This applies only to regular files.  If invoked on directories or
326
 
        symlinks, it will return None.
327
 
        :param file_id: The file-id of the file
328
 
        """
329
 
        raise NotImplementedError(self.get_file_size)
330
 
 
 
133
        raise NotImplementedError("subclasses must implement kind")
 
134
 
 
135
    def _get_inventory(self):
 
136
        return self._inventory
 
137
    
331
138
    def get_file_by_path(self, path):
332
 
        raise NotImplementedError(self.get_file_by_path)
333
 
 
334
 
    def is_executable(self, file_id, path=None):
335
 
        """Check if a file is executable.
336
 
 
337
 
        :param file_id: The handle for this file.
338
 
        :param path: The path that this file can be found at.
339
 
            These must point to the same object.
340
 
        """
341
 
        raise NotImplementedError(self.is_executable)
342
 
 
343
 
    def iter_files_bytes(self, desired_files):
344
 
        """Iterate through file contents.
345
 
 
346
 
        Files will not necessarily be returned in the order they occur in
347
 
        desired_files.  No specific order is guaranteed.
348
 
 
349
 
        Yields pairs of identifier, bytes_iterator.  identifier is an opaque
350
 
        value supplied by the caller as part of desired_files.  It should
351
 
        uniquely identify the file version in the caller's context.  (Examples:
352
 
        an index number or a TreeTransform trans_id.)
353
 
 
354
 
        bytes_iterator is an iterable of bytestrings for the file.  The
355
 
        kind of iterable and length of the bytestrings are unspecified, but for
356
 
        this implementation, it is a tuple containing a single bytestring with
357
 
        the complete text of the file.
358
 
 
359
 
        :param desired_files: a list of (file_id, identifier) pairs
360
 
        """
361
 
        for file_id, identifier in desired_files:
362
 
            # We wrap the string in a tuple so that we can return an iterable
363
 
            # of bytestrings.  (Technically, a bytestring is also an iterable
364
 
            # of bytestrings, but iterating through each character is not
365
 
            # performant.)
366
 
            cur_file = (self.get_file_text(file_id),)
367
 
            yield identifier, cur_file
368
 
 
369
 
    def get_symlink_target(self, file_id, path=None):
370
 
        """Get the target for a given file_id.
371
 
 
372
 
        It is assumed that the caller already knows that file_id is referencing
373
 
        a symlink.
374
 
        :param file_id: Handle for the symlink entry.
375
 
        :param path: The path of the file.
376
 
        If both file_id and path are supplied, an implementation may use
377
 
        either one.
378
 
        :return: The path the symlink points to.
379
 
        """
380
 
        raise NotImplementedError(self.get_symlink_target)
381
 
 
382
 
    def get_root_id(self):
383
 
        """Return the file_id for the root of this tree."""
384
 
        raise NotImplementedError(self.get_root_id)
385
 
 
386
 
    def annotate_iter(self, file_id,
387
 
                      default_revision=_mod_revision.CURRENT_REVISION):
388
 
        """Return an iterator of revision_id, line tuples.
389
 
 
390
 
        For working trees (and mutable trees in general), the special
391
 
        revision_id 'current:' will be used for lines that are new in this
392
 
        tree, e.g. uncommitted changes.
393
 
        :param file_id: The file to produce an annotated version from
394
 
        :param default_revision: For lines that don't match a basis, mark them
395
 
            with this revision id. Not all implementations will make use of
396
 
            this value.
397
 
        """
398
 
        raise NotImplementedError(self.annotate_iter)
399
 
 
400
 
    def _get_plan_merge_data(self, file_id, other, base):
401
 
        from bzrlib import versionedfile
402
 
        vf = versionedfile._PlanMergeVersionedFile(file_id)
403
 
        last_revision_a = self._get_file_revision(file_id, vf, 'this:')
404
 
        last_revision_b = other._get_file_revision(file_id, vf, 'other:')
405
 
        if base is None:
406
 
            last_revision_base = None
407
 
        else:
408
 
            last_revision_base = base._get_file_revision(file_id, vf, 'base:')
409
 
        return vf, last_revision_a, last_revision_b, last_revision_base
410
 
 
411
 
    def plan_file_merge(self, file_id, other, base=None):
412
 
        """Generate a merge plan based on annotations.
413
 
 
414
 
        If the file contains uncommitted changes in this tree, they will be
415
 
        attributed to the 'current:' pseudo-revision.  If the file contains
416
 
        uncommitted changes in the other tree, they will be assigned to the
417
 
        'other:' pseudo-revision.
418
 
        """
419
 
        data = self._get_plan_merge_data(file_id, other, base)
420
 
        vf, last_revision_a, last_revision_b, last_revision_base = data
421
 
        return vf.plan_merge(last_revision_a, last_revision_b,
422
 
                             last_revision_base)
423
 
 
424
 
    def plan_file_lca_merge(self, file_id, other, base=None):
425
 
        """Generate a merge plan based lca-newness.
426
 
 
427
 
        If the file contains uncommitted changes in this tree, they will be
428
 
        attributed to the 'current:' pseudo-revision.  If the file contains
429
 
        uncommitted changes in the other tree, they will be assigned to the
430
 
        'other:' pseudo-revision.
431
 
        """
432
 
        data = self._get_plan_merge_data(file_id, other, base)
433
 
        vf, last_revision_a, last_revision_b, last_revision_base = data
434
 
        return vf.plan_lca_merge(last_revision_a, last_revision_b,
435
 
                                 last_revision_base)
436
 
 
437
 
    def _iter_parent_trees(self):
438
 
        """Iterate through parent trees, defaulting to Tree.revision_tree."""
439
 
        for revision_id in self.get_parent_ids():
440
 
            try:
441
 
                yield self.revision_tree(revision_id)
442
 
            except errors.NoSuchRevisionInTree:
443
 
                yield self.repository.revision_tree(revision_id)
444
 
 
445
 
    def _get_file_revision(self, file_id, vf, tree_revision):
446
 
        """Ensure that file_id, tree_revision is in vf to plan the merge."""
447
 
 
448
 
        if getattr(self, '_repository', None) is None:
449
 
            last_revision = tree_revision
450
 
            parent_keys = [(file_id, t.get_file_revision(file_id)) for t in
451
 
                self._iter_parent_trees()]
452
 
            vf.add_lines((file_id, last_revision), parent_keys,
453
 
                         self.get_file_lines(file_id))
454
 
            repo = self.branch.repository
455
 
            base_vf = repo.texts
456
 
        else:
457
 
            last_revision = self.get_file_revision(file_id)
458
 
            base_vf = self._repository.texts
459
 
        if base_vf not in vf.fallback_versionedfiles:
460
 
            vf.fallback_versionedfiles.append(base_vf)
461
 
        return last_revision
 
139
        return self.get_file(self._inventory.path2id(path))
 
140
 
 
141
    inventory = property(_get_inventory,
 
142
                         doc="Inventory of this Tree")
462
143
 
463
144
    def _check_retrieved(self, ie, f):
464
145
        if not __debug__:
465
 
            return
466
 
        fp = osutils.fingerprint_file(f)
 
146
            return  
 
147
        fp = fingerprint_file(f)
467
148
        f.seek(0)
468
 
 
469
 
        if ie.text_size is not None:
 
149
        
 
150
        if ie.text_size != None:
470
151
            if ie.text_size != fp['size']:
471
 
                raise errors.BzrError(
472
 
                        "mismatched size for file %r in %r" %
473
 
                        (ie.file_id, self._store),
 
152
                raise BzrError("mismatched size for file %r in %r" % (ie.file_id, self._store),
474
153
                        ["inventory expects %d bytes" % ie.text_size,
475
154
                         "file is actually %d bytes" % fp['size'],
476
155
                         "store is probably damaged/corrupt"])
477
156
 
478
157
        if ie.text_sha1 != fp['sha1']:
479
 
            raise errors.BzrError("wrong SHA-1 for file %r in %r" %
480
 
                    (ie.file_id, self._store),
 
158
            raise BzrError("wrong SHA-1 for file %r in %r" % (ie.file_id, self._store),
481
159
                    ["inventory expects %s" % ie.text_sha1,
482
160
                     "file is actually %s" % fp['sha1'],
483
161
                     "store is probably damaged/corrupt"])
484
162
 
485
 
    def path2id(self, path):
486
 
        """Return the id for path in this tree."""
487
 
        raise NotImplementedError(self.path2id)
488
 
 
489
 
    def paths2ids(self, paths, trees=[], require_versioned=True):
490
 
        """Return all the ids that can be reached by walking from paths.
491
 
 
492
 
        Each path is looked up in this tree and any extras provided in
493
 
        trees, and this is repeated recursively: the children in an extra tree
494
 
        of a directory that has been renamed under a provided path in this tree
495
 
        are all returned, even if none exist under a provided path in this
496
 
        tree, and vice versa.
497
 
 
498
 
        :param paths: An iterable of paths to start converting to ids from.
499
 
            Alternatively, if paths is None, no ids should be calculated and None
500
 
            will be returned. This is offered to make calling the api unconditional
501
 
            for code that *might* take a list of files.
502
 
        :param trees: Additional trees to consider.
503
 
        :param require_versioned: If False, do not raise NotVersionedError if
504
 
            an element of paths is not versioned in this tree and all of trees.
505
 
        """
506
 
        return find_ids_across_trees(paths, [self] + list(trees), require_versioned)
507
 
 
508
 
    def iter_children(self, file_id):
509
 
        entry = self.iter_entries_by_dir([file_id]).next()[1]
510
 
        for child in getattr(entry, 'children', {}).itervalues():
511
 
            yield child.file_id
 
163
 
 
164
    def print_file(self, file_id):
 
165
        """Print file with id `file_id` to stdout."""
 
166
        import sys
 
167
        sys.stdout.write(self.get_file_text(file_id))
512
168
 
513
169
    def lock_read(self):
514
 
        """Lock this tree for multiple read only operations.
515
 
        
516
 
        :return: A bzrlib.lock.LogicalLockResult.
517
 
        """
518
170
        pass
519
171
 
520
 
    def revision_tree(self, revision_id):
521
 
        """Obtain a revision tree for the revision revision_id.
522
 
 
523
 
        The intention of this method is to allow access to possibly cached
524
 
        tree data. Implementors of this method should raise NoSuchRevision if
525
 
        the tree is not locally available, even if they could obtain the
526
 
        tree via a repository or some other means. Callers are responsible
527
 
        for finding the ultimate source for a revision tree.
528
 
 
529
 
        :param revision_id: The revision_id of the requested tree.
530
 
        :return: A Tree.
531
 
        :raises: NoSuchRevision if the tree cannot be obtained.
532
 
        """
533
 
        raise errors.NoSuchRevisionInTree(self, revision_id)
534
 
 
535
172
    def unknowns(self):
536
173
        """What files are present in this tree and unknown.
537
 
 
 
174
        
538
175
        :return: an iterator over the unknown files.
539
176
        """
540
177
        return iter([])
543
180
        pass
544
181
 
545
182
    def filter_unversioned_files(self, paths):
546
 
        """Filter out paths that are versioned.
547
 
 
548
 
        :return: set of paths.
549
 
        """
550
 
        raise NotImplementedError(self.filter_unversioned_files)
551
 
 
552
 
    def walkdirs(self, prefix=""):
553
 
        """Walk the contents of this tree from path down.
554
 
 
555
 
        This yields all the data about the contents of a directory at a time.
556
 
        After each directory has been yielded, if the caller has mutated the
557
 
        list to exclude some directories, they are then not descended into.
558
 
 
559
 
        The data yielded is of the form:
560
 
        ((directory-relpath, directory-path-from-root, directory-fileid),
561
 
        [(relpath, basename, kind, lstat, path_from_tree_root, file_id,
562
 
          versioned_kind), ...]),
563
 
         - directory-relpath is the containing dirs relpath from prefix
564
 
         - directory-path-from-root is the containing dirs path from /
565
 
         - directory-fileid is the id of the directory if it is versioned.
566
 
         - relpath is the relative path within the subtree being walked.
567
 
         - basename is the basename
568
 
         - kind is the kind of the file now. If unknonwn then the file is not
569
 
           present within the tree - but it may be recorded as versioned. See
570
 
           versioned_kind.
571
 
         - lstat is the stat data *if* the file was statted.
572
 
         - path_from_tree_root is the path from the root of the tree.
573
 
         - file_id is the file_id if the entry is versioned.
574
 
         - versioned_kind is the kind of the file as last recorded in the
575
 
           versioning system. If 'unknown' the file is not versioned.
576
 
        One of 'kind' and 'versioned_kind' must not be 'unknown'.
577
 
 
578
 
        :param prefix: Start walking from prefix within the tree rather than
579
 
        at the root. This allows one to walk a subtree but get paths that are
580
 
        relative to a tree rooted higher up.
581
 
        :return: an iterator over the directory data.
582
 
        """
583
 
        raise NotImplementedError(self.walkdirs)
584
 
 
585
 
    def supports_content_filtering(self):
586
 
        return False
587
 
 
588
 
    def _content_filter_stack(self, path=None, file_id=None):
589
 
        """The stack of content filters for a path if filtering is supported.
590
 
 
591
 
        Readers will be applied in first-to-last order.
592
 
        Writers will be applied in last-to-first order.
593
 
        Either the path or the file-id needs to be provided.
594
 
 
595
 
        :param path: path relative to the root of the tree
596
 
            or None if unknown
597
 
        :param file_id: file_id or None if unknown
598
 
        :return: the list of filters - [] if there are none
599
 
        """
600
 
        filter_pref_names = filters._get_registered_names()
601
 
        if len(filter_pref_names) == 0:
602
 
            return []
603
 
        if path is None:
604
 
            path = self.id2path(file_id)
605
 
        prefs = self.iter_search_rules([path], filter_pref_names).next()
606
 
        stk = filters._get_filter_stack_for(prefs)
607
 
        if 'filters' in debug.debug_flags:
608
 
            trace.note("*** %s content-filter: %s => %r" % (path,prefs,stk))
609
 
        return stk
610
 
 
611
 
    def _content_filter_stack_provider(self):
612
 
        """A function that returns a stack of ContentFilters.
613
 
 
614
 
        The function takes a path (relative to the top of the tree) and a
615
 
        file-id as parameters.
616
 
 
617
 
        :return: None if content filtering is not supported by this tree.
618
 
        """
619
 
        if self.supports_content_filtering():
620
 
            return lambda path, file_id: \
621
 
                    self._content_filter_stack(path, file_id)
622
 
        else:
623
 
            return None
624
 
 
625
 
    def iter_search_rules(self, path_names, pref_names=None,
626
 
        _default_searcher=None):
627
 
        """Find the preferences for filenames in a tree.
628
 
 
629
 
        :param path_names: an iterable of paths to find attributes for.
630
 
          Paths are given relative to the root of the tree.
631
 
        :param pref_names: the list of preferences to lookup - None for all
632
 
        :param _default_searcher: private parameter to assist testing - don't use
633
 
        :return: an iterator of tuple sequences, one per path-name.
634
 
          See _RulesSearcher.get_items for details on the tuple sequence.
635
 
        """
636
 
        if _default_searcher is None:
637
 
            _default_searcher = rules._per_user_searcher
638
 
        searcher = self._get_rules_searcher(_default_searcher)
639
 
        if searcher is not None:
640
 
            if pref_names is not None:
641
 
                for path in path_names:
642
 
                    yield searcher.get_selected_items(path, pref_names)
643
 
            else:
644
 
                for path in path_names:
645
 
                    yield searcher.get_items(path)
646
 
 
647
 
    def _get_rules_searcher(self, default_searcher):
648
 
        """Get the RulesSearcher for this tree given the default one."""
649
 
        searcher = default_searcher
650
 
        return searcher
651
 
 
652
 
 
653
 
class InventoryTree(Tree):
654
 
    """A tree that relies on an inventory for its metadata.
655
 
 
656
 
    Trees contain an `Inventory` object, and also know how to retrieve
657
 
    file texts mentioned in the inventory, either from a working
658
 
    directory or from a store.
659
 
 
660
 
    It is possible for trees to contain files that are not described
661
 
    in their inventory or vice versa; for this use `filenames()`.
662
 
 
663
 
    Subclasses should set the _inventory attribute, which is considered
664
 
    private to external API users.
665
 
    """
666
 
 
667
 
    def get_canonical_inventory_paths(self, paths):
668
 
        """Like get_canonical_inventory_path() but works on multiple items.
669
 
 
670
 
        :param paths: A sequence of paths relative to the root of the tree.
671
 
        :return: A list of paths, with each item the corresponding input path
672
 
        adjusted to account for existing elements that match case
673
 
        insensitively.
674
 
        """
675
 
        return list(self._yield_canonical_inventory_paths(paths))
676
 
 
677
 
    def get_canonical_inventory_path(self, path):
678
 
        """Returns the first inventory item that case-insensitively matches path.
679
 
 
680
 
        If a path matches exactly, it is returned. If no path matches exactly
681
 
        but more than one path matches case-insensitively, it is implementation
682
 
        defined which is returned.
683
 
 
684
 
        If no path matches case-insensitively, the input path is returned, but
685
 
        with as many path entries that do exist changed to their canonical
686
 
        form.
687
 
 
688
 
        If you need to resolve many names from the same tree, you should
689
 
        use get_canonical_inventory_paths() to avoid O(N) behaviour.
690
 
 
691
 
        :param path: A paths relative to the root of the tree.
692
 
        :return: The input path adjusted to account for existing elements
693
 
        that match case insensitively.
694
 
        """
695
 
        return self._yield_canonical_inventory_paths([path]).next()
696
 
 
697
 
    def _yield_canonical_inventory_paths(self, paths):
698
 
        for path in paths:
699
 
            # First, if the path as specified exists exactly, just use it.
700
 
            if self.path2id(path) is not None:
701
 
                yield path
702
 
                continue
703
 
            # go walkin...
704
 
            cur_id = self.get_root_id()
705
 
            cur_path = ''
706
 
            bit_iter = iter(path.split("/"))
707
 
            for elt in bit_iter:
708
 
                lelt = elt.lower()
709
 
                new_path = None
710
 
                for child in self.iter_children(cur_id):
711
 
                    try:
712
 
                        # XXX: it seem like if the child is known to be in the
713
 
                        # tree, we shouldn't need to go from its id back to
714
 
                        # its path -- mbp 2010-02-11
715
 
                        #
716
 
                        # XXX: it seems like we could be more efficient
717
 
                        # by just directly looking up the original name and
718
 
                        # only then searching all children; also by not
719
 
                        # chopping paths so much. -- mbp 2010-02-11
720
 
                        child_base = os.path.basename(self.id2path(child))
721
 
                        if (child_base == elt):
722
 
                            # if we found an exact match, we can stop now; if
723
 
                            # we found an approximate match we need to keep
724
 
                            # searching because there might be an exact match
725
 
                            # later.  
726
 
                            cur_id = child
727
 
                            new_path = osutils.pathjoin(cur_path, child_base)
728
 
                            break
729
 
                        elif child_base.lower() == lelt:
730
 
                            cur_id = child
731
 
                            new_path = osutils.pathjoin(cur_path, child_base)
732
 
                    except errors.NoSuchId:
733
 
                        # before a change is committed we can see this error...
734
 
                        continue
735
 
                if new_path:
736
 
                    cur_path = new_path
737
 
                else:
738
 
                    # got to the end of this directory and no entries matched.
739
 
                    # Return what matched so far, plus the rest as specified.
740
 
                    cur_path = osutils.pathjoin(cur_path, elt, *list(bit_iter))
741
 
                    break
742
 
            yield cur_path
743
 
        # all done.
744
 
 
745
 
    def _get_inventory(self):
746
 
        return self._inventory
747
 
 
748
 
    inventory = property(_get_inventory,
749
 
                         doc="Inventory of this Tree")
750
 
 
751
 
    @needs_read_lock
752
 
    def path2id(self, path):
753
 
        """Return the id for path in this tree."""
754
 
        return self._inventory.path2id(path)
755
 
 
756
 
    def id2path(self, file_id):
757
 
        """Return the path for a file id.
758
 
 
759
 
        :raises NoSuchId:
760
 
        """
761
 
        return self.inventory.id2path(file_id)
762
 
 
763
 
    def has_id(self, file_id):
764
 
        return self.inventory.has_id(file_id)
765
 
 
766
 
    def has_or_had_id(self, file_id):
767
 
        return self.inventory.has_id(file_id)
768
 
 
769
 
    def all_file_ids(self):
770
 
        return set(self.inventory)
771
 
 
772
 
    @deprecated_method(deprecated_in((2, 4, 0)))
773
 
    def __iter__(self):
774
 
        return iter(self.inventory)
775
 
 
776
 
    def filter_unversioned_files(self, paths):
777
 
        """Filter out paths that are versioned.
 
183
        """Filter out paths that are not versioned.
778
184
 
779
185
        :return: set of paths.
780
186
        """
781
187
        # NB: we specifically *don't* call self.has_filename, because for
782
 
        # WorkingTrees that can indicate files that exist on disk but that
 
188
        # WorkingTrees that can indicate files that exist on disk but that 
783
189
        # are not versioned.
784
190
        pred = self.inventory.has_filename
785
191
        return set((p for p in paths if not pred(p)))
786
192
 
787
 
    @needs_read_lock
788
 
    def iter_entries_by_dir(self, specific_file_ids=None, yield_parents=False):
789
 
        """Walk the tree in 'by_dir' order.
790
 
 
791
 
        This will yield each entry in the tree as a (path, entry) tuple.
792
 
        The order that they are yielded is:
793
 
 
794
 
        See Tree.iter_entries_by_dir for details.
795
 
 
796
 
        :param yield_parents: If True, yield the parents from the root leading
797
 
            down to specific_file_ids that have been requested. This has no
798
 
            impact if specific_file_ids is None.
799
 
        """
800
 
        return self.inventory.iter_entries_by_dir(
801
 
            specific_file_ids=specific_file_ids, yield_parents=yield_parents)
802
 
 
803
 
    def get_file_by_path(self, path):
804
 
        return self.get_file(self._inventory.path2id(path), path)
805
 
 
 
193
 
 
194
# for compatibility
 
195
from bzrlib.revisiontree import RevisionTree
 
196
 
 
197
 
 
198
class EmptyTree(Tree):
 
199
 
 
200
    def __init__(self):
 
201
        self._inventory = Inventory()
 
202
        warn('EmptyTree is deprecated as of bzr 0.9 please use '
 
203
            'repository.revision_tree instead.',
 
204
            DeprecationWarning, stacklevel=2)
 
205
 
 
206
    def get_parent_ids(self):
 
207
        return []
 
208
 
 
209
    def get_symlink_target(self, file_id):
 
210
        return None
 
211
 
 
212
    def has_filename(self, filename):
 
213
        return False
 
214
 
 
215
    def kind(self, file_id):
 
216
        assert self._inventory[file_id].kind == "root_directory"
 
217
        return "root_directory"
 
218
 
 
219
    def list_files(self):
 
220
        return iter([])
 
221
    
 
222
    def __contains__(self, file_id):
 
223
        return file_id in self._inventory
 
224
 
 
225
    def get_file_sha1(self, file_id, path=None):
 
226
        assert self._inventory[file_id].kind == "root_directory"
 
227
        return None
 
228
 
 
229
 
 
230
######################################################################
 
231
# diff
 
232
 
 
233
# TODO: Merge these two functions into a single one that can operate
 
234
# on either a whole tree or a set of files.
 
235
 
 
236
# TODO: Return the diff in order by filename, not by category or in
 
237
# random order.  Can probably be done by lock-stepping through the
 
238
# filenames from both trees.
 
239
 
 
240
 
 
241
def file_status(filename, old_tree, new_tree):
 
242
    """Return single-letter status, old and new names for a file.
 
243
 
 
244
    The complexity here is in deciding how to represent renames;
 
245
    many complex cases are possible.
 
246
    """
 
247
    old_inv = old_tree.inventory
 
248
    new_inv = new_tree.inventory
 
249
    new_id = new_inv.path2id(filename)
 
250
    old_id = old_inv.path2id(filename)
 
251
 
 
252
    if not new_id and not old_id:
 
253
        # easy: doesn't exist in either; not versioned at all
 
254
        if new_tree.is_ignored(filename):
 
255
            return 'I', None, None
 
256
        else:
 
257
            return '?', None, None
 
258
    elif new_id:
 
259
        # There is now a file of this name, great.
 
260
        pass
 
261
    else:
 
262
        # There is no longer a file of this name, but we can describe
 
263
        # what happened to the file that used to have
 
264
        # this name.  There are two possibilities: either it was
 
265
        # deleted entirely, or renamed.
 
266
        assert old_id
 
267
        if new_inv.has_id(old_id):
 
268
            return 'X', old_inv.id2path(old_id), new_inv.id2path(old_id)
 
269
        else:
 
270
            return 'D', old_inv.id2path(old_id), None
 
271
 
 
272
    # if the file_id is new in this revision, it is added
 
273
    if new_id and not old_inv.has_id(new_id):
 
274
        return 'A'
 
275
 
 
276
    # if there used to be a file of this name, but that ID has now
 
277
    # disappeared, it is deleted
 
278
    if old_id and not new_inv.has_id(old_id):
 
279
        return 'D'
 
280
 
 
281
    return 'wtf?'
 
282
 
 
283
    
 
284
 
 
285
def find_renames(old_inv, new_inv):
 
286
    for file_id in old_inv:
 
287
        if file_id not in new_inv:
 
288
            continue
 
289
        old_name = old_inv.id2path(file_id)
 
290
        new_name = new_inv.id2path(file_id)
 
291
        if old_name != new_name:
 
292
            yield (old_name, new_name)
 
293
            
806
294
 
807
295
def find_ids_across_trees(filenames, trees, require_versioned=True):
808
296
    """Find the ids corresponding to specified filenames.
809
 
 
 
297
    
810
298
    All matches in all trees will be used, and all children of matched
811
299
    directories will be used.
812
300
 
813
 
    :param filenames: The filenames to find file_ids for (if None, returns
814
 
        None)
 
301
    :param filenames: The filenames to find file_ids for
815
302
    :param trees: The trees to find file_ids within
816
303
    :param require_versioned: if true, all specified filenames must occur in
817
 
        at least one tree.
 
304
    at least one tree.
818
305
    :return: a set of file ids for the specified filenames and their children.
819
306
    """
820
307
    if not filenames:
821
308
        return None
822
 
    specified_path_ids = _find_ids_across_trees(filenames, trees,
823
 
        require_versioned)
824
 
    return _find_children_across_trees(specified_path_ids, trees)
825
 
 
826
 
 
827
 
def _find_ids_across_trees(filenames, trees, require_versioned):
 
309
    specified_ids = _find_filename_ids_across_trees(filenames, trees, 
 
310
                                                    require_versioned)
 
311
    return _find_children_across_trees(specified_ids, trees)
 
312
 
 
313
 
 
314
def _find_filename_ids_across_trees(filenames, trees, require_versioned):
828
315
    """Find the ids corresponding to specified filenames.
829
 
 
830
 
    All matches in all trees will be used, but subdirectories are not scanned.
 
316
    
 
317
    All matches in all trees will be used.
831
318
 
832
319
    :param filenames: The filenames to find file_ids for
833
320
    :param trees: The trees to find file_ids within
834
321
    :param require_versioned: if true, all specified filenames must occur in
835
 
        at least one tree.
 
322
    at least one tree.
836
323
    :return: a set of file ids for the specified filenames
837
324
    """
838
325
    not_versioned = []
840
327
    for tree_path in filenames:
841
328
        not_found = True
842
329
        for tree in trees:
843
 
            file_id = tree.path2id(tree_path)
 
330
            file_id = tree.inventory.path2id(tree_path)
844
331
            if file_id is not None:
845
332
                interesting_ids.add(file_id)
846
333
                not_found = False
852
339
 
853
340
 
854
341
def _find_children_across_trees(specified_ids, trees):
855
 
    """Return a set including specified ids and their children.
856
 
 
 
342
    """Return a set including specified ids and their children
 
343
    
857
344
    All matches in all trees will be used.
858
345
 
859
346
    :param trees: The trees to find file_ids within
860
 
    :return: a set containing all specified ids and their children
 
347
    :return: a set containing all specified ids and their children 
861
348
    """
862
349
    interesting_ids = set(specified_ids)
863
350
    pending = interesting_ids
867
354
        new_pending = set()
868
355
        for file_id in pending:
869
356
            for tree in trees:
870
 
                if not tree.has_or_had_id(file_id):
 
357
                if file_id not in tree:
871
358
                    continue
872
 
                for child_id in tree.iter_children(file_id):
873
 
                    if child_id not in interesting_ids:
874
 
                        new_pending.add(child_id)
 
359
                entry = tree.inventory[file_id]
 
360
                for child in getattr(entry, 'children', {}).itervalues():
 
361
                    if child.file_id not in interesting_ids:
 
362
                        new_pending.add(child.file_id)
875
363
        interesting_ids.update(new_pending)
876
364
        pending = new_pending
877
365
    return interesting_ids
883
371
    Its instances have methods like 'compare' and contain references to the
884
372
    source and target trees these operations are to be carried out on.
885
373
 
886
 
    Clients of bzrlib should not need to use InterTree directly, rather they
 
374
    clients of bzrlib should not need to use InterTree directly, rather they
887
375
    should use the convenience methods on Tree such as 'Tree.compare()' which
888
376
    will pass through to InterTree as appropriate.
889
377
    """
890
378
 
891
 
    # Formats that will be used to test this InterTree. If both are
892
 
    # None, this InterTree will not be tested (e.g. because a complex
893
 
    # setup is required)
894
 
    _matching_from_tree_format = None
895
 
    _matching_to_tree_format = None
896
 
 
897
 
    _optimisers = []
898
 
 
899
 
    @classmethod
900
 
    def is_compatible(kls, source, target):
901
 
        # The default implementation is naive and uses the public API, so
902
 
        # it works for all trees.
903
 
        return True
904
 
 
905
 
    def _changes_from_entries(self, source_entry, target_entry,
906
 
        source_path=None, target_path=None):
907
 
        """Generate a iter_changes tuple between source_entry and target_entry.
908
 
 
909
 
        :param source_entry: An inventory entry from self.source, or None.
910
 
        :param target_entry: An inventory entry from self.target, or None.
911
 
        :param source_path: The path of source_entry, if known. If not known
912
 
            it will be looked up.
913
 
        :param target_path: The path of target_entry, if known. If not known
914
 
            it will be looked up.
915
 
        :return: A tuple, item 0 of which is an iter_changes result tuple, and
916
 
            item 1 is True if there are any changes in the result tuple.
917
 
        """
918
 
        if source_entry is None:
919
 
            if target_entry is None:
920
 
                return None
921
 
            file_id = target_entry.file_id
922
 
        else:
923
 
            file_id = source_entry.file_id
924
 
        if source_entry is not None:
925
 
            source_versioned = True
926
 
            source_name = source_entry.name
927
 
            source_parent = source_entry.parent_id
928
 
            if source_path is None:
929
 
                source_path = self.source.id2path(file_id)
930
 
            source_kind, source_executable, source_stat = \
931
 
                self.source._comparison_data(source_entry, source_path)
932
 
        else:
933
 
            source_versioned = False
934
 
            source_name = None
935
 
            source_parent = None
936
 
            source_kind = None
937
 
            source_executable = None
938
 
        if target_entry is not None:
939
 
            target_versioned = True
940
 
            target_name = target_entry.name
941
 
            target_parent = target_entry.parent_id
942
 
            if target_path is None:
943
 
                target_path = self.target.id2path(file_id)
944
 
            target_kind, target_executable, target_stat = \
945
 
                self.target._comparison_data(target_entry, target_path)
946
 
        else:
947
 
            target_versioned = False
948
 
            target_name = None
949
 
            target_parent = None
950
 
            target_kind = None
951
 
            target_executable = None
952
 
        versioned = (source_versioned, target_versioned)
953
 
        kind = (source_kind, target_kind)
954
 
        changed_content = False
955
 
        if source_kind != target_kind:
956
 
            changed_content = True
957
 
        elif source_kind == 'file':
958
 
            if (self.source.get_file_sha1(file_id, source_path, source_stat) !=
959
 
                self.target.get_file_sha1(file_id, target_path, target_stat)):
960
 
                changed_content = True
961
 
        elif source_kind == 'symlink':
962
 
            if (self.source.get_symlink_target(file_id) !=
963
 
                self.target.get_symlink_target(file_id)):
964
 
                changed_content = True
965
 
            # XXX: Yes, the indentation below is wrong. But fixing it broke
966
 
            # test_merge.TestMergerEntriesLCAOnDisk.
967
 
            # test_nested_tree_subtree_renamed_and_modified. We'll wait for
968
 
            # the fix from bzr.dev -- vila 2009026
969
 
            elif source_kind == 'tree-reference':
970
 
                if (self.source.get_reference_revision(file_id, source_path)
971
 
                    != self.target.get_reference_revision(file_id, target_path)):
972
 
                    changed_content = True
973
 
        parent = (source_parent, target_parent)
974
 
        name = (source_name, target_name)
975
 
        executable = (source_executable, target_executable)
976
 
        if (changed_content is not False or versioned[0] != versioned[1]
977
 
            or parent[0] != parent[1] or name[0] != name[1] or
978
 
            executable[0] != executable[1]):
979
 
            changes = True
980
 
        else:
981
 
            changes = False
982
 
        return (file_id, (source_path, target_path), changed_content,
983
 
                versioned, parent, name, kind, executable), changes
 
379
    _optimisers = set()
984
380
 
985
381
    @needs_read_lock
986
382
    def compare(self, want_unchanged=False, specific_files=None,
987
 
        extra_trees=None, require_versioned=False, include_root=False,
988
 
        want_unversioned=False):
 
383
        extra_trees=None, require_versioned=False):
989
384
        """Return the changes from source to target.
990
385
 
991
386
        :return: A TreeDelta.
1000
395
        :param require_versioned: An optional boolean (defaults to False). When
1001
396
            supplied and True all the 'specific_files' must be versioned, or
1002
397
            a PathsNotVersionedError will be thrown.
1003
 
        :param want_unversioned: Scan for unversioned paths.
1004
398
        """
1005
 
        trees = (self.source,)
 
399
        # NB: show_status depends on being able to pass in non-versioned files and
 
400
        # report them as unknown
 
401
        trees = (self.source, self.target)
1006
402
        if extra_trees is not None:
1007
403
            trees = trees + tuple(extra_trees)
1008
 
        # target is usually the newer tree:
1009
 
        specific_file_ids = self.target.paths2ids(specific_files, trees,
1010
 
            require_versioned=require_versioned)
 
404
        specific_file_ids = find_ids_across_trees(specific_files,
 
405
            trees, require_versioned=require_versioned)
1011
406
        if specific_files and not specific_file_ids:
1012
407
            # All files are unversioned, so just return an empty delta
1013
408
            # _compare_trees would think we want a complete delta
1014
 
            result = delta.TreeDelta()
1015
 
            fake_entry = inventory.InventoryFile('unused', 'unused', 'unused')
1016
 
            result.unversioned = [(path, None,
1017
 
                self.target._comparison_data(fake_entry, path)[0]) for path in
1018
 
                specific_files]
1019
 
            return result
 
409
            return delta.TreeDelta()
1020
410
        return delta._compare_trees(self.source, self.target, want_unchanged,
1021
 
            specific_files, include_root, extra_trees=extra_trees,
1022
 
            require_versioned=require_versioned,
1023
 
            want_unversioned=want_unversioned)
1024
 
 
1025
 
    def iter_changes(self, include_unchanged=False,
1026
 
                      specific_files=None, pb=None, extra_trees=[],
1027
 
                      require_versioned=True, want_unversioned=False):
1028
 
        """Generate an iterator of changes between trees.
1029
 
 
1030
 
        A tuple is returned:
1031
 
        (file_id, (path_in_source, path_in_target),
1032
 
         changed_content, versioned, parent, name, kind,
1033
 
         executable)
1034
 
 
1035
 
        Changed_content is True if the file's content has changed.  This
1036
 
        includes changes to its kind, and to a symlink's target.
1037
 
 
1038
 
        versioned, parent, name, kind, executable are tuples of (from, to).
1039
 
        If a file is missing in a tree, its kind is None.
1040
 
 
1041
 
        Iteration is done in parent-to-child order, relative to the target
1042
 
        tree.
1043
 
 
1044
 
        There is no guarantee that all paths are in sorted order: the
1045
 
        requirement to expand the search due to renames may result in children
1046
 
        that should be found early being found late in the search, after
1047
 
        lexically later results have been returned.
1048
 
        :param require_versioned: Raise errors.PathsNotVersionedError if a
1049
 
            path in the specific_files list is not versioned in one of
1050
 
            source, target or extra_trees.
1051
 
        :param specific_files: An optional list of file paths to restrict the
1052
 
            comparison to. When mapping filenames to ids, all matches in all
1053
 
            trees (including optional extra_trees) are used, and all children
1054
 
            of matched directories are included. The parents in the target tree
1055
 
            of the specific files up to and including the root of the tree are
1056
 
            always evaluated for changes too.
1057
 
        :param want_unversioned: Should unversioned files be returned in the
1058
 
            output. An unversioned file is defined as one with (False, False)
1059
 
            for the versioned pair.
1060
 
        """
1061
 
        lookup_trees = [self.source]
1062
 
        if extra_trees:
1063
 
             lookup_trees.extend(extra_trees)
1064
 
        # The ids of items we need to examine to insure delta consistency.
1065
 
        precise_file_ids = set()
1066
 
        changed_file_ids = []
1067
 
        if specific_files == []:
1068
 
            specific_file_ids = []
1069
 
        else:
1070
 
            specific_file_ids = self.target.paths2ids(specific_files,
1071
 
                lookup_trees, require_versioned=require_versioned)
1072
 
        if specific_files is not None:
1073
 
            # reparented or added entries must have their parents included
1074
 
            # so that valid deltas can be created. The seen_parents set
1075
 
            # tracks the parents that we need to have.
1076
 
            # The seen_dirs set tracks directory entries we've yielded.
1077
 
            # After outputting version object in to_entries we set difference
1078
 
            # the two seen sets and start checking parents.
1079
 
            seen_parents = set()
1080
 
            seen_dirs = set()
1081
 
        if want_unversioned:
1082
 
            all_unversioned = sorted([(p.split('/'), p) for p in
1083
 
                                     self.target.extras()
1084
 
                if specific_files is None or
1085
 
                    osutils.is_inside_any(specific_files, p)])
1086
 
            all_unversioned = collections.deque(all_unversioned)
1087
 
        else:
1088
 
            all_unversioned = collections.deque()
1089
 
        to_paths = {}
1090
 
        from_entries_by_dir = list(self.source.iter_entries_by_dir(
1091
 
            specific_file_ids=specific_file_ids))
1092
 
        from_data = dict((e.file_id, (p, e)) for p, e in from_entries_by_dir)
1093
 
        to_entries_by_dir = list(self.target.iter_entries_by_dir(
1094
 
            specific_file_ids=specific_file_ids))
1095
 
        num_entries = len(from_entries_by_dir) + len(to_entries_by_dir)
1096
 
        entry_count = 0
1097
 
        # the unversioned path lookup only occurs on real trees - where there
1098
 
        # can be extras. So the fake_entry is solely used to look up
1099
 
        # executable it values when execute is not supported.
1100
 
        fake_entry = inventory.InventoryFile('unused', 'unused', 'unused')
1101
 
        for target_path, target_entry in to_entries_by_dir:
1102
 
            while (all_unversioned and
1103
 
                all_unversioned[0][0] < target_path.split('/')):
1104
 
                unversioned_path = all_unversioned.popleft()
1105
 
                target_kind, target_executable, target_stat = \
1106
 
                    self.target._comparison_data(fake_entry, unversioned_path[1])
1107
 
                yield (None, (None, unversioned_path[1]), True, (False, False),
1108
 
                    (None, None),
1109
 
                    (None, unversioned_path[0][-1]),
1110
 
                    (None, target_kind),
1111
 
                    (None, target_executable))
1112
 
            source_path, source_entry = from_data.get(target_entry.file_id,
1113
 
                (None, None))
1114
 
            result, changes = self._changes_from_entries(source_entry,
1115
 
                target_entry, source_path=source_path, target_path=target_path)
1116
 
            to_paths[result[0]] = result[1][1]
1117
 
            entry_count += 1
1118
 
            if result[3][0]:
1119
 
                entry_count += 1
1120
 
            if pb is not None:
1121
 
                pb.update('comparing files', entry_count, num_entries)
1122
 
            if changes or include_unchanged:
1123
 
                if specific_file_ids is not None:
1124
 
                    new_parent_id = result[4][1]
1125
 
                    precise_file_ids.add(new_parent_id)
1126
 
                    changed_file_ids.append(result[0])
1127
 
                yield result
1128
 
            # Ensure correct behaviour for reparented/added specific files.
1129
 
            if specific_files is not None:
1130
 
                # Record output dirs
1131
 
                if result[6][1] == 'directory':
1132
 
                    seen_dirs.add(result[0])
1133
 
                # Record parents of reparented/added entries.
1134
 
                versioned = result[3]
1135
 
                parents = result[4]
1136
 
                if not versioned[0] or parents[0] != parents[1]:
1137
 
                    seen_parents.add(parents[1])
1138
 
        while all_unversioned:
1139
 
            # yield any trailing unversioned paths
1140
 
            unversioned_path = all_unversioned.popleft()
1141
 
            to_kind, to_executable, to_stat = \
1142
 
                self.target._comparison_data(fake_entry, unversioned_path[1])
1143
 
            yield (None, (None, unversioned_path[1]), True, (False, False),
1144
 
                (None, None),
1145
 
                (None, unversioned_path[0][-1]),
1146
 
                (None, to_kind),
1147
 
                (None, to_executable))
1148
 
        # Yield all remaining source paths
1149
 
        for path, from_entry in from_entries_by_dir:
1150
 
            file_id = from_entry.file_id
1151
 
            if file_id in to_paths:
1152
 
                # already returned
1153
 
                continue
1154
 
            if not self.target.has_id(file_id):
1155
 
                # common case - paths we have not emitted are not present in
1156
 
                # target.
1157
 
                to_path = None
1158
 
            else:
1159
 
                to_path = self.target.id2path(file_id)
1160
 
            entry_count += 1
1161
 
            if pb is not None:
1162
 
                pb.update('comparing files', entry_count, num_entries)
1163
 
            versioned = (True, False)
1164
 
            parent = (from_entry.parent_id, None)
1165
 
            name = (from_entry.name, None)
1166
 
            from_kind, from_executable, stat_value = \
1167
 
                self.source._comparison_data(from_entry, path)
1168
 
            kind = (from_kind, None)
1169
 
            executable = (from_executable, None)
1170
 
            changed_content = from_kind is not None
1171
 
            # the parent's path is necessarily known at this point.
1172
 
            changed_file_ids.append(file_id)
1173
 
            yield(file_id, (path, to_path), changed_content, versioned, parent,
1174
 
                  name, kind, executable)
1175
 
        changed_file_ids = set(changed_file_ids)
1176
 
        if specific_file_ids is not None:
1177
 
            for result in self._handle_precise_ids(precise_file_ids,
1178
 
                changed_file_ids):
1179
 
                yield result
1180
 
 
1181
 
    def _get_entry(self, tree, file_id):
1182
 
        """Get an inventory entry from a tree, with missing entries as None.
1183
 
 
1184
 
        If the tree raises NotImplementedError on accessing .inventory, then
1185
 
        this is worked around using iter_entries_by_dir on just the file id
1186
 
        desired.
1187
 
 
1188
 
        :param tree: The tree to lookup the entry in.
1189
 
        :param file_id: The file_id to lookup.
1190
 
        """
1191
 
        try:
1192
 
            inventory = tree.inventory
1193
 
        except NotImplementedError:
1194
 
            # No inventory available.
1195
 
            try:
1196
 
                iterator = tree.iter_entries_by_dir(specific_file_ids=[file_id])
1197
 
                return iterator.next()[1]
1198
 
            except StopIteration:
1199
 
                return None
1200
 
        else:
1201
 
            try:
1202
 
                return inventory[file_id]
1203
 
            except errors.NoSuchId:
1204
 
                return None
1205
 
 
1206
 
    def _handle_precise_ids(self, precise_file_ids, changed_file_ids,
1207
 
        discarded_changes=None):
1208
 
        """Fill out a partial iter_changes to be consistent.
1209
 
 
1210
 
        :param precise_file_ids: The file ids of parents that were seen during
1211
 
            the iter_changes.
1212
 
        :param changed_file_ids: The file ids of already emitted items.
1213
 
        :param discarded_changes: An optional dict of precalculated
1214
 
            iter_changes items which the partial iter_changes had not output
1215
 
            but had calculated.
1216
 
        :return: A generator of iter_changes items to output.
1217
 
        """
1218
 
        # process parents of things that had changed under the users
1219
 
        # requested paths to prevent incorrect paths or parent ids which
1220
 
        # aren't in the tree.
1221
 
        while precise_file_ids:
1222
 
            precise_file_ids.discard(None)
1223
 
            # Don't emit file_ids twice
1224
 
            precise_file_ids.difference_update(changed_file_ids)
1225
 
            if not precise_file_ids:
1226
 
                break
1227
 
            # If the there was something at a given output path in source, we
1228
 
            # have to include the entry from source in the delta, or we would
1229
 
            # be putting this entry into a used path.
1230
 
            paths = []
1231
 
            for parent_id in precise_file_ids:
1232
 
                try:
1233
 
                    paths.append(self.target.id2path(parent_id))
1234
 
                except errors.NoSuchId:
1235
 
                    # This id has been dragged in from the source by delta
1236
 
                    # expansion and isn't present in target at all: we don't
1237
 
                    # need to check for path collisions on it.
1238
 
                    pass
1239
 
            for path in paths:
1240
 
                old_id = self.source.path2id(path)
1241
 
                precise_file_ids.add(old_id)
1242
 
            precise_file_ids.discard(None)
1243
 
            current_ids = precise_file_ids
1244
 
            precise_file_ids = set()
1245
 
            # We have to emit all of precise_file_ids that have been altered.
1246
 
            # We may have to output the children of some of those ids if any
1247
 
            # directories have stopped being directories.
1248
 
            for file_id in current_ids:
1249
 
                # Examine file_id
1250
 
                if discarded_changes:
1251
 
                    result = discarded_changes.get(file_id)
1252
 
                    old_entry = None
1253
 
                else:
1254
 
                    result = None
1255
 
                if result is None:
1256
 
                    old_entry = self._get_entry(self.source, file_id)
1257
 
                    new_entry = self._get_entry(self.target, file_id)
1258
 
                    result, changes = self._changes_from_entries(
1259
 
                        old_entry, new_entry)
1260
 
                else:
1261
 
                    changes = True
1262
 
                # Get this parents parent to examine.
1263
 
                new_parent_id = result[4][1]
1264
 
                precise_file_ids.add(new_parent_id)
1265
 
                if changes:
1266
 
                    if (result[6][0] == 'directory' and
1267
 
                        result[6][1] != 'directory'):
1268
 
                        # This stopped being a directory, the old children have
1269
 
                        # to be included.
1270
 
                        if old_entry is None:
1271
 
                            # Reusing a discarded change.
1272
 
                            old_entry = self._get_entry(self.source, file_id)
1273
 
                        for child in old_entry.children.values():
1274
 
                            precise_file_ids.add(child.file_id)
1275
 
                    changed_file_ids.add(result[0])
1276
 
                    yield result
1277
 
 
1278
 
 
1279
 
InterTree.register_optimiser(InterTree)
1280
 
 
1281
 
 
1282
 
class MultiWalker(object):
1283
 
    """Walk multiple trees simultaneously, getting combined results."""
1284
 
 
1285
 
    # Note: This could be written to not assume you can do out-of-order
1286
 
    #       lookups. Instead any nodes that don't match in all trees could be
1287
 
    #       marked as 'deferred', and then returned in the final cleanup loop.
1288
 
    #       For now, I think it is "nicer" to return things as close to the
1289
 
    #       "master_tree" order as we can.
1290
 
 
1291
 
    def __init__(self, master_tree, other_trees):
1292
 
        """Create a new MultiWalker.
1293
 
 
1294
 
        All trees being walked must implement "iter_entries_by_dir()", such
1295
 
        that they yield (path, object) tuples, where that object will have a
1296
 
        '.file_id' member, that can be used to check equality.
1297
 
 
1298
 
        :param master_tree: All trees will be 'slaved' to the master_tree such
1299
 
            that nodes in master_tree will be used as 'first-pass' sync points.
1300
 
            Any nodes that aren't in master_tree will be merged in a second
1301
 
            pass.
1302
 
        :param other_trees: A list of other trees to walk simultaneously.
1303
 
        """
1304
 
        self._master_tree = master_tree
1305
 
        self._other_trees = other_trees
1306
 
 
1307
 
        # Keep track of any nodes that were properly processed just out of
1308
 
        # order, that way we don't return them at the end, we don't have to
1309
 
        # track *all* processed file_ids, just the out-of-order ones
1310
 
        self._out_of_order_processed = set()
1311
 
 
1312
 
    @staticmethod
1313
 
    def _step_one(iterator):
1314
 
        """Step an iter_entries_by_dir iterator.
1315
 
 
1316
 
        :return: (has_more, path, ie)
1317
 
            If has_more is False, path and ie will be None.
1318
 
        """
1319
 
        try:
1320
 
            path, ie = iterator.next()
1321
 
        except StopIteration:
1322
 
            return False, None, None
1323
 
        else:
1324
 
            return True, path, ie
1325
 
 
1326
 
    @staticmethod
1327
 
    def _cmp_path_by_dirblock(path1, path2):
1328
 
        """Compare two paths based on what directory they are in.
1329
 
 
1330
 
        This generates a sort order, such that all children of a directory are
1331
 
        sorted together, and grandchildren are in the same order as the
1332
 
        children appear. But all grandchildren come after all children.
1333
 
 
1334
 
        :param path1: first path
1335
 
        :param path2: the second path
1336
 
        :return: negative number if ``path1`` comes first,
1337
 
            0 if paths are equal
1338
 
            and a positive number if ``path2`` sorts first
1339
 
        """
1340
 
        # Shortcut this special case
1341
 
        if path1 == path2:
1342
 
            return 0
1343
 
        # This is stolen from _dirstate_helpers_py.py, only switching it to
1344
 
        # Unicode objects. Consider using encode_utf8() and then using the
1345
 
        # optimized versions, or maybe writing optimized unicode versions.
1346
 
        if not isinstance(path1, unicode):
1347
 
            raise TypeError("'path1' must be a unicode string, not %s: %r"
1348
 
                            % (type(path1), path1))
1349
 
        if not isinstance(path2, unicode):
1350
 
            raise TypeError("'path2' must be a unicode string, not %s: %r"
1351
 
                            % (type(path2), path2))
1352
 
        return cmp(MultiWalker._path_to_key(path1),
1353
 
                   MultiWalker._path_to_key(path2))
1354
 
 
1355
 
    @staticmethod
1356
 
    def _path_to_key(path):
1357
 
        dirname, basename = osutils.split(path)
1358
 
        return (dirname.split(u'/'), basename)
1359
 
 
1360
 
    def _lookup_by_file_id(self, extra_entries, other_tree, file_id):
1361
 
        """Lookup an inventory entry by file_id.
1362
 
 
1363
 
        This is called when an entry is missing in the normal order.
1364
 
        Generally this is because a file was either renamed, or it was
1365
 
        deleted/added. If the entry was found in the inventory and not in
1366
 
        extra_entries, it will be added to self._out_of_order_processed
1367
 
 
1368
 
        :param extra_entries: A dictionary of {file_id: (path, ie)}.  This
1369
 
            should be filled with entries that were found before they were
1370
 
            used. If file_id is present, it will be removed from the
1371
 
            dictionary.
1372
 
        :param other_tree: The Tree to search, in case we didn't find the entry
1373
 
            yet.
1374
 
        :param file_id: The file_id to look for
1375
 
        :return: (path, ie) if found or (None, None) if not present.
1376
 
        """
1377
 
        if file_id in extra_entries:
1378
 
            return extra_entries.pop(file_id)
1379
 
        # TODO: Is id2path better as the first call, or is
1380
 
        #       inventory[file_id] better as a first check?
1381
 
        try:
1382
 
            cur_path = other_tree.id2path(file_id)
1383
 
        except errors.NoSuchId:
1384
 
            cur_path = None
1385
 
        if cur_path is None:
1386
 
            return (None, None)
1387
 
        else:
1388
 
            self._out_of_order_processed.add(file_id)
1389
 
            cur_ie = other_tree.inventory[file_id]
1390
 
            return (cur_path, cur_ie)
1391
 
 
1392
 
    def iter_all(self):
1393
 
        """Match up the values in the different trees."""
1394
 
        for result in self._walk_master_tree():
1395
 
            yield result
1396
 
        self._finish_others()
1397
 
        for result in self._walk_others():
1398
 
            yield result
1399
 
 
1400
 
    def _walk_master_tree(self):
1401
 
        """First pass, walk all trees in lock-step.
1402
 
 
1403
 
        When we are done, all nodes in the master_tree will have been
1404
 
        processed. _other_walkers, _other_entries, and _others_extra will be
1405
 
        set on 'self' for future processing.
1406
 
        """
1407
 
        # This iterator has the most "inlining" done, because it tends to touch
1408
 
        # every file in the tree, while the others only hit nodes that don't
1409
 
        # match.
1410
 
        master_iterator = self._master_tree.iter_entries_by_dir()
1411
 
 
1412
 
        other_walkers = [other.iter_entries_by_dir()
1413
 
                         for other in self._other_trees]
1414
 
        other_entries = [self._step_one(walker) for walker in other_walkers]
1415
 
        # Track extra nodes in the other trees
1416
 
        others_extra = [{} for i in xrange(len(self._other_trees))]
1417
 
 
1418
 
        master_has_more = True
1419
 
        step_one = self._step_one
1420
 
        lookup_by_file_id = self._lookup_by_file_id
1421
 
        out_of_order_processed = self._out_of_order_processed
1422
 
 
1423
 
        while master_has_more:
1424
 
            (master_has_more, path, master_ie) = step_one(master_iterator)
1425
 
            if not master_has_more:
1426
 
                break
1427
 
 
1428
 
            file_id = master_ie.file_id
1429
 
            other_values = []
1430
 
            other_values_append = other_values.append
1431
 
            next_other_entries = []
1432
 
            next_other_entries_append = next_other_entries.append
1433
 
            for idx, (other_has_more, other_path, other_ie) in enumerate(other_entries):
1434
 
                if not other_has_more:
1435
 
                    other_values_append(lookup_by_file_id(
1436
 
                        others_extra[idx], self._other_trees[idx], file_id))
1437
 
                    next_other_entries_append((False, None, None))
1438
 
                elif file_id == other_ie.file_id:
1439
 
                    # This is the critical code path, as most of the entries
1440
 
                    # should match between most trees.
1441
 
                    other_values_append((other_path, other_ie))
1442
 
                    next_other_entries_append(step_one(other_walkers[idx]))
1443
 
                else:
1444
 
                    # This walker did not match, step it until it either
1445
 
                    # matches, or we know we are past the current walker.
1446
 
                    other_walker = other_walkers[idx]
1447
 
                    other_extra = others_extra[idx]
1448
 
                    while (other_has_more and
1449
 
                           self._cmp_path_by_dirblock(other_path, path) < 0):
1450
 
                        other_file_id = other_ie.file_id
1451
 
                        if other_file_id not in out_of_order_processed:
1452
 
                            other_extra[other_file_id] = (other_path, other_ie)
1453
 
                        other_has_more, other_path, other_ie = \
1454
 
                            step_one(other_walker)
1455
 
                    if other_has_more and other_ie.file_id == file_id:
1456
 
                        # We ended up walking to this point, match and step
1457
 
                        # again
1458
 
                        other_values_append((other_path, other_ie))
1459
 
                        other_has_more, other_path, other_ie = \
1460
 
                            step_one(other_walker)
1461
 
                    else:
1462
 
                        # This record isn't in the normal order, see if it
1463
 
                        # exists at all.
1464
 
                        other_values_append(lookup_by_file_id(
1465
 
                            other_extra, self._other_trees[idx], file_id))
1466
 
                    next_other_entries_append((other_has_more, other_path,
1467
 
                                               other_ie))
1468
 
            other_entries = next_other_entries
1469
 
 
1470
 
            # We've matched all the walkers, yield this datapoint
1471
 
            yield path, file_id, master_ie, other_values
1472
 
        self._other_walkers = other_walkers
1473
 
        self._other_entries = other_entries
1474
 
        self._others_extra = others_extra
1475
 
 
1476
 
    def _finish_others(self):
1477
 
        """Finish walking the other iterators, so we get all entries."""
1478
 
        for idx, info in enumerate(self._other_entries):
1479
 
            other_extra = self._others_extra[idx]
1480
 
            (other_has_more, other_path, other_ie) = info
1481
 
            while other_has_more:
1482
 
                other_file_id = other_ie.file_id
1483
 
                if other_file_id not in self._out_of_order_processed:
1484
 
                    other_extra[other_file_id] = (other_path, other_ie)
1485
 
                other_has_more, other_path, other_ie = \
1486
 
                    self._step_one(self._other_walkers[idx])
1487
 
        del self._other_entries
1488
 
 
1489
 
    def _walk_others(self):
1490
 
        """Finish up by walking all the 'deferred' nodes."""
1491
 
        # TODO: One alternative would be to grab all possible unprocessed
1492
 
        #       file_ids, and then sort by path, and then yield them. That
1493
 
        #       might ensure better ordering, in case a caller strictly
1494
 
        #       requires parents before children.
1495
 
        for idx, other_extra in enumerate(self._others_extra):
1496
 
            others = sorted(other_extra.itervalues(),
1497
 
                            key=lambda x: self._path_to_key(x[0]))
1498
 
            for other_path, other_ie in others:
1499
 
                file_id = other_ie.file_id
1500
 
                # We don't need to check out_of_order_processed here, because
1501
 
                # the lookup_by_file_id will be removing anything processed
1502
 
                # from the extras cache
1503
 
                other_extra.pop(file_id)
1504
 
                other_values = [(None, None) for i in xrange(idx)]
1505
 
                other_values.append((other_path, other_ie))
1506
 
                for alt_idx, alt_extra in enumerate(self._others_extra[idx+1:]):
1507
 
                    alt_idx = alt_idx + idx + 1
1508
 
                    alt_extra = self._others_extra[alt_idx]
1509
 
                    alt_tree = self._other_trees[alt_idx]
1510
 
                    other_values.append(self._lookup_by_file_id(
1511
 
                                            alt_extra, alt_tree, file_id))
1512
 
                yield other_path, file_id, None, other_values
 
411
            specific_file_ids)