mozversioncontrol package

Submodules

mozversioncontrol.repoupdate module

mozversioncontrol.repoupdate.update_git_repo(repo: str, path: str | Path)

Ensure a git repository exists at a path and is up to date.

mozversioncontrol.repoupdate.update_mercurial_repo(repo: str, path: str | Path, revision='default', hostfingerprints=None, global_args=None)

Ensure a HG repository exists at a path and is up to date.

Module contents

exception mozversioncontrol.CannotDeleteFromRootOfRepositoryException

Bases: Exception

Represents that the code attempted to delete all files from the root of the repository, which is not permitted.

class mozversioncontrol.GitRepository(path: Path, git='git')

Bases: Repository

An implementation of Repository for Git repositories.

add_remove_files(*paths: str | Path)

Add and remove files under paths in this repository’s working copy.

property base_ref

Hash of revision the current topic branch is based on.

base_ref_as_hg()

Mercurial hash of revision the current topic branch is based on.

Return None if the hg hash of the base ref could not be calculated.

property branch

Current branch or bookmark the checkout has active.

clean_directory(path: str | Path)

Undo all changes (including removing new untracked files) in the given path.

create_try_commit(message: str)

Create a temporary try commit.

Create a new commit using commit_message as the commit message. The commit may be empty, for example when only including try syntax.

forget_add_remove_files(*paths: str | Path)

Undo the effects of a previous add_remove_files call for paths.

get_branch_nodes() List[str]

Return a list of commit SHAs for nodes on the current branch.

get_changed_files(diff_filter='ADM', mode='unstaged', rev=None)

Return a list of files that are changed in this repository’s working copy.

diff_filter controls which kinds of modifications are returned. It is a string which may only contain the following characters:

A - Include files that were added D - Include files that were deleted M - Include files that were modified

By default, all three will be included.

mode can be one of ‘unstaged’, ‘staged’ or ‘all’. Only has an effect on git. Defaults to ‘unstaged’.

rev is a specifier for which changesets to consider for changes. The exact meaning depends on the vcs system being used.

get_commit_patches(nodes: List[str]) List[bytes]

Return the contents of the patch node in the VCS’ standard format.

get_commit_time()

Return the Unix time of the HEAD revision.

get_ignored_files_finder()

Obtain a mozpack.files.BaseFinder of ignored files in the working directory.

The Finder will have its list of all files in the repo cached for its entire lifetime, so operations on the Finder will not track with, for example, changes to the repo during the Finder’s lifetime.

get_mozilla_remote_args() List[str]

Return a list of –remotes arguments to limit commits to official remotes.

get_mozilla_upstream_remotes() Iterator[str]

Return the Mozilla-official upstream remotes for this repo.

get_outgoing_files(diff_filter='ADM', upstream=None)

Return a list of changed files compared to upstream.

diff_filter works the same as get_changed_files. upstream is a remote ref to compare against. If unspecified, this will be determined automatically. If there is no remote ref, a MissingUpstreamRepo exception will be raised.

get_tracked_files_finder(path=None)

Obtain a mozpack.files.BaseFinder of managed files in the working directory.

The Finder will have its list of all files in the repo cached for its entire lifetime, so operations on the Finder will not track with, for example, commits to the repo during the Finder’s lifetime.

get_user_email()

Return the user’s email address.

If no email is configured, then None is returned.

property has_git_cinnabar

True if the repository is using git cinnabar.

property head_ref

Hash of HEAD revision.

property name

Name of the tool.

push_to_try(message, allow_log_capture=False)

Create a temporary commit, push it to try and clean it up afterwards.

With mercurial, MissingVCSExtension will be raised if the push-to-try extension is not installed. On git, MissingVCSExtension will be raised if git cinnabar is not present.

If allow_log_capture is set to True, then the push-to-try will be run using Popen instead of check_call so that the logs can be captured elsewhere.

remove_current_commit()

Remove the currently checked out commit from VCS history.

set_config(name, value)
sparse_checkout_present()

Whether the working directory is using a sparse checkout.

A sparse checkout is defined as a working directory that only materializes a subset of files in a given revision.

Returns a bool.

update(ref)

Update the working directory to the specified reference.

working_directory_clean(untracked=False, ignored=False)

Determine if the working directory is free of modifications.

Returns True if the working directory does not have any file modifications. False otherwise.

By default, untracked and ignored files are not considered. If untracked or ignored are set, they influence the clean check to factor these file classes into consideration.

class mozversioncontrol.HgRepository(path: Path, hg='hg')

Bases: Repository

An implementation of Repository for Mercurial repositories.

add_remove_files(*paths: str | Path)

Add and remove files under paths in this repository’s working copy.

property base_ref

Hash of revision the current topic branch is based on.

base_ref_as_hg()

Mercurial hash of revision the current topic branch is based on.

Return None if the hg hash of the base ref could not be calculated.

property branch

Current branch or bookmark the checkout has active.

clean_directory(path: str | Path)

Undo all changes (including removing new untracked files) in the given path.

create_try_commit(commit_message: str)

Create a temporary try commit.

Create a new commit using commit_message as the commit message. The commit may be empty, for example when only including try syntax.

forget_add_remove_files(*paths: str | Path)

Undo the effects of a previous add_remove_files call for paths.

get_branch_nodes(base_ref: str | None = None) List[str]

Return a list of commit SHAs for nodes on the current branch.

get_changed_files(diff_filter='ADM', mode='unstaged', rev=None)

Return a list of files that are changed in this repository’s working copy.

diff_filter controls which kinds of modifications are returned. It is a string which may only contain the following characters:

A - Include files that were added D - Include files that were deleted M - Include files that were modified

By default, all three will be included.

mode can be one of ‘unstaged’, ‘staged’ or ‘all’. Only has an effect on git. Defaults to ‘unstaged’.

rev is a specifier for which changesets to consider for changes. The exact meaning depends on the vcs system being used.

get_commit_patches(nodes: List[str]) List[bytes]

Return the contents of the patch node in the VCS’ standard format.

get_commit_time()

Return the Unix time of the HEAD revision.

get_ignored_files_finder()

Obtain a mozpack.files.BaseFinder of ignored files in the working directory.

The Finder will have its list of all files in the repo cached for its entire lifetime, so operations on the Finder will not track with, for example, changes to the repo during the Finder’s lifetime.

get_outgoing_files(diff_filter='ADM', upstream=None)

Return a list of changed files compared to upstream.

diff_filter works the same as get_changed_files. upstream is a remote ref to compare against. If unspecified, this will be determined automatically. If there is no remote ref, a MissingUpstreamRepo exception will be raised.

get_tracked_files_finder(path=None)

Obtain a mozpack.files.BaseFinder of managed files in the working directory.

The Finder will have its list of all files in the repo cached for its entire lifetime, so operations on the Finder will not track with, for example, commits to the repo during the Finder’s lifetime.

get_user_email()

Return the user’s email address.

If no email is configured, then None is returned.

property head_ref

Hash of HEAD revision.

property name

Name of the tool.

push_to_try(message, allow_log_capture=False)

Create a temporary commit, push it to try and clean it up afterwards.

With mercurial, MissingVCSExtension will be raised if the push-to-try extension is not installed. On git, MissingVCSExtension will be raised if git cinnabar is not present.

If allow_log_capture is set to True, then the push-to-try will be run using Popen instead of check_call so that the logs can be captured elsewhere.

raise_for_missing_extension(extension: str)

Raise MissingVCSExtension if extension is not installed and enabled.

remove_current_commit()

Remove the currently checked out commit from VCS history.

sparse_checkout_present()

Whether the working directory is using a sparse checkout.

A sparse checkout is defined as a working directory that only materializes a subset of files in a given revision.

Returns a bool.

update(ref)

Update the working directory to the specified reference.

working_directory_clean(untracked=False, ignored=False)

Determine if the working directory is free of modifications.

Returns True if the working directory does not have any file modifications. False otherwise.

By default, untracked and ignored files are not considered. If untracked or ignored are set, they influence the clean check to factor these file classes into consideration.

exception mozversioncontrol.InvalidRepoPath

Bases: Exception

Represents a failure to find a VCS repo at a specified path.

exception mozversioncontrol.MissingConfigureInfo

Bases: MissingVCSInfo

Represents error finding VCS info from configure data.

exception mozversioncontrol.MissingUpstreamRepo

Bases: Exception

Represents a failure to automatically detect an upstream repo.

exception mozversioncontrol.MissingVCSExtension(ext)

Bases: MissingVCSInfo

Represents error finding a required VCS extension.

exception mozversioncontrol.MissingVCSInfo

Bases: Exception

Represents a general failure to resolve a VCS interface.

exception mozversioncontrol.MissingVCSTool

Bases: Exception

Represents a failure to find a version control tool binary.

class mozversioncontrol.Repository(path: Path, tool: str | None = None)

Bases: object

A class wrapping utility methods around version control repositories.

This class is abstract and never instantiated. Obtain an instance by calling a get_repository_*() helper function.

Clients are recommended to use the object as a context manager. But not all methods require this.

abstract add_remove_files(*paths: str | Path)

Add and remove files under paths in this repository’s working copy.

abstract property base_ref

Hash of revision the current topic branch is based on.

abstract base_ref_as_hg()

Mercurial hash of revision the current topic branch is based on.

Return None if the hg hash of the base ref could not be calculated.

abstract property branch

Current branch or bookmark the checkout has active.

abstract clean_directory(path: str | Path)

Undo all changes (including removing new untracked files) in the given path.

commit(message, author=None, date=None, paths=None)

Create a commit using the provided commit message. The author, date, and files/paths to be included may also be optionally provided. The message, author and date arguments must be strings, and are passed as-is to the commit command. Multiline commit messages are supported. The paths argument must be None or an array of strings that represents the set of files and folders to include in the commit.

abstract create_try_commit(commit_message: str)

Create a temporary try commit.

Create a new commit using commit_message as the commit message. The commit may be empty, for example when only including try syntax.

abstract forget_add_remove_files(*paths: str | Path)

Undo the effects of a previous add_remove_files call for paths.

abstract get_branch_nodes() List[str]

Return a list of commit SHAs for nodes on the current branch.

abstract get_changed_files(diff_filter, mode='unstaged', rev=None)

Return a list of files that are changed in this repository’s working copy.

diff_filter controls which kinds of modifications are returned. It is a string which may only contain the following characters:

A - Include files that were added D - Include files that were deleted M - Include files that were modified

By default, all three will be included.

mode can be one of ‘unstaged’, ‘staged’ or ‘all’. Only has an effect on git. Defaults to ‘unstaged’.

rev is a specifier for which changesets to consider for changes. The exact meaning depends on the vcs system being used.

abstract get_commit_patches(nodes: str) List[bytes]

Return the contents of the patch node in the VCS’s standard format.

abstract get_commit_time()

Return the Unix time of the HEAD revision.

abstract get_ignored_files_finder()

Obtain a mozpack.files.BaseFinder of ignored files in the working directory.

The Finder will have its list of all files in the repo cached for its entire lifetime, so operations on the Finder will not track with, for example, changes to the repo during the Finder’s lifetime.

abstract get_outgoing_files(diff_filter, upstream)

Return a list of changed files compared to upstream.

diff_filter works the same as get_changed_files. upstream is a remote ref to compare against. If unspecified, this will be determined automatically. If there is no remote ref, a MissingUpstreamRepo exception will be raised.

abstract get_tracked_files_finder(path=None)

Obtain a mozpack.files.BaseFinder of managed files in the working directory.

The Finder will have its list of all files in the repo cached for its entire lifetime, so operations on the Finder will not track with, for example, commits to the repo during the Finder’s lifetime.

abstract get_user_email()

Return the user’s email address.

If no email is configured, then None is returned.

property has_git_cinnabar

True if the repository is using git cinnabar.

abstract property head_ref

Hash of HEAD revision.

abstract property name

Name of the tool.

abstract push_to_try(message, allow_log_capture=False)

Create a temporary commit, push it to try and clean it up afterwards.

With mercurial, MissingVCSExtension will be raised if the push-to-try extension is not installed. On git, MissingVCSExtension will be raised if git cinnabar is not present.

If allow_log_capture is set to True, then the push-to-try will be run using Popen instead of check_call so that the logs can be captured elsewhere.

abstract remove_current_commit()

Remove the currently checked out commit from VCS history.

abstract sparse_checkout_present()

Whether the working directory is using a sparse checkout.

A sparse checkout is defined as a working directory that only materializes a subset of files in a given revision.

Returns a bool.

property tool_version

Return the version of the VCS tool in use as a string.

abstract update(ref)

Update the working directory to the specified reference.

abstract working_directory_clean(untracked=False, ignored=False)

Determine if the working directory is free of modifications.

Returns True if the working directory does not have any file modifications. False otherwise.

By default, untracked and ignored files are not considered. If untracked or ignored are set, they influence the clean check to factor these file classes into consideration.

class mozversioncontrol.SrcRepository(path: Path, src='src')

Bases: Repository

An implementation of Repository for Git repositories.

add_remove_files(*paths: str | Path)

Add and remove files under paths in this repository’s working copy.

property base_ref

Hash of revision the current topic branch is based on.

base_ref_as_hg()

Mercurial hash of revision the current topic branch is based on.

Return None if the hg hash of the base ref could not be calculated.

property branch

Current branch or bookmark the checkout has active.

clean_directory(path: str | Path)

Undo all changes (including removing new untracked files) in the given path.

forget_add_remove_files(*paths: str | Path)

Undo the effects of a previous add_remove_files call for paths.

get_changed_files(diff_filter='ADM', mode='unstaged', rev=None)

Return a list of files that are changed in this repository’s working copy.

diff_filter controls which kinds of modifications are returned. It is a string which may only contain the following characters:

A - Include files that were added D - Include files that were deleted M - Include files that were modified

By default, all three will be included.

mode can be one of ‘unstaged’, ‘staged’ or ‘all’. Only has an effect on git. Defaults to ‘unstaged’.

rev is a specifier for which changesets to consider for changes. The exact meaning depends on the vcs system being used.

get_commit_time()

Return the Unix time of the HEAD revision.

get_files(path)

This function gets all files in your source folder e.g mozilla-central and creates a list of that

get_outgoing_files(diff_filter='ADM', upstream=None)

Return a list of changed files compared to upstream.

diff_filter works the same as get_changed_files. upstream is a remote ref to compare against. If unspecified, this will be determined automatically. If there is no remote ref, a MissingUpstreamRepo exception will be raised.

get_tracked_files_finder(path)

Get files, similar to ‘hg files -0’ or ‘git ls-files -z’, thats why we read the .gitignore file for patterns to ignore. Speed could probably be improved.

get_upstream()
get_user_email()

Return the user’s email address.

If no email is configured, then None is returned.

git_ignore(path)

This function reads the mozilla-central/.gitignore file and creates a list of the patterns to ignore

property has_git_cinnabar

True if the repository is using git cinnabar.

property head_ref

Hash of HEAD revision.

property name

Name of the tool.

push_to_try(message, allow_log_capture=False)

Create a temporary commit, push it to try and clean it up afterwards.

With mercurial, MissingVCSExtension will be raised if the push-to-try extension is not installed. On git, MissingVCSExtension will be raised if git cinnabar is not present.

If allow_log_capture is set to True, then the push-to-try will be run using Popen instead of check_call so that the logs can be captured elsewhere.

set_config(name, value)
sparse_checkout_present()

Whether the working directory is using a sparse checkout.

A sparse checkout is defined as a working directory that only materializes a subset of files in a given revision.

Returns a bool.

update(ref)

Update the working directory to the specified reference.

working_directory_clean(untracked=False, ignored=False)

Determine if the working directory is free of modifications.

Returns True if the working directory does not have any file modifications. False otherwise.

By default, untracked and ignored files are not considered. If untracked or ignored are set, they influence the clean check to factor these file classes into consideration.

mozversioncontrol.get_repository_from_build_config(config)

Obtain a repository from the build configuration.

Accepts an object that has a topsrcdir and subst attribute.

mozversioncontrol.get_repository_from_env()

Obtain a repository object by looking at the environment.

If inside a build environment (denoted by presence of a buildconfig module), VCS info is obtained from it, as found via configure. This allows us to respect what was passed into configure. Otherwise, we fall back to scanning the filesystem.

mozversioncontrol.get_repository_object(path: str | Path | None, hg='hg', git='git', src='src')

Get a repository object for the repository at path. If path is not a known VCS repository, raise an exception.

mozversioncontrol.get_tool_path(tool: str | Path | None = None)