pygittools 0.1.0__tar.gz

pygittools-0.1.0/LICENSE

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

pygittools-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: pygittools
+Version: 0.1.0
+Summary: Hooks and task storage in Git
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygit2>=1.12.0
+Dynamic: license-file
+
+# PyGitTools
+
+Authentication, hooks, and pygit2 workflows used by PyGitWeb. Can be used headless for many purposes.
+
+## 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.

pygittools-0.1.0/README.md

@@ -0,0 +1,16 @@
+# PyGitTools
+
+Authentication, hooks, and pygit2 workflows used by PyGitWeb. Can be used headless for many purposes.
+
+## 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.

pygittools-0.1.0/__init__.py

@@ -0,0 +1,10 @@
+import pygittools.__meta__
+
+"""
+Python hooks and metadata storage in Git
+"""
+__version__ = pygittools.__meta__.__version__
+__author__ = pygittools.__meta__.__author__
+__description__ = pygittools.__meta__.__description__
+__url__ = pygittools.__meta__.__url__
+__license__ = pygittools.__meta__.__license__

pygittools-0.1.0/__meta__.py

@@ -0,0 +1,9 @@
+"""
+Metadata for PyGitTools - this is the canonical source of all information below.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Will Bowers"
+__license__ = "MIT"
+__description__ = "Python hooks and metadata storage in Git"
+__url__ = "https://pygitweb.com"

pygittools-0.1.0/hook_samples/README.md

@@ -0,0 +1,44 @@
+# Sample Hooks
+
+Place these as desired in `.git/hooks/` WITHOUT the suffix.
+
+You will just need UV with pygittools in your virtual environment.
+
+## post-receive.notify and post-commit.notify
+
+Wake pygitweb's long-poll subscribers (`updates=true`) on every push (server-side) and
+every local commit (client-side). They share two environment variables:
+
+- `PYGITWEB_NOTIFY_URL` — the running server's notify endpoint (default
+  `http://127.0.0.1:8000/_internal/notify`)
+- `PYGITWEB_PROJECT` — project path as known to pygitweb (default: the bare repo's
+  directory name with `.git` stripped, or for non-bare clones the working-tree directory
+  name)
+
+The pygitweb summary page can install both at once via the **Hooks** row (the `update`
+bundle installs `post-commit.notify` and `post-receive.notify` together).
+
+## pre-receive.protected-pattern
+
+Reject pushes to protected refs when any newly introduced non-merge commit message does
+not match a pattern. Merge commits are skipped by default; set `PYGITWEB_REJECT_MERGE_COMMITS=1`
+to refuse merge commits and require squash or rebase instead.
+
+Environment variables:
+
+- `PYGITWEB_PROTECTED_REF_PATTERN` — refs to protect (default `^refs/heads/(main|master)$`)
+- `PYGITWEB_COMMIT_MSG_PATTERN` — message regex (default `^(\S+): (.+)`)
+- `PYGITWEB_REJECT_MERGE_COMMITS` — set to `1`/`true`/`yes` to reject merge commits
+
+## post-commit.push-remotes
+
+After each local commit, force-with-lease push the current branch to every configured
+remote when the branch name matches a pattern. Uses the git CLI (`git push
+--force-with-lease`), so SSH remotes honor `~/.ssh/config` like a normal push. Push
+failures are logged on stderr but do not affect the commit (post-commit hooks cannot undo
+a commit).
+
+Environment variables:
+
+- `PYGITWEB_PUSH_BRANCH_PATTERN` — branch name regex (default `^wip/`)
+- `GIT` — git executable (default: `git` on `PATH`)

pygittools-0.1.0/hook_samples/commit-msg.pattern

@@ -0,0 +1,24 @@
+#!/usr/bin/env -S uv run python
+
+from __future__ import annotations
+
+__VERSION__ = "1"
+
+import sys
+import pygit2
+from pygittools.hooks import HookResult
+from pygittools.hooks_patterns import CommitMsgPattern
+
+PATTERN = r"^(\S+): (.+)"
+
+
+def main() -> int:
+    repo = pygit2.Repository(".")
+    result = CommitMsgPattern(repo, PATTERN).run(sys.argv[1])
+    if result.value == HookResult.FAILURE:
+        print("Commit message does not match pattern:", PATTERN, file=sys.stderr)
+    return int(result.value)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pygittools-0.1.0/hook_samples/post-commit.notify

@@ -0,0 +1,24 @@
+#!/usr/bin/env -S uv run python
+
+from __future__ import annotations
+
+__VERSION__ = "1"
+
+import os
+
+import pygit2
+
+from pygittools.hooks_notify import PostCommitNotify
+
+NOTIFY_URL = os.environ.get("PYGITWEB_NOTIFY_URL", "http://127.0.0.1:8000/_internal/notify")
+PROJECT = os.environ.get("PYGITWEB_PROJECT") or os.path.basename(os.getcwd()).removesuffix(".git")
+
+
+def main() -> int:
+	repo = pygit2.Repository(".")
+	result = PostCommitNotify(repo, NOTIFY_URL, PROJECT).run()
+	return int(result.value)
+
+
+if __name__ == "__main__":
+	raise SystemExit(main())

pygittools-0.1.0/hook_samples/post-commit.push-remotes

@@ -0,0 +1,23 @@
+#!/usr/bin/env -S uv run python
+
+from __future__ import annotations
+
+__VERSION__ = "1"
+
+import os
+
+import pygit2
+
+from pygittools.hooks_push import PostCommitPushRemotes
+
+BRANCH_PATTERN = os.environ.get("PYGITWEB_PUSH_BRANCH_PATTERN", r"^wip/")
+
+
+def main() -> int:
+	repo = pygit2.Repository(".")
+	result = PostCommitPushRemotes(repo, BRANCH_PATTERN).run()
+	return int(result.value)
+
+
+if __name__ == "__main__":
+	raise SystemExit(main())

pygittools-0.1.0/hook_samples/post-receive.notify

@@ -0,0 +1,27 @@
+#!/usr/bin/env -S uv run python
+
+from __future__ import annotations
+
+__VERSION__ = "1"
+
+import os
+import sys
+
+import pygit2
+
+from pygittools.hooks import parse_ref_updates
+from pygittools.hooks_notify import PostReceiveNotify
+
+NOTIFY_URL = os.environ.get("PYGITWEB_NOTIFY_URL", "http://127.0.0.1:8000/_internal/notify")
+PROJECT = os.environ.get("PYGITWEB_PROJECT") or os.path.basename(os.getcwd()).removesuffix(".git")
+
+
+def main() -> int:
+	repo = pygit2.Repository(".")
+	updates = parse_ref_updates(sys.stdin)
+	result = PostReceiveNotify(repo, NOTIFY_URL, PROJECT).run(updates)
+	return int(result.value)
+
+
+if __name__ == "__main__":
+	raise SystemExit(main())

pygittools-0.1.0/hook_samples/pre-commit.ruff

@@ -0,0 +1,18 @@
+#!/usr/bin/env -S uv run python
+
+from __future__ import annotations
+
+__VERSION__ = "1"
+
+import pygit2
+from pygittools.hooks_ruff import PreCommitRuff
+
+
+def main() -> int:
+    repo = pygit2.Repository(".")
+    result = PreCommitRuff(repo).run()
+    return int(result.value)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pygittools-0.1.0/hook_samples/pre-receive.protected-pattern

@@ -0,0 +1,37 @@
+#!/usr/bin/env -S uv run python
+
+from __future__ import annotations
+
+__VERSION__ = "1"
+
+import os
+import sys
+
+import pygit2
+
+from pygittools.hooks import HookResult, parse_ref_updates
+from pygittools.hooks_patterns import PreReceiveProtectedPattern
+
+PROTECTED_REF_PATTERN = os.environ.get("PYGITWEB_PROTECTED_REF_PATTERN", r"^refs/heads/(main|master)$")
+COMMIT_MSG_PATTERN = os.environ.get("PYGITWEB_COMMIT_MSG_PATTERN", r"^(\S+): (.+)")
+REJECT_MERGE_COMMITS = os.environ.get("PYGITWEB_REJECT_MERGE_COMMITS", "").lower() in {
+	"1",
+	"true",
+	"yes",
+}
+
+
+def main() -> int:
+	repo = pygit2.Repository(".")
+	updates = parse_ref_updates(sys.stdin)
+	result = PreReceiveProtectedPattern(
+		repo,
+		PROTECTED_REF_PATTERN,
+		COMMIT_MSG_PATTERN,
+		reject_merge_commits=REJECT_MERGE_COMMITS,
+	).run(updates)
+	return int(result.value)
+
+
+if __name__ == "__main__":
+	raise SystemExit(main())

pygittools-0.1.0/hooks.py

@@ -0,0 +1,336 @@
+import sys
+from dataclasses import dataclass
+from enum import Enum
+from typing import IO
+
+import pygit2
+
+
+class HookResult(Enum):
+	SUCCESS = 0
+	FAILURE = 1
+
+
+@dataclass
+class Hook:
+	repo: pygit2.Repository
+
+
+RefUpdate = tuple[str, str, str]
+
+
+def parse_ref_updates(stream: IO[str] | None = None) -> list[RefUpdate]:
+	"""Parse `<old-oid> <new-oid> <ref-name>` lines (one per ref) from a receive-pack hook's stdin."""
+	source: IO[str] = stream if stream is not None else sys.stdin
+	updates: list[RefUpdate] = []
+	for raw in source:
+		parts: list[str] = raw.strip().split(maxsplit=2)
+		if len(parts) == 3:
+			updates.append((parts[0], parts[1], parts[2]))
+	return updates
+
+
+"""
+Pre-Commit Hook (Client-side)
+Runs before a commit is made, before a commit message is written (if not supplied by -m).
+Use this hook to:
+- Check for uncommitted changes
+- Run tests, lints, security checks, etc.
+This can be bypassed with --no-verify by the user.
+"""
+
+
+class PreCommit(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Prepare-Commit-Msg Hook (Client-side)
+Runs right after the default log message is prepared and before the editor is started.
+Use this hook to:
+- Edit the message file in place (e.g. strip template comments)
+- Insert a standard prefix/suffix (e.g. branch name, ticket ID)
+- Add Signed-off-by from a template
+Takes 1–3 parameters: message file path, source (message|template|merge|squash|commit),
+and optionally commit hash for amend.
+"""
+
+
+class PrepareCommitMsg(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(
+		self,
+		message_file: str,
+		source: str = "",
+		commit_hash: str | None = None,
+	) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Commit-Msg Hook (Client-side)
+Runs after the commit message is prepared; can be bypassed with --no-verify.
+Use this hook to:
+- Enforce a project standard format (e.g. conventional commits)
+- Validate or normalize the message in place
+- Reject the commit (e.g. duplicate Signed-off-by, missing ticket reference)
+Takes one parameter: the path to the file holding the proposed commit log message.
+"""
+
+
+class CommitMsg(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, message_file: str) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Post-Commit Hook (Client-side)
+Runs after a commit is made. Cannot affect the outcome of git commit.
+Use this hook to:
+- Notify (e.g. log, webhook, chat)
+- Run post-commit checks or backups
+- Update external metadata or caches
+"""
+
+
+class PostCommit(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Pre-Merge-Commit Hook (Client-side)
+Runs after a merge has been carried out successfully and before the merge commit
+message is finalized; can be bypassed with --no-verify.
+Use this hook to:
+- Validate the merged tree (e.g. run tests on the result)
+- Inspect or adjust the merge commit message
+- Abort the merge commit if checks fail
+Takes no parameters.
+"""
+
+
+class PreMergeCommit(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Pre-Rebase Hook (Client-side)
+Called by git rebase; can be used to prevent a branch from being rebased.
+Use this hook to:
+- Block rebasing certain branches (e.g. main)
+- Run checks before rewriting history
+Takes one or two parameters: upstream ref, and optionally the branch being rebased
+(absent when rebasing the current branch).
+"""
+
+
+class PreRebase(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, upstream: str, branch: str | None = None) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Post-Checkout Hook (Client-side)
+Runs after git checkout, git switch, or git clone (when a worktree is updated).
+Use this hook to:
+- Restore working tree metadata (e.g. permissions, ACLs)
+- Auto-display differences from the previous HEAD
+- Run repository validity checks or refresh generated files
+Takes three parameters: previous HEAD ref, new HEAD ref, and a flag (1 = branch checkout, 0 = file checkout).
+"""
+
+
+class PostCheckout(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, prev_head: str, new_head: str, branch_checkout: str) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Post-Merge Hook (Client-side)
+Runs after a successful git merge (e.g. after git pull). Cannot affect the outcome.
+Use this hook to:
+- Restore working tree metadata in conjunction with pre-commit
+- Run post-merge checks or notifications
+Takes one parameter: a status flag indicating whether the merge was a squash merge.
+"""
+
+
+class PostMerge(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, squash: str) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Pre-Push Hook (Client-side)
+Called by git push; can be used to prevent a push.
+Use this hook to:
+- Run tests or lint before pushing
+- Enforce branch naming or ref permissions
+- Validate commits being pushed
+Takes two parameters: remote name and remote URL. Ref updates are provided on stdin.
+"""
+
+
+class PrePush(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, remote_name: str, remote_url: str) -> HookResult:
+		return HookResult.SUCCESS
+
+
+# -----------------------------------------------------------------------------
+# Server-side hooks (run in $GIT_DIR on receive-pack / push)
+# -----------------------------------------------------------------------------
+
+"""
+Update Hook (Server-side)
+Invoked by git-receive-pack once per ref being updated, before the ref is updated.
+Use this hook to:
+- Enforce fast-forward only (reject non-FF updates)
+- Implement per-ref access control
+- Log or validate old → new for specific refs
+Takes three parameters: ref name, old object name, new object name.
+"""
+
+
+class Update(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, ref_name: str, old_oid: str, new_oid: str) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Post-Update Hook (Server-side)
+Invoked by git-receive-pack once after all refs have been updated.
+Use this hook to:
+- Notify or trigger CI for updated refs
+- Run git update-server-info for dumb transports (e.g. HTTP)
+- Update caches or derived data
+Takes a variable number of parameters: the name of each ref that was updated.
+"""
+
+
+class PostUpdate(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, *ref_names: str) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Push-To-Checkout Hook (Server-side)
+Invoked when a push updates the currently checked-out branch and receive.denyCurrentBranch is updateInstead.
+Use this hook to:
+- Override how the working tree and index are updated to match the new commit
+- Run git read-tree -u -m to emulate a reverse fetch
+- Refuse the push by exiting non-zero (without modifying index or worktree)
+Takes one parameter: the commit object name the tip of the current branch will be updated to.
+"""
+
+
+class PushToCheckout(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, new_commit: str) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Pre-Auto-GC Hook
+Invoked by git gc --auto before automatic garbage collection runs.
+Use this hook to:
+- Prevent or delay gc when the repo is busy (e.g. long-running operations)
+- Run housekeeping or consistency checks before gc
+- Notify or log that auto-gc is about to run
+Takes no parameters. Exiting with non-zero status prevents gc from running.
+"""
+
+
+class PreAutoGc(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Pre-Receive Hook (Server-side)
+Invoked by git-receive-pack once before any refs are updated. Receives ref updates on
+stdin as `<old-oid> <new-oid> <ref-name>` lines (one per ref). Exiting non-zero rejects
+the entire push (no refs are updated).
+Use this hook to:
+- Reject pushes that violate global policy (e.g. force-push to protected refs)
+- Notify a long-poll change queue so subscribers can react quickly
+"""
+
+
+class PreReceive(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, ref_updates: list[RefUpdate]) -> HookResult:
+		return HookResult.SUCCESS
+
+
+"""
+Post-Receive Hook (Server-side)
+Invoked by git-receive-pack once after all refs have been updated. Receives ref updates
+on stdin in the same format as pre-receive. Exit code does not affect the receive.
+Use this hook to:
+- Notify caches / long-poll subscribers (refs are visible at this point)
+- Trigger CI, mirroring, or webhook delivery
+"""
+
+
+class PostReceive(Hook):
+	def __init__(self, repo: pygit2.Repository):
+		super().__init__(repo)
+
+	def run(self, ref_updates: list[RefUpdate]) -> HookResult:
+		return HookResult.SUCCESS
+
+
+# -----------------------------------------------------------------------------
+# Hooks skipped (not implemented in this module)
+# -----------------------------------------------------------------------------
+#
+# E-mail / git-am hooks (skipped by design):
+#   - applypatch-msg   (message file; used by git am)
+#   - pre-applypatch   (no params; used by git am)
+#   - post-applypatch  (no params; used by git am)
+#
+# Other stdin-only / protocol hooks (skipped: pkt-line or transactional state):
+#   - reference-transaction (state string + ref updates on stdin)
+#   - proc-receive        (pkt-line protocol on stdin/stdout)