Metadata-Version: 2.4
Name: gitforge-cli
Version: 0.1.0
Summary: A practical Git workflow automation tool for branches, snapshots, releases, and repository hygiene.
Author-email: shazeus <efeborazan07@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/shazeus/gitforge-cli
Project-URL: Repository, https://github.com/shazeus/gitforge-cli
Project-URL: Issues, https://github.com/shazeus/gitforge-cli/issues
Keywords: git,cli,workflow,automation,release,changelog
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <h1 align="center">GitForge</h1>
  <p align="center">Practical Git workflow automation for branches, snapshots, releases, and repository hygiene.</p>
  <p align="center">
    <a href="https://pypi.org/project/gitforge-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/gitforge-cli.svg"></a>
    <a href="https://pypi.org/project/gitforge-cli/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/gitforge-cli.svg"></a>
    <a href="https://github.com/shazeus/gitforge-cli/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/shazeus/gitforge-cli.svg"></a>
    <a href="https://github.com/shazeus/gitforge-cli/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/shazeus/gitforge-cli.svg?style=social"></a>
  </p>
</p>

---

GitForge is a terminal-first Git workflow assistant for developers who want repeatable branch naming, safer commits, fast repository health checks, release tags, changelogs, branch cleanup, and ref comparisons without memorizing a pile of shell snippets. It uses the real Git executable, prints clean Rich tables, and keeps every operation explicit so it fits normal local and CI workflows.

- **Repository health checks** - inspect branch, upstream, dirty state, remotes, conflicts, and local Git identity.
- **Branch automation** - turn ticket titles into consistent branch names and optionally switch to them.
- **Snapshot commits** - stage tracked or all files, commit with guardrails, and optionally push.
- **Release tagging** - create annotated semantic-version tags with dirty-tree protection.
- **Changelog generation** - group commit history into Markdown or JSON output.
- **Cleanup and compare tools** - remove merged branches safely and summarize ref differences.

## Installation

```bash
pip install gitforge-cli
```

The installed console command is:

```bash
gitforge --help
```

## Usage

Inspect a repository:

```bash
gitforge status --repo .
gitforge doctor --repo .
```

Create a workflow branch:

```bash
gitforge branch "Add OAuth callback validation" --ticket AUTH-42 --prefix feature
```

Commit a snapshot:

```bash
gitforge snapshot -m "Implement OAuth callback validation"
```

Generate a changelog:

```bash
gitforge changelog --since v0.1.0 --output CHANGELOG.md
```

Create a release tag:

```bash
gitforge release 1.2.0 --push
```

## Commands

| Command | Description | Example |
| --- | --- | --- |
| `gitforge status` | Show branch, upstream, dirty state, remote, and last tag. | `gitforge status --json` |
| `gitforge doctor` | Check Git availability, repo state, identity, remote, upstream, and conflicts. | `gitforge doctor` |
| `gitforge branch <title>` | Create a normalized branch name from a ticket/title. | `gitforge branch "Fix login" --ticket WEB-7` |
| `gitforge snapshot` | Stage changes and commit with safety checks. | `gitforge snapshot -m "Fix login"` |
| `gitforge sync` | Fetch, pull with rebase or merge, and optionally push. | `gitforge sync --autostash` |
| `gitforge release <version>` | Create an annotated release tag. | `gitforge release 1.0.0` |
| `gitforge changelog` | Render commit history as grouped Markdown or JSON. | `gitforge changelog --max-count 25` |
| `gitforge compare <base> [head]` | Compare two refs by unique commits and changed files. | `gitforge compare main HEAD` |
| `gitforge cleanup` | List or delete merged local branches. | `gitforge cleanup --apply` |
| `gitforge ignore` | Append built-in `.gitignore` templates. | `gitforge ignore python macos` |

## Configuration

GitForge intentionally uses standard Git configuration instead of its own config file.

```bash
git config user.name "Your Name"
git config user.email "you@example.com"
git remote add origin git@github.com:you/project.git
git branch --set-upstream-to origin/main main
```

Most commands accept `--repo` so they can operate on another checkout without changing directories.

## License

MIT License. See [LICENSE](LICENSE).

