Metadata-Version: 2.4
Name: scrippy-git
Version: 2.0.0
Summary: Git support for the Scrippy Python scripting framework
Home-page: https://codeberg.org/scrippy/scrippy-git
Author: Michael Costa, Florent Chevalier
Author-email: michael.costa@mcos.nc, florent.chevalier.nc@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Environment :: Console
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: GitPython>=3.1.43
Provides-Extra: dev
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: wheel>=0.37.0; extra == "dev"
Requires-Dist: flake8>=4.0.1; extra == "dev"
Requires-Dist: flake8-breakpoint>=1.1.0; extra == "dev"
Requires-Dist: flake8-builtins>=1.5.3; extra == "dev"
Requires-Dist: flake8-print>=4.0.0; extra == "dev"
Requires-Dist: flake8-return>=1.1.3; extra == "dev"
Requires-Dist: pep8-naming>=0.8.2; extra == "dev"
Requires-Dist: pytest>=6.2.2; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: bump2version>=1.0.1; extra == "dev"
Requires-Dist: setuptools>=60.9.2; extra == "dev"
Requires-Dist: pypirc-chappers>=1.0.8; extra == "dev"
Requires-Dist: pylint>=2.12.2; extra == "dev"
Dynamic: license-file


![Build Status](https://drone-ext.mcos.nc/api/badges/scrippy/scrippy-git/status.svg) ![License](https://img.shields.io/static/v1?label=license&color=orange&message=MIT) ![Language](https://img.shields.io/static/v1?label=language&color=informational&message=Python)

![Scrippy, my Scrangourou friend](./scrippy-git.png "Scrippy, my Scrangourou friend")

# `scrippy_git`

Git client for the [`Scrippy`](https://codeberg.org/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

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

### With `pip`

```bash
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

```python
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:

```python
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.

```python
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:

```bash
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).
