git-graphable 0.1.0__tar.gz

git_graphable-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  check:
+    name: Check and Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install just
+        uses: extractions/setup-just@v2
+
+      - name: Run checks
+        run: just check

git_graphable-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Mandatory for trusted publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish

git_graphable-0.1.0/.gitignore

@@ -0,0 +1,131 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so may contain sensitive information.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+htmlrep/
+.pytest_worker_jsons/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# PEP 582; used by e.g. github.com/lincolnloop/python-extern
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath libraries
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# OS X
+.DS_Store

git_graphable-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

git_graphable-0.1.0/Justfile

@@ -0,0 +1,92 @@
+set dotenv-load
+
+GIT_BRANCH:=`git branch --show-current`
+GIT_COMMIT:=`git rev-parse HEAD`
+
+@_:
+    just --list
+
+_browser *args:
+    @uv run -m webbrowser -t {{ args }}
+
+_cleandir name:
+    @rm -rf {{ name }}
+
+_cleanfiles type:
+    @find . -type f -name "*.{{ type }}" -delete
+
+[group('docs')]
+usage:
+    PYTHONPATH=src uv run typer git_graphable.cli utils docs --name git-graphable --output USAGE.md
+
+[group('env')]
+@clean:
+    just _cleandir build
+    just _cleandir __pycache__
+    just _cleandir .coverage
+    just _cleandir .pytest_cache
+    just _cleandir .ruff_cache
+    just _cleandir htmlcov
+    just _cleandir htmlrep
+    just _cleandir _minted
+    just _cleandir svg-inkscape
+    just _cleandir docs/_build
+    just _cleandir docs/_extra
+
+[group('env')]
+fresh: nuke install
+
+[group('env')]
+install:
+    uv sync
+
+[group('env')]
+nuke: clean
+    just _cleandir .venv
+
+[group('env')]
+update:
+    uv sync --upgrade
+
+[group('package')]
+build:
+    uv build
+
+[group('package')]
+publish: build
+    uv publish
+
+[group('qa')]
+check: lint typing coverage
+
+[group('qa')]
+@coverage *args:
+    just test --cov=. --cov-report html --cov-report term-missing {{ args }}
+
+[group('qa')]
+[group('view')]
+covrep:
+    just _browser htmlcov/index.html
+
+[group('qa')]
+lint:
+    uv run isort .
+    uv run ruff format
+    uv run ruff check --fix
+
+[group('qa')]
+@test *args:
+    uv run -m pytest --git-branch {{ GIT_BRANCH }} --git-commit {{ GIT_COMMIT }} --html-output htmlrep -n auto --should-open-report never {{ args }}
+
+[group('qa')]
+[group('view')]
+testrep:
+    just _browser htmlrep/report.html
+
+[group('qa')]
+typing:
+    uv run ty check
+
+[group('run')]
+@run *args:
+    uv run git-graphable {{ args }}

git_graphable-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: git-graphable
+Version: 0.1.0
+Summary: A powerful tool to convert Git commit history into beautiful flowcharts.
+Project-URL: Homepage, https://github.com/TheTrueSCU/git-graphable
+Project-URL: Issues, https://github.com/TheTrueSCU/git-graphable/issues
+Project-URL: Repository, https://github.com/TheTrueSCU/git-graphable
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Keywords: analysis,d2,git,graph,hygiene,mermaid,topology,visualization
+Requires-Python: >=3.13
+Requires-Dist: graphable>=0.6.0
+Provides-Extra: cli
+Requires-Dist: rich>=13.0.0; extra == 'cli'
+Requires-Dist: typer>=0.12.0; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# Git Graphable
+
+A powerful Python tool to convert Git commit history into beautiful, interactive flowcharts using the `graphable` library. Supporting Mermaid, D2, Graphviz, and PlantUML.
+
+## Git Plugin Support
+When installed in your PATH, you can use this as a native Git plugin:
+```bash
+git graphable .
+```
+
+## Features
+
+- **Multi-Engine Support**: Export to Mermaid (.mmd), D2 (.d2), Graphviz (.dot), or PlantUML (.puml).
+- **Automatic Visualization**: Generates and opens an image (SVG/PNG) automatically if no output is specified.
+- **Advanced Highlighting**: Visualize author patterns, topological distance, and specific merge paths.
+- **Hygiene Analysis**: Identify commits that are "behind" a base branch with divergence analysis.
+- **Flexible Input**: Works with local repository paths or remote Git URLs.
+- **Dual CLI**: Modern Rich/Typer interface with a robust argparse fallback for bare environments.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv sync --all-extras
+```
+
+## Usage
+
+For a complete reference of all command-line options, see the [USAGE.md](USAGE.md) file.
+
+```bash
+# Basic usage (opens a Mermaid image)
+uv run git-graphable .
+
+# Specify an engine and output file
+uv run git-graphable https://github.com/TheTrueSCU/graphable/ --engine d2 -o graph.svg
+
+# Simplify the graph (only show branches/tags)
+uv run git-graphable . --simplify
+```
+
+## Highlighting Options
+
+Git Graphable provides several ways to highlight commits and relationships. Multiple options can be combined to layer information.
+
+| Option | Target | Effect | Conflicts With |
+| :--- | :--- | :--- | :--- |
+| `--highlight-authors` | **Fill** | Unique color per author | Distance, Stale |
+| `--highlight-distance-from` | **Fill** | Blue gradient fading by distance | Authors, Stale |
+| `--highlight-stale` | **Fill** | Gradient white to red by age | Authors, Distance |
+| `--highlight-path` | **Edge** | Thick Orange edge connecting nodes | None |
+| `--highlight-critical` | **Stroke** | Thick Red Solid outline | None |
+| `--highlight-diverging-from` | **Stroke** | Orange Dashed outline | None |
+| `--highlight-orphans` | **Stroke** | Grey Dashed outline | None |
+| `--highlight-long-running` | **Stroke/Edge** | Purple outline and thick Purple edge | None |
+
+### Highlighting Priorities
+- **Fill**: `--highlight-authors`, `--highlight-distance-from`, and `--highlight-stale` are mutually exclusive.
+- **Edge**: Path highlighting (Thick Orange) takes priority over Long-Running highlighting (Thick Purple).
+- **Stroke**: Critical outlines (Thick Red) take priority over all other outlines (Divergence, Orphan, Long-Running).
+
+## Advanced Examples
+
+### Divergence Analysis (Hygiene)
+Highlight commits that exist in `main` but are missing from your feature branches:
+```bash
+uv run git-graphable . --highlight-diverging-from main
+```
+
+### Path Highlighting
+See the exact sequence of commits between a feature branch and a specific tag:
+```bash
+uv run git-graphable . --highlight-path develop..v1.0.0
+```
+
+### Large Repositories
+For repositories with long histories, use the `--limit` flag to keep the graph readable and avoid engine rendering limits:
+```bash
+uv run git-graphable . --limit 100 --highlight-authors
+```
+
+## Development
+
+Run tests and linting:
+```bash
+just check
+```
+
+### CI/CD
+This project uses GitHub Actions for continuous integration and automated publishing:
+- **CI**: Runs `just check` on all pushes and PRs to `main`.
+- **Publish**: Automatically builds and publishes to PyPI when a version tag (`v*`) is pushed.

git_graphable-0.1.0/README.md

@@ -0,0 +1,92 @@
+# Git Graphable
+
+A powerful Python tool to convert Git commit history into beautiful, interactive flowcharts using the `graphable` library. Supporting Mermaid, D2, Graphviz, and PlantUML.
+
+## Git Plugin Support
+When installed in your PATH, you can use this as a native Git plugin:
+```bash
+git graphable .
+```
+
+## Features
+
+- **Multi-Engine Support**: Export to Mermaid (.mmd), D2 (.d2), Graphviz (.dot), or PlantUML (.puml).
+- **Automatic Visualization**: Generates and opens an image (SVG/PNG) automatically if no output is specified.
+- **Advanced Highlighting**: Visualize author patterns, topological distance, and specific merge paths.
+- **Hygiene Analysis**: Identify commits that are "behind" a base branch with divergence analysis.
+- **Flexible Input**: Works with local repository paths or remote Git URLs.
+- **Dual CLI**: Modern Rich/Typer interface with a robust argparse fallback for bare environments.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv sync --all-extras
+```
+
+## Usage
+
+For a complete reference of all command-line options, see the [USAGE.md](USAGE.md) file.
+
+```bash
+# Basic usage (opens a Mermaid image)
+uv run git-graphable .
+
+# Specify an engine and output file
+uv run git-graphable https://github.com/TheTrueSCU/graphable/ --engine d2 -o graph.svg
+
+# Simplify the graph (only show branches/tags)
+uv run git-graphable . --simplify
+```
+
+## Highlighting Options
+
+Git Graphable provides several ways to highlight commits and relationships. Multiple options can be combined to layer information.
+
+| Option | Target | Effect | Conflicts With |
+| :--- | :--- | :--- | :--- |
+| `--highlight-authors` | **Fill** | Unique color per author | Distance, Stale |
+| `--highlight-distance-from` | **Fill** | Blue gradient fading by distance | Authors, Stale |
+| `--highlight-stale` | **Fill** | Gradient white to red by age | Authors, Distance |
+| `--highlight-path` | **Edge** | Thick Orange edge connecting nodes | None |
+| `--highlight-critical` | **Stroke** | Thick Red Solid outline | None |
+| `--highlight-diverging-from` | **Stroke** | Orange Dashed outline | None |
+| `--highlight-orphans` | **Stroke** | Grey Dashed outline | None |
+| `--highlight-long-running` | **Stroke/Edge** | Purple outline and thick Purple edge | None |
+
+### Highlighting Priorities
+- **Fill**: `--highlight-authors`, `--highlight-distance-from`, and `--highlight-stale` are mutually exclusive.
+- **Edge**: Path highlighting (Thick Orange) takes priority over Long-Running highlighting (Thick Purple).
+- **Stroke**: Critical outlines (Thick Red) take priority over all other outlines (Divergence, Orphan, Long-Running).
+
+## Advanced Examples
+
+### Divergence Analysis (Hygiene)
+Highlight commits that exist in `main` but are missing from your feature branches:
+```bash
+uv run git-graphable . --highlight-diverging-from main
+```
+
+### Path Highlighting
+See the exact sequence of commits between a feature branch and a specific tag:
+```bash
+uv run git-graphable . --highlight-path develop..v1.0.0
+```
+
+### Large Repositories
+For repositories with long histories, use the `--limit` flag to keep the graph readable and avoid engine rendering limits:
+```bash
+uv run git-graphable . --limit 100 --highlight-authors
+```
+
+## Development
+
+Run tests and linting:
+```bash
+just check
+```
+
+### CI/CD
+This project uses GitHub Actions for continuous integration and automated publishing:
+- **CI**: Runs `just check` on all pushes and PRs to `main`.
+- **Publish**: Automatically builds and publishes to PyPI when a version tag (`v*`) is pushed.

git_graphable-0.1.0/USAGE.md

@@ -0,0 +1,35 @@
+# `git-graphable`
+
+Git graph to Mermaid/Graphviz/D2/PlantUML converter.
+
+**Usage**:
+
+```console
+$ git-graphable [OPTIONS] PATH
+```
+
+**Arguments**:
+
+* `PATH`: Path to local directory or git URL  [required]
+
+**Options**:
+
+* `--date-format TEXT`: Date format for commit labels  [default: %Y%m%d%H%M%S]
+* `--engine [mermaid|graphviz|d2|plantuml]`: Visualization engine  [default: mermaid]
+* `-o, --output TEXT`: Output file path
+* `--image`: Export as image even when output path is provided
+* `--simplify`: Pass --simplify-by-decoration to git log
+* `--limit INTEGER`: Limit the number of commits to process
+* `--highlight-critical TEXT`: Branch names to highlight as critical
+* `--highlight-authors`: Assign colors to different authors
+* `--highlight-distance-from TEXT`: Base branch/hash for distance highlighting
+* `--highlight-path TEXT`: Highlight path between two SHAs (START..END)
+* `--highlight-diverging-from TEXT`: Base branch/hash for divergence/behind analysis
+* `--highlight-orphans`: Highlight dangling/orphan commits
+* `--highlight-stale INTEGER`: Threshold in days to highlight stale branch tips
+* `--highlight-long-running INTEGER`: Threshold in days to highlight long-running branches
+* `--long-running-base TEXT`: Base branch for long-running analysis  [default: main]
+* `--bare`: Force bare mode (no rich output)
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.

git_graphable-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" },
+]
+dependencies = [
+    "graphable>=0.6.0",
+]
+description = "A powerful tool to convert Git commit history into beautiful flowcharts."
+keywords = [
+    "analysis",
+    "d2",
+    "git",
+    "graph",
+    "hygiene",
+    "mermaid",
+    "topology",
+    "visualization",
+]
+name = "git-graphable"
+readme = "README.md"
+requires-python = ">=3.13"
+version = "0.1.0"
+
+[project.optional-dependencies]
+cli = [
+    "rich>=13.0.0",
+    "typer>=0.12.0",
+]
+
+[project.scripts]
+git-graphable = "git_graphable.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/TheTrueSCU/git-graphable"
+Issues = "https://github.com/TheTrueSCU/git-graphable/issues"
+Repository = "https://github.com/TheTrueSCU/git-graphable"
+
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[dependency-groups]
+dev = [
+    "pytest-cov>=7.0.0",
+    "pytest-gitignore>=1.3",
+    "pytest-html-plus>=0.5.0",
+    "pytest-isort>=4.0.0",
+    "pytest-randomly>=4.0.1",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "pytest>=9.0.2",
+    "ruff>=0.15.4",
+    "ty>=0.0.20",
+    "typer-cli>=0.24.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/git_graphable"]
+
+[tool.uv]
+package = true
+
+[tool.coverage.run]
+omit = [
+    "src/git_graphable/cli.py",
+]
+
+[tool.coverage.report]
+fail_under = 75
+show_missing = true
+skip_covered = true

git_graphable-0.1.0/src/git_graphable/__init__.py

@@ -0,0 +1,19 @@
+from .core import (
+    CommitMetadata,
+    GitCommit,
+    GitLogConfig,
+    generate_summary,
+    process_repo,
+)
+from .parser import get_git_log
+from .styler import export_graph
+
+__all__ = [
+    "CommitMetadata",
+    "GitCommit",
+    "GitLogConfig",
+    "generate_summary",
+    "get_git_log",
+    "export_graph",
+    "process_repo",
+]