rbtools.clients.git¶

A client for Git.

Functions

get_git_candidates([target_platform])

Return candidate names for the git command line tool.

Classes

`GitClient`(**kwargs)	A client for Git.
`GitPatcher`(, scmclient, *kwargs)	A patcher that applies Git patches to a tree.

class rbtools.clients.git.GitClient(**kwargs)[source]¶

Bases: BaseSCMClient

A client for Git.

This is a wrapper around the git executable that fetches repository information and generates compatible diffs. This will attempt to generate a diff suitable for the remote repository, whether git, SVN or Perforce.

TYPE_GIT: ClassVar[int] = 0¶

TYPE_GIT_P4: ClassVar[int] = 2¶

TYPE_GIT_SVN: ClassVar[int] = 1¶

__firstlineno__ = 318¶

__init__(**kwargs) → None[source]¶

Initialize the client.

Parameters:: **kwargs (dict) – Keyword arguments to pass through to the superclass.

__static_attributes__ = ('_git', '_git_dir', '_git_svn_remote_info', '_git_toplevel', '_git_version_at_least_180', '_head_ref', '_type', 'bare')¶

amend_commit_description(message: str, revisions: SCMClientRevisionSpec) → None[source]¶

Update a commit message to the given string.

Parameters:

message (str) – The commit message to use when amending the commit.
revisions (dict) – A dictionary of revisions, as returned by parse_revision_spec().

Raises:

rbtools.clients.errors.AmendError – The commit could not be amended. This may occur if the tip is not the most recent commit, or if there’s an error invoking git.

bare: bool¶: Whether the repository is a bare git repository.

can_amend_commit: bool = True[source]¶

Whether commits can be amended.

Type:: bool

can_branch: bool = True[source]¶

Whether new branches can be created.

Type:: bool

can_delete_branch: bool = True[source]¶

Whether branch names can be deleted.

Type:: bool

can_get_file_content: bool = True[source]¶

Whether the tool can get files at specific revisions.

Added in version 5.0.

Type:: bool

can_merge: bool = True[source]¶

Whether the SCM can create merges.

Type:: bool

can_push_upstream: bool = True[source]¶

Whether commits can be pushed upstream.

Type:: bool

can_squash_merges: bool = True[source]¶

Whether commits can be squashed during merge.

Type:: bool

check_dependencies() → None[source]¶

Check whether all dependencies for the client are available.

This checks for the presence of git (along with git.cmd on Windows) in the system path.

Added in version 4.0.

Raises:: rbtools.clients.errors.SCMClientDependencyError – A git tool could not be found.

create_commit(message: str, author: PatchAuthor | None, run_editor: bool, files: Sequence[str] | None = None, all_files: bool = False) → None[source]¶

Create a commit based on the provided message and author.

Changed in version 6.0: The author can now be None, for cases where author information is not available (e.g. authors who have private profiles).

Parameters:

message (str) – The commit message to use.
author (rbtools.diffs.patches.PatchAuthor) –
The author of the commit.

Changed in version 6.0: This can now be None, for cases where author information is not available (e.g. authors who have private profiles).
run_editor (bool) – Whether to run the user’s editor on the commit message before committing.
files (list of str, optional) – The list of filenames to commit.
all_files (bool, optional) – Whether to commit all changed files, ignoring the files argument.

Raises:

rbtools.clients.errors.CreateCommitError – The commit message could not be created. It may have been aborted by the user.

delete_branch(branch_name: str, merged_only: bool = True) → None[source]¶

Delete the specified branch.

Parameters:

branch_name (str) – The name of the branch to delete.
merged_only (bool, optional) – Whether to limit branch deletion to only those branches which have been merged into the current HEAD.

Raises:

rbtools.clients.errors.SCMError – An error occurred while deleting the branch.

diff(revisions: SCMClientRevisionSpec | None, *, include_files: Sequence[str] | None = None, exclude_patterns: Sequence[str] | None = None, no_renames: bool = False, repository_info: RepositoryInfo | None = None, with_parent_diff: bool = True, **kwargs) → SCMClientDiffResult[source]¶

Perform a diff using the given revisions.

If no revisions are specified, this will do a diff of the contents of the current branch since the tracking branch (which defaults to ‘master’). If one revision is specified, this will get the diff of that specific change. If two revisions are specified, this will do a diff between those two revisions.

If a parent branch is specified via the command line options, or would make sense given the requested revisions and the tracking branch, this will also return a parent diff.

Parameters:

revisions (dict) – A dictionary of revisions, as returned by parse_revision_spec().
include_files (list of str, optional) – A list of files to whitelist during the diff generation.
exclude_patterns (list of str, optional) – A list of shell-style glob patterns to blacklist during diff generation.
no_renames (bool, optional) – Whether to avoid rename detection.
repository_info (rbtools.clients.base.repository.RepositoryInfo, optional) – The repository info.
with_parent_diff (bool, optional) – Whether or not to compute a parent diff.
**kwargs (dict, unused) – Unused keyword arguments.

Returns:

A dictionary containing keys documented in SCMClientDiffResult.

Return type:

dict

get_commit_history(revisions: SCMClientRevisionSpec) → Sequence[SCMClientCommitHistoryItem] | None[source]¶

Return the commit history specified by the revisions.

Parameters:: revisions (dict) – A dictionary of revisions to generate history for, as returned by parse_revision_spec().
Returns:: The list of history entries, in order.
Return type:: list of rbtools.clients.base.scmclient.SCMClientCommitHistoryItem
Raises:: rbtools.clients.errors.SCMError – The history is non-linear or there is a commit with no parents.

get_current_branch() → str | None[source]¶

Return the name of the current branch.

Returns:: The name of the directory corresponding to the root of the current working directory (whether a plain checkout or a git worktree). If no repository can be found, this will return None.
Return type:: str

get_file_content(*, filename: str, revision: str) → bytes[source]¶

Return the contents of a file at a given revision.

Added in version 5.0.

Parameters:

filename (str) – The file to fetch.
revision (str) – The revision of the file to get.

Returns:

The read file.

Return type:

bytes

Raises:

rbtools.clients.errors.SCMError – The file could not be found.

get_file_size(*, filename: str, revision: str) → int[source]¶

Return the size of a file at a given revision.

Added in version 5.0.

Parameters:

filename (str) – The file to check.
revision (object) – The revision of the file to check.

Returns:

The size of the file, in bytes.

Return type:

int

Raises:

rbtools.clients.errors.SCMError – The file could not be found.

get_head_ref() → str[source]¶

Return the HEAD reference.

Returns:: The name of the HEAD reference.
Return type:: str

get_local_path() → str | None[source]¶

Return the local path to the working tree.

Returns:: The filesystem path of the repository on the client system.
Return type:: str

get_raw_commit_message(revisions: dict[str, str]) → str[source]¶

Extract the commit message based on the provided revision range.

Parameters:: revisions (dict) – A dictionary containing base and tip keys.
Returns:: The commit messages of all commits between (base, tip].
Return type:: str

get_repository_info() → RepositoryInfo | None[source]¶

Return repository information for the current working tree.

Returns:: The repository info structure.
Return type:: rbtools.clients.base.repository.RepositoryInfo

property git: str[source]¶

The name of the command line tool for Git.

Callers must call setup() or has_dependencies() before accessing this. This will be required starting in RBTools 5.0.

This will fall back to “bzr” if neither Bazaar nor Breezy is installed.

Type:: str

has_pending_changes() → bool[source]¶

Check if there are changes waiting to be committed.

Returns:: True if the working directory has been modified or if changes have been staged in the index.
Return type:: bool

make_diff(merge_base: str, base: str, tip: str, include_files: Sequence[str], exclude_patterns: Sequence[str], no_renames: bool, find_renames_threshold: str | None) → bytes | None[source]¶

Perform a diff on a particular branch range.

Parameters:

merge_base (str) – The ID of the merge base commit. This is only used when creating diffs with git-svn or git-p4 clones.
base (str) – The ID of the base commit for the diff.
tip (str) – The ID of the tip commit for the diff.
include_files (list of str) – A list of files to whitelist during the diff generation.
exclude_patterns (list of str) – A list of shell-style glob patterns to blacklist during diff generation.
no_renames (bool) – Whether to skip rename detection.
find_renames_threshold (str) – The threshold to pass to --find-renames, if any.

Returns:

The diff between (base, tip].

Return type:

bytes

make_perforce_diff(merge_base: str, diff_lines: Sequence[bytes]) → bytes[source]¶

Format a git-p4 diff to apply correctly against a P4 repository.

This reformats the diff from a git p4 clone to look like it came from a Perforce repository. This is needed so that the PerforceTool in Review Board can properly parse the diff.

Parameters:

merge_base (str) – The ID of the merge base commit. This is only used when creating diffs with git svn or git p4 clones.
diff_lines (list of bytes) – The lines of the diff.

Returns:

The reformatted diff contents.

Return type:

bytes

make_svn_diff(merge_base: str, diff_lines: Sequence[bytes]) → bytes | None[source]¶

Format a git-svn diff to apply correctly against an SVN repository.

This reformats the diff from a git-svn clone to look like it came from svn diff. This is needed so that the SVNTool in Review Board can properly parse the diff.

This currently does not support renames/moves/copies (though SVN diffs have problems natively with these anyway).

Parameters:

merge_base (str) – The ID of the merge base commit. This is only used when creating diffs with git svn or git p4 clones.
diff_lines (list of bytes) – The lines of the diff.

Returns:

The reformatted diff contents.

Return type:

bytes

merge(target: str, destination: str, message: str, author: PatchAuthor | None, squash: bool = False, run_editor: bool = False, close_branch: bool = False, **kwargs) → None[source]¶

Merge the target branch with destination branch.

Changed in version 6.0: The author can now be None, for cases where author information is not available (e.g. authors who have private profiles).

Parameters:

target (str) – The name of the branch to merge.
destination (str) – The name of the branch to merge into.
message (str) – The commit message to use.
author (rbtools.diffs.patches.PatchAuthor) –
The author of the commit.

Changed in version 6.0: This can now be None, for cases where author information is not available (e.g. authors who have private profiles).
squash (bool, optional) – Whether to squash the commits or do a plain merge.
run_editor (bool, optional) – Whether to run the user’s editor on the commit message before committing.
close_branch (bool, optional) – Whether to delete the branch after merging.
**kwargs (dict, unused) – Additional keyword arguments passed, for future expansion.

Raises:

rbtools.clients.errors.MergeError – An error occurred while merging the branch.

name: str = 'Git'[source]¶

The name of the client.

Type:: str

parse_revision_spec(revisions: Sequence[str] | None = None) → SCMClientRevisionSpec[source]¶

Parse the given revision spec.

These will be used to generate the diffs to upload to Review Board (or print). The diff for review will include the changes in (base, tip], and the parent diff (if necessary) will include (parent_base, base].

If a single revision is passed in, this will return the parent of that revision for “base” and the passed-in revision for “tip”.

If zero revisions are passed in, this will return the current HEAD as “tip”, and the upstream branch as “base”, taking into account parent branches explicitly specified via --parent.

Parameters:

revisions (list of str, optional) – A list of revisions as specified by the user.

Returns:

The parsed revision spec.

See SCMClientRevisionSpec for the format of this dictionary.

This always populates base, commit_id, and tip.

parent_base may also be populated.

Return type:

dict

Raises:

rbtools.clients.errors.InvalidRevisionSpecError – The given revisions could not be parsed.
rbtools.clients.errors.SCMError – There was an error retrieving information from Git.
rbtools.clients.errors.TooManyRevisionsError – The specified revisions list contained too many revisions.

patcher_cls[source]¶: alias of GitPatcher

push_upstream(local_branch: str) → None[source]¶

Push the current branch to upstream.

Parameters:: local_branch (str) – The name of the branch to push.
Raises:: rbtools.client.errors.PushError – The branch was unable to be pushed.

scan_for_server(repository_info: RepositoryInfo) → str | None[source]¶

Find the Review Board server matching this repository.

Parameters:: repository_info (rbtools.clients.base.repository.RepositoryInfo) – The repository information structure.
Returns:: The Review Board server URL, if available, or None if not found.
Return type:: str

scmclient_id: str = 'git'[source]¶

The unique ID of the client.

Added in version 4.0: This will be required in RBTools 5.0.

Type:: str

server_tool_ids: ClassVar[Sequence[str] | None] = ['git', 'perforce', 'subversion', 'tfs_git'][source]¶

A comma-separated list of SCMClient IDs on the server.

This supersedes server_tool_names when running on a version of Review Board that supports passing tool IDs to the repositories list API.

Added in version 5.0.1.

Type:: str

server_tool_names: ClassVar[str | None] = 'Git,Perforce,Subversion'[source]¶

A comma-separated list of SCMClient names on the server.

Added in version 3.0.

Type:: str

supports_commit_history: bool = True[source]¶

Whether the SCM client can generate a commit history.

Type:: bool

supports_diff_exclude_patterns: bool = True[source]¶

Whether the SCM client supports excluding files from the diff.

Type:: bool

supports_empty_files() → bool[source]¶

Return whether the RB server supports added/deleted empty files.

Returns:: True if the Review Board server supports showing empty files.
Return type:: bool

supports_no_renames: bool = True[source]¶

Whether the SCM client can generate diffs without renamed files.

Type:: bool

supports_parent_diffs: bool = True[source]¶

Whether the SCM client supports generating parent diffs.

Added in version 3.0.

Type:: bool

supports_patch_revert: bool = True[source]¶

Whether the SCM client supports reverting patches.

Type:: bool

class rbtools.clients.git.GitPatcher(*, scmclient: TSCMClient, **kwargs: Unpack[PatcherKwargs])[source]¶

Bases: SCMClientPatcher[GitClient]

A patcher that applies Git patches to a tree.

This applies patches one-by-one using git apply -3. This enables merging of patches, and will stop the patching process at the first patch that has conflicts or otherwise fails.

Added in version 5.1.

__annotations_cache__ = {}¶

__firstlineno__ = 87¶

__static_attributes__ = ()¶

apply_single_patch(*, patch: Patch, patch_num: int) → PatchResult[source]¶

Apply a single patch.

This is an internal method that will take a single patch and apply it using Git.

Parameters:

patch (rbtools.diffs.patches.Patch) – The patch to apply, opened for reading.
patch_num (int) – The 1-based index of this patch in the full list of patches.

Returns:

The result of the patch application, whether the patch applied successfully or with normal patch failures.

Return type:

rbtools.diffs.patches.PatchResult

handle_add_file(path: str, content: bytes) → None[source]¶

Add a file.

Added in version 6.0.

Parameters:

path (str) – The path to the file.
content (bytes) – The content for the file.

Raises:

OSError – A file operation failed.
Exception – An error occurred when running git.

handle_move_file(old_path: str, new_path: str) → None[source]¶

Move a file.

Added in version 6.0.

Parameters:

old_path (str) – The old filename.
new_path (str) – The new filename.

Raises:

OSError – A file operation failed.
Exception – An error occurred when running git.

handle_remove_file(path: str) → None[source]¶

Delete a file.

Added in version 6.0.

Parameters:: path (str) – The path to the file to delete.
Raises:: Exception – An error occurred when running git.

rbtools.clients.git.get_git_candidates(target_platform: str = 'darwin') → Sequence[str][source]¶

Return candidate names for the git command line tool.

Results may vary based on platform.

This should be considered internal API.

Added in version 4.0.

Parameters:

target_platform (str, optional) –

The target platform for which to return candidates. Defaults to the current platform.

This is intended for unit tests.

Returns:

The list of possible names for git.

Return type:

list of str