b.r.Repository(_RelockDebugMixin, controldir.ControlComponent) : class documentation

Part of bzrlib.repository View In Hierarchy

Known subclasses: bzrlib.foreign.ForeignRepository, bzrlib.repository.MetaDirRepository, bzrlib.tests.test_bzrdir.SampleRepository, bzrlib.vf_repository.VersionedFileRepository

Repository holding history for one or more branches.

The repository holds and retrieves historical information including revisions and file history. It's normally accessed only by the Branch, which views a particular line of development through that history.

See VersionedFileRepository in bzrlib.vf_repository for the base class for most Bazaar repositories.

Method abort_write_group Commit the contents accrued within the current write group.
Method add_fallback_repository Add a repository to use for looking up data not held locally.
Method all_revision_ids Returns a list of all the revision ids in the repository.
Method break_lock Break a lock if one is present from another instance.
Static Method create Construct the current default format repository in controldir.
Method __init__ instantiate a Repository.
Method user_transport Undocumented
Method control_transport Undocumented
Method __repr__ Undocumented
Method has_same_location Returns a boolean indicating if this repository is at the same
Method is_in_write_group Return True if there is an open write group.
Method is_locked Undocumented
Method is_write_locked Return True if this object is write locked.
Method lock_write Lock this repository for writing.
Method lock_read Lock the repository for read operations.
Method get_physical_lock_status Undocumented
Method leave_lock_in_place Tell this repository not to release the physical lock when this
Method dont_leave_lock_in_place Tell this repository to release the physical lock when this
Method gather_stats Gather statistics from a revision id.
Method find_branches Find branches underneath this repository.
Method search_missing_revision_ids Return the revision ids that other has that this does not.
Static Method open Open the repository rooted at base.
Method copy_content_into Make a complete copy of the content in self into destination.
Method commit_write_group Commit the contents accrued within the current write group.
Method suspend_write_group Undocumented
Method refresh_data Re-read any data needed to synchronise with disk.
Method resume_write_group Undocumented
Method fetch Fetch the content required to construct revision_id from source.
Method create_bundle Undocumented
Method get_commit_builder Obtain a CommitBuilder for this repository.
Method unlock Undocumented
Method clone Clone this repository into controldir using the current format.
Method start_write_group Start a write group in the repository.
Method sprout Create a descendent repository for new development.
Method has_revision True if this repository has a copy of the revision.
Method has_revisions Probe to find out the presence of multiple revisions.
Method get_revision Return the Revision object for a named revision.
Method get_revision_reconcile 'reconcile' helper routine that allows access to a revision always.
Method get_revisions Get many revisions at once.
Method get_deltas_for_revisions Produce a generator of revision deltas.
Method get_revision_delta Return the delta for one revision.
Method store_revision_signature Undocumented
Method add_signature_text Store a signature text for a revision.
Method iter_files_bytes Iterate through file versions.
Method get_rev_id_for_revno Return the revision id of a revno, given a later (revno, revid)
Method iter_reverse_revision_history Iterate backwards through revision ids in the lefthand history
Method is_shared Return True if this repository is flagged as a shared repository.
Method reconcile Reconcile this repository.
Method revision_tree Return Tree for a revision on this branch.
Method revision_trees Return Trees for revisions in this repository.
Method get_ancestry Return a list of revision-ids integrated by a revision.
Method pack Compress the data within the repository.
Method get_transaction Undocumented
Method get_parent_map See graph.StackedParentsProvider.get_parent_map
Method get_known_graph_ancestry Return the known graph for a set of revision ids and their ancestors.
Method get_file_graph Return the graph walker for files.
Method get_graph Return the graph walker for this repository format
Method revision_ids_to_search_result Convert a set of revision ids to a graph SearchResult.
Method set_make_working_trees Set the policy flag for making working trees when creating branches.
Method make_working_trees Returns the policy for making working trees on new branches.
Method sign_revision Undocumented
Method verify_revision Verify the signature on a revision.
Method has_signature_for_revision_id Query for a revision signature for revision_id in the repository.
Method get_signature_text Return the text for a signature.
Method check Check consistency of all history of given revision_ids.
Method supports_rich_root Undocumented
Method _abort_write_group Template method for per-repository write group cleanup.
Method _check_fallback_repository Check that this repository can fallback to repository safely.
Method _all_revision_ids Returns a list of all the revision ids in the repository.
Method _has_same_fallbacks Returns true if the repositories have the same fallbacks.
Method _commit_write_group Template method for per-repository write group cleanup.
Method _resume_write_group Undocumented
Method _start_write_group Template method for per-repository write group startup.
Method _create_sprouting_repo Undocumented
Method _find_parent_ids_of_revisions Find all parent ids that are mentioned in the revision graph.
Method _refresh_data Helper called from lock_* to ensure coherency with disk.
Method _get_parent_map_no_fallbacks Same as Repository.get_parent_map except doesn't query fallbacks.
Method _make_parents_provider Undocumented
Method _make_parents_provider_unstacked Undocumented
Method _check Undocumented
Method _warn_if_deprecated Undocumented
Method _check_ascii_revisionid Private helper for ascii-only repositories.

Inherited from _RelockDebugMixin:

Method _note_lock Undocumented
def abort_write_group(self, suppress_errors=False):
Commit the contents accrued within the current write group.
Parameterssuppress_errorsif true, abort_write_group will catch and log unexpected errors that happen during the abort, rather than allowing them to propagate. Defaults to False.
See Alsostart_write_group.
def _abort_write_group(self):
Template method for per-repository write group cleanup.

This is called during abort before the write group is considered to be finished and should cleanup any internal state accrued during the write group. There is no requirement that data handed to the repository be not made available - this is not a rollback - but neither should any attempt be made to ensure that data added is fully commited. Abort is invoked when an error has occured so futher disk or network operations may not be possible or may error and if possible should not be attempted.

def add_fallback_repository(self, repository):
Add a repository to use for looking up data not held locally.
ParametersrepositoryA repository.
def _check_fallback_repository(self, repository):
Check that this repository can fallback to repository safely.

Raise an error if not.

ParametersrepositoryA repository to fallback to.
def all_revision_ids(self):
Returns a list of all the revision ids in the repository.

This is conceptually deprecated because code should generally work on the graph reachable from a particular revision, and ignore any other revisions that might be present. There is no direct replacement method.

def _all_revision_ids(self):
Returns a list of all the revision ids in the repository.

These are in as much topological order as the underlying store can present.

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.

@staticmethod
def create(controldir):
Construct the current default format repository in controldir.
def __init__(self, _format, controldir, control_files):
instantiate a Repository.
Parameters_formatThe format of the repository on disk.
controldirThe ControlDir of the repository.
control_filesControl files to use for locking, etc.
@property
def user_transport(self):
Undocumented
@property
def control_transport(self):
Undocumented
def __repr__(self):
Undocumented
def _has_same_fallbacks(self, other_repo):
Returns true if the repositories have the same fallbacks.
def has_same_location(self, other):
Returns a boolean indicating if this repository is at the same location as another repository.

This might return False even when two repository objects are accessing the same physical repository via different URLs.

def is_in_write_group(self):
Return True if there is an open write group.
See Alsostart_write_group.
def is_locked(self):
Undocumented
def is_write_locked(self):
Return True if this object is write locked.
def lock_write(self, token=None):
Lock this repository for writing.

This causes caching within the repository obejct to start accumlating data during reads, and allows a 'write_group' to be obtained. Write groups must be used for actual data insertion.

A token should be passed in if you know that you have locked the object some other way, and need to synchronise this object's state with that fact.

XXX: this docstring is duplicated in many places, e.g. lockable_files.py

Parameterstokenif this is already locked, then lock_write will fail unless the token matches the existing lock.
ReturnsA RepositoryWriteLockResult.
RaisesTokenLockingNotSupportedwhen a token is given but this instance doesn't support using token locks.
MismatchedTokenif the specified token doesn't match the token of the existing lock.
See Alsostart_write_group.
def lock_read(self):
Lock the repository for read operations.
ReturnsAn object with an unlock method which will release the lock obtained.
def get_physical_lock_status(self):
Undocumented
def leave_lock_in_place(self):
Tell this repository not to release the physical lock when this object is unlocked.

If lock_write doesn't return a token, then this method is not supported.

def dont_leave_lock_in_place(self):
Tell this repository to release the physical lock when this object is unlocked, even if it didn't originally acquire it.

If lock_write doesn't return a token, then this method is not supported.

@needs_read_lock
def gather_stats(self, revid=None, committers=None):
Gather statistics from a revision id.

:param revid: The revision id to gather statistics from, if None, then
    no revision specific statistics are gathered.
:param committers: Optional parameter controlling whether to grab
    a count of committers from the revision specific statistics.
:return: A dictionary of statistics. Currently this contains:
    committers: The number of committers if requested.
    firstrev: A tuple with timestamp, timezone for the penultimate left
        most ancestor of revid, if revid is not the NULL_REVISION.
    latestrev: A tuple with timestamp, timezone for revid, if revid is
        not the NULL_REVISION.
    revisions: The total revision count in the repository.
    size: An estimate disk size of the repository in bytes.
def find_branches(self, using=False):
Find branches underneath this repository.

This will include branches inside other branches.

ParametersusingIf True, list only branches using this repository.
@needs_read_lock
def search_missing_revision_ids(self, other, revision_id=symbol_versioning.DEPRECATED_PARAMETER, find_ghosts=True, revision_ids=None, if_present_ids=None, limit=None):
Return the revision ids that other has that this does not.

These are returned in topological order.

revision_id: only return revision ids included by revision_id.

@staticmethod
def open(base):
Open the repository rooted at base.

For instance, if the repository is at URL/.bzr/repository, Repository.open(URL) -> a Repository instance.

def copy_content_into(self, destination, revision_id=None):
Make a complete copy of the content in self into destination.

This is a destructive operation! Do not use it on existing repositories.

def commit_write_group(self):
Commit the contents accrued within the current write group.
Returnsit may return an opaque hint that can be passed to 'pack'.
See Alsostart_write_group.
def _commit_write_group(self):
Template method for per-repository write group cleanup.

This is called before the write group is considered to be finished and should ensure that all data handed to the repository for writing during the write group is safely committed (to the extent possible considering file system caching etc).

def suspend_write_group(self):
Undocumented
def refresh_data(self):
Re-read any data needed to synchronise with disk.

This method is intended to be called after another repository instance (such as one used by a smart server) has inserted data into the repository. On all repositories this will work outside of write groups. Some repository formats (pack and newer for bzrlib native formats) support refresh_data inside write groups. If called inside a write group on a repository that does not support refreshing in a write group IsInWriteGroupError will be raised.

def resume_write_group(self, tokens):
Undocumented
def _resume_write_group(self, tokens):
Undocumented
def fetch(self, source, revision_id=None, find_ghosts=False, fetch_spec=None):
Fetch the content required to construct revision_id from source.

If revision_id is None and fetch_spec is None, then all content is copied.

fetch() may not be used when the repository is in a write group - either finish the current write group before using fetch, or use fetch before starting the write group.

Parametersfind_ghostsFind and copy revisions in the source that are ghosts in the target (and not reachable directly by walking out to the first-present revision in target from revision_id).
revision_idIf specified, all the content needed for this revision ID will be copied to the target. Fetch will determine for itself which content needs to be copied.
fetch_specIf specified, a SearchResult or PendingAncestryResult that describes which revisions to copy. This allows copying multiple heads at once. Mutually exclusive with revision_id.
def create_bundle(self, target, base, fileobj, format=None):
Undocumented
def get_commit_builder(self, branch, parents, config, timestamp=None, timezone=None, committer=None, revprops=None, revision_id=None, lossy=False):
Obtain a CommitBuilder for this repository.
ParametersbranchBranch to commit to.
parentsRevision ids of the parents of the new revision.
configConfiguration to use.
timestampOptional timestamp recorded for commit.
timezoneOptional timezone for timestamp.
committerOptional committer to set for commit.
revpropsOptional dictionary of revision properties.
revision_idOptional revision id.
lossyWhether to discard data that can not be natively represented, when pushing to a foreign VCS
@only_raises(errors.LockNotHeld, errors.LockBroken)
def unlock(self):
Undocumented
@needs_read_lock
def clone(self, controldir, revision_id=None):
Clone this repository into controldir using the current format.

Currently no check is made that the format of this repository and the bzrdir format are compatible. FIXME RBC 20060201.

ReturnsThe newly created destination repository.
def start_write_group(self):
Start a write group in the repository.

Write groups are used by repositories which do not have a 1:1 mapping between file ids and backend store to manage the insertion of data from both fetch and commit operations.

A write lock is required around the start_write_group/commit_write_group for the support of lock-requiring repository formats.

One can only insert data into a repository inside a write group.

ReturnsNone.
def _start_write_group(self):
Template method for per-repository write group startup.

This is called before the write group is considered to be entered.

@needs_read_lock
def sprout(self, to_bzrdir, revision_id=None):
Create a descendent repository for new development.

Unlike clone, this does not copy the settings of the repository.

def _create_sprouting_repo(self, a_bzrdir, shared):
Undocumented
@needs_read_lock
def has_revision(self, revision_id):
True if this repository has a copy of the revision.
@needs_read_lock
def has_revisions(self, revision_ids):
Probe to find out the presence of multiple revisions.
Parametersrevision_idsAn iterable of revision_ids.
ReturnsA set of the revision_ids that were present.
@needs_read_lock
def get_revision(self, revision_id):
Return the Revision object for a named revision.
def get_revision_reconcile(self, revision_id):
'reconcile' helper routine that allows access to a revision always.

This variant of get_revision does not cross check the weave graph against the revision one as get_revision does: but it should only be used by reconcile, or reconcile-alike commands that are correcting or testing the revision graph.

def get_revisions(self, revision_ids):
Get many revisions at once.

Repositories that need to check data on every revision read should subclass this method.

def get_deltas_for_revisions(self, revisions, specific_fileids=None):
Produce a generator of revision deltas.

Note that the input is a sequence of REVISIONS, not revision_ids. Trees will be held in memory until the generator exits. Each delta is relative to the revision's lefthand predecessor.

Parametersspecific_fileidsif not None, the result is filtered so that only those file-ids, their parents and their children are included.
@needs_read_lock
def get_revision_delta(self, revision_id, specific_fileids=None):
Return the delta for one revision.

The delta is relative to the left-hand predecessor of the revision.

Parametersspecific_fileidsif not None, the result is filtered so that only those file-ids, their parents and their children are included.
@needs_write_lock
def store_revision_signature(self, gpg_strategy, plaintext, revision_id):
Undocumented
def add_signature_text(self, revision_id, signature):
Store a signature text for a revision.
Parametersrevision_idRevision id of the revision
signatureSignature text.
def _find_parent_ids_of_revisions(self, revision_ids):
Find all parent ids that are mentioned in the revision graph.
Returnsset of revisions that are parents of revision_ids which are not part of revision_ids themselves
def iter_files_bytes(self, desired_files):
Iterate through file versions.

Files will not necessarily be returned in the order they occur in desired_files. No specific order is guaranteed.

Yields pairs of identifier, bytes_iterator. identifier is an opaque value supplied by the caller as part of desired_files. It should uniquely identify the file version in the caller's context. (Examples: an index number or a TreeTransform trans_id.)

Parametersdesired_filesa list of (file_id, revision_id, identifier) triples
def get_rev_id_for_revno(self, revno, known_pair):
Return the revision id of a revno, given a later (revno, revid) pair in the same history.
Returnsif found (True, revid). If the available history ran out before reaching the revno, then this returns (False, (closest_revno, closest_revid)).
@symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4, 0)))
def iter_reverse_revision_history(self, revision_id):
Iterate backwards through revision ids in the lefthand history
Parametersrevision_idThe revision id to start with. All its lefthand ancestors will be traversed.
def is_shared(self):
Return True if this repository is flagged as a shared repository.
@needs_write_lock
def reconcile(self, other=None, thorough=False):
Reconcile this repository.
def _refresh_data(self):
Helper called from lock_* to ensure coherency with disk.

The default implementation does nothing; it is however possible for repositories to maintain loaded indices across multiple locks by checking inside their implementation of this method to see whether their indices are still valid. This depends of course on the disk format being validatable in this manner. This method is also called by the refresh_data() public interface to cause a refresh to occur while in a write lock so that data inserted by a smart server push operation is visible on the client's instance of the physical repository.

@needs_read_lock
def revision_tree(self, revision_id):
Return Tree for a revision on this branch.

revision_id may be NULL_REVISION for the empty tree revision.

def revision_trees(self, revision_ids):
Return Trees for revisions in this repository.
Parametersrevision_idsa sequence of revision-ids; a revision-id may not be None or 'null:'
@needs_read_lock
@symbol_versioning.deprecated_method(symbol_versioning.deprecated_in((2, 4, 0)))
def get_ancestry(self, revision_id, topo_sorted=True):
Return a list of revision-ids integrated by a revision.

The first element of the list is always None, indicating the origin revision. This might change when we have history horizons, or perhaps we should have a new API.

This is topologically sorted.

def pack(self, hint=None, clean_obsolete_packs=False):
Compress the data within the repository.

This operation only makes sense for some repository types. For other types it should be a no-op that just returns.

This stub method does not require a lock, but subclasses should use @needs_write_lock as this is a long running call it's reasonable to implicitly lock for the user.

ParametershintIf not supplied, the whole repository is packed. If supplied, the repository may use the hint parameter as a hint for the parts of the repository to pack. A hint can be obtained from the result of commit_write_group(). Out of date hints are simply ignored, because concurrent operations can obsolete them rapidly.
clean_obsolete_packsClean obsolete packs immediately after the pack operation.
def get_transaction(self):
Undocumented
def get_parent_map(self, revision_ids):
See graph.StackedParentsProvider.get_parent_map
def _get_parent_map_no_fallbacks(self, revision_ids):
Same as Repository.get_parent_map except doesn't query fallbacks.
def _make_parents_provider(self):
Undocumented
def _make_parents_provider_unstacked(self):
Undocumented
@needs_read_lock
def get_known_graph_ancestry(self, revision_ids):
Return the known graph for a set of revision ids and their ancestors.
def get_file_graph(self):
Return the graph walker for files.
def get_graph(self, other_repository=None):
Return the graph walker for this repository format
def revision_ids_to_search_result(self, result_set):
Convert a set of revision ids to a graph SearchResult.
@needs_write_lock
def set_make_working_trees(self, new_value):
Set the policy flag for making working trees when creating branches.

This only applies to branches that use this repository.

The default is 'True'.
:param new_value: True to restore the default, False to disable making
                  working trees.
def make_working_trees(self):
Returns the policy for making working trees on new branches.
@needs_write_lock
def sign_revision(self, revision_id, gpg_strategy):
Undocumented
@needs_read_lock
def verify_revision(self, revision_id, gpg_strategy):
Verify the signature on a revision.

:param revision_id: the revision to verify
:gpg_strategy: the GPGStrategy object to used

:return: gpg.SIGNATURE_VALID or a failed SIGNATURE_ value
def has_signature_for_revision_id(self, revision_id):
Query for a revision signature for revision_id in the repository.
def get_signature_text(self, revision_id):
Return the text for a signature.
def check(self, revision_ids=None, callback_refs=None, check_repo=True):
Check consistency of all history of given revision_ids.

Different repository implementations should override _check().

Parametersrevision_idsA non-empty list of revision_ids whose ancestry will be checked. Typically the last revision_id of a branch.
callback_refsA dict of check-refs to resolve and callback the check/_check method on the items listed as wanting the ref. see bzrlib.check.
check_repoIf False do not check the repository contents, just calculate the data callback_refs requires and call them back.
def _check(self, revision_ids=None, callback_refs=None, check_repo=True):
Undocumented
def _warn_if_deprecated(self, branch=None):
Undocumented
def supports_rich_root(self):
Undocumented
def _check_ascii_revisionid(self, revision_id, method):
Private helper for ascii-only repositories.
API Documentation for Bazaar, generated by pydoctor at 2022-06-16 00:25:16.