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.MergeStrategy(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Possible strategies for a merge

ORT#
ORT_OURS#
RECURSIVE#
OCTOPUS#
OURS#
SUBTREE#
class pontos.git.ConfigScope(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

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.TagSort(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Sorting for git tags

VERSION#

Sort tags by version number

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

Run git commands as subprocesses

Create a new Git instance

Parameters:

cwd (Optional[Path]) – Set the current working directory for the git commands

property cwd: Optional[Path]#

Get the current working directory as Path

init(*, bare=False)#

Init a git repository

Parameters:

bare (Optional[bool]) – 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 (Optional[str]) – 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 (Optional[str]) – Apply changes on this branch. If not set the current branch is used.

  • onto (Optional[str]) – Apply changes on top of this branch.

  • strategy (Optional[MergeStrategy]) – 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 (Optional[str]) – Branch to checkout. By default the default branch is used.

  • remote (Optional[str]) – Store repo url under this remote name

push(*, remote=None, branch=None, follow_tags=False, force=None)#

Push changes to remote repository

Parameters:
  • remote (Optional[str]) – Push changes to the named remote

  • branch (Optional[str]) – Branch to push. Will only be considered in combination with a remote.

  • follow_tags (bool) – Push all tags pointing to a commit included in the to be pushed branch.

  • force (Optional[bool]) – Force push changes.

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 (Optional[str]) – Value to set for a Git setting.

  • scope (Optional[ConfigScope]) – 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 (Optional[TagSort]) – Apply a specific sort algorithm for the git tags. By default git uses a lexicographic sorting.

  • tag_name (Optional[str]) – Filter list by the tagname pattern. For example: “22.4*”

  • sort_suffix (Optional[List[str]]) – A list of version suffix to consider.

Return type:

List[str]

add(files)#

Add files to the git staging area

Parameters:

files (Union[PathLike, List[PathLike]]) – A single file or a list of files to add to the staging area

commit(message, *, verify=None, gpg_signing_key=None)#

Create a new commit

Parameters:
  • message (str) – Message of the commit

  • verify (Optional[bool]) – Set to False to skip git hooks

  • gpg_signing_key (Optional[str]) – GPG Key ID to use to sign the commit

tag(tag, *, gpg_key_id=None, message=None, force=False)#

Create a Tag

Parameters:
  • tag (str) – Tag name to create.

  • gpg_key_id (Optional[str]) – GPG Key to sign the tag.

  • message (Optional[str]) – Use message to annotate the given tag.

  • force (Optional[bool]) – True to replace an existing tag.

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

Fetch from changes from remote

Parameters:
  • remote (Optional[str]) – Remote to fetch changes from

  • refspec (Optional[str]) – 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 (Optional[str]) – Create a new branch from this git ref.

log(*log_args, oneline=None)#

Get log of a git repository

Parameters:
  • log_args (str) – Additional arguments for git log

  • oneline (Optional[bool]) – Print the abbreviated commit id and commit message in one line per commit

Return type:

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 (Optional[int]) – Only list nth oldest commits

  • abbrev_commit (Optional[bool]) – 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 (Optional[Iterable[PathLike]]) – 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]