Skip to content

Twig

Twig is a self-hosted Git server with a web interface for browsing and managing repositories. It is a single Rust/Actix-web application backed by a local SQLite database (bundled rusqlite) and Git's smart-HTTP backend.

Features

  • Public namespace and repository browsing, with search, Markdown rendering, Mermaid diagrams, file browsing, commit history, license display, optional slide presentations, and an optional long-form Paper reader configured in .twig.toml.
  • A configurable Scripts tab: group repository scripts in .twig.toml and readers run them with one copied curl … | bash command.
  • Git clone/fetch over HTTP; pushes use HTTP Basic Auth. Repositories can be made private in .twig.toml.
  • Account signup by one-time invite, session-based web login, owned namespaces, and repository creation from the UI or Git push.
  • Settings for updating email, moving repositories between your namespaces, and deleting repositories/namespaces.
  • Optional endpoint test runner (TEST_USER) and read-only database browser (ADMIN_USER).
  • API endpoint for the application version (GET /api/version).

Quick start

Run locally with mise:

mise run run

The development configuration sets PROJECT_ROOT=tests/git/srv, RESET_DB=true, BIND_ADDRESS=127.0.0.1, PORT=8080, and TEST_USER=admin. With RESET_DB=true, Twig resets its local database and seeds an admin / admin account for local browsing. This mode is rejected on port 80, on non-loopback binds, and in release builds. Do not use it for persistent data.

The container listens on port 80. Persist both the Git root and database file when deploying, and set SESSION_KEY to a stable secret so browser sessions survive restarts. For example:

docker run --rm -p 8080:80 \
  -e PROJECT_ROOT=/data/git \
  -e DB_PATH=/data/twig.db \
  -e SESSION_KEY='replace-with-a-long-random-secret' \
  -e API_KEY='replace-with-a-secret' \
  -v twig-data:/data \
  silenloc/twig

See Environment Variables for the complete configuration reference.

Documentation

DocumentDescription
APIApplication version endpoint
Git BackendClone, fetch, push, authentication, and repository creation
Web UIPages, account access, settings, and optional admin tools
Pull RequestsRequests, reviews, merges, and the Forgejo-compatible API used by T3 Code and fj/tea
CIRunning .twig/mise.toml's ci task on pushes, and the Actions routes fj uses
Environment VariablesRuntime configuration

These Markdown files are also embedded in the application and shown under Docs at /_info, where each page can be copied as Markdown.

Authentication overview

ActionAuthentication
Browse public namespaces/repositoriesNone
Read a private repositoryHTTP Basic Auth for Git; web login for the UI
Generate a signup inviteAPI_KEY entered on the invite page
Sign upUnused one-time invite
Create namespace/repository in the UIWeb session; repository creation also requires an email on the account
Push over Git HTTPHTTP Basic Auth and access to the namespace
Read database tablesLogged-in user named by ADMIN_USER
Use the endpoint test pageLogged-in user named by TEST_USER, or a valid session PIN

Git reads are public for public repositories. An authenticated push can create a missing namespace and repository; the new namespace belongs to the pushing user. Namespaces and repositories created in the web UI belong to the logged-in user.