gitforge-cli 0.1.0__tar.gz

gitforge_cli-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 shazeus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

gitforge_cli-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+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).
+

gitforge_cli-0.1.0/README.md

@@ -0,0 +1,99 @@
+<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).
+

gitforge_cli-0.1.0/gitforge/__init__.py

@@ -0,0 +1,4 @@
+"""GitForge package metadata."""
+
+__version__ = "0.1.0"
+

gitforge_cli-0.1.0/gitforge/__main__.py

@@ -0,0 +1,8 @@
+"""Run GitForge with ``python -m gitforge``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()
+

gitforge_cli-0.1.0/gitforge/changelog.py

@@ -0,0 +1,101 @@
+"""Changelog extraction and rendering."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .git import git_text
+
+
+@dataclass(frozen=True)
+class CommitEntry:
+    """A Git commit prepared for display."""
+
+    full_hash: str
+    short_hash: str
+    subject: str
+    author: str
+    date: str
+    group: str
+
+    def as_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+GROUP_LABELS = {
+    "feat": "Features",
+    "fix": "Fixes",
+    "docs": "Documentation",
+    "test": "Tests",
+    "perf": "Performance",
+    "refactor": "Refactors",
+    "build": "Build",
+    "ci": "CI",
+    "other": "Other",
+}
+
+
+def classify_subject(subject: str) -> str:
+    """Classify a commit using conventional-commit style prefixes."""
+
+    prefix = subject.split(":", 1)[0].lower()
+    prefix = prefix.split("(", 1)[0]
+    return prefix if prefix in GROUP_LABELS else "other"
+
+
+def load_commits(
+    repo: str | Path,
+    *,
+    rev_range: str | None = None,
+    max_count: int = 100,
+) -> list[CommitEntry]:
+    """Load commits from git log."""
+
+    pretty = "%H%x1f%h%x1f%s%x1f%an%x1f%ad%x1e"
+    args = ["log", f"--max-count={max_count}", "--date=short", f"--pretty=format:{pretty}"]
+    if rev_range:
+        args.insert(1, rev_range)
+    output = git_text(args, repo)
+    commits: list[CommitEntry] = []
+    for record in output.split("\x1e"):
+        record = record.strip()
+        if not record:
+            continue
+        parts = record.split("\x1f")
+        if len(parts) != 5:
+            continue
+        full_hash, short_hash, subject, author, date = parts
+        commits.append(
+            CommitEntry(
+                full_hash=full_hash,
+                short_hash=short_hash,
+                subject=subject,
+                author=author,
+                date=date,
+                group=classify_subject(subject),
+            )
+        )
+    return commits
+
+
+def render_markdown(commits: list[CommitEntry], title: str = "Changelog") -> str:
+    """Render commits as grouped Markdown."""
+
+    if not commits:
+        return f"## {title}\n\nNo commits found for the selected range.\n"
+
+    lines = [f"## {title}", ""]
+    for group, label in GROUP_LABELS.items():
+        group_commits = [commit for commit in commits if commit.group == group]
+        if not group_commits:
+            continue
+        lines.append(f"### {label}")
+        for commit in group_commits:
+            lines.append(
+                f"- `{commit.short_hash}` {commit.subject} "
+                f"({commit.author}, {commit.date})"
+            )
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+