[OCaml] Mobile-friendly clone of cgit.

View raw

README for ogit

Author
Marius Peter
Date
<2025-05-13 Tue>
Table of Contents

Objective

A lightweight, mobile-friendly alternative to cgit.

Architecture

The executable in bin/main.ml loads configuration and delegates to lib/main.ml. Startup fails visibly when an explicitly selected configuration file is missing or when configuration cannot be parsed or validated.

Requests flow through the following layers:

  1. Routes defines bidirectional, type-safe paths used for both Dream route registration and generated links.
  2. Handlers opens and validates one repository context per request, maps application errors to HTTP statuses, and coordinates data access with rendering.
  3. Resolvers provides repository discovery and Git data access. An opened repository context owns its Git store, resolved metadata, and default-branch policy so operations in one request reuse the same store.
  4. Views renders data supplied by handlers. Views do not access the filesystem or load configuration.
  5. Static_handler serves assets embedded at build time by ocaml-crunch.

Resolver failures retain their category until the HTTP boundary: malformed input becomes 400 Bad Request, missing repositories or Git objects become 404 Not Found, and storage or filesystem failures become 500 Internal Server Error.

View layer

The view layer is split into three levels so that page code stays declarative:

  1. Ui is the only module that names HTML elements. It is generic: it knows nothing about Git or ogit's routes, and every function takes plain strings and already-built nodes. It supplies links, lists, disclosures, breadcrumbs, toolbars, pagination, line-numbered code listings, a diff viewer, and document scaffolding. The class names it emits are its contract with styles.css. Its public surface is fixed by ui.mli, which also carries the module's documentation; attribute plumbing stays private, so callers compose blocks rather than assembling attributes.
  2. Components names ogit's page parts — navigation bars, repository rows, tree rows, commit-type badges — and wires them to Routes, so URLs are never written by hand. Layout composes the page shell.
  3. Root and Repo describe pages: they say which parts a page is made of and hand them to Layout. Neither contains markup.

Supporting logic lives beside them rather than inside the page descriptions: Syntax guesses a blob's language for highlighting, and Time_fmt formats Git dates. Charts generates standalone SVG.

Documentation

API documentation is generated with odoc:

dune build @doc

The entry point is _build/default/_doc/_html/index.html. scripts/docs.sh runs the same build and opens that file in a browser; scripts/docs.sh --print prints the path instead.

The landing page at doc/index.mld orders the modules by the request flow described above. doc/conventions.mld records where documentation is expected to live.

Unresolved type links pointing into Dream, Toml, Git or dream-html are expected: those packages' own documentation is not built here.

Configuration

Ogit reads the path named by OGIT_CONFIG. Otherwise it checks $XDG_CONFIG_HOME/ogit/config.toml and finally /etc/ogit/config.toml. When no explicit OGIT_CONFIG is selected, a missing file uses environment-derived defaults; malformed or invalid files never silently fall back.

See config.toml at the project root for a reference of all available variables with their defaults and documentation.

The commits_max_displayed value controls commit list lengths on all-commit and branch pages. default_branch is tried after HEAD and before the conventional main and master fallbacks.

Deployment

Repository layout

Git repositories are expected under /srv/git (the default git_project_root), owned by a dedicated git user:

/srv/git/           git:git  750
/srv/git/repo.git/  git:git  750

The ogit service runs as a separate user (e.g. ogit) with group git for read access. This allows ProtectHomeyes= in systemd hardening.

SSH push access

Push access uses the git user over SSH. Place authorized public keys in /srv/git/.ssh/authorized_keys. Set the git user's shell to /usr/bin/git-shell to restrict interactive login.

systemd

A sample unit file is provided in deploy/ogit.service.

Alternatives