about summary refs log tree commit diff stats
path: root/README.md
blob: f55fb731b2f2b9283437edb3614f9c255fb3aae7 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
<!--
Back - An extremely simple git bug visualization system. Inspired by TVL's
panettone.

Copyright (C) 2024 Benedikt Peetz <benedikt.peetz@b-peetz.de>
Copyright (C) 2025 Benedikt Peetz <benedikt.peetz@b-peetz.de>
SPDX-License-Identifier: AGPL-3.0-or-later

This file is part of Back.

You should have received a copy of the License along with this program.
If not, see <https://www.gnu.org/licenses/agpl.txt>.
-->

# Back

> An extremely simple git issue tracking system. Inspired by tvix's panettone.

## Usage

`back` is modelled after `cgit`, only for `git-bug` initialized repositories.
The server is than started at `http://127.0.0.1:8000` and provides access to the
issues (bugs) tracked via `git-bug`, via multiple routes:

### `/`

The default index is a list of all repositories that have `git-bug` data in
them.

### `<repo_path>/issues/?query=<query>`

This path displays all issues that match the query `<query>` for the repository
at `<repo_path>`.

### `<repo_path>/issue/<issue_id>`

Displays the actual issue with `id` `<issue_id>`.

### `<repo_path>/issues/feed`

An RSS feed usable to subscribe to. This includes all issues and all comments of
issues.

## Configuration file

The config file is passed to `back` via the first command line argument. It is
written in JSON. An example configuration file is available at
[`./contrib/config.json`](./contrib/config.json).

Following keys are required:

### `source_code_repository_url`

The URL to the source code of this instance of `back`.

### `root_url`

The root URL this instance of `back` is hosted at. For example:
`https://issues.foss-syndicate.org`. This is required by the RSS feed to
generate links to the various issues/comments.

### `scan_path`

The path under which to search for the repositories as specified by the
`projects.list` file. This is semantically the same as `cgit`'s `scan-path`.

### `project_list`

The path to the file specifying the repositories to search. A repository path
per line. This is semantically the same as `cgit`'s `project-list`.

### Note

`back` needs write access to the repository, because it will generate an entity
lookup cache at `.git/git-bug-rs`.

## Licensing

This project complies with the REUSE v3.3 specification. This means that every
file clearly states its copyright.