main / README.md
2.6 KB · Markdown Raw
1# gitgud
2
3A small, self-hosted GitHub clone written in Go. It serves real git repositories over
4HTTP (clone / push / pull) and provides a web UI for browsing code, opening issues, and
5reviewing and merging pull requests.
6
7## Features
8
9- User registration, login, and session auth
10- Public and private repositories (private repos are invisible to others — 404, not 403)
11- Real git over HTTP via `git http-backend` (clone, push, pull) with HTTP Basic auth
12- Code browsing: file tree, syntax-highlighted files, rendered README, branch switcher,
13 commit log, and commit diffs (powered by go-git)
14- Issues: per-repo numbering, comments, open/close, markdown bodies
15- Pull requests: compare two branches, view the diff and commits, comment, and merge
16- Flash messages, friendly 404/403/500 pages, and CSRF-protected forms
17
18## Run locally
19
20Requirements: **Go 1.25+** and the **`git`** binary on your `PATH`.
21
22```bash
23go run ./cmd/server # serves http://localhost:8080
24# data (SQLite db + bare repos) lands in ./data
25```
26
27Configuration is read from the environment (a local `.env` file is loaded automatically):
28
29| Variable | Example | Purpose |
30| -------------------- | ----------------- | --------------------------------------- |
31| `GITGUD_ADDR` | `:8080` | Listen address |
32| `GITGUD_DATA_DIR` | `./data` | Where the database and repos are stored |
33| `GITGUD_SESSION_KEY` | `a-random-secret` | Session secret (use a random value) |
34| `GITGUD_BASE_URL` | `https://gitgud.ikuro.dev` | External URL used in the clone instructions shown in the UI (defaults to `http://localhost:8080`) |
35
36Then register a user, create a repository, and follow the on-screen clone instructions:
37
38```bash
39git clone http://localhost:8080/<you>/<repo>.git
40cd <repo>
41echo "# <repo>" > README.md
42git add README.md && git commit -m "first commit"
43git push -u origin main # prompts for your gitgud username/password
44```
45
46## How it works
47
48gitgud has two git surfaces — a smart-HTTP server (`git http-backend` via CGI) for
49clone/push/pull, and a go-git reader for the web browsing UI — sitting on top of a clean,
50layered architecture (domain / application / interface / infrastructure). See
51[docs/00-overview.md](docs/00-overview.md) for the full design, and the numbered files in
52[docs/](docs/) for how each milestone was built.
53
54## Known limitations (v1)
55
56- Git over HTTP only (no SSH)
57- Pull requests are between two branches of the **same** repo (no forks)
58- Single-node; SQLite storage; bare repos on the local filesystem