scrippy_git

Git client for the Scrippy framework.

Prerequisites

• Python >= 3.11
• Git

Python Modules

List of Required Modules

The modules listed below will be automatically installed.

• GitPython >= 3.1.43

Installation

Manual

git clone https://codeberg.org/scrippy/scrippy-git.git
cd scrippy-git
python -m pip install -r requirements.txt
make install

With pip

pip install scrippy-git

Usage

The scrippy_git.git module provides the Repo object for easy manipulation of a Git repository over SSH or HTTPS.

SSH

import os
from scrippy_git import git

username = "git"
host = "gitlab.monty.py"
port = 2242
reponame = "luiggi.vercotti/monty_python.git"
branch = "master"
workspace_path = "/tmp"

repo = git.Repo(username, host, port, reponame)
local_path = os.path.join(workspace_path, "monty_python")
repo.clone(branch=branch, path=local_path)

test_fname = os.path.join(local_path, "dead_parrot.txt")
with open(test_fname, mode="w") as test_file:
  test_file.write("Nobody expects the Spanish inquisition !")

commit_message = "Inquisition shall not be expected"
repo.commit_push(commit_message)

The env parameter of clone() sets environment variables used by every subsequent Git command (clone, pull, push...), for instance to use a specific SSH key:

env = {"GIT_SSH_COMMAND": "ssh -i /path/to/private.key"}
repo.clone(branch=branch, path=local_path, env=env)

HTTPS

With protocol="https", password is used to authenticate on the remote Git server. It is usually an authentication token, username being the token name or the literal oauth2 depending on your Git provider. Special characters in username and password are URL-encoded.

repo = git.Repo(username="oauth2",
                host="gitlab.monty.py",
                reponame="luiggi.vercotti/monty_python.git",
                protocol="https",
                password="my-secret-token")

Default ports

When port is not set, it defaults to 22 with the ssh protocol and to 443 with the https protocol.

Behavior

• commit() adds every change (including untracked files) and commits them. On a clean repository it raises a ScrippyGitError, unless error_on_clean_repo=False is given, in which case it only logs a warning.
• pull() uses the Git default strategy (merge, equivalent to pull.rebase=false): diverged branches are reconciled with a merge commit.
• push() raises a ScrippyGitError when the push is rejected (e.g. the remote branch has diverged and has not been pulled).
• commit_push() chains commit(), pull() and push().
• commit(), pull(), push() and commit_push() raise a ScrippyGitError when called before clone().
• An unsupported protocol (other than ssh or https) raises a ScrippyGitError.

All errors are raised as scrippy_git.ScrippyGitError.

Tests

Integration tests require a Gitolite server provided as a Docker image:

cd tests/docker
make build run
cd ../..
chmod 600 tests/ssh/scrippy.rsa
SCRIPPY_GIT_TEST_HOST=localhost make tests

The SCRIPPY_GIT_TEST_HOST environment variable sets the host name of the test Gitolite server (default: gitolite, as used by the CI).