---
id: BB-SPEC-BWAY3QWL
type: spec
title: Luigit public Git web interface
research:
  - BB-RESEARCH-C4LYIYLA
  - BB-RESEARCH-_H2TE28K
  - BB-RESEARCH-BWD1AIED
  - BB-RESEARCH-ZQOAYUPA
  - BB-RESEARCH-RMUENXZX
  - BB-RESEARCH-F1ZMINXT
  - BB-RESEARCH-4W1UKHAD
  - BB-RESEARCH-4JDRXJS3
  - BB-RESEARCH-IPXDXOUR
---

# Luigit public Git web interface

## Intent

Provide a fast, read-only Git web interface at `vcs.bugabinga.net`.
Luigit stays smaller than a forge while exposing powerful Git concepts clearly.
It has no accounts, mutation, or social model beyond valid `mailto:` author links.

## Public boundary

Luigit is public and unauthenticated.
It exposes only publicly advertised refs and objects reachable from them.
A public note does not make an otherwise unreachable target public.

Bare repositories are authoritative for Git content and state.
A current versioned public manifest supplies only repository name, owner, description, public visibility, and discovery state.
Luigit receives no Soft Serve database, configuration, credentials, or host keys.

Publication requires an unexpired public manifest entry, `git-daemon-export-ok`, and the repository at its declared canonical path.
Hidden public repositories are omitted from catalog and search but remain directly addressable through the same authorization checks.
Transport settings such as anonymous access do not authorize Luigit publication.
Conflicting or unknown metadata fails closed and visibly; an unsupported manifest shape fails readiness.

## Repository discovery

The site landing prioritizes global search, then a compact repository list with description, owner, default branch, and last activity.
Empty public repositories remain visible with metadata, SSH clone guidance, and an explicit empty state.

Repository pages prioritize the rendered README.
A context rail contains clone and current-state information on wide screens.
Narrow screens become one reading flow: README, context, then source.

[Accepted repository landing](assets/repository-landing.html)

## Git browsing

Luigit provides:

- Repository log, refs, commits, diffs, trees, files, raw content, feeds, patches, and archives.
- Navigation by advertised branch, tag, or reachable commit.
- Publicly advertised branches, tags, and notes refs.
- Path history with rename following only where the selected Git capability provides it.
- Full history plus a secondary first-parent view.
- Annotated-tag views with message, tagger, signature, notes, target, and archives.
- Lightweight tags as named object references.
- Stable commit-based links for files, diffs, and selected line ranges while their objects remain publicly reachable.
- SHA-1 and SHA-256 object formats without fixed-length object-ID assumptions.

Core browsing works without JavaScript.
JavaScript may progressively enhance search, copying, preferences, large diffs, and interactive visualizations.

## Source rendering

Syntax highlighting is mandatory and preserves exact source text.
Source, diff, and object-ID text disables discretionary ligatures.
Unknown or unsupported text remains readable without highlighting.

README files render as documents.
Other Markdown files offer rendered preview without replacing source.
Markdown allows a sanitized structural HTML subset, including useful elements such as `details`, `summary`, `kbd`, `sub`, `sup`, and `abbr`.
Scripts, event handlers, forms, iframes, styles, inline SVG, unsafe attributes, and unsafe URL protocols are removed.

Repository-local raster images render inline.
Remote images load directly in the visitor's browser without server proxying.
Other non-text content exposes metadata and raw download.

## Future rich documents

V1 renders D2, DOT, Mermaid, and TeX as source and exposes SVG as source plus download only.
Later previews remain optional enhancements over exact escaped source.

Every format requires structural admission, finite work and output limits, stoppable execution, final output validation, and explicit failure states.
Diagram output is self-contained and presented as an image, never inserted into the document DOM.
Repository SVG is never inline or exposed through `object` or `embed`.
TeX support means bounded mathematical notation with semantic output, never general TeX execution, packages, file access, or shell escape.

## History and comparison

History is primarily an ordered commit list with a narrow contextual topology gutter.
It defaults to one selected ref and adds side history only on request.
Commit metadata and navigation never depend on hover.
Narrow screens retain ordered rows, parent count, merge state, and ancestry summaries rather than compressing a desktop graph.

Comparing a branch to the default branch uses its merge base by default, answering what the branch introduces.
Comparing two explicit commits uses their exact snapshots by default.
Either comparison mode remains selectable.

Branch listings show ahead, behind, or diverged state relative to the default branch.
Comparisons expose commits, changed files, statistics, and rendered diffs.
Merge commits default to their first-parent diff and permit selecting each parent.
Combined merge diff remains research-dependent.

Luigit owns diff presentation, escaping, navigation, highlighting, and responsiveness.
Unified and side-by-side views are required, with unified as the default and a local preference.
Semantic diff may enhance supported languages only through a vetted, maintained general-purpose library.
Unsupported or failed semantic analysis always falls back to ordinary textual diff.
Luigit owns no per-language semantic parsers.
Repository-configured external diff commands and text converters never execute.

Large comparisons expose a complete file summary before file bodies and always retain complete patch download.
Each file has an explicit ready, collapsed, filtered, binary, oversized, truncated, timed-out, or unavailable state where applicable.
Files render independently with stable file, hunk, and line links plus previous and next navigation.
No-JavaScript navigation can request one bounded file or hunk at a time.

The canonical result is a complete escaped textual diff within admitted limits.
Unified and side-by-side views share the same Git and line-change facts.
Intraline, highlighting, structural, and interactive layers may disappear under failure or budget without removing canonical content.
Cancellation reaches queued or active cooperative work; no request creates unbounded work, queues, allocations, output, or cache entries.
Omissions and skipped rename or enhancement work are explicit and never presented as complete.

Blame is a secondary, opt-in file view rather than primary navigation.

## Git Notes

Luigit discovers publicly advertised notes refs and displays exact namespace names in deterministic groups.
It assigns no hidden semantics from namespace names.
Notes receive a dedicated repository explorer and appear contextually on their target objects.

Commit, tag, tree, and blob targets are supported.
Blob notes may appear at multiple paths or revisions because blobs are content-addressed.
Unreachable targets remain unavailable even when their notes are public.

Valid UTF-8 note content renders as sanitized Markdown by default with plain and raw views.
Non-text content remains downloadable.
Full or uniquely resolvable abbreviated object IDs in note text become links; other references are not guessed.

Each note exposes its current content, target context, namespace, revision history, version diffs, and notes-ref update identity.
Notes-ref merge commits expose parent versions and resolved content without inventing conflict rationale.
Current note content is searchable.
Historical note search is an explicit scope rather than the default.
Each notes namespace has a separate Atom feed.

The notes explorer uses exact namespace navigation, contextual targets, Markdown content, version links, and semantic signature indicators.
Explanatory filler and redundant labels are forbidden.

[Accepted notes explorer](assets/notes-explorer.html)

## Signatures

Luigit recognizes SSH, OpenPGP, and S/MIME signatures on commits, annotated tags, and notes-ref history.
It distinguishes unsigned, valid, invalid, and unverifiable signatures and shows format plus signer details.
Status uses semantic icon, form, text, and color rather than color alone.

Luigit claims verified identity only when an authoritative source binds the signing key to that identity.
Soft Serve authentication-key registration is not an identity verification authority and provides no v1 signer enrichment.

## Submodules

Submodule entries show path, declared URL, and pinned commit.
Locally known public repositories link to the exact reachable commit.
External repositories are never fetched.
Unresolved, inaccessible, or missing targets remain explicit.

Official GitHub, GitLab.com, Codeberg, SourceHut, and Bitbucket Cloud URLs may receive deterministic repository, commit, tree, and comparison links.
Unknown and self-hosted providers fall back to the declared URL.
Provider enrichment performs no API requests or availability claims.

SSH clone guidance is tailored to the deployment and easy to copy.
Repositories containing submodules also offer clearly labeled recursive clone guidance.
Source archives contain the selected repository tree and gitlinks, never fetched submodule content.

## Search

Search covers repositories, paths, selected-snapshot content, commit messages, refs, and current notes.
Scope follows context: all repositories from the catalog, current repository within a repository, and current revision while browsing source.
Users can widen or narrow scope explicitly.

Plain text is case-insensitive literal search.
Optional qualifiers include repository, path, ref, author, and result type.
Explicit regular-expression syntax is supported within bounded work and result limits.
Search syntax help stays unobtrusive but immediately accessible.

Broad source search covers advertised branch and tag snapshots, not every historical commit.
Commit-message history remains searchable.
The index proposes candidates but never authorizes disclosure; every result is verified against current public content before output.

Results arrive progressively without blocking navigation and identify indexed coverage, stale scopes, partial results, and exhausted budgets.
A changed scope disappears immediately and returns only after its exact current snapshot is indexed.
Unchanged scopes and direct browsing remain available during indexing, rebuilding, corruption recovery, or low-storage degradation.

## Visual understanding

Every visualization answers a named user question and remains contextual rather than forming a dashboard.
Visuals are exceptionally clear, keyboard accessible, and paired with inspectable text.
Color never carries meaning alone.

Commit topology attaches branch tips, tags, signature state, and note presence to commit rows.
Branch comparison exposes base, head, merge base, ahead and behind counts, unique commits, changed-file summary, and selected comparison semantics before the full diff.

Repository hotspots begin as a ranked, sortable most-changed-paths view.
Every aggregate identifies metric, selected ref, time range, and path scope, then links back to files and commits.
Contributor activity means commit authors touching a path, applies `.mailmap` when present, and is never labeled ownership.
Submodule relationships show local and external repositories, pinned commits, and unresolved states without inferring dependencies.

Commit and comparison summaries use the adopted mirrored per-file skyline.
Exact textual totals remain authoritative.
The skyline bounds width through deterministic grouping and distinguishes exact text, binary old/new byte units, and labeled oversized-text estimates by form as well as color.
Partial or unavailable inputs remain explicit.

## Presentation

Luigit uses deploy-time light and dark semantic theme data.
The deployment supplies generated Nugu palettes for both UI and syntax highlighting.
System theme is the default; visitors may choose a discreet local override.

Fonts are self-hosted with no CDN dependency.
IBM Plex Sans serves UI and prose; IBM Plex Mono serves source, diffs, object IDs, refs, blame, code blocks, and literal graph labels.
Pinned unmodified static WOFF2 files come from one inspected release with license, source, size, and digest provenance.
Luigit uses no remote CSS, `local()` source, JavaScript font loading, synthesized faces, or optional ligatures in literal text.

Typography gates test legibility, reflow, alignment, fallback, zoom, light and dark palettes, and blocked fonts on native Linux, Windows, and macOS browser engines.
Cross-platform acceptance concerns task invariants, not pixel equality.

The interface is English-only.
It is responsive, mobile-ready, fully keyboard accessible, and gracefully functional without progressive enhancements.
Screen-reader behavior is best effort, not a formal conformance target.

## Performance and derived state

Ordinary warm page generation targets p95 below 100 milliseconds on the recorded benchmark environment.
Warm search targets first results at p95 below 250 milliseconds.
Navigation never waits for background maintenance.
Pushed content becomes visible automatically within seconds; any stale or incomplete view identifies its state.

Search indexes and caches are derived and disposable.
Deleting them costs rebuild time only.
Deployment sets finite memory, byte, inode, concurrency, and temporary-space budgets.
Cache admission and eviction account for owned bytes and recomputation cost, not entry count alone.
Every cached result is reauthorized before disclosure.

Unreachable index data is pruned, regenerable cache data is evicted, and usage plus reclamation failures are observable.
High storage pressure stops optional admission and expensive maintenance before browsing.
Critical pressure stops index writes and compaction while safely authorized completed search coverage and direct browsing continue with a degraded state.
Luigit never performs Git garbage collection or mutates authoritative repositories.

Browsing continues while indexes rebuild.
A previous valid and currently authorized index remains usable when available; first-build results report incomplete coverage.
Recurring reconciliation, indexing, integrity, and derived-state reclamation are resource-bounded, non-overlapping, and throttled under interactive load.

## Runtime constraints

Luigit deploys as one application executable in one rootless container under the ordinary klops service user.
It has no runtime helper executables and no outbound network requirement.
Bare repositories and hosting metadata are strictly read-only.
Only bounded derived storage is writable.
Caddy is the sole public HTTP boundary through the existing reverse-proxy network; Luigit publishes no host port.

Dependencies and internal boundaries must preserve dual object-format support, exact Git facts, bounded work, truthful fallback, one-executable packaging, and complete license provenance.
Maintained embeddable libraries are preferred when correctness and capability are comparable.
Repository-controlled executable behavior is forbidden.

Operational diagnostics use structured logs and health/readiness state, not a public administration UI.
Invalid deployment configuration or visibility ambiguity fails readiness.
A corrupt repository or object fails only its repository or request.
Public failures never expose internal paths or stack traces.

## Public route

Luigit is the sole Git web frontend at `https://vcs.bugabinga.net`.
Stagit and Legit services are absent.
Brief planned downtime is acceptable; no rollback system or legacy Git-web URL compatibility is required.

## Explicit exclusions

V1 excludes:

- Authentication and private repositories.
- Web mutation, issues, discussions, pull requests, profiles, and reactions.
- CI and package integration.
- Git LFS object resolution.
- General language-semantic code analysis.
- Runtime plugins and a stable general JSON API.
- Localization.
- External repository fetching.
- Git HTTPS cloning.
- D2, DOT, Mermaid, SVG, and TeX rendering.

Narrow internal endpoints required by progressive enhancement do not constitute a supported public API.
CI, package, advanced document rendering, and general API integration remain possible later work.

## Acceptance

- A representative fixture suite covers SHA-1 and SHA-256 repositories, empty repositories, merges, tags, hidden refs, unreachable objects, all note target types, note history, all signature states, supported submodule providers, unsafe Markdown, and large diffs.
- Manifest expiry, unknown versions, missing export markers, hidden discovery state, and conflicting metadata fail according to the public boundary without exposing Soft Serve secrets.
- Public visibility and object reachability tests prove hidden refs or removed content cannot render through direct IDs, notes, search, caches, feeds, archives, or derivatives.
- Search tests cover context, qualifiers, regular expressions, notes, branch and tag snapshots, authorization before output, changed-scope suppression, progressive indexing, low-storage degradation, and bounded work.
- Diff tests cover comparison modes, merge parents, summary-first delivery, unified and split rendering, binary and oversized content, explicit file states, cancellation, safe fallback, and complete patch access.
- Visual fixtures verify topology landmarks, comparison state, hotspot and contribution labels, submodule evidence, and authoritative textual equivalents.
- Skyline fixtures cover exact text, binary units, oversized estimates, deterministic grouping, unavailable data, light and dark palettes, and narrow screens.
- Native Linux, Windows, and macOS browser verification covers IBM Plex loading and fallback, light and dark palettes, local override, keyboard navigation, no-JavaScript browsing, zoom, reflow, responsive layouts, and accepted visual hierarchy.
- Performance measurements use a recorded corpus and environment and satisfy the warm p95 targets under admitted concurrency and storage pressure.
- Container verification proves one executable, read-only authoritative inputs, bounded writable derived state, no direct host port, and no required outbound access.
- Public Git web traffic reaches Luigit; Stagit and Legit services are absent.