1# Gitview
 2
 3A self-hosted Git repository browser written in Go, with a GitHub-inspired interface. Browse files, READMEs, history, diffs, branches, and tags; clone repositories or download archives. Language indicators and size-weighted breakdowns are computed locally using [go-enry](https://github.com/go-enry/go-enry). Vendor, generated, binary, documentation, and data files are excluded; detection can differ from GitHub and does not apply `.gitattributes` overrides. HTTP push is disabled.
 4
 5## Run
 6
 7Requires Go 1.23+ and Git.
 8
 9```sh
10go build -o bin/gitview ./cmd
11./bin/gitview --config ./config.yaml
12```
13
14Open http://localhost:5555. In [config.yaml](config.yaml), set `repo.scanPath` to your repository directory, `meta.title` to the browser tab title, and `meta.username` to the name shown in the top bar and on repository pages. Repositories must contain at least one commit.
15
16Set `meta.logo` to an image path relative to `dirs.static` (for example `branding/logo.png` for `static/branding/logo.png`). The same image is used as the top-bar logo and favicon:
17
18```yaml
19meta:
20  title: git.website.com
21  username: yourusername
22  logo: favicon.svg
23```
24
25To show selected repositories first, list them in the desired order:
26
27```yaml
28repo:
29  pinned: [project-one, project-two]
30```
31
32Names may include the `.git` suffix. Other repositories follow by last updated; ignored or unlisted repositories stay hidden. Restart Gitview after configuration changes.
33
34Or run with Docker:
35
36```sh
37docker compose -f contrib/docker-compose.yml up --build
38```
39
40## Mirror GitHub repositories
41
42Mirror all public repositories owned by a GitHub user (including forks and archived repositories):
43
44```sh
45./scripts/mirror-github.sh githubusername
46# Custom directory: use the value of repo.scanPath.
47./scripts/mirror-github.sh githubusername /opt/gitview/repos
48```
49
50Requires Bash, Git, curl, Python 3, and `flock`. Defaults to this project's `repos/` directory. Rerun to discover new repositories and update existing mirrors, descriptions, and default branches. An optional `GITHUB_TOKEN` environment variable increases the API rate limit.
51
52The script uses `git clone --mirror` and fetches updates with pruning. Upstream updates overwrite mirrored refs; deleted upstream refs are removed. Keep development changes in a separate clone. Unrelated local repositories are skipped with an error; repositories removed from GitHub are kept locally. Gitview displays updates without restarting.
53
54For automatic updates every five minutes, run `crontab -e` as the repository owner and add this line, replacing the paths and username:
55
56```cron
57*/5 * * * * /opt/gitview/scripts/mirror-github.sh githubusername /opt/gitview/repos >> /opt/gitview/mirror.log 2>&1
58```
59
60The script locks the destination to prevent overlapping updates. The owner must be able to write the repositories and log file. With Docker, run synchronization on the host; Compose mounts the repositories read-only into Gitview.
61
62Mirrors copy Git data, not GitHub issues, pull requests, or release attachments. See the [Git mirror documentation](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---mirror).
63
64## Checks
65
66```sh
67go test ./...
68go vet ./...
69python3 -B scripts/tests/test_mirror_github.py
70```
71