Metadata-Version: 2.4
Name: pygittools
Version: 0.3.0
Summary: Hooks and task storage in Git
License-Expression: MIT
License-File: LICENSE
Requires-Dist: abcreg==0.2.0
Requires-Dist: pygit2>=1.12.0
Requires-Dist: pyratatui>=0.3.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# PyGitTools

Hooks, tooling, and pygit2 workflows used by PyGitWeb. Can be used headless for many purposes.

## PGT

`pgt` is a terminal UI for commits, branches, tasks, and worktrees. The home page has **Status**, **Log**, **Tasks**, and **Worktrees** tabs. `H` / `L` switch tabs, `J` / `K` move the selection, `Q` or `Ctrl-C` quits, and `?` opens help. On **Status**, `!` or the Actions row runs project scripts from `pyproject.toml` or `actions.toml`. Full key bindings are in the in-app help (`src/pygittools/help.md`).

To run from the repo root, use `uv run pgt`.

Task objects may include `points`, a Fibonacci story-point value: `0`, `1`, `2`, `3`, `5`, `8`, `13`, or `21`. Leave it unset when the task is unestimated.

## Hook framework

`pygittools.hooks` provides a thin `Hook` base class plus one subclass per git hook type
(client- and server-side). Receive-pack hooks (`PreReceive`, `PostReceive`) parse their
ref-update lines via `parse_ref_updates(stdin)`.

`pygittools.hooks_notify` adds `PreReceiveNotify` / `PostReceiveNotify`: minimal hook
variants that POST `?project=<name>` to a pygitweb `/_internal/notify` endpoint so its
long-poll `updates=true` subscribers wake up immediately on each push. Notification
failures never reject the push.

See `hook_samples/` for ready-to-use scripts.

## MCP task server

Boards, tasks, and comments stored in Git can be exposed to AI tools via MCP.

Configure the repository path with `PYGITTOOLS_REPO`, or set `PYGITWEB_PROJECTROOT` and pass a
`project` argument to each tool. When neither is set, the server discovers a repo from the current
working directory.

Run locally:

```bash
PYGITTOOLS_REPO=/path/to/repo uv run pygittools-mcp
```

Cursor project config (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pygittools-tasks": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pygitweb", "pygittools-mcp"],
      "env": {
        "PYGITTOOLS_REPO": "/path/to/your/repo"
      }
    }
  }
}
```

Tools: `list_boards_tool`, `list_tasks_tool`, `get_task_tool`, `board_by_status_tool`.
Resources: `board://{board_name}`, `task://{task_ref}`.

