1<h1 align="center">legit</h1>
  2
  3<p align="center">
  4    <strong>A git web frontend written in Go.</strong>
  5    <br>
  6    Pronounced however you like; I prefer channeling my inner beret-wearing
  7    Frenchman, and saying <em>"Oui, il est le git!"</em>
  8</p>
  9
 10![Screenshot](/assets/screenshot.png)
 11
 12![Codeberg Release](https://img.shields.io/gitea/v/release/maxwelljensen/legit?gitea_url=https%3A%2F%2Fcodeberg.org&style=for-the-badge)
 13![Codeberg License](assets/eupl-12-badge.svg)
 14
 15---
 16
 17## What is legit?
 18
 19`legit` is a self-hosted git repository browser for the web. Point it at a
 20directory full of repos and it'll give you a clean, modern web interface for
 21browsing files, viewing commits, exploring branches and tags, and cloning over
 22HTTPS.
 23
 24It's not CGI. It's not Gitea. It's just a single binary that serves your repos.
 25
 26## Quick start
 27
 28```bash
 29# Build
 30go build -o legit
 31
 32# Run
 33./legit --config ./config.yaml
 34```
 35
 36You'll need a `config.yaml` (see below) and at least one bare git repo in your
 37`scanPath`.
 38
 39## Features
 40
 41|   |                    |
 42|---|--------------------|
 43| 🖥️ | Browse repos, files, trees, and commits |
 44| 🌲 | File tree view with mode and size |
 45| 📜 | Commit log with full diff output |
 46| 🏷️ | Tag and branch listing |
 47| 📦 | Archive downloads (tar.gz) |
 48| 🎨 | Syntax highlighting (chroma) |
 49| 🪨 | Markdown readme rendering |
 50| 🔗 | Cloning over HTTPS (smart HTTP protocol) |
 51| 📄 | Templated HTML (fully customisable) |
 52| 🌙 | Dark mode (CSS media query) |
 53
 54## How do I configure legit?
 55
 56Configuration is via `config.yaml`. By default it looks in the current
 57directory; use `--config <path>` to point elsewhere.
 58
 59```yaml
 60repo:
 61  scanPath: /var/www/git
 62  readme:
 63    - README.md
 64    - README
 65  mainBranch:
 66    - master
 67  ignore:
 68    - foo
 69  unlisted:
 70    - private-repo
 71dirs:
 72  templates: ./templates
 73  static: ./static
 74meta:
 75  favicon: favicon.svg
 76  title: git good
 77  description: come get your free software
 78  syntaxHighlight: monokailight
 79server:
 80  name: git.example.com
 81  host: 127.0.0.1
 82  port: 5555
 83```
 84
 85| Field | Description |
 86|-------|-------------|
 87| `repo.scanPath` | Directory containing repos (flat — subdirectories are not traversed) |
 88| `repo.readme` | Readme filenames to look for (first match wins) |
 89| `repo.mainBranch` | Branch names to try as default branch |
 90| `repo.ignore` | Repos to exclude entirely (returns 404) |
 91| `repo.unlisted` | Repos to hide from the index (still accessible by URL) |
 92| `dirs.templates` | Path to custom Go html/template files |
 93| `dirs.static` | Path to custom static assets (CSS, images) |
 94| `meta.syntaxHighlight` | [Chroma style](https://swapoff.org/chroma/playground/) for syntax highlighting; empty = no highlighting |
 95| `server.name` | Used for `go-import` meta tags and clone URLs |
 96
 97## What about cloning?
 98
 99Cloning works over HTTPS via git's smart HTTP protocol.
100
101```
102git clone https://git.example.com/my-repo
103```
104
105**Things to know:**
106- Cloning only works with **bare repos** (a limitation of git itself, non-bare
107  repos still display fine in the web UI).
108- Pushing over HTTPS is deliberately **disabled**. Use SSH.
109- Run legit behind a TLS-terminating proxy (nginx, relayd, etc.).
110
111## How does one host it?
112
113```bash
114# Docker
115docker run -p 5555:5555 \
116  -v /var/www/git:/var/www/git \
117  ghcr.io/icyphox/legit:latest
118
119# systemd (see contrib/legit.service)
120systemctl enable --now legit
121```
122
123Pre-built Docker images are available at
124`ghcr.io/icyphox/legit:{master,latest,vX.Y.Z}`.
125
126## Building
127
128```bash
129go build -o legit
130```
131
132No external dependencies beyond the Go toolchain. A Nix flake is also available
133for reproducible builds (`nix build`).
134
135## How does it work?
136
137```
138HTTP request
139      ↓
140 ┌────────────┐
141 │  main.go   │  Parse config, unveil(2) on OpenBSD
142 └────────────┘
143      ↓
144 ┌────────────┐
145 │   routes   │  Route requests: web UI or git smart protocol
146 │ handler.go │
147 └────────────┘
148      ↓
149 ┌────────────┐
150 │    git/    │  Read repos via go-git, exec git-upload-pack
151 └────────────┘
152      ↓
153 ┌────────────┐
154 │ templates  │  Render HTML via Go html/template
155 └────────────┘
156```
157
158The `/{name}` endpoint is a **multiplexer**: it detects git HTTP protocol
159requests (`info/refs?service=git-upload-pack`, `git-upload-pack` POST) and
160routes them to the git backend, or renders the web UI otherwise.
161
162## Licence
163
164Original code (c) Anirudh Oppiliappan under MIT Licence.
165
166Modifications (c) Maxwell Jensen under [European Union Public Licence
1671.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12).
168
169See `LICENCE.txt` for details.