Metadata-Version: 2.4
Name: gh-clean
Version: 0.1.0
Summary: Remote GitHub branch cleanup reporting tool
Author: Timothy Mansfield
License: MIT
Project-URL: Homepage, https://github.com/manzoid/gh-clean
Project-URL: Repository, https://github.com/manzoid/gh-clean
Project-URL: Issues, https://github.com/manzoid/gh-clean/issues
Keywords: github,git,branches,cleanup,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gh-clean

`gh-clean` is a remote GitHub branch cleanup tool. It evaluates branches
using GitHub repository state, produces a report, and can delete
branches after re-validating that they are still safe to remove.

## Requirements

- Python 3.9+
- [GitHub CLI](https://cli.github.com/) installed
- `gh auth login` completed for the target repositories

`gh-clean` currently uses `gh` for GitHub API access and authentication.

## Install

### With `uv`

Install once:

```bash
uv tool install gh-clean
```

Run without installing globally:

```bash
uvx gh-clean report --repo OWNER/REPO
```

### With `pipx`

```bash
pipx install gh-clean
```

## Authenticate

Before using the tool:

```bash
gh auth login
```

If your org requires SAML SSO, authorize the current `gh` token for that
organization as needed.

## Repository config

The target repository must contain a root `.gh-clean.yml` file with a
non-empty `protected_branches` list.

Example:

```yaml
protected_branches:
  - main
  - staging
  - production
```

This list is checked in addition to GitHub branch protection rules and
rulesets.

If you need a one-off run before the config is committed, you can bypass
the remote file with a CLI override:

```bash
gh-clean report --repo OWNER/REPO --protected-branches main,staging,production
```

## Usage

Generate a report:

```bash
gh-clean report --repo OWNER/REPO
gh-clean report --repo OWNER/REPO --format json
gh-clean report --repo OWNER/REPO --protected-branches main,staging,production
```

Add extra protected branches at runtime:

```bash
gh-clean report --repo OWNER/REPO --exclude develop --exclude release/v2
```

Delete from a prior report with re-validation:

```bash
gh-clean report --repo OWNER/REPO --format json > report.json
gh-clean delete --repo OWNER/REPO --input report.json --recommendation delete-candidate --dry-run
gh-clean delete --repo OWNER/REPO --input report.json --recommendation delete-candidate
gh-clean delete --repo OWNER/REPO --input report.json --recommendation delete-candidate --protected-branches main,staging,production
```

Delete specific branches:

```bash
gh-clean delete --repo OWNER/REPO --branch feature/foo --branch feature/bar --dry-run
```

Override only the merged-tip mismatch soft veto:

```bash
gh-clean delete --repo OWNER/REPO --branch feature/foo --force-merged-tip-mismatch --dry-run
```

## Development

Run directly from the checkout:

```bash
python3 -m gh_clean report --repo gh-clean-sandbox/sandbox
uv run gh-clean report --repo gh-clean-sandbox/sandbox
```

Run tests:

```bash
python3 -m unittest discover -s tests -v
```
