githelp 0.1.0__py3-none-any.whl

githelp/__init__.py

@@ -0,0 +1,3 @@
+"""gg - a tiny git helper."""
+
+__version__ = "0.1.0"

githelp/cli.py

@@ -0,0 +1,203 @@
+"""Command-line entry points for `gg` and `ggi`."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import questionary
+from rich.console import Console
+
+from . import gitignore, gitutil
+from .gitutil import GitError
+
+console = Console()
+err = Console(stderr=True)
+
+FILE_WARN = 100  # warn when staging more than this many files
+LINE_WARN = 100_000  # warn when staging more than this many changed lines
+
+
+# --------------------------------------------------------------------------- #
+# gg : add . + commit (no quotes needed) + push
+# --------------------------------------------------------------------------- #
+
+GG_USAGE = """\
+[bold]gg[/bold] - stage everything, commit, and push in one shot.
+
+[bold]Usage:[/bold]
+  gg <your commit message with no quotes>
+
+[bold]Example:[/bold]
+  gg fix the login bug and update readme
+
+Runs: git add .  ->  git commit -m "<your message>"  ->  git push
+Warns before committing if more than %d files or %s changed lines are staged.\
+""" % (FILE_WARN, f"{LINE_WARN:,}")
+
+
+def gg_main() -> None:
+    sys.exit(_gg(sys.argv[1:]))
+
+
+def _gg(args: list[str]) -> int:
+    if not args or args[0] in ("-h", "--help"):
+        console.print(GG_USAGE)
+        return 0 if args else 1
+
+    message = " ".join(args).strip()
+    if not message:
+        err.print("[red]A commit message is required.[/red]")
+        return 1
+
+    try:
+        if not gitutil.is_inside_repo():
+            err.print("[red]Not inside a git repository.[/red]")
+            return 1
+
+        gitutil.run_git(["add", "."])
+        stats = gitutil.staged_stats()
+
+        if stats.files == 0:
+            console.print("[yellow]Nothing to commit - working tree is clean.[/yellow]")
+            return 0
+
+        console.print(
+            f"Staged [bold]{stats.files}[/bold] file(s), "
+            f"[bold]{stats.lines:,}[/bold] changed line(s)."
+        )
+
+        if stats.files > FILE_WARN and not _confirm(
+            f"That is more than {FILE_WARN} files. Are you sure you want to commit?"
+        ):
+            console.print("[yellow]Aborted. (Files are still staged.)[/yellow]")
+            return 1
+
+        if stats.lines > LINE_WARN and not _confirm(
+            f"That is more than {LINE_WARN:,} changed lines. Are you sure?"
+        ):
+            console.print("[yellow]Aborted. (Files are still staged.)[/yellow]")
+            return 1
+
+        gitutil.run_git(["commit", "-m", message])
+        console.print(f'[green]Committed:[/green] "{message}"')
+
+        _push()
+        return 0
+
+    except GitError as exc:
+        err.print(f"[red]{exc}[/red]")
+        return 1
+
+
+def _push() -> None:
+    """Push the current branch, setting upstream automatically if needed."""
+    proc = gitutil.run_git(["push"], check=False)
+    if proc.returncode == 0:
+        console.print("[green]Pushed.[/green]")
+        return
+
+    stderr = (proc.stderr or "").lower()
+    branch = gitutil.current_branch()
+    if "no upstream" in stderr and branch:
+        console.print("[yellow]No upstream set - pushing with --set-upstream origin.[/yellow]")
+        up = gitutil.run_git(["push", "--set-upstream", "origin", branch], check=False)
+        if up.returncode == 0:
+            console.print("[green]Pushed.[/green]")
+            return
+        raise GitError((up.stderr or up.stdout or "git push failed.").strip())
+
+    raise GitError((proc.stderr or proc.stdout or "git push failed.").strip())
+
+
+# --------------------------------------------------------------------------- #
+# ggi : add a .gitignore template from github/gitignore
+# --------------------------------------------------------------------------- #
+
+GGI_USAGE = """\
+[bold]ggi[/bold] - add a .gitignore template (live from github/gitignore).
+
+[bold]Usage:[/bold]
+  ggi              # interactive: pick a template by typing/searching
+  ggi Python       # add a named template directly
+
+Appends the chosen template to your repository's .gitignore.\
+"""
+
+
+def ggi_main() -> None:
+    sys.exit(_ggi(sys.argv[1:]))
+
+
+def _ggi(args: list[str]) -> int:
+    if args and args[0] in ("-h", "--help"):
+        console.print(GGI_USAGE)
+        return 0
+
+    try:
+        available = gitignore.list_templates()
+    except gitignore.GitignoreError as exc:
+        err.print(f"[red]{exc}[/red]")
+        return 1
+
+    if args:
+        chosen = gitignore.resolve_name(args[0], available)
+        if chosen is None:
+            err.print(
+                f"[red]Unknown template {args[0]!r}.[/red] "
+                "Run [bold]ggi[/bold] with no arguments to browse the list."
+            )
+            return 1
+    else:
+        chosen = questionary.autocomplete(
+            "Which .gitignore template do you want to add?",
+            choices=available,
+            match_middle=True,
+            ignore_case=True,
+        ).ask()
+        if not chosen:
+            console.print("[yellow]Cancelled.[/yellow]")
+            return 1
+        chosen = gitignore.resolve_name(chosen, available)
+        if chosen is None:
+            err.print("[red]That is not a valid template name.[/red]")
+            return 1
+
+    try:
+        name, source = gitignore.fetch_template(chosen)
+    except gitignore.GitignoreError as exc:
+        err.print(f"[red]{exc}[/red]")
+        return 1
+
+    target = os.path.join(gitutil.repo_root() or os.getcwd(), ".gitignore")
+    marker = f"# >>> {name}.gitignore (added by gg) >>>"
+
+    existing = ""
+    if os.path.exists(target):
+        with open(target, "r", encoding="utf-8") as fh:
+            existing = fh.read()
+
+    if marker in existing:
+        console.print(
+            f"[yellow]{name} is already present in {target} - nothing to do.[/yellow]"
+        )
+        return 0
+
+    block = f"{marker}\n{source.rstrip()}\n# <<< {name}.gitignore <<<\n"
+    prefix = "" if (not existing or existing.endswith("\n")) else "\n"
+    with open(target, "a", encoding="utf-8") as fh:
+        if existing and not existing.endswith("\n\n"):
+            fh.write(prefix + "\n")
+        fh.write(block)
+
+    console.print(f"[green]Added {name} template to[/green] {target}")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+
+def _confirm(question: str) -> bool:
+    answer = questionary.confirm(question, default=False).ask()
+    return bool(answer)

githelp/gitignore.py

@@ -0,0 +1,61 @@
+"""Fetch .gitignore templates live from github/gitignore via the GitHub API."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+API_LIST = "https://api.github.com/gitignore/templates"
+API_TEMPLATE = "https://api.github.com/gitignore/templates/{name}"
+TIMEOUT = 15.0
+
+
+class GitignoreError(RuntimeError):
+    """Raised when a template cannot be listed or fetched."""
+
+
+def _headers() -> dict[str, str]:
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    # Use a token if present to avoid the unauthenticated rate limit.
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def list_templates() -> list[str]:
+    """Return the list of available template names (e.g. 'Python', 'Node')."""
+    try:
+        resp = httpx.get(API_LIST, headers=_headers(), timeout=TIMEOUT)
+        resp.raise_for_status()
+        return list(resp.json())
+    except httpx.HTTPError as exc:
+        raise GitignoreError(f"Could not fetch the template list: {exc}") from exc
+
+
+def fetch_template(name: str) -> tuple[str, str]:
+    """Fetch one template. Returns (canonical_name, source_text)."""
+    try:
+        resp = httpx.get(
+            API_TEMPLATE.format(name=name), headers=_headers(), timeout=TIMEOUT
+        )
+        if resp.status_code == 404:
+            raise GitignoreError(f"No gitignore template named {name!r}.")
+        resp.raise_for_status()
+        data = resp.json()
+        return data["name"], data["source"]
+    except httpx.HTTPError as exc:
+        raise GitignoreError(f"Could not fetch template {name!r}: {exc}") from exc
+
+
+def resolve_name(name: str, available: list[str]) -> str | None:
+    """Match user input to an available template, case-insensitively."""
+    lowered = name.strip().lower()
+    for candidate in available:
+        if candidate.lower() == lowered:
+            return candidate
+    return None

githelp/gitutil.py

@@ -0,0 +1,71 @@
+"""Thin wrappers around the `git` command-line."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+
+
+class GitError(RuntimeError):
+    """Raised when a git command fails or git is unavailable."""
+
+
+def run_git(args: list[str], check: bool = True) -> subprocess.CompletedProcess:
+    """Run a git command, capturing stdout/stderr as text."""
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:  # git not installed
+        raise GitError("git is not installed or not on your PATH.") from exc
+
+    if check and proc.returncode != 0:
+        message = (proc.stderr or proc.stdout or "").strip()
+        raise GitError(message or f"git {' '.join(args)} failed.")
+    return proc
+
+
+def is_inside_repo() -> bool:
+    proc = run_git(["rev-parse", "--is-inside-work-tree"], check=False)
+    return proc.returncode == 0 and proc.stdout.strip() == "true"
+
+
+def repo_root() -> str | None:
+    proc = run_git(["rev-parse", "--show-toplevel"], check=False)
+    if proc.returncode == 0:
+        return proc.stdout.strip()
+    return None
+
+
+def current_branch() -> str | None:
+    proc = run_git(["rev-parse", "--abbrev-ref", "HEAD"], check=False)
+    if proc.returncode == 0:
+        branch = proc.stdout.strip()
+        return branch if branch and branch != "HEAD" else None
+    return None
+
+
+@dataclass
+class StagedStats:
+    files: int
+    lines: int  # added + removed across all staged files
+
+
+def staged_stats() -> StagedStats:
+    """Summarise what is currently staged using `git diff --cached --numstat`."""
+    proc = run_git(["diff", "--cached", "--numstat"])
+    files = 0
+    lines = 0
+    for raw in proc.stdout.splitlines():
+        parts = raw.split("\t")
+        if len(parts) < 3:
+            continue
+        added, removed = parts[0], parts[1]
+        files += 1
+        if added.isdigit():
+            lines += int(added)
+        if removed.isdigit():
+            lines += int(removed)
+    return StagedStats(files=files, lines=lines)

githelp-0.1.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: githelp
+Version: 0.1.0
+Summary: githelp - a tiny git helper (gg/ggi): commit without quotes, and add .gitignore templates from github/gitignore
+Project-URL: Homepage, https://github.com/rosaboyle/githelp
+Project-URL: Repository, https://github.com/rosaboyle/githelp
+Project-URL: Issues, https://github.com/rosaboyle/githelp/issues
+Author-email: Dheeraj Pai <dheeraj.pai@leanmcp.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,commit,git,gitignore
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Requires-Dist: httpx==0.28.1
+Requires-Dist: questionary==2.1.1
+Requires-Dist: rich==15.0.0
+Description-Content-Type: text/markdown
+
+# githelp
+
+A tiny git helper published as [`githelp`](https://pypi.org/project/githelp/). It
+installs two commands: **`gg`** and **`ggi`**.
+
+```
+pip install githelp
+```
+
+- Repository: <https://github.com/rosaboyle/githelp>
+- PyPI: <https://pypi.org/project/githelp/>
+
+---
+
+## `gg` — commit without quotes
+
+Type your message straight after `gg`, no quotes:
+
+```
+gg fix the login bug and update the readme
+```
+
+That runs, in order:
+
+```
+git add .
+git commit -m "fix the login bug and update the readme"
+git push
+```
+
+It **warns you and asks "are you sure?"** before committing when:
+
+- more than **100 files** are staged, or
+- more than **100,000 changed lines** are staged.
+
+If you decline, it aborts (your files stay staged). If neither threshold is
+crossed, it just commits and pushes. If the current branch has no upstream, it
+pushes with `--set-upstream origin <branch>` automatically.
+
+```
+gg --help     # usage
+```
+
+## `ggi` — add a .gitignore template
+
+Templates are fetched **live** from
+[`github/gitignore`](https://github.com/github/gitignore) through the GitHub API,
+so they are always the current upstream versions (nothing is bundled or stale).
+
+```
+ggi            # interactive: type to fuzzy-search the full list, then pick one
+ggi Python     # add a named template directly
+ggi --help     # usage
+```
+
+The selected template is appended to your repository's `.gitignore` inside a
+clearly marked block, so it is easy to find and is never added twice.
+
+> Tip: set `GITHUB_TOKEN` (or `GH_TOKEN`) in your environment to avoid GitHub's
+> unauthenticated API rate limit.
+
+---
+
+## Install from source / develop
+
+```bash
+git clone https://github.com/rosaboyle/githelp
+cd githelp
+pip install -e .
+```
+
+## Dependencies
+
+Pinned to the latest releases:
+
+| Package      | Version |
+|--------------|---------|
+| httpx        | 0.28.1  |
+| questionary  | 2.1.1   |
+| rich         | 15.0.0  |
+
+Requires Python 3.9+.
+
+---
+
+## Publishing
+
+A helper script is provided: [`publish.sh`](./publish.sh).
+
+```bash
+./publish.sh            # build + upload to PyPI
+./publish.sh --test     # upload to TestPyPI instead
+./publish.sh --check    # build only, validate with twine, do not upload
+```
+
+Manual equivalent:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+Authenticate to PyPI with an API token: create one at
+<https://pypi.org/manage/account/token/> and either set `TWINE_USERNAME=__token__`
+and `TWINE_PASSWORD=<your-token>`, or let twine prompt you.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

githelp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+githelp/__init__.py,sha256=R1TFSwPV-RZGfv5x94KmaSbW6-S7wvoxSfj2igibgak,53
+githelp/cli.py,sha256=RJGqDdSs64u3f3CHMdpD91do7r_W51CJdrfimdPl9nY,6370
+githelp/gitignore.py,sha256=Tj-QqbZhYe-1RAjyWIGUkWge2Bd2WBqKlFeXVOXatic,2013
+githelp/gitutil.py,sha256=hzsaW9UAGWMX2vIjkCyR6VScz_dIqXEScG1vOc7DabE,2101
+githelp-0.1.0.dist-info/METADATA,sha256=h-ahn4UEtim0oj9Vtl2vhCJgRioTKljeml0CGt1N0r0,3401
+githelp-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+githelp-0.1.0.dist-info/entry_points.txt,sha256=rHb_oBlXstXQ5QrrvXQikWr7afSLEXBsmHXdLQT7u7A,70
+githelp-0.1.0.dist-info/licenses/LICENSE,sha256=aqonVRTrI_8qReGCiAAL7lAeepyC-BR8kfea7HH4qNY,1068
+githelp-0.1.0.dist-info/RECORD,,

githelp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

githelp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+gg = githelp.cli:gg_main
+ggi = githelp.cli:ggi_main

githelp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dheeraj Pai
+
+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.