b.w.WorkingTree(bzrlib.mutabletree.MutableTree, controldir.ControlComponent) : class documentation

Part of bzrlib.workingtree View In Hierarchy

Known subclasses: bzrlib.workingtree.InventoryWorkingTree

Working copy tree.
Instance VariablesbasedirThe root of the tree on disk. This is a unicode path object (as opposed to a URL).
Method __init__ Construct a WorkingTree instance. This is not a public API.
Method user_transport Undocumented
Method control_transport Undocumented
Method is_control_filename True if filename is the name of a control file in this tree.
Method has_versioned_directories See Tree.has_versioned_directories.
Method break_lock Break a lock if one is present from another instance.
Method requires_rich_root Undocumented
Method supports_tree_reference Undocumented
Method supports_content_filtering Undocumented
Method supports_views Undocumented
Static Method open Open an existing working tree at path.
Static Method open_containing Open an existing working tree which has its root about path.
Static Method open_containing_paths Open the WorkingTree that contains a set of paths.
Method safe_relpath_files Convert file_list into a list of relpaths in tree.
Static Method open_downlevel Open an unsupported working tree.
Static Method find_trees Undocumented
Method all_file_ids See Tree.iter_all_file_ids
Method __repr__ Undocumented
Method abspath Undocumented
Method basis_tree Return RevisionTree for the current last revision.
Method relpath Return the local path portion from a given path.
Method has_filename Undocumented
Method get_file Undocumented
Method get_file_with_stat See Tree.get_file_with_stat.
Method get_file_text Undocumented
Method get_file_byname Undocumented
Method get_file_lines See Tree.get_file_lines()
Method get_parent_ids See Tree.get_parent_ids.
Method get_root_id Return the id of this trees root
Method clone Duplicate this working tree into to_bzr, including all state.
Method copy_content_into Copy the current content and user files of this tree into tree.
Method id2abspath Undocumented
Method iter_entries_by_dir See Tree.iter_entries_by_dir()
Method get_file_size See Tree.get_file_size
Method add_parent_tree_id Add revision_id as a parent.
Method add_parent_tree Add revision_id, tree tuple as a parent.
Method add_pending_merge Undocumented
Method path_content_summary See Tree.path_content_summary.
Method set_parent_ids Set the parent ids to revision_ids.
Method set_pending_merges Undocumented
Method set_merge_modified Undocumented
Method merge_from_branch Merge from a branch into this working tree.
Method merge_modified Return a dictionary of files modified by a merge.
Method mkdir See MutableTree.mkdir().
Method get_symlink_target Undocumented
Method subsume Undocumented
Method extract Extract a subtree from this tree.
Method flush Write the in memory meta data to disk.
Method list_files List all files as (path, class, kind, id, entry).
Method move Rename files.
Method rename_one Rename one file.
Method unknowns Return all unknown files.
Method unversion Remove the file ids in file_ids from the current versioned set.
Method pull Undocumented
Method put_file_bytes_non_atomic See MutableTree.put_file_bytes_non_atomic.
Method extras Yield all unversioned files in this WorkingTree.
Method ignored_files Yield list of PATH, IGNORE_PATTERN
Method get_ignore_list Return list of ignore patterns.
Method is_ignored Check whether the filename matches an ignore pattern.
Method kind Undocumented
Method stored_kind See Tree.stored_kind
Method last_revision Return the last revision of the branch for this tree.
Method is_locked Undocumented
Method lock_read Lock the tree for reading.
Method lock_tree_write See MutableTree.lock_tree_write, and WorkingTree.unlock.
Method lock_write See MutableTree.lock_write, and WorkingTree.unlock.
Method get_physical_lock_status Undocumented
Method set_last_revision Change the last revision in the working tree.
Method remove Remove nominated files from the working tree metadata.
Method revert Undocumented
Method revision_tree See Tree.revision_tree.
Method set_root_id Set the root id for this tree.
Method unlock See Branch.unlock.
Method update Update a working tree along its branch.
Method set_conflicts Undocumented
Method add_conflicts Undocumented
Method conflicts Undocumented
Method walkdirs Walk the directories of this tree.
Method auto_resolve Automatically resolve text conflicts according to contents.
Method check_state Check that the working state is/isn't valid.
Method reset_state Reset the state of the working tree.
Method get_shelf_manager Return the ShelfManager for this WorkingTree.
Method _make_views Undocumented
Method _cleanup Undocumented
Method _check_for_tree_references See if directories have become tree-references.
Method _gather_kinds See MutableTree._gather_kinds.
Method _file_content_summary Undocumented
Method _check_parents_for_ghosts Common ghost checking functionality from set_parent_*.
Method _set_merges_from_parent_ids Undocumented
Method _filter_parent_ids_by_ancestry Check that all merged revisions are proper 'heads'.
Method _sha_from_stat Get a sha digest from the tree's stat cache.
Method _put_rio Undocumented
Method _setup_directory_is_tree_reference Undocumented
Method _directory_is_never_tree_reference Undocumented
Method _directory_may_be_tree_reference Undocumented
Method _kind Undocumented
Method _flush_ignore_list_cache Resets the cached ignore list to force a cache rebuild.
Method _comparison_data Undocumented
Method _file_size Undocumented
Method _last_revision helper for get_parent_ids.
Method _must_be_locked Undocumented
Method _reset_data Reset transient data that cannot be revalidated.
Method _change_last_revision Template method part of set_last_revision to perform the change.
Method _set_root_id Set the root id for this tree, in a format specific manner.
Method _update_tree Update a tree to the master branch.
Method _walkdirs Walk the directories of this tree.
Method _validate Validate internal structures.
Method _get_rules_searcher See Tree._get_rules_searcher.

Inherited from MutableTree:

Method add Add paths to the set of versioned paths.
Method add_reference Add a TreeReference to the tree, pointing at sub_tree
Method apply_inventory_delta Apply changes to the inventory as an atomic operation.
Method commit Undocumented
Method has_changes Quickly check that the tree contains at least one commitable change.
Method check_changed_or_out_of_date Check the tree for uncommitted changes and branch synchronization.
Method set_parent_trees Set the parents of the working tree.
Method smart_add Version file_list, optionally recursing into directories.
Method _add_reference Standard add_reference implementation, for use by subclasses
Method _add Helper function for add - updates the inventory.
Method _observed_sha1 Tell the tree we have observed a paths sha1.
def _make_views(self):
Undocumented
def __init__(self, basedir='.', branch=DEPRECATED_PARAMETER, _control_files=None, _internal=False, _format=None, _bzrdir=None):
Construct a WorkingTree instance. This is not a public API.
ParametersbranchA branch to override probing for the branch.
@property
def user_transport(self):
Undocumented
@property
def control_transport(self):
Undocumented
def is_control_filename(self, filename):
True if filename is the name of a control file in this tree.

This is true IF and ONLY IF the filename is part of the meta data that bzr controls in this tree. I.E. a random .bzr directory placed on disk will not be a control file for this tree.

ParametersfilenameA filename within the tree. This is a relative path from the root of this tree.
def has_versioned_directories(self):
See Tree.has_versioned_directories.
def break_lock(self):
Break a lock if one is present from another instance.

Uses the ui factory to ask for confirmation if the lock may be from an active process.

This will probe the repository for its lock as well.

def requires_rich_root(self):
Undocumented
def supports_tree_reference(self):
Undocumented
def supports_content_filtering(self):
Undocumented
def supports_views(self):
Undocumented
@staticmethod
def open(path=None, _unsupported=False):
Open an existing working tree at path.
@staticmethod
def open_containing(path=None):
Open an existing working tree which has its root about path.

This probes for a working tree at path and searches upwards from there.

Basically we keep looking up until we find the control directory or run into /. If there isn't one, raises NotBranchError. TODO: give this a new exception. If there is one, it is returned, along with the unused portion of path.

ReturnsThe WorkingTree that contains 'path', and the rest of path
@staticmethod
def open_containing_paths(file_list, default_directory=None, canonicalize=True, apply_view=True):
Open the WorkingTree that contains a set of paths.

Fail if the paths given are not all in a single tree.

This is used for the many command-line interfaces that take a list of any number of files and that require they all be in the same tree.

def safe_relpath_files(self, file_list, canonicalize=True, apply_view=True):
Convert file_list into a list of relpaths in tree.
ParametersselfA tree to operate on.
file_listA list of user provided paths or None.
apply_viewif True and a view is set, apply it or check that specified files are within it
ReturnsA list of relative paths.
Raiseserrors.PathNotChildWhen a provided path is in a different self than self.
@staticmethod
def open_downlevel(path=None):
Open an unsupported working tree.

Only intended for advanced situations like upgrading part of a bzrdir.

@staticmethod
def find_trees(location):
Undocumented
def all_file_ids(self):
See Tree.iter_all_file_ids
def __repr__(self):
Undocumented
def abspath(self, filename):
Undocumented
def basis_tree(self):
Return RevisionTree for the current last revision.

If the left most parent is a ghost then the returned tree will be an empty tree - one obtained by calling repository.revision_tree(NULL_REVISION).

def _cleanup(self):
Undocumented
def relpath(self, path):
Return the local path portion from a given path.

The path may be absolute or relative. If its a relative path it is interpreted relative to the python current working directory.

def has_filename(self, filename):
Undocumented
def get_file(self, file_id, path=None, filtered=True):
Undocumented
def get_file_with_stat(self, file_id, path=None, filtered=True, _fstat=osutils.fstat):
See Tree.get_file_with_stat.
def get_file_text(self, file_id, path=None, filtered=True):
Undocumented
def get_file_byname(self, filename, filtered=True):
Undocumented
def get_file_lines(self, file_id, path=None, filtered=True):
See Tree.get_file_lines()
def get_parent_ids(self):
See Tree.get_parent_ids.

This implementation reads the pending merges list and last_revision value and uses that to decide what the parents list should be.

def get_root_id(self):
Return the id of this trees root
@needs_read_lock
def clone(self, to_controldir, revision_id=None):

Duplicate this working tree into to_bzr, including all state.

Specifically modified files are kept as modified, but ignored and unknown files are discarded.

If you want to make a new line of development, see ControlDir.sprout()

revision
If not None, the cloned tree will have its last revision set to revision, and difference between the source trees last revision and this one merged in.
@needs_read_lock
def copy_content_into(self, tree, revision_id=None):
Copy the current content and user files of this tree into tree.
def id2abspath(self, file_id):
Undocumented
def _check_for_tree_references(self, iterator):
See if directories have become tree-references.
def iter_entries_by_dir(self, specific_file_ids=None, yield_parents=False):
See Tree.iter_entries_by_dir()
def get_file_size(self, file_id):
See Tree.get_file_size
@needs_tree_write_lock
def _gather_kinds(self, files, kinds):
See MutableTree._gather_kinds.
@needs_write_lock
def add_parent_tree_id(self, revision_id, allow_leftmost_as_ghost=False):
Add revision_id as a parent.

This is equivalent to retrieving the current list of parent ids and setting the list to its value plus revision_id.

Parametersrevision_idThe revision id to add to the parent list. It may be a ghost revision as long as its not the first parent to be added, or the allow_leftmost_as_ghost parameter is set True.
allow_leftmost_as_ghostAllow the first parent to be a ghost.
@needs_tree_write_lock
def add_parent_tree(self, parent_tuple, allow_leftmost_as_ghost=False):
Add revision_id, tree tuple as a parent.

This is equivalent to retrieving the current list of parent trees and setting the list to its value plus parent_tuple. See also add_parent_tree_id - if you only have a parent id available it will be simpler to use that api. If you have the parent already available, using this api is preferred.

Parametersparent_tupleThe (revision id, tree) to add to the parent list. If the revision_id is a ghost, pass None for the tree.
allow_leftmost_as_ghostAllow the first parent to be a ghost.
@needs_tree_write_lock
def add_pending_merge(self, *revision_ids):
Undocumented
def path_content_summary(self, path, _lstat=os.lstat, _mapper=osutils.file_kind_from_stat_mode):
See Tree.path_content_summary.
def _file_content_summary(self, path, stat_result):
Undocumented
def _check_parents_for_ghosts(self, revision_ids, allow_leftmost_as_ghost):
Common ghost checking functionality from set_parent_*.

This checks that the left hand-parent exists if there are any revisions present.

def _set_merges_from_parent_ids(self, parent_ids):
Undocumented
def _filter_parent_ids_by_ancestry(self, revision_ids):
Check that all merged revisions are proper 'heads'.

This will always return the first revision_id, and any merged revisions which are

@needs_tree_write_lock
def set_parent_ids(self, revision_ids, allow_leftmost_as_ghost=False):
Set the parent ids to revision_ids.

See also set_parent_trees. This api will try to retrieve the tree data for each element of revision_ids from the trees repository. If you have tree data already available, it is more efficient to use set_parent_trees rather than set_parent_ids. set_parent_ids is however an easier API to use.

Parametersrevision_idsThe revision_ids to set as the parent ids of this working tree. Any of these may be ghosts.
@needs_tree_write_lock
def set_pending_merges(self, rev_list):
Undocumented
@needs_tree_write_lock
def set_merge_modified(self, modified_hashes):
Undocumented
def _sha_from_stat(self, path, stat_result):
Get a sha digest from the tree's stat cache.

The default implementation assumes no stat cache is present.

ParameterspathThe path.
stat_resultThe stat result being looked up.
def _put_rio(self, filename, stanzas, header):
Undocumented
@needs_write_lock
def merge_from_branch(self, branch, to_revision=None, from_revision=None, merge_type=None, force=False):
Merge from a branch into this working tree.
ParametersbranchThe branch to merge from.
to_revisionIf non-None, the merge will merge to to_revision, but not beyond it. to_revision does not need to be in the history of the branch when it is supplied. If None, to_revision defaults to branch.last_revision().
def merge_modified(self):
Return a dictionary of files modified by a merge.

The list is initialized by WorkingTree.set_merge_modified, which is typically called after we make some automatic updates to the tree because of a merge.

This returns a map of file_id->sha1, containing only files which are still in the working inventory and have that text hash.

@needs_write_lock
def mkdir(self, path, file_id=None):
See MutableTree.mkdir().
def get_symlink_target(self, file_id, path=None):
Undocumented
def subsume(self, other_tree):
Undocumented
def _setup_directory_is_tree_reference(self):
Undocumented
def _directory_is_never_tree_reference(self, relpath):
Undocumented
def _directory_may_be_tree_reference(self, relpath):
Undocumented
def extract(self, file_id, format=None):
Extract a subtree from this tree.

A new branch will be created, relative to the path for this tree.

def flush(self):
Write the in memory meta data to disk.
def _kind(self, relpath):
Undocumented
def list_files(self, include_root=False, from_dir=None, recursive=True):
List all files as (path, class, kind, id, entry).

Lists, but does not descend into unversioned directories. This does not include files that have been deleted in this tree. Skips the control directory.

Parametersinclude_rootif True, return an entry for the root
from_dirstart from this directory or None for the root
recursivewhether to recurse into subdirectories or not
def move(self, from_paths, to_dir=None, after=False):
Rename files.

to_dir must be known to the working tree.

If to_dir exists and is a directory, the files are moved into it, keeping their old names.

Note that to_dir is only the last component of the new name; this doesn't change the directory.

For each entry in from_paths the move mode will be determined independently.

The first mode moves the file in the filesystem and updates the working tree metadata. The second mode only updates the working tree metadata without touching the file on the filesystem.

move uses the second mode if 'after == True' and the target is not versioned but present in the working tree.

move uses the second mode if 'after == False' and the source is versioned but no longer in the working tree, and the target is not versioned but present in the working tree.

move uses the first mode if 'after == False' and the source is versioned and present in the working tree, and the target is not versioned and not present in the working tree.

Everything else results in an error.

This returns a list of (from_path, to_path) pairs for each entry that is moved.

@needs_tree_write_lock
def rename_one(self, from_rel, to_rel, after=False):
Rename one file.

This can change the directory or the filename or both.

rename_one has several 'modes' to work. First, it can rename a physical file and change the file_id. That is the normal mode. Second, it can only change the file_id without touching any physical file.

rename_one uses the second mode if 'after == True' and 'to_rel' is either not versioned or newly added, and present in the working tree.

rename_one uses the second mode if 'after == False' and 'from_rel' is versioned but no longer in the working tree, and 'to_rel' is not versioned but present in the working tree.

rename_one uses the first mode if 'after == False' and 'from_rel' is versioned and present in the working tree, and 'to_rel' is not versioned and not present in the working tree.

Everything else results in an error.

@needs_read_lock
def unknowns(self):
Return all unknown files.

These are files in the working directory that are not versioned or control files or ignored.

def unversion(self, file_ids):
Remove the file ids in file_ids from the current versioned set.

When a file_id is unversioned, all of its children are automatically unversioned.

Parametersfile_idsThe file ids to stop versioning.
RaisesNoSuchId if any fileid is not currently versioned.
@needs_write_lock
def pull(self, source, overwrite=False, stop_revision=None, change_reporter=None, possible_transports=None, local=False, show_base=False):
Undocumented
@needs_write_lock
def put_file_bytes_non_atomic(self, file_id, bytes):
See MutableTree.put_file_bytes_non_atomic.
def extras(self):
Yield all unversioned files in this WorkingTree.

If there are any unversioned directories then only the directory is returned, not all its children. But if there are unversioned files under a versioned subdirectory, they are returned.

Currently returned depth-first, sorted by name within directories. This is the same order used by 'osutils.walkdirs'.

def ignored_files(self):
Yield list of PATH, IGNORE_PATTERN
def get_ignore_list(self):
Return list of ignore patterns.

Cached in the Tree object after the first call.

def _flush_ignore_list_cache(self):
Resets the cached ignore list to force a cache rebuild.
def is_ignored(self, filename):
Check whether the filename matches an ignore pattern.

Patterns containing '/' or '' need to match the whole path; others match against only the last component. Patterns starting with '!' are ignore exceptions. Exceptions take precedence over regular patterns and cause the filename to not be ignored.

If the file is ignored, returns the pattern which caused it to be ignored, otherwise None. So this can simply be used as a boolean if desired.

def kind(self, file_id):
Undocumented
def stored_kind(self, file_id):
See Tree.stored_kind
def _comparison_data(self, entry, path):
Undocumented
def _file_size(self, entry, stat_value):
Undocumented
def last_revision(self):
Return the last revision of the branch for this tree.

This format tree does not support a separate marker for last-revision compared to the branch.

See MutableTree.last_revision

@needs_read_lock
def _last_revision(self):
helper for get_parent_ids.
def is_locked(self):
Undocumented
def _must_be_locked(self):
Undocumented
def lock_read(self):
Lock the tree for reading.

This also locks the branch, and can be unlocked via self.unlock().

ReturnsA bzrlib.lock.LogicalLockResult.
def lock_tree_write(self):
See MutableTree.lock_tree_write, and WorkingTree.unlock.
ReturnsA bzrlib.lock.LogicalLockResult.
def lock_write(self):
See MutableTree.lock_write, and WorkingTree.unlock.
ReturnsA bzrlib.lock.LogicalLockResult.
def get_physical_lock_status(self):
Undocumented
def _reset_data(self):
Reset transient data that cannot be revalidated.
def set_last_revision(self, new_revision):
Change the last revision in the working tree.
def _change_last_revision(self, new_revision):
Template method part of set_last_revision to perform the change.

This is used to allow WorkingTree3 instances to not affect branch when their last revision is set.

@needs_tree_write_lock
def remove(self, files, verbose=False, to_file=None, keep_files=True, force=False):
Remove nominated files from the working tree metadata.
Unknown Field: filesFile paths relative to the basedir.
Unknown Field: keep_filesIf true, the files will also be kept.
Unknown Field: forceDelete files and directories, even if they are changed and even if the directories are not empty.
@needs_tree_write_lock
def revert(self, filenames=None, old_tree=None, backups=True, pb=None, report_changes=False):
Undocumented
def revision_tree(self, revision_id):
See Tree.revision_tree.

WorkingTree can supply revision_trees for the basis revision only because there is only one cached inventory in the bzr directory.

@needs_tree_write_lock
def set_root_id(self, file_id):
Set the root id for this tree.
def _set_root_id(self, file_id):
Set the root id for this tree, in a format specific manner.
Parametersfile_idThe file id to assign to the root. It must not be present in the current inventory or an error will occur. It must not be None, but rather a valid file id.
def unlock(self):
See Branch.unlock.

WorkingTree locking just uses the Branch locking facilities. This is current because all working trees have an embedded branch within them. IF in the future, we were to make branch data shareable between multiple working trees, i.e. via shared storage, then we would probably want to lock both the local tree, and the branch.

def update(self, change_reporter=None, possible_transports=None, revision=None, old_tip=_marker, show_base=False):

Update a working tree along its branch.

This will update the branch if its bound too, which means we have multiple trees involved:

  • The new basis tree of the master.
  • The old basis tree of the branch.
  • The old basis tree of the working tree.
  • The current working tree state.

Pathologically, all three may be different, and non-ancestors of each other. Conceptually we want to:

  • Preserve the wt.basis->wt.state changes
  • Transform the wt.basis to the new master basis.
  • Apply a merge of the old branch basis to get any 'local' changes from it into the tree.
  • Restore the wt.basis->wt.state changes.

There isn't a single operation at the moment to do that, so we:

  • Merge current state -> basis tree of the master w.r.t. the old tree basis.
  • Do a 'normal' merge of the old branch basis if it is relevant.
ParametersrevisionThe target revision to update to. Must be in the revision history.
old_tipIf branch.update() has already been run, the value it returned (old tip of the branch or None). _marker is used otherwise.
@needs_tree_write_lock
def _update_tree(self, old_tip=None, change_reporter=None, revision=None, show_base=False):
Update a tree to the master branch.
Parametersold_tipif supplied, the previous tip revision the branch, before it was changed to the master branch's tip.
def set_conflicts(self, arg):
Undocumented
def add_conflicts(self, arg):
Undocumented
def conflicts(self):
Undocumented
def walkdirs(self, prefix=''):
Walk the directories of this tree.

returns a generator which yields items in the form:
((curren_directory_path, fileid),
[(file1_path, file1_name, file1_kind, (lstat), file1_id,
file1_kind), ... ])

This API returns a generator, which is only valid during the current tree transaction - within a single lock_read or lock_write duration.

If the tree is not locked, it may cause an error to be raised, depending on the tree implementation.

def _walkdirs(self, prefix=''):
Walk the directories of this tree.

:param prefix: is used as the directrory to start with.
:returns: a generator which yields items in the form::

    ((curren_directory_path, fileid),
     [(file1_path, file1_name, file1_kind, None, file1_id,
       file1_kind), ... ])
@needs_tree_write_lock
def auto_resolve(self):
Automatically resolve text conflicts according to contents.

Only text conflicts are auto_resolvable. Files with no conflict markers are considered 'resolved', because bzr always puts conflict markers into files that have text conflicts. The corresponding .THIS .BASE and .OTHER files are deleted, as per 'resolve'.

Returnsa tuple of ConflictLists: (un_resolved, resolved).
def _validate(self):
Validate internal structures.

This is meant mostly for the test suite. To give it a chance to detect corruption after actions have occurred. The default implementation is a just a no-op.

ReturnsNone. An exception should be raised if there is an error.
def check_state(self):
Check that the working state is/isn't valid.
def reset_state(self, revision_ids=None):
Reset the state of the working tree.

This does a hard-reset to a last-known-good state. This is a way to fix if something got corrupted (like the .bzr/checkout/dirstate file)

def _get_rules_searcher(self, default_searcher):
See Tree._get_rules_searcher.
def get_shelf_manager(self):
Return the ShelfManager for this WorkingTree.
API Documentation for Bazaar, generated by pydoctor at 2019-09-18 00:32:59.