Pygitweb

Gitweb reimplementation using Python, FastAPI, and Pygit2, ported from git/gitweb/gitweb.perl.

Config

Settings load from ~/.pygitweb/settings.json (or PYGITWEB_SETTINGS_CONFIG), PYGITWEB_* environment variables, and optionally a .env file in the working directory via pydantic-settings. See src/pygitweb/config.py and settings.schema.json for the full schema. Common ones:

• PYGITWEB_PROJECTROOT — absolute path to directory containing git repositories (default: $HOME)
• PYGITWEB_PROJECTS_LIST — directory to scan, or path to a project-list file (default: PROJECTROOT)
• PYGITWEB_EXPORT_OK — filename that must exist to allow export (e.g. git-daemon-export-ok); empty = no check
• PYGITWEB_SITE_NAME — site name in titles (default: PyGitWeb)
• PYGITWEB_GIT — path to the git executable (default: git)
• PYGITWEB_AUTH — 0 / false / off disables auth; 1 / true / on enables it. If unset or empty, auth defaults to on.
• PYGITWEB_AUTH_CONFIG — path to the auth JSON file (default: ~/.pygitweb/auth.json). Generated to a reasonable default if not present.
• PYGITWEB_SETTINGS_CONFIG — path to the settings JSON file (default: ~/.pygitweb/settings.json). Created from the environment on first run if missing.
• PYGITWEB_ENABLED_PLUGINS — installed plugins to load. The settings page can change this list and reload plugins immediately (POST /settings/pygitweb/plugins).
• PYGITWEB_API_KEY_MAX_COUNT — maximum Smart HTTP API keys each local user may hold (default: 2).
• PYGITWEB_API_KEY_EXPIRY_DAYS — lifetime of a newly issued API key, in days. 0 means the key does not expire (the default).
• Browser login: GET /login (optional ?next=/path), POST /login with form fields username, password, next; sets an HttpOnly cookie with an opaque in-process session id (also accepted by protected routes via Authorization: Bearer). Sessions are wiped when the process exits. GET /logout?next=/ revokes the session and clears the cookie.
• Account and Smart HTTP keys (auth required): GET /user is the account page. POST /user/keys with JSON {"id": "...", "readonly": false} issues a key and returns the plaintext secret once; only its scrypt hash is stored. readonly: true allows fetch but not push. DELETE /user/keys?id=<id> revokes one key. Clone and push attempts are appended to ~/.pygitweb/smart_http.log.

Routes

Load the /docs page for a detailed view of routes (below the readme).

No-project routes

• GET /: project list
• GET /index: plain text project index (path, owner)
• GET /opml: OPML feed list
• GET /project/{name}: Project dispatch (See actions table)

Hook management routes

• GET /project/{name}/hooks: JSON {hooks: [...samples...], bundles: [...]} with current status (installed, not_installed, different) for every pygittools sample and bundle
• POST /project/{name}/hook?name=<sample-or-bundle>&op=<add|remove|check>: install, remove, or check one sample or bundle. name may be a sample filename (e.g. post-receive.notify) or a bundle name (e.g. update, which expands to post-commit.notify + post-receive.notify). add/remove refuse to clobber a custom hook with different content (returns 409)

Actions

Blog, boards, and tasks

• GET /project/{project}/blog/: markdown blog page when articles/manifest.json exists at HEAD. Otherwise the summary link stays disabled.
• GET /project/{project}/blog/raw/{path}: raw blob from HEAD for the blog viewer (markdown, manifest, and assets). Paths that escape the tree return 404.
• POST /tasks/move?project=<name>&board=<source>&task=<ref>&target=<board>: move a task onto another board, such as a sprint board. Column headers on the board page show a running points total. points on create and update accepts 0, 1, 2, 3, 5, 8, 13, or 21; any other value is stored as unestimated.
• POST /tasks/archive?project=<name>&board=<source>&task=<ref>: move a task to the archive board.
• POST /tasks/delete?project=<name>&board=<source>&task=<ref>: delete a task.

Query parameter short names (CGI mapping)

• p → project
• a → action
• f → file_name
• fp → file_parent
• h → hash
• hp → hash_parent
• hb → hash_base
• hpb → hash_parent_base
• pg → page
• o → order
• s → searchtext
• st → searchtype
• sf → snapshot_format
• opt → extra_options
• sr → search_use_regexp
• by_tag → ctag
• ds → diff_style
• pf → project_filter
• updates → long-poll subscription flag (true parks the request up to 30s; returns 200 OK with an empty body on timeout/shutdown, or the action data when the queue is notified)

Live updates (long polling)

Supported actions (history, log, shortlog, heads, tags) accept updates=true to subscribe to the project's change queue. The request is held for up to 30 seconds:

• A POST /_internal/notify?project=<name> (typically from a server-side git hook) wakes matching subscribers, who then receive the freshly-rendered action response.
• If no notification arrives in 30 seconds (or the server is shutting down), the response is 200 OK with an empty body.
• Combine with pf=<prefix> to subscribe to every project under a path prefix instead of just the URL project (the action is still rendered for the URL project).

The notify endpoint is intended for loopback use by pygittools post-receive hooks (see pygittools/hook_samples/post-receive.notify). The server enforces loopback-only access and rejects unknown projects; production deployments should still restrict it at the reverse proxy.

Hook management

The project summary page exposes a Hooks row that lists installed hooks and lets you install or remove pygittools samples, including the update bundle: post-receive.notify (feeds the change queue when refs are pushed) and post-commit.notify (feeds the change queue when a working clone of this repo records a local commit). Either is sufficient to wake long-poll subscribers; installing both covers server-side and client-side commit paths.

The same operations are available programmatically via POST /project/{name}/hook?name=<sample-or-bundle>&op=<...>. Bundle status is INSTALLED only when every member is installed, DIFFERENT if any member's path holds a custom hook (the bundle then refuses to install or remove anything to preserve the custom hook), otherwise NOT_INSTALLED. When PYGITWEB_AUTH is enabled, add and remove require a valid access token (Authorization: Bearer … from POST /token, or the cookie from POST /login); check is always allowed.