Part of bzrlib.controldir View In Hierarchy
Known subclasses: bzrlib.bzrdir.BzrDir, bzrlib.tests.test_controldir.NotBzrDir
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 |
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.
Parameters | filename | A filename within the root transport of this controldir. |
For instance, if the repository format is out of date but the branch and working tree are not, this should return True.
Parameters | format | Optional parameter indicating a specific desired format we plan to arrive at. |
Parameters | shared | If a shared repository should be created |
Returns | The newly created repository |
The controldirs format will control what branch format is created. For more control see BranchFormatXX.create(a_controldir).
Parameters | name | Name of the colocated branch to create, None for the default branch. |
append_revisions_only | Whether this branch should only allow appending new revisions to its history. |
Parameters | name | Name of the branch to destroy, None for the default branch. |
Parameters | revision_id | create it as of this revision id. |
from_branch | override controldir branch (for lightweight checkouts) | |
accelerator_tree | A 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. |
Formats that do not support this may raise UnsupportedOperation.
The contents of working tree files are not affected. Formats that do not support this may raise UnsupportedOperation.
This might be a synthetic object for e.g. RemoteBranch and SVN.
Parameters | name | Optional colocated branch name |
Returns | The URL the branch in this controldir references if it is a reference branch, or None for regular branches. | |
Raises | NotBranchError | If there is no Branch. |
NoColocatedBranchSupport | If a branch name was specified but colocated branches are not supported. |
If unsupported is True, then no longer supported branch formats can still be opened.
TODO: static convenience version of this?
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 | _unsupported | a private parameter, not part of the api. |
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.
Parameters | recommend_upgrade | Optional 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_branch | override controldir branch (for lightweight checkouts) |
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.)
Returns | Name of the branch selected by the user, or None. |
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.)
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.
Returns | a ControlDirFormat with all component formats either set appropriately or set to None if that component should not be created. | |
Unknown Field: require_stacking | If True, non-stackable formats will be upgraded to similar stackable formats. |
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.
Parameters | revision_id | if revision_id is not None, then the clone operation may tune itself to download less data. |
accelerator_tree | A 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. | |
hardlink | If true, hard-link files from accelerator_tree, where possible. | |
stacked | If true, create a stacked branch referring to the location of this control directory. | |
create_tree_if_local | If true, a working-tree will be created when working locally. |
Return None for tree if not present or inaccessible. Raise NotBranchError if no branch is present. :return: (tree, branch)
Parameters | name | Name of colocated branch to open. |
Parameters | url | The url create the clone at. If url's last component does not exist, it will be created. |
revision_id | The 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_repo | Do not use a shared repository for the target even if one is available. | |
preserve_stacking | When cloning a stacked branch, stack the new branch on top of the other branch's stacked-on branch. |
Parameters | transport | The transport for the location to produce the clone at. If the target directory does not exist, it will be created. |
revision_id | The 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_repo | Do not use a shared repository for the target, even if one is available. | |
preserve_stacking | When cloning a stacked branch, stack the new branch on top of the other branch's stacked-on branch. | |
create_prefix | Create any missing directories leading up to to_transport. | |
use_existing_dir | Use an existing directory if one exists. | |
no_tree | If set to true prevents creation of a working tree. |
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.
Parameters | evaluate | An 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_current | if supplied, use this function to list the current directory, instead of Transport.list_dir | |
Returns | a generator of found bzrdirs, or whatever evaluate returns. |
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
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.
Parameters | base | The URL to create the branch at. |
force_new_repo | If True a new repository is always created. | |
format | If supplied, the format of branch to create. If not supplied, the default is used. |
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.
Parameters | base | The URL to create the branch at. |
force_new_repo | If True a new repository is always created. | |
force_new_tree | If True or False force creation of a tree or prevent such creation respectively. | |
format | Override for the controldir format to create. | |
possible_transports | An optional reusable transports list. |
'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.
Parameters | format | Override for the controldir format to create. |
Returns | The WorkingTree object. |
Parameters | _unsupported | a private parameter to the ControlDir class. |
Parameters | transport | Transport containing the controldir. |
_unsupported | private. |
See open_containing_from_transport for more detail.
Parameters | url | url to search from. |
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.
Returns | The ControlDir that contains the path, and a Unicode path for the rest of the URL. |
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)
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.
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.
Parameters | format | If supplied, the format of branch to create. If not supplied, the default is used. |
possible_transports | If supplied, a list of transports that can be reused to share a remote connection. |