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.

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

Return candidate names for the git command line tool.

Results may vary based on platform.

This should be considered internal API.

New 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

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.

scmclient_id: str = 'git'[source]¶

The unique ID of the client.

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

Type:: str

name: str = 'Git'[source]¶

The name of the client.

Type:: str

server_tool_names: Optional[str] = 'Git,Perforce,Subversion,Team Foundation Server (git)'[source]¶

A comma-separated list of SCMClient names on the server

New 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_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.

New in version 3.0.

Type:: bool

supports_patch_revert: bool = True[source]¶

Whether the SCM client supports reverting patches.

Type:: bool

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.

New 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

TYPE_GIT = 0[source]¶

TYPE_GIT_SVN = 1[source]¶

TYPE_GIT_P4 = 2[source]¶

__init__(**kwargs)[source]¶

Initialize the client.

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

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

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.

New in version 4.0.

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

parse_revision_spec(revisions: List[str] = []) → 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.

get_local_path() → Optional[str][source]¶

Return the local path to the working tree.

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

get_repository_info() → Optional[RepositoryInfo][source]¶

Return repository information for the current working tree.

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

scan_for_server(repository_info)[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

get_raw_commit_message(revisions)[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_head_ref()[source]¶

Return the HEAD reference.

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

diff(revisions: SCMClientRevisionSpec, *, include_files: List[str] = [], exclude_patterns: List[str] = [], no_renames: bool = False, repository_info: Optional[RepositoryInfo] = 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 unicode, optional) – A list of files to whitelist during the diff generation.
exclude_patterns (list of unicode, optional) – A list of shell-style glob patterns to blacklist during diff generation.
no_renames (bool, optional) – Whether to avoid rename detection.
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

make_diff(merge_base, base, tip, include_files, exclude_patterns, no_renames, find_renames_threshold)[source]¶

Perform a diff on a particular branch range.

Parameters:

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

Returns:

The diff between (base, tip].

Return type:

bytes

make_svn_diff(merge_base, diff_lines)[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 (unicode) – 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_perforce_diff(merge_base, diff_lines)[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 (unicode) – 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

has_pending_changes()[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

amend_commit_description(message, revisions)[source]¶

Update a commit message to the given string.

Parameters:

message (unicode) – 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.

apply_patch(patch_file, base_path=None, base_dir=None, p=None, revert=False)[source]¶

Apply the given patch to index.

This will take the given patch file and apply it to the index, scheduling all changes for commit.

Parameters:

patch_file (unicode) – The name of the patch file to apply.
base_path (unicode, unused) – The base path that the diff was generated in. All git diffs are absolute to the repository root, so this is unused.
base_dir (unicode, unused) – The path of the current working directory relative to the root of the repository. All git diffs are absolute to the repository root, so this is unused.
p (unicode, optional) – The prefix level of the diff.
revert (bool, optional) – Whether the patch should be reverted rather than applied.

Returns:

The result of the patch operation.

Return type:

rbtools.clients.base.patch.PatchResult

create_commit(message, author, run_editor, files=[], all_files=False)[source]¶

Commit the given modified files.

This is expected to be called after applying a patch. This commits the patch using information from the review request, opening the commit message in $EDITOR to allow the user to update it.

Parameters:

message (unicode) – The commit message to use.
author (object) – The author of the commit. This is expected to have fullname and email attributes.
run_editor (bool) – Whether to run the user’s editor on the commit message before committing.
files (list of unicode, 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, merged_only=True)[source]¶

Delete the specified branch.

Parameters:

branch_name (unicode) – 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.

merge(target, destination, message, author, squash=False, run_editor=False, close_branch=False, **kwargs)[source]¶

Merge the target branch with destination branch.

Parameters:

target (unicode) – The name of the branch to merge.
destination (unicode) – The name of the branch to merge into.
message (unicode) – The commit message to use.
author (object) – The author of the commit. This is expected to have fullname and email attributes.
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.

push_upstream(local_branch)[source]¶

Push the current branch to upstream.

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

get_current_branch()[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:: unicode

get_commit_history(revisions)[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. The dictionaries have the following keys:

commit_id:: The unique identifier of the commit.
parent_id:: The unique identifier of the parent commit.
author_name:: The name of the commit’s author.
author_email:: The e-mail address of the commit’s author.
author_date:: The date the commit was authored.
committer_name:: The committer’s name.
committer_email:: The e-mail address of the committer.
committer_date:: The date the commit was committed.
commit_message:: The commit’s message.

Return type:

list of dict

Raises:

rbtools.clients.errors.SCMError – The history is non-linear or there is a commit with no parents.

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

Return the contents of a file at a given revision.

New 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.

New 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.