1# bbgit
2
3A Git web interface written in Go.
4
5## Features
6
7- **Repository Management**: Supports multiple repositories grouped by category in `config.yaml`.
8- **Browsing**: Navigate commit history, directory files, and file contents.
9- **Syntax Highlighting**: Automatic language detection and highlighting via [Chroma](https://github.com/alecthomas/chroma).
10- **Markdown Rendering**: Renders README files with GFM support and GitHub-style alerts via [Goldmark](https://github.com/yuin/goldmark).
11- **Language Statistics**: Visual breakdown of programming languages used in each repository.
12- **Marker Scanning**: Scans for `TODO:` and `FIXME:` comments across repository source files.
13- **Diffs & Patches**: Side-by-side diff view for commits and raw patch export.
14- **Archives**: Download repository snapshots as `.tar.gz`.
15- **RSS Feeds**: Commit history and tag updates delivered via standard RSS feeds.
16- **Caching**: Persistent caching of commit statistics and repository metadata to improve performance.
17
18## Getting Started
19
201. **Configure**: Define your repositories in `config.yaml`:
21 ```yaml
22 repositories:
23 - name: "my-project"
24 path: "/path/to/repo"
25 description: "Project description"
26 group: "Category"
27 ```
282. **Run**:
29 ```bash
30 go run .
31 ```
323. **Access**: Open http://localhost:8080
33
34## Configuration
35
36The `config.yaml` file defines the repositories served by `bbgit`:
37
38| Field | Description |
39|-------|-------------|
40| `name` | Unique identifier used in the URL (`/r/{name}`). |
41| `path` | Absolute path to the local Git repository. |
42| `description` | Short text displayed on the repository index. |
43| `group` | Category name used to group repositories on the home page. |
44
45## Deployment (systemd)
46
471. Copy the service file:
48 ```bash
49 sudo cp bbgit.service /etc/systemd/system/
50 ```
512. Edit `/etc/systemd/system/bbgit.service` to set the correct `User`, `Group`, `WorkingDirectory`, and `ExecStart` paths.
523. Reload and start:
53 ```bash
54 sudo systemctl daemon-reload
55 sudo systemctl enable --now bbgit
56 ```
57
58## Reverse Proxy (Nginx)
59
60To serve `bbgit` behind Nginx, add the following to your server block:
61
62```nginx
63location / {
64 proxy_pass http://127.0.0.1:8080;
65 proxy_set_header X-Real-IP $remote_addr;
66 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
67 proxy_set_header X-Forwarded-Proto $scheme;
68}
69```
70
71## Technical Details
72
73- **Language**: Go 1.22+
74- **No external JS**: Server-side rendered using Go templates.
75- **Metadata Cache**: Stored in `bbgit.cache`. Persistent data is saved on `SIGINT` or `SIGTERM`.
76- **Build**: Compile a static binary with `go build -o bbgit .`.
77
78## Routing Table
79
80| Endpoint | Description |
81|----------|-------------|
82| `/` | Home page with grouped repository list. |
83| `/r/{name}` | Commit history (log) for the repository. |
84| `/r/{name}/files/{path}` | Directory file browser. |
85| `/r/{name}/blob/{path}` | File viewer with syntax highlighting. |
86| `/r/{name}/raw/{path}` | Raw file download. |
87| `/r/{name}/markers` | Results of the `TODO:` and `FIXME:` scanner. |
88| `/r/{name}/commits.rss` | RSS feed for commit history (supports `?ref=`). |
89| `/r/{name}/tags.rss` | RSS feed for repository tags. |
90| `/r/{name}/archive/{path}` | Snapshot download in `.tar.gz` format. |
91| `/r/{name}/c/{hash}` | Commit detail view with side-by-side diff. |
92| `/r/{name}/c/{hash}/patch` | Raw patch file for the commit. |
93
94## Libraries
95
96- [go-git](https://github.com/go-git/go-git): Git implementation in Go.
97- [Chroma](https://github.com/alecthomas/chroma): General purpose syntax highlighter.
98- [Goldmark](https://github.com/yuin/goldmark): Markdown parser and renderer.
99- [go-enry](https://github.com/go-enry/go-enry): Programming language detection.
100- [yaml.v3](https://github.com/go-yaml/yaml): YAML support for configuration.
101
102## License
103
104BSD 2-Clause License. See `LICENSE` for details.