pontos.git package¶

exception pontos.git.GitError(returncode, cmd, output=None, stderr=None)¶

Bases: CalledProcessError, PontosError

Error raised while executing a git command

class pontos.git.ConfigScope(value)¶

Possible scopes for git settings

GLOBAL¶: Apply setting user wide (~/.gitconfig)

LOCAL¶: Apply setting to the local repository only (.git/config)

SYSTEM¶: Apply settings system wide (/etc/gitconfig)

WORKTREE¶: Similar to LOCAL except that $GIT_DIR/config.worktree is used if extensions.worktreeConfig is enabled. If not it’s the same as LOCAL.

class pontos.git.Git(cwd=None)¶

Run git commands as subprocesses

Create a new Git instance

Parameters:: cwd (Path | None) – Set the current working directory for the git commands

property cwd: Path | None¶: Get the current working directory as Path

property version: str¶: Get the version string of the installed git

init(*, bare=False)¶

Init a git repository

Parameters:: bare (bool | None) – Wether to create a bare repository or not. Defaults to false.

create_branch(branch, *, start_point=None)¶

Create a new branch

Parameters:

branch (str) – Name of the branch to be created
start_point (str | None) – An optional git reference (branch, tag, sha, …) from where to start the branch

rebase(base, *, head=None, onto=None, strategy=None)¶

Rebase a branch

Parameters:

base (str) – Apply changes of this branch.
head (str | None) – Apply changes on this branch. If not set the current branch is used.
onto (str | None) – Apply changes on top of this branch.
strategy (MergeStrategy | None) – Merge strategy to use.

clone(repo_url, destination, *, branch=None, remote=None, depth=None)¶

Clone a repository

Parameters:

repo_url (str) – URL of the repo to clone
destination (Path) – Where to checkout the clone
branch (str | None) – Branch to checkout. By default the default branch is used.
remote (str | None) – Store repo url under this remote name

push(refspec=None, *, remote=None, branch=None, follow_tags=False, force=None, delete=None)¶

Push changes to remote repository

Parameters:

refspec (str | Iterable[str] | None) – Refs to push
remote (str | None) – Push changes to the named remote
branch (str | None) – Branch to push. Will only be considered in combination with a remote. Deprecated, use refs instead.
follow_tags (bool) – Push all tags pointing to a commit included in the to be pushed branch.
force (bool | None) – Force push changes.
delete (bool | None) – Delete remote refspec

config(key, value=None, *, scope=None)¶

Get and set a git config

Parameters:

key (str) – Key of the Git config setting. For example: core.filemode
value (str | None) – Value to set for a Git setting.
scope (ConfigScope | str | None) – Scope of the setting.

Return type:

str

cherry_pick(commits)¶

Apply changes of a commit(s) to the current branch

Parameters:: commit – A single git reference (e.g. sha) of the commit or a list of git references.

list_tags(*, sort=None, tag_name=None, sort_suffix=None)¶

List all available tags

Parameters:

sort (TagSort | str | None) – Apply a specific sort algorithm for the git tags. By default git uses a lexicographic sorting.
tag_name (str | None) – Filter list by the tagname pattern. For example: “22.4*”
sort_suffix (list[str] | None) – A list of version suffix to consider.

Return type:

list[str]

add(files)¶

Add files to the git staging area

Parameters:: files (str | PathLike[str] | Sequence[PathLike[str] | str]) – A single file or a list of files to add to the staging area

commit(message, *, verify=None, gpg_sign=None, gpg_signing_key=None)¶

Create a new commit

Parameters:

message (str) – Message of the commit
verify (bool | None) – Set to False to skip git hooks
gpg_sign (bool | None) – Set to False to skip signing the commit via GPG
gpg_signing_key (str | None) – GPG Key ID to use to sign the commit

tag(tag, *, gpg_key_id=None, message=None, force=False, sign=None)¶

Create a Tag

Parameters:

tag (str) – Tag name to create.
gpg_key_id (str | None) – GPG Key to sign the tag.
message (str | None) – Use message to annotate the given tag.
force (bool | None) – True to replace an existing tag.
sign (bool | None) – Set to False to deactivate signing of the tag.

delete_tag(tag)¶

Delete a Tag

Parameters:: tag (str) – Tag name to delete

fetch(remote=None, refspec=None, *, verbose=False)¶

Fetch from changes from remote

Parameters:

remote (str | None) – Remote to fetch changes from
refspec (str | None) – Specifies which refs to fetch and which local refs to update.
verbose (bool) – Print verbose output.

add_remote(remote, url)¶

Add a new git remote

Parameters:

remote (str) – Name of the new remote
url (str) – Git URL of the remote repository

remote_url(remote='origin')¶

Get the url of a remote

Parameters:: remote (str) – Name of the remote. Default: origin.
Return type:: str

checkout(branch, *, start_point=None)¶

Checkout a branch

Parameters:

branch (str) – Branch to checkout or new branch name if starting_point is given.
start_point (str | None) – Create a new branch from this git ref.

log(*log_args, oneline=None, format=None)¶

Get log of a git repository

Parameters:

format (str | None) – Pretty format the output.
log_args (str) – Additional arguments for git log
oneline (bool | None) – Print the abbreviated commit id and commit message in one line per commit

Return type:

list[str]

show(*show_args, format=None, oneline=None, patch=None, objects=None)¶

Show various types of git objects

Parameters:

format (str | None) – Pretty format the output.
oneline (bool | None) – Print the abbreviated commit id and commit message in one line per commit.
patch (bool | None) – True to generate patch output. False to suppress diff output.
show_args (str) – Additional arguments for git show
objects (str | Collection[str] | None) – Git objects (commits, refs, …) to get details for.

Returns:

A list of details about the passed object the object if more then one object is passed. Otherwise a single details is returned.

Return type:

str | list[str]

rev_list(*commit, max_parents=None, abbrev_commit=False)¶

Lists commit objects in reverse chronological order

Parameters:

commit (str) – commit objects.
max_parents (int | None) – Only list nth oldest commits
abbrev_commit (bool | None) – Set to True to show prefix that names the commit object uniquely instead of the full commit ID.

Return type:

list[str]

Examples

This will “list all the commits which are reachable from foo or bar, but not from baz”.

from pontos.git import Git

git = Git()
git.rev_list("foo", "bar", "^baz")

This will return the first commit of foo.

from pontos.git import Git

git = Git()
git.rev_list("foo", max_parents=0)

move(old, new)¶

Move a file from old to new

remove(to_remove)¶

Remove a file from git

status(files=None)¶

Get information about the current git status.

Parameters:: files (Iterable[PathLike] | None) – specify an iterable of os.PathLike and exclude all other paths for the status.
Returns:: An iterator of StatusEntry instances that contain the status of the specific files.
Return type:: Iterator[StatusEntry]

reset(commit, *, mode)¶

Reset the git history

Parameters:

commit – Git reference to reset the checked out tree to
mode (ResetMode | str) – The reset mode to use

Examples

This will “list all the commits which are reachable from foo or bar, but not from baz”.

from pontos.git import Git, ResetMode

git = Git()
git.reset("HEAD^", mode=ResetMode.HARD)

class pontos.git.MergeStrategy(value)¶

Possible strategies for a merge

ORT¶

ORT_OURS¶

RECURSIVE¶

OCTOPUS¶

OURS¶

SUBTREE¶

class pontos.git.ResetMode(value)¶: An enumeration.

class pontos.git.Status(value)¶: Status of a file in git

class pontos.git.StatusEntry(status_string)¶

Status of a file in the git index and working tree.

Implements the os.PathLike protocol.

index¶: Status in the index

working_tree¶: Status in the working tree

path¶: Path to the file

old_path¶: Set for renamed files

class pontos.git.TagSort(value)¶

Sorting for git tags

VERSION¶: Sort tags by version number