Metadata-Version: 2.4
Name: git-core-slug
Version: 0.20.0
Summary: Scripts to interact with PLD git repos
Author-email: Kacper Kornet <draenog@pld-linux.org>
License-Expression: GPL-2.0-only
License-File: COPYING
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Provides-Extra: test
Requires-Dist: pytest-benchmark; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# git-pld

Run git commands across PLD Linux package repositories in parallel.

`git pld <command>` works like `git <command>`, but executes it in every matching package repo at once. Any standard git command is supported -- arguments are passed through to git unmodified.

```sh
git pld pull                        # pull --rebase --autostash in all repos
git pld status                      # short status across all repos
git pld log --oneline -3            # recent commits across repos
git pld --pattern 'perl-*' fetch    # fetch only perl packages
git pld checkout main               # switch all repos to main
```

For operations that have no single-repo equivalent, there are slug-specific commands: `update`, `clone`, `list`, `init`.

## Installation

```sh
python3 setup.py install
```

The package is also available as `git-core-slug` RPM in PLD Linux.

## Development

Install test dependencies:

```sh
python3 -m pip install pytest pytest-cov
```

Run the test suite:

```sh
make test
```

Run with coverage:

```sh
python3 -m pytest --cov=slug --cov=git_slug --cov-report=term-missing
```

Run benchmarks only:

```sh
python3 -m pytest --benchmark-only
```

Run a focused subset while working on one area:

```sh
python3 -m pytest tests/test_cli.py
python3 -m pytest tests/test_slug_commands.py
```

The test suite is intentionally lightweight:

- `pytest` is the primary framework.
- `pytest-cov` is used only for coverage reporting.
- Most tests are unit-style and use mocking rather than real PLD infrastructure.
- The suite does not require live SSH access or the centralized Refs repo.

Current test coverage is split roughly by responsibility:

- `tests/test_cli.py` checks argv splitting, top-level dispatch, help/version, and parser exit codes.
- `tests/test_config_defaults.py` checks git-config and hardcoded default precedence.
- `tests/test_passthrough.py` checks git passthrough command assembly and output/error handling.
- `tests/test_slug_commands.py` checks `update`, `clone`, `list`, and `init` command wiring.
- `tests/test_failure_paths.py` checks common error paths that previously regressed.
- `tests/test_refsdata.py` and `tests/test_gitrepo.py` cover small helper-module behavior.
- `tests/test_benchmark.py` performance benchmarks (pytest-benchmark).

## Setup

Add your name and email to git configuration:

```sh
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
```

If you have RW access to PLD repositories, use `<your_login>@pld-linux.org` as email.

## Usage

### Getting packages

Clone selected packages:

```sh
git pld clone perl-*
git pld clone python-*
```

Clone all packages (takes a while):

```sh
git pld clone
```

### Keeping up to date

Pull with rebase (default -- autostash handles dirty trees):

```sh
git pld pull
```

Fetch without touching working trees:

```sh
git pld fetch
```

Smart update using centralized Refs repo (faster for large sets, only fetches changed branches):

```sh
git pld update
git pld update --new -p 'perl-*'    # also init new and prune deleted repos
```

### Any git command works

```sh
git pld status
git pld diff --stat
git pld log --oneline -5
git pld branch -a
git pld push
git pld stash
```

### Filtering repos

```sh
git pld --pattern 'perl-*' status
git pld --pattern 'python-*' --pattern 'perl-*' pull
```

### Slug-specific commands

| Command | Description |
|---------|-------------|
| `update` | Smart selective fetch via centralized Refs repo. Supports `--new`, `-p`/`--prune`, `-b`/`--branch`, `--depth`. |
| `clone`  | Batch clone matching packages from the PLD server. |
| `list`   | List upstream repositories matching patterns. |
| `init`   | Create new package repositories on the server. |

## Global options

Options before the command name are slug options. Options after go to git.

```
git pld [-d DIR] [-j N] [-q] [--pattern PAT] <command> [<git-args>...]
```

| Option | Description |
|--------|-------------|
| `-d`, `--packagesdir DIR` | Local directory with repos (default: `~/rpm/packages`) |
| `-j`, `--jobs N` | Number of parallel workers (default: `min(cpu_count*4, 32)`) |
| `-q`, `--quiet` | Suppress stdout from successful repos |
| `--pattern PAT` | Repo name glob, repeatable (default: `*`) |
| `--version` | Print version |

## Smart defaults

Slug passes sensible defaults via `git -c` flags, affecting only the `git pld` invocation (not your regular git settings):

| Command | Defaults applied |
|---------|-----------------|
| `pull`  | `pull.rebase=true`, `pull.autostash=true` |
| `fetch` | `fetch.prune=true` |
| `status`| `status.short=true` |

Your CLI flags always override these (e.g. `git pld pull --no-rebase`).

## Configuration

All options can be set persistently in `~/.gitconfig` under the `[PLD]` section:

```ini
[PLD]
    packagesdir = ~/work/pld-packages
    jobs = 8
```

Per-command defaults can be overridden or disabled:

```ini
[PLD]
    # Use merge instead of rebase for pull
    pull-config = pull.rebase=false

    # Disable slug's fetch defaults entirely
    fetch-config =

    # Add branch info to status
    status-config = status.short=true status.branch=true
```

## Help

```sh
git pld --help              # slug global options
git pld pull --help         # git pull man page
git pld update --help       # slug update options
```

## Project structure

- `slug.py` — client CLI entry point
- `git_slug/` — client library (gitrepo, refsdata, constants)
- `server/` — server-side components (gitolite hooks, slug_watch daemon, admin commands); see `server/README.md`
- `doc/man/` — man page sources (asciidoc); build with `make man`
- `tests/` — test suite

## License

See [COPYING](COPYING).
