D 2026-10-13T23:47:00.672
L new-repo
N text/x-markdown
P bfe80a677f9dbe76e6c9e9e8b2f4ee84c7b99dc9daf9f495cfbf331a3bdfb7ea
U dmestas
W 5765
# Adding a Repository
How to put a new repo on fossil.craftdesign.group. Five commands, then `apply.py` does the rest: skin, Bone Hive logo, home page, public access, and the card on the landing page.
Everything happens on the server as `dmestas`. `<name>` is the URL slug, so keep it lowercase with hyphens.
## 1. Create the repository
```bash
fossil init /var/fossil/repos/<name>.fossil
fossil user new dmestas dmestas /var/fossil/repos/<name>.fossil
```
To host an existing project instead, skip `init` and copy its `.fossil` file into `/var/fossil/repos/`. Git projects are mirrored rather than copied, see [Mirrors](#mirrors) below. zit repositories cannot be read by Fossil directly: serve them with `zit serve --port 8899` and `fossil clone http://localhost:8899/ <name>.fossil` to get a Fossil file.
Also set the name shown in the title bar and on the landing page, and the one-line description used as a fallback:
```bash
fossil config -R /var/fossil/repos/<name>.fossil set project-name <name>
fossil config -R /var/fossil/repos/<name>.fossil set project-description "What this repo does"
```
## 2. Write the meta file
`/var/fossil/repos/<name>.meta` drives the landing-page card and the public access policy. One value per line:
| Line | Meaning | Default when missing |
|------|---------|----------------------|
| 1 | Icon: a name from the list below, or an emoji | `package` |
| 2 | Description shown on the landing page | project-description |
| 3 | Fossil capabilities for `nobody` (not logged in) | `jh` (read wiki only) |
| 4 | Capabilities for `anonymous` (clicked "Anonymous login") | same as line 3 |
```bash
printf 'package\nWhat this repo does\nghoj\n' > /var/fossil/repos/<name>.meta
```
**Icons.** Names map to SVG files in `/var/fossil/skin/icons/` (Phosphor duotone, MIT licensed). Current set: `bone`, `broadcast`, `git-diff`, `hammer`, `hard-drives`, `package`, `plugs-connected`, `scroll`, `swatches`. To add one, pick an icon at [phosphoricons.com](https://phosphoricons.com), download its Duotone SVG into that directory as `<name>.svg`, and use that name.
**Access.** Common capability strings:
- `jh` private: visitors can read the wiki, nothing else
- `ghoj` public read: files, timeline, wiki, tickets
- `ghoj2` as above plus reading the forum
- `ghoj23` on line 4 lets anonymous users post to the forum, with posts held for moderation (this is what `zit` uses)
The full list is at `/<name>/setup_ucap_list` on any repo. Lines 3 and 4 are re-applied on every `apply.py` run, so they are the source of truth for public access; changes made in the web UI get overwritten.
## 3. Create the home page
`apply.py` sets the repo's home page to the wiki page named `Home`, or `index` if there is no `Home`. Create one before running it (the extra "index" title is hidden by the skin, so start the page with the real heading):
```bash
fossil wiki create index -mimetype text/x-markdown \
-R /var/fossil/repos/<name>.fossil << 'WIKI'
# <name>
What this repo does.
## Clone
fossil clone https://fossil.craftdesign.group/<name>/ <name>.fossil
WIKI
```
A repo that already has a `README.md` can use that instead: `fossil wiki create index -mimetype text/x-markdown -R ... < README.md`.
## 4. Join the login group
One login works across every repo on the server. Join the group through any existing member:
```bash
fossil login-group join /var/fossil/repos/zit.fossil -R /var/fossil/repos/<name>.fossil
fossil login-group -R /var/fossil/repos/<name>.fossil # lists the members
```
Because of this, the new repo's `dmestas` user needs no password of its own.
## 5. Apply
```bash
python3 /var/fossil/skin/apply.py
```
For every repo this installs the skin (CSS, header, footer), the Bone Hive logo, sets `nobody` and `anonymous` capabilities from the meta file, and sets the home page if it isn't set yet. It then regenerates the repo grid on the landing page. It is safe to run as often as you like.
The repo is now live at `https://fossil.craftdesign.group/<name>/`. Cloudflare caches nothing from Fossil itself, but browsers keep the logo for an hour.
## Copy-paste version
```bash
NAME=myrepo
DESC="What this repo does"
ICON=package # see the icon list above
CAPS=ghoj # public read; use jh for wiki-only
R=/var/fossil/repos/$NAME.fossil
fossil init $R
fossil user new dmestas dmestas $R
fossil config -R $R set project-name $NAME
fossil config -R $R set project-description "$DESC"
printf '%s\n%s\n%s\n' "$ICON" "$DESC" "$CAPS" > /var/fossil/repos/$NAME.meta
printf '# %s\n\n%s\n' "$NAME" "$DESC" | fossil wiki create index -mimetype text/x-markdown -R $R
fossil login-group join /var/fossil/repos/zit.fossil -R $R
python3 /var/fossil/skin/apply.py
```
## Mirrors
Repos that live on GitHub (`go-libfossil`, `edgesync`) are imported with full history by `/var/fossil/mirror/git-mirror.sh` and refreshed hourly from cron. To add one:
```bash
/var/fossil/mirror/git-mirror.sh init <name> <git-url> "<description>"
```
Then do steps 2, 4 and 5 above. Don't commit to a mirrored repo on this server; changes go to GitHub and arrive on the next sync. The log is at `/var/fossil/mirror/sync.log`.
## Where things live
| Path | What |
|------|------|
| `/var/fossil/repos/*.fossil` | the repositories |
| `/var/fossil/repos/*.meta` | icon, description, public access |
| `/var/fossil/skin/` | `apply.py`, `css.txt`, `header.txt`, `footer.txt`, `logo.png`, `icons/` |
| `/var/fossil/www/index.html` | landing page; the repo grid between the `REPO-GRID` markers is generated |
| `/var/fossil/mirror/` | git mirror script, marks files, sync log |
The skin and scripts are versioned in the [fossil-skin](/fossil-skin/) repo. Edit there, then `scp` the files to the server and run `apply.py`.
Z a58406f5a9fe9afff8f1fabbc841f964