gitforge-cli 0.1.0__py3-none-any.whl

gitforge/__init__.py

@@ -0,0 +1,4 @@
+"""GitForge package metadata."""
+
+__version__ = "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/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"
+

gitforge/cli.py

@@ -0,0 +1,530 @@
+"""Command line interface for GitForge."""
+
+from __future__ import annotations
+
+from functools import wraps
+import json
+from pathlib import Path
+import re
+from typing import Any, Callable
+
+import click
+from rich import box
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+
+from . import __version__
+from .changelog import load_commits, render_markdown
+from .git import (
+    GitForgeError,
+    branch_exists,
+    current_branch,
+    get_status,
+    git_available,
+    git_text,
+    is_repo,
+    list_merged_branches,
+    origin_url,
+    repo_root,
+    run_git,
+    safe_git,
+    tag_exists,
+    upstream_branch,
+)
+from .templates import available_templates, render_templates
+
+
+console = Console()
+
+
+def handle_errors(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Convert internal errors into clean Click errors."""
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return func(*args, **kwargs)
+        except ValueError as exc:
+            raise click.ClickException(str(exc)) from exc
+        except GitForgeError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    return wrapper
+
+
+def repo_option(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Add a common repository option to a command."""
+
+    return click.option(
+        "--repo",
+        type=click.Path(file_okay=False, path_type=Path),
+        default=Path("."),
+        show_default=True,
+        help="Repository path.",
+    )(func)
+
+
+def status_word(ok: bool, warn: bool = False) -> str:
+    """Return a styled check status."""
+
+    if ok:
+        return "[green]PASS[/green]"
+    if warn:
+        return "[yellow]WARN[/yellow]"
+    return "[red]FAIL[/red]"
+
+
+def slugify(value: str, *, max_length: int = 54) -> str:
+    """Convert text into a Git-safe branch slug."""
+
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    slug = re.sub(r"-{2,}", "-", slug)
+    if not slug:
+        raise ValueError("branch title must contain at least one letter or number")
+    return slug[:max_length].strip("-")
+
+
+def make_branch_name(prefix: str, ticket: str | None, title: str) -> str:
+    """Compose a branch name from user inputs."""
+
+    cleaned_prefix = slugify(prefix, max_length=24)
+    pieces = []
+    if ticket:
+        pieces.append(slugify(ticket, max_length=24))
+    pieces.append(slugify(title))
+    return f"{cleaned_prefix}/{'-'.join(pieces)}"
+
+
+def print_command_output(output: str | None) -> None:
+    """Print command output when Git returned any."""
+
+    if output:
+        console.print(output)
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="gitforge")
+def main() -> None:
+    """Automate everyday Git workflows from one practical CLI."""
+
+
+@main.command("status")
+@repo_option
+@click.option("--json", "as_json", is_flag=True, help="Print machine-readable JSON.")
+@handle_errors
+def status_command(repo: Path, as_json: bool) -> None:
+    """Show branch, dirty-state, remote, and upstream health."""
+
+    status = get_status(repo)
+    if as_json:
+        click.echo(json.dumps(status.as_dict(), indent=2))
+        return
+
+    table = Table(title="Repository Status", box=box.SIMPLE_HEAVY)
+    table.add_column("Field", style="cyan", no_wrap=True)
+    table.add_column("Value")
+    table.add_row("Root", status.root)
+    table.add_row("Branch", status.branch)
+    table.add_row("Commit", status.commit or "none")
+    table.add_row("Upstream", status.upstream or "not configured")
+    table.add_row("Ahead / Behind", f"{status.ahead} / {status.behind}")
+    table.add_row("Staged", str(status.staged))
+    table.add_row("Unstaged", str(status.unstaged))
+    table.add_row("Untracked", str(status.untracked))
+    table.add_row("Conflicts", str(status.conflicts))
+    table.add_row("Origin", status.remote or "not configured")
+    table.add_row("Last tag", status.last_tag or "none")
+    console.print(table)
+
+
+@main.command()
+@repo_option
+@click.option("--json", "as_json", is_flag=True, help="Print machine-readable JSON.")
+@handle_errors
+def doctor(repo: Path, as_json: bool) -> None:
+    """Check whether a repository is ready for daily workflow automation."""
+
+    checks: list[dict[str, str]] = []
+    checks.append(
+        {
+            "check": "git executable",
+            "status": "pass" if git_available() else "fail",
+            "detail": "available on PATH" if git_available() else "missing from PATH",
+        }
+    )
+
+    repo_ready = is_repo(repo)
+    checks.append(
+        {
+            "check": "repository",
+            "status": "pass" if repo_ready else "fail",
+            "detail": str(repo.resolve()) if repo_ready else "not inside a Git work tree",
+        }
+    )
+
+    if repo_ready:
+        root = repo_root(repo)
+        name = safe_git(["config", "--get", "user.name"], root)
+        email = safe_git(["config", "--get", "user.email"], root)
+        remote = origin_url(root)
+        upstream = upstream_branch(root)
+        status = get_status(root)
+        checks.extend(
+            [
+                {
+                    "check": "user.name",
+                    "status": "pass" if name else "warn",
+                    "detail": name or "not configured locally or globally",
+                },
+                {
+                    "check": "user.email",
+                    "status": "pass" if email else "warn",
+                    "detail": email or "not configured locally or globally",
+                },
+                {
+                    "check": "origin remote",
+                    "status": "pass" if remote else "warn",
+                    "detail": remote or "remote.origin.url not configured",
+                },
+                {
+                    "check": "upstream",
+                    "status": "pass" if upstream else "warn",
+                    "detail": upstream or "current branch has no upstream",
+                },
+                {
+                    "check": "merge conflicts",
+                    "status": "pass" if status.conflicts == 0 else "fail",
+                    "detail": f"{status.conflicts} conflict marker(s) in Git status",
+                },
+                {
+                    "check": "working tree",
+                    "status": "pass" if not status.is_dirty else "warn",
+                    "detail": "clean" if not status.is_dirty else "contains local changes",
+                },
+            ]
+        )
+
+    if as_json:
+        click.echo(json.dumps(checks, indent=2))
+        return
+
+    table = Table(title="Repository Doctor", box=box.SIMPLE_HEAVY)
+    table.add_column("Check", style="cyan")
+    table.add_column("Status", justify="center")
+    table.add_column("Detail")
+    for item in checks:
+        state = item["status"]
+        table.add_row(
+            item["check"],
+            status_word(state == "pass", warn=state == "warn"),
+            item["detail"],
+        )
+    console.print(table)
+
+
+@main.command()
+@repo_option
+@click.argument("title")
+@click.option("--prefix", default="feature", show_default=True, help="Branch prefix.")
+@click.option("--ticket", help="Optional ticket or issue id to include.")
+@click.option("--from-ref", default="HEAD", show_default=True, help="Start point.")
+@click.option("--checkout/--no-checkout", default=True, show_default=True, help="Switch to the branch after creating it.")
+@click.option("--reuse", is_flag=True, help="Switch to an existing branch instead of failing.")
+@handle_errors
+def branch(
+    repo: Path,
+    title: str,
+    prefix: str,
+    ticket: str | None,
+    from_ref: str,
+    checkout: bool,
+    reuse: bool,
+) -> None:
+    """Create a consistently named workflow branch."""
+
+    root = repo_root(repo)
+    name = make_branch_name(prefix, ticket, title)
+    exists = branch_exists(root, name)
+    if exists and not reuse:
+        raise GitForgeError(f"branch already exists: {name}")
+
+    if exists and reuse:
+        if checkout:
+            print_command_output(git_text(["switch", name], root))
+        console.print(Panel.fit(f"[green]Using existing branch[/green]\n{name}"))
+        return
+
+    command = ["switch", "-c", name, from_ref] if checkout else ["branch", name, from_ref]
+    print_command_output(git_text(command, root))
+    console.print(Panel.fit(f"[green]Created branch[/green]\n{name}"))
+
+
+@main.command()
+@repo_option
+@click.option("-m", "--message", required=True, help="Commit message.")
+@click.option("--all/--tracked", "include_untracked", default=True, show_default=True, help="Stage all changes or only tracked files.")
+@click.option("--allow-empty", is_flag=True, help="Allow creating an empty commit.")
+@click.option("--push", is_flag=True, help="Push the current branch after committing.")
+@click.option("--dry-run", is_flag=True, help="Show what would be committed.")
+@handle_errors
+def snapshot(
+    repo: Path,
+    message: str,
+    include_untracked: bool,
+    allow_empty: bool,
+    push: bool,
+    dry_run: bool,
+) -> None:
+    """Stage changes and create a commit with guardrails."""
+
+    root = repo_root(repo)
+    stage_args = ["add", "-A"] if include_untracked else ["add", "-u"]
+
+    if dry_run:
+        console.print(Panel.fit("[yellow]Dry run[/yellow]\nNo files were staged or committed."))
+        print_command_output(git_text(["status", "--short"], root))
+        return
+
+    git_text(stage_args, root)
+    status = get_status(root)
+    if status.staged == 0 and not allow_empty:
+        raise GitForgeError("no staged changes to commit; use --allow-empty to force a commit")
+
+    commit_args = ["commit", "-m", message]
+    if allow_empty:
+        commit_args.insert(1, "--allow-empty")
+    print_command_output(git_text(commit_args, root))
+
+    if push:
+        branch_name = current_branch(root)
+        upstream = upstream_branch(root)
+        if upstream:
+            print_command_output(git_text(["push"], root))
+        else:
+            if origin_url(root) is None:
+                raise GitForgeError("cannot push because origin remote is not configured")
+            print_command_output(git_text(["push", "-u", "origin", branch_name], root))
+
+    console.print("[green]Snapshot complete[/green]")
+
+
+@main.command()
+@repo_option
+@click.option("--remote", default="origin", show_default=True, help="Remote to fetch and push.")
+@click.option("--rebase/--merge", "use_rebase", default=True, show_default=True, help="Pull strategy.")
+@click.option("--autostash", is_flag=True, help="Use git pull --autostash for local changes.")
+@click.option("--push/--no-push", "do_push", default=True, show_default=True, help="Push after pulling.")
+@handle_errors
+def sync(repo: Path, remote: str, use_rebase: bool, autostash: bool, do_push: bool) -> None:
+    """Fetch, pull, and optionally push the current branch."""
+
+    root = repo_root(repo)
+    branch_name = current_branch(root)
+    if branch_name.startswith("detached@") or branch_name == "unborn":
+        raise GitForgeError("sync requires a named branch")
+
+    print_command_output(git_text(["fetch", "--prune", remote], root))
+
+    upstream = upstream_branch(root)
+    if upstream:
+        pull_args = ["pull", "--rebase" if use_rebase else "--no-rebase"]
+        if autostash:
+            pull_args.append("--autostash")
+        print_command_output(git_text(pull_args, root))
+    else:
+        console.print("[yellow]No upstream configured; skipping pull.[/yellow]")
+
+    if do_push:
+        if upstream:
+            print_command_output(git_text(["push"], root))
+        else:
+            print_command_output(git_text(["push", "-u", remote, branch_name], root))
+    console.print("[green]Sync complete[/green]")
+
+
+@main.command()
+@repo_option
+@click.argument("version")
+@click.option("-m", "--message", help="Annotated tag message.")
+@click.option("--push", is_flag=True, help="Push the tag to origin.")
+@click.option("--dry-run", is_flag=True, help="Show the tag operation without changing the repo.")
+@click.option("--allow-dirty", is_flag=True, help="Allow tagging with uncommitted changes.")
+@handle_errors
+def release(
+    repo: Path,
+    version: str,
+    message: str | None,
+    push: bool,
+    dry_run: bool,
+    allow_dirty: bool,
+) -> None:
+    """Create an annotated release tag."""
+
+    root = repo_root(repo)
+    tag = version if version.startswith("v") else f"v{version}"
+    if not re.match(r"^v?\d+\.\d+\.\d+([-.][0-9A-Za-z.]+)?$", version):
+        raise GitForgeError("version must look like 1.2.3, v1.2.3, or include a prerelease suffix")
+    if tag_exists(root, tag):
+        raise GitForgeError(f"tag already exists: {tag}")
+    status = get_status(root)
+    if status.is_dirty and not allow_dirty:
+        raise GitForgeError("working tree is not clean; commit changes or use --allow-dirty")
+
+    tag_message = message or f"Release {tag}"
+    if dry_run:
+        console.print(Panel.fit(f"[yellow]Dry run[/yellow]\nWould create annotated tag {tag}"))
+        return
+
+    print_command_output(git_text(["tag", "-a", tag, "-m", tag_message], root))
+    if push:
+        print_command_output(git_text(["push", "origin", tag], root))
+    console.print(Panel.fit(f"[green]Release tag created[/green]\n{tag}"))
+
+
+@main.command()
+@repo_option
+@click.option("--since", help="Start at this tag or commit, ending at HEAD.")
+@click.option("--range", "rev_range", help="Explicit git revision range, such as v1.0.0..HEAD.")
+@click.option("--max-count", default=100, show_default=True, type=click.IntRange(1, 1000), help="Maximum commits to read.")
+@click.option("--output", type=click.Path(dir_okay=False, path_type=Path), help="Write Markdown changelog to a file.")
+@click.option("--json", "as_json", is_flag=True, help="Print machine-readable JSON.")
+@handle_errors
+def changelog(
+    repo: Path,
+    since: str | None,
+    rev_range: str | None,
+    max_count: int,
+    output: Path | None,
+    as_json: bool,
+) -> None:
+    """Generate a grouped changelog from commit history."""
+
+    root = repo_root(repo)
+    selected_range = rev_range or (f"{since}..HEAD" if since else None)
+    commits = load_commits(root, rev_range=selected_range, max_count=max_count)
+
+    if as_json:
+        click.echo(json.dumps([commit.as_dict() for commit in commits], indent=2))
+        return
+
+    markdown = render_markdown(commits)
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(markdown, encoding="utf-8")
+        console.print(f"[green]Wrote changelog:[/green] {output}")
+    console.print(Markdown(markdown))
+
+
+@main.command()
+@repo_option
+@click.argument("base")
+@click.argument("head", required=False, default="HEAD")
+@click.option("--json", "as_json", is_flag=True, help="Print machine-readable JSON.")
+@handle_errors
+def compare(repo: Path, base: str, head: str, as_json: bool) -> None:
+    """Compare two refs with commit and file-change summaries."""
+
+    root = repo_root(repo)
+    commit_lines = git_text(["log", "--left-right", "--cherry-pick", "--oneline", f"{base}...{head}"], root)
+    file_lines = git_text(["diff", "--name-status", f"{base}...{head}"], root)
+    commits_left = [line[1:].strip() for line in commit_lines.splitlines() if line.startswith("<")]
+    commits_right = [line[1:].strip() for line in commit_lines.splitlines() if line.startswith(">")]
+    files = [line.split(maxsplit=1) for line in file_lines.splitlines() if line.strip()]
+
+    payload = {
+        "base": base,
+        "head": head,
+        "base_only_commits": commits_left,
+        "head_only_commits": commits_right,
+        "changed_files": [{"status": item[0], "path": item[1] if len(item) > 1 else ""} for item in files],
+    }
+    if as_json:
+        click.echo(json.dumps(payload, indent=2))
+        return
+
+    summary = Table(title=f"Compare {base}...{head}", box=box.SIMPLE_HEAVY)
+    summary.add_column("Metric", style="cyan")
+    summary.add_column("Count", justify="right")
+    summary.add_row("Commits only in base", str(len(commits_left)))
+    summary.add_row("Commits only in head", str(len(commits_right)))
+    summary.add_row("Changed files", str(len(files)))
+    console.print(summary)
+
+    if files:
+        file_table = Table(title="Changed Files", box=box.SIMPLE)
+        file_table.add_column("Status", style="cyan", no_wrap=True)
+        file_table.add_column("Path")
+        for item in payload["changed_files"]:
+            file_table.add_row(item["status"], item["path"])
+        console.print(file_table)
+
+
+@main.command()
+@repo_option
+@click.option("--apply", "apply_changes", is_flag=True, help="Delete branches instead of only listing them.")
+@click.option("--protected", default="main,master,develop,dev,trunk", show_default=True, help="Comma-separated branches never to delete.")
+@click.option("--prune", is_flag=True, help="Run git fetch --prune before checking merged branches.")
+@handle_errors
+def cleanup(repo: Path, apply_changes: bool, protected: str, prune: bool) -> None:
+    """List or delete local branches already merged into HEAD."""
+
+    root = repo_root(repo)
+    if prune:
+        print_command_output(git_text(["fetch", "--prune"], root))
+
+    current = current_branch(root)
+    protected_names = {item.strip() for item in protected.split(",") if item.strip()}
+    candidates = [
+        branch_name
+        for branch_name in list_merged_branches(root)
+        if branch_name != current and branch_name not in protected_names
+    ]
+
+    table = Table(title="Merged Branch Cleanup", box=box.SIMPLE_HEAVY)
+    table.add_column("Branch", style="cyan")
+    table.add_column("Action")
+    for branch_name in candidates:
+        if apply_changes:
+            git_text(["branch", "-d", branch_name], root)
+            table.add_row(branch_name, "deleted")
+        else:
+            table.add_row(branch_name, "would delete")
+    if not candidates:
+        table.add_row("-", "nothing to clean")
+    console.print(table)
+    if not apply_changes:
+        console.print("[yellow]Dry run. Add --apply to delete listed branches.[/yellow]")
+
+
+@main.command("ignore")
+@repo_option
+@click.argument("templates", nargs=-1)
+@click.option("--list", "list_templates", is_flag=True, help="List available templates.")
+@handle_errors
+def ignore_command(repo: Path, templates: tuple[str, ...], list_templates: bool) -> None:
+    """Append useful snippets to .gitignore."""
+
+    if list_templates:
+        table = Table(title="Available .gitignore Templates", box=box.SIMPLE_HEAVY)
+        table.add_column("Template", style="cyan")
+        for name in available_templates():
+            table.add_row(name)
+        console.print(table)
+        return
+
+    if not templates:
+        raise GitForgeError("provide at least one template or use --list")
+
+    root = repo_root(repo)
+    gitignore = root / ".gitignore"
+    block = render_templates(list(templates))
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    separator = "\n\n" if existing.strip() else ""
+    gitignore.write_text(existing.rstrip() + separator + block, encoding="utf-8")
+    console.print(f"[green]Updated[/green] {gitignore}")
+
+
+if __name__ == "__main__":
+    main()

gitforge/git.py

@@ -0,0 +1,255 @@
+"""Small, typed wrappers around the Git executable."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+import shutil
+import subprocess
+from typing import Iterable
+
+
+class GitForgeError(RuntimeError):
+    """Base exception for user-facing GitForge errors."""
+
+
+class GitCommandError(GitForgeError):
+    """Raised when a git command fails."""
+
+    def __init__(
+        self,
+        command: Iterable[str],
+        cwd: Path,
+        returncode: int,
+        stdout: str,
+        stderr: str,
+    ) -> None:
+        self.command = list(command)
+        self.cwd = cwd
+        self.returncode = returncode
+        self.stdout = stdout.strip()
+        self.stderr = stderr.strip()
+        message = self.stderr or self.stdout or f"git exited with {returncode}"
+        super().__init__(f"{' '.join(self.command)} failed in {cwd}: {message}")
+
+
+@dataclass(frozen=True)
+class RepoStatus:
+    """A compact view of repository state."""
+
+    root: str
+    branch: str
+    commit: str | None
+    upstream: str | None
+    ahead: int
+    behind: int
+    staged: int
+    unstaged: int
+    untracked: int
+    conflicts: int
+    remote: str | None
+    last_tag: str | None
+
+    @property
+    def is_dirty(self) -> bool:
+        return any((self.staged, self.unstaged, self.untracked, self.conflicts))
+
+    def as_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["is_dirty"] = self.is_dirty
+        return data
+
+
+def git_available() -> bool:
+    """Return true when the Git executable can be found."""
+
+    return shutil.which("git") is not None
+
+
+def normalize_path(path: str | Path) -> Path:
+    """Normalize a user-provided repository path."""
+
+    resolved = Path(path).expanduser().resolve()
+    if not resolved.exists():
+        raise GitForgeError(f"path does not exist: {resolved}")
+    return resolved
+
+
+def run_git(
+    args: Iterable[str],
+    cwd: str | Path = ".",
+    *,
+    check: bool = True,
+    input_text: str | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Run a git command and return the completed process."""
+
+    if not git_available():
+        raise GitForgeError("git executable was not found on PATH")
+
+    workdir = normalize_path(cwd)
+    command = ["git", *list(args)]
+    process = subprocess.run(
+        command,
+        cwd=str(workdir),
+        input=input_text,
+        capture_output=True,
+        text=True,
+    )
+    if check and process.returncode != 0:
+        raise GitCommandError(
+            command=command,
+            cwd=workdir,
+            returncode=process.returncode,
+            stdout=process.stdout,
+            stderr=process.stderr,
+        )
+    return process
+
+
+def git_text(args: Iterable[str], cwd: str | Path = ".", *, check: bool = True) -> str:
+    """Run git and return stripped stdout."""
+
+    return run_git(args, cwd, check=check).stdout.strip()
+
+
+def safe_git(args: Iterable[str], cwd: str | Path = ".") -> str | None:
+    """Run git and return stripped stdout, or None on failure."""
+
+    process = run_git(args, cwd, check=False)
+    if process.returncode != 0:
+        return None
+    output = process.stdout.strip()
+    return output or None
+
+
+def repo_root(path: str | Path = ".") -> Path:
+    """Return the root directory for a Git repository."""
+
+    root = safe_git(["rev-parse", "--show-toplevel"], path)
+    if root is None:
+        raise GitForgeError(f"not a git repository: {Path(path).expanduser().resolve()}")
+    return Path(root).resolve()
+
+
+def is_repo(path: str | Path = ".") -> bool:
+    """Return true if path is inside a Git work tree."""
+
+    return safe_git(["rev-parse", "--is-inside-work-tree"], path) == "true"
+
+
+def current_branch(path: str | Path = ".") -> str:
+    """Return the current branch, or a detached-head label."""
+
+    branch = safe_git(["branch", "--show-current"], path)
+    if branch:
+        return branch
+    commit = safe_git(["rev-parse", "--short", "HEAD"], path)
+    if commit:
+        return f"detached@{commit}"
+    return "unborn"
+
+
+def current_commit(path: str | Path = ".") -> str | None:
+    """Return the short current commit hash if one exists."""
+
+    return safe_git(["rev-parse", "--short", "HEAD"], path)
+
+
+def upstream_branch(path: str | Path = ".") -> str | None:
+    """Return the configured upstream branch."""
+
+    return safe_git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], path)
+
+
+def origin_url(path: str | Path = ".") -> str | None:
+    """Return origin URL when configured."""
+
+    return safe_git(["config", "--get", "remote.origin.url"], path)
+
+
+def last_tag(path: str | Path = ".") -> str | None:
+    """Return the closest reachable tag."""
+
+    return safe_git(["describe", "--tags", "--abbrev=0"], path)
+
+
+def branch_exists(path: str | Path, branch: str) -> bool:
+    """Return true when a local branch exists."""
+
+    return safe_git(["rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"], path) is not None
+
+
+def tag_exists(path: str | Path, tag: str) -> bool:
+    """Return true when a tag exists."""
+
+    return safe_git(["rev-parse", "--verify", "--quiet", f"refs/tags/{tag}"], path) is not None
+
+
+def parse_porcelain(output: str) -> tuple[int, int, int, int]:
+    """Return staged, unstaged, untracked, conflict counts from porcelain status."""
+
+    staged = unstaged = untracked = conflicts = 0
+    conflict_codes = {"DD", "AU", "UD", "UA", "DU", "AA", "UU"}
+    for raw_line in output.splitlines():
+        if not raw_line:
+            continue
+        code = raw_line[:2]
+        if code == "??":
+            untracked += 1
+            continue
+        if code in conflict_codes:
+            conflicts += 1
+        if code[0] not in (" ", "?"):
+            staged += 1
+        if code[1] not in (" ", "?"):
+            unstaged += 1
+    return staged, unstaged, untracked, conflicts
+
+
+def ahead_behind(path: str | Path = ".") -> tuple[int, int]:
+    """Return ahead and behind counts against upstream."""
+
+    if upstream_branch(path) is None:
+        return 0, 0
+    counts = safe_git(["rev-list", "--left-right", "--count", "HEAD...@{u}"], path)
+    if not counts:
+        return 0, 0
+    left, right = counts.split()[:2]
+    return int(left), int(right)
+
+
+def get_status(path: str | Path = ".") -> RepoStatus:
+    """Collect repository status in one dataclass."""
+
+    root = repo_root(path)
+    porcelain = git_text(["status", "--porcelain=v1"], root)
+    staged, unstaged, untracked, conflicts = parse_porcelain(porcelain)
+    ahead, behind = ahead_behind(root)
+    return RepoStatus(
+        root=str(root),
+        branch=current_branch(root),
+        commit=current_commit(root),
+        upstream=upstream_branch(root),
+        ahead=ahead,
+        behind=behind,
+        staged=staged,
+        unstaged=unstaged,
+        untracked=untracked,
+        conflicts=conflicts,
+        remote=origin_url(root),
+        last_tag=last_tag(root),
+    )
+
+
+def list_merged_branches(path: str | Path = ".") -> list[str]:
+    """Return local branches already merged into HEAD."""
+
+    output = git_text(["branch", "--merged"], path)
+    branches: list[str] = []
+    for line in output.splitlines():
+        name = line.replace("*", "", 1).strip()
+        if name:
+            branches.append(name)
+    return branches
+

gitforge/templates.py

@@ -0,0 +1,67 @@
+"""Built-in .gitignore snippets."""
+
+from __future__ import annotations
+
+
+IGNORE_TEMPLATES = {
+    "python": """# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+""",
+    "node": """# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.next/
+dist/
+coverage/
+""",
+    "macos": """# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+""",
+    "vscode": """# VS Code
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+""",
+    "jetbrains": """# JetBrains
+.idea/
+*.iml
+""",
+    "logs": """# Logs
+*.log
+logs/
+""",
+}
+
+
+def available_templates() -> list[str]:
+    """Return the names of available ignore templates."""
+
+    return sorted(IGNORE_TEMPLATES)
+
+
+def render_templates(names: list[str]) -> str:
+    """Render selected templates into a single block."""
+
+    unknown = sorted(set(names) - set(IGNORE_TEMPLATES))
+    if unknown:
+        valid = ", ".join(available_templates())
+        raise ValueError(f"unknown template(s): {', '.join(unknown)}. Available: {valid}")
+
+    blocks = ["# Added by gitforge"]
+    for name in names:
+        blocks.append(IGNORE_TEMPLATES[name].strip())
+    return "\n\n".join(blocks).rstrip() + "\n"
+

gitforge_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+gitforge/__init__.py,sha256=I-8wASZCo9pdZOUfvL5Ldr2PIGzV66HvI4v17nmFbLg,57
+gitforge/__main__.py,sha256=2ki6bVTO98sPwQ45HdDBv4xupTPN1OJUGMUMHxh3UgU,112
+gitforge/changelog.py,sha256=JDZtlrxTpt9vahWA187dQEFJoYOIDkgS-Q6kUpT6roo,2659
+gitforge/cli.py,sha256=O9HT8btFsw6a2NaLVRKoDk_Y04qXpxlXIZx44I7RvU0,19137
+gitforge/git.py,sha256=1AfaYssUXDOr5dGm0PXtKBbuCoFuGOh1sAafm883QV8,7274
+gitforge/templates.py,sha256=pNFxBr3eIk25k-nacp_LJCCwer-0K8xzeoGsm96Lg14,1204
+gitforge_cli-0.1.0.dist-info/licenses/LICENSE,sha256=8HmUM0xaQoOvbP-GXsiGksa4MLaHRzZ5F-I-syTXt5c,1065
+gitforge_cli-0.1.0.dist-info/METADATA,sha256=7Cj75kqXvVTnXJrYhFzzjz4rSf4_gP2eUm9ks9MY-nI,5268
+gitforge_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gitforge_cli-0.1.0.dist-info/entry_points.txt,sha256=OZP7AiAMba3B-lOCCXx1jnM3tKlecnd-6b7ovaphYYA,47
+gitforge_cli-0.1.0.dist-info/top_level.txt,sha256=OlGVDBN_LBdvLsNaeGrSd5BpWYI1O3tR_BstvULOkdQ,9
+gitforge_cli-0.1.0.dist-info/RECORD,,

gitforge_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gitforge_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitforge = gitforge.cli:main

gitforge_cli-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+gitforge