b.c.ControlDir(ControlComponent) : class documentation

Part of bzrlib.controldir View In Hierarchy

Known subclasses: bzrlib.bzrdir.BzrDir, bzrlib.tests.test_controldir.NotBzrDir

A control directory.

While this represents a generic control directory, there are a few features that are present in this interface that are currently only supported by one of its implementations, BzrDir.

These features (bound branches, stacked branches) are currently only supported by Bazaar, but could be supported by other version control systems as well. Implementations are required to raise the appropriate exceptions when an operation is requested that is not supported.

This also makes life easier for API users who can rely on the implementation always allowing a particular feature to be requested but raising an exception when it is not supported, rather than requiring the API users to check for magic attributes to see what features are supported.

Method can_convert_format Return true if this controldir is one whose format we can convert
Method list_branches Return a sequence of all branches local to this control directory.
Method is_control_filename True if filename is the name of a path which is reserved for
Method needs_format_conversion Return true if this controldir needs convert_format run on it.
Method create_repository Create a new repository in this control directory.
Method destroy_repository Destroy the repository in this ControlDir.
Method create_branch Create a branch in this ControlDir.
Method destroy_branch Destroy a branch in this ControlDir.
Method create_workingtree Create a working tree at this ControlDir.
Method destroy_workingtree Destroy the working tree at this ControlDir.
Method destroy_workingtree_metadata Destroy the control files for the working tree at this ControlDir.
Method find_branch_format Find the branch 'format' for this controldir.
Method get_branch_reference Return the referenced URL for the branch in this controldir.
Method open_branch Open the branch object at this ControlDir if one is present.
Method open_repository Open the repository object at this ControlDir if one is present.
Method find_repository Find the repository that should be used.
Method open_workingtree Open the workingtree object at this ControlDir if one is present.
Method has_branch Tell if this controldir contains a branch.
Method has_workingtree Tell if this controldir contains a working tree.
Method cloning_metadir Produce a metadir suitable for cloning or sprouting with.
Method checkout_metadir Produce a metadir suitable for checkouts of this controldir.
Method sprout Create a copy of this controldir prepared for use as a new line of
Method push_branch Push the source branch into this ControlDir.
Method get_config Get configuration for this ControlDir.
Method check_conversion_target Check that a controldir as a whole can be converted to a new format.
Method clone Clone this controldir and its contents to url verbatim.
Method clone_on_transport Clone this controldir and its contents to transport verbatim.
Class Method find_bzrdirs Find control dirs recursively from current location.
Class Method find_branches Find all branches under a transport.
Class Method create_branch_and_repo Create a new ControlDir, Branch and Repository at the url 'base'.
Class Method create_branch_convenience Create a new ControlDir, Branch and Repository at the url 'base'.
Class Method create_standalone_workingtree Create a new ControlDir, WorkingTree, Branch and Repository at 'base'.
Class Method open_unsupported Open a branch which is not supported.
Class Method open Open an existing controldir, rooted at 'base' (url).
Class Method open_from_transport Open a controldir within a particular directory.
Class Method open_containing Open an existing branch which contains url.
Class Method open_containing_from_transport Open an existing branch which contains a_transport.base.
Class Method open_tree_or_branch Return the branch and working tree at a location.
Class Method open_containing_tree_or_branch Return the branch and working tree contained by a location.
Class Method open_containing_tree_branch_or_repository Return the working tree, branch and repo contained by a location.
Class Method create Create a new ControlDir at the url 'base'.
Method _get_selected_branch Return the name of the branch selected by the user.
Method _get_tree_branch Return the branch and tree, if any, for this controldir.

Inherited from ControlComponent:

Method control_transport Undocumented
Method control_url Undocumented
Method user_transport Undocumented
Method user_url Undocumented
def can_convert_format(self):
Return true if this controldir is one whose format we can convert from.
def list_branches(self):
Return a sequence of all branches local to this control directory.
def is_control_filename(self, filename):
overridden in bzrlib.bzrdir.BzrDir
True if filename is the name of a path which is reserved for controldirs.

This is true IF and ONLY IF the filename is part of the namespace reserved for bzr control dirs. Currently this is the '.bzr' directory in the root of the root_transport. it is expected that plugins will need to extend this in the future - for instance to make bzr talk with svn working trees.

ParametersfilenameA filename within the root transport of this controldir.
def needs_format_conversion(self, format=None):
Return true if this controldir needs convert_format run on it.

For instance, if the repository format is out of date but the branch and working tree are not, this should return True.

ParametersformatOptional parameter indicating a specific desired format we plan to arrive at.
def create_repository(self, shared=False):
Create a new repository in this control directory.
ParameterssharedIf a shared repository should be created
ReturnsThe newly created repository
def destroy_repository(self):
Destroy the repository in this ControlDir.
def create_branch(self, name=None, repository=None, append_revisions_only=None):
Create a branch in this ControlDir.

The controldirs format will control what branch format is created. For more control see BranchFormatXX.create(a_controldir).

ParametersnameName of the colocated branch to create, None for the default branch.
append_revisions_onlyWhether this branch should only allow appending new revisions to its history.
def destroy_branch(self, name=None):
Destroy a branch in this ControlDir.
ParametersnameName of the branch to destroy, None for the default branch.
def create_workingtree(self, revision_id=None, from_branch=None, accelerator_tree=None, hardlink=False):
Create a working tree at this ControlDir.
Parametersrevision_idcreate it as of this revision id.
from_branchoverride controldir branch (for lightweight checkouts)
accelerator_treeA tree which can be used for retrieving file contents more quickly than the revision tree, i.e. a workingtree. The revision tree will be used for cases where accelerator_tree's content is different.
def destroy_workingtree(self):
Destroy the working tree at this ControlDir.

Formats that do not support this may raise UnsupportedOperation.

def destroy_workingtree_metadata(self):
Destroy the control files for the working tree at this ControlDir.

The contents of working tree files are not affected. Formats that do not support this may raise UnsupportedOperation.

def find_branch_format(self, name=None):
Find the branch 'format' for this controldir.

This might be a synthetic object for e.g. RemoteBranch and SVN.

def get_branch_reference(self, name=None):
Return the referenced URL for the branch in this controldir.
ParametersnameOptional colocated branch name
ReturnsThe URL the branch in this controldir references if it is a reference branch, or None for regular branches.
RaisesNotBranchErrorIf there is no Branch.
NoColocatedBranchSupportIf a branch name was specified but colocated branches are not supported.
def open_branch(self, name=None, unsupported=False, ignore_fallbacks=False):
Open the branch object at this ControlDir if one is present.

If unsupported is True, then no longer supported branch formats can still be opened.

TODO: static convenience version of this?

def open_repository(self, _unsupported=False):
Open the repository object at this ControlDir if one is present.

This will not follow the Branch object pointer - it's strictly a direct open facility. Most client code should use open_branch().repository to get at a repository.

TODO: static convenience version of this?

Parameters_unsupporteda private parameter, not part of the api.
def find_repository(self):
overridden in bzrlib.bzrdir.BzrDir
Find the repository that should be used.

This does not require a branch as we use it to find the repo for new branches as well as to hook existing branches up to their repository.

def open_workingtree(self, _unsupported=False, recommend_upgrade=True, from_branch=None):
Open the workingtree object at this ControlDir if one is present.
Parametersrecommend_upgradeOptional keyword parameter, when True (the default), emit through the ui module a recommendation that the user upgrade the working tree when the workingtree being opened is old (but still fully supported).
from_branchoverride controldir branch (for lightweight checkouts)
def has_branch(self, name=None):
Tell if this controldir contains a branch.

Note: if you're going to open the branch, you should just go ahead and try, and not ask permission first. (This method just opens the branch and discards it, and that's somewhat expensive.)

def _get_selected_branch(self):
Return the name of the branch selected by the user.
ReturnsName of the branch selected by the user, or None.
def has_workingtree(self):
Tell if this controldir contains a working tree.

This will still raise an exception if the controldir has a workingtree that is remote & inaccessible.

Note: if you're going to open the working tree, you should just go ahead and try, and not ask permission first. (This method just opens the workingtree and discards it, and that's somewhat expensive.)

def cloning_metadir(self, require_stacking=False):
overridden in bzrlib.bzrdir.BzrDir
Produce a metadir suitable for cloning or sprouting with.

These operations may produce workingtrees (yes, even though they're "cloning" something that doesn't have a tree), so a viable workingtree format must be selected.

Returnsa ControlDirFormat with all component formats either set appropriately or set to None if that component should not be created.
Unknown Field: require_stackingIf True, non-stackable formats will be upgraded to similar stackable formats.
def checkout_metadir(self):
Produce a metadir suitable for checkouts of this controldir.
def sprout(self, url, revision_id=None, force_new_repo=False, recurse='down', possible_transports=None, accelerator_tree=None, hardlink=False, stacked=False, source_branch=None, create_tree_if_local=True):
overridden in bzrlib.bzrdir.BzrDir
Create a copy of this controldir prepared for use as a new line of development.

If url's last component does not exist, it will be created.

Attributes related to the identity of the source branch like branch nickname will be cleaned, a working tree is created whether one existed before or not; and a local branch is always created.

Parametersrevision_idif revision_id is not None, then the clone operation may tune itself to download less data.
accelerator_treeA tree which can be used for retrieving file contents more quickly than the revision tree, i.e. a workingtree. The revision tree will be used for cases where accelerator_tree's content is different.
hardlinkIf true, hard-link files from accelerator_tree, where possible.
stackedIf true, create a stacked branch referring to the location of this control directory.
create_tree_if_localIf true, a working-tree will be created when working locally.
def push_branch(self, source, revision_id=None, overwrite=False, remember=False, create_prefix=False):
Push the source branch into this ControlDir.
def _get_tree_branch(self, name=None):
Return the branch and tree, if any, for this controldir.

Return None for tree if not present or inaccessible. Raise NotBranchError if no branch is present. :return: (tree, branch)

ParametersnameName of colocated branch to open.
def get_config(self):
overridden in bzrlib.bzrdir.BzrDir
Get configuration for this ControlDir.
def check_conversion_target(self, target_format):
overridden in bzrlib.bzrdir.BzrDir
Check that a controldir as a whole can be converted to a new format.
def clone(self, url, revision_id=None, force_new_repo=False, preserve_stacking=False):
Clone this controldir and its contents to url verbatim.
ParametersurlThe url create the clone at. If url's last component does not exist, it will be created.
revision_idThe tip revision-id to use for any branch or working tree. If not None, then the clone operation may tune itself to download less data.
force_new_repoDo not use a shared repository for the target even if one is available.
preserve_stackingWhen cloning a stacked branch, stack the new branch on top of the other branch's stacked-on branch.
def clone_on_transport(self, transport, revision_id=None, force_new_repo=False, preserve_stacking=False, stacked_on=None, create_prefix=False, use_existing_dir=True, no_tree=False):
overridden in bzrlib.bzrdir.BzrDir
Clone this controldir and its contents to transport verbatim.
ParameterstransportThe transport for the location to produce the clone at. If the target directory does not exist, it will be created.
revision_idThe tip revision-id to use for any branch or working tree. If not None, then the clone operation may tune itself to download less data.
force_new_repoDo not use a shared repository for the target, even if one is available.
preserve_stackingWhen cloning a stacked branch, stack the new branch on top of the other branch's stacked-on branch.
create_prefixCreate any missing directories leading up to to_transport.
use_existing_dirUse an existing directory if one exists.
no_treeIf set to true prevents creation of a working tree.
@classmethod
def find_bzrdirs(klass, transport, evaluate=None, list_current=None):
Find control dirs recursively from current location.

This is intended primarily as a building block for more sophisticated functionality, like finding trees under a directory, or finding branches that use a given repository.

ParametersevaluateAn optional callable that yields recurse, value, where recurse controls whether this controldir is recursed into and value is the value to yield. By default, all bzrdirs are recursed into, and the return value is the controldir.
list_currentif supplied, use this function to list the current directory, instead of Transport.list_dir
Returnsa generator of found bzrdirs, or whatever evaluate returns.
@classmethod
def find_branches(klass, transport):
Find all branches under a transport.

This will find all branches below the transport, including branches inside other branches. Where possible, it will use Repository.find_branches.

To list all the branches that use a particular Repository, see Repository.find_branches

@classmethod
def create_branch_and_repo(klass, base, force_new_repo=False, format=None):
Create a new ControlDir, Branch and Repository at the url 'base'.

This will use the current default ControlDirFormat unless one is specified, and use whatever repository format that that uses via controldir.create_branch and create_repository. If a shared repository is available that is used preferentially.

The created Branch object is returned.

ParametersbaseThe URL to create the branch at.
force_new_repoIf True a new repository is always created.
formatIf supplied, the format of branch to create. If not supplied, the default is used.
@classmethod
def create_branch_convenience(klass, base, force_new_repo=False, force_new_tree=None, format=None, possible_transports=None):
Create a new ControlDir, Branch and Repository at the url 'base'.

This is a convenience function - it will use an existing repository if possible, can be told explicitly whether to create a working tree or not.

This will use the current default ControlDirFormat unless one is specified, and use whatever repository format that that uses via ControlDir.create_branch and create_repository. If a shared repository is available that is used preferentially. Whatever repository is used, its tree creation policy is followed.

The created Branch object is returned. If a working tree cannot be made due to base not being a file:// url, no error is raised unless force_new_tree is True, in which case no data is created on disk and NotLocalUrl is raised.

ParametersbaseThe URL to create the branch at.
force_new_repoIf True a new repository is always created.
force_new_treeIf True or False force creation of a tree or prevent such creation respectively.
formatOverride for the controldir format to create.
possible_transportsAn optional reusable transports list.
@classmethod
def create_standalone_workingtree(klass, base, format=None):
Create a new ControlDir, WorkingTree, Branch and Repository at 'base'.

'base' must be a local path or a file:// url.

This will use the current default ControlDirFormat unless one is specified, and use whatever repository format that that uses for bzrdirformat.create_workingtree, create_branch and create_repository.

ParametersformatOverride for the controldir format to create.
ReturnsThe WorkingTree object.
@classmethod
def open_unsupported(klass, base):
Open a branch which is not supported.
@classmethod
def open(klass, base, _unsupported=False, possible_transports=None):
Open an existing controldir, rooted at 'base' (url).
Parameters_unsupporteda private parameter to the ControlDir class.
@classmethod
def open_from_transport(klass, transport, _unsupported=False, _server_formats=True):
Open a controldir within a particular directory.
ParameterstransportTransport containing the controldir.
_unsupportedprivate.
@classmethod
def open_containing(klass, url, possible_transports=None):
Open an existing branch which contains url.

See open_containing_from_transport for more detail.

Parametersurlurl to search from.
@classmethod
def open_containing_from_transport(klass, a_transport):
Open an existing branch which contains a_transport.base.

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

Basically we keep looking up until we find the control directory or run into the root. If there isn't one, raises NotBranchError. If there is one and it is either an unrecognised format or an unsupported format, UnknownFormatError or UnsupportedFormatError are raised. If there is one, it is returned, along with the unused portion of url.

ReturnsThe ControlDir that contains the path, and a Unicode path for the rest of the URL.
@classmethod
def open_tree_or_branch(klass, location):
Return the branch and working tree at a location.

If there is no tree at the location, tree will be None. If there is no branch at the location, an exception will be raised :return: (tree, branch)

@classmethod
def open_containing_tree_or_branch(klass, location):
Return the branch and working tree contained by a location.

Returns (tree, branch, relpath). If there is no tree at containing the location, tree will be None. If there is no branch containing the location, an exception will be raised relpath is the portion of the path that is contained by the branch.

@classmethod
def open_containing_tree_branch_or_repository(klass, location):
Return the working tree, branch and repo contained by a location.

Returns (tree, branch, repository, relpath). If there is no tree containing the location, tree will be None. If there is no branch containing the location, branch will be None. If there is no repository containing the location, repository will be None. relpath is the portion of the path that is contained by the innermost ControlDir.

If no tree, branch or repository is found, a NotBranchError is raised.

@classmethod
def create(klass, base, format=None, possible_transports=None):
overridden in bzrlib.bzrdir.BzrDir
Create a new ControlDir at the url 'base'.
ParametersformatIf supplied, the format of branch to create. If not supplied, the default is used.
possible_transportsIf supplied, a list of transports that can be reused to share a remote connection.
API Documentation for Bazaar, generated by pydoctor at 2022-06-16 00:25:16.