# xgit

**Author:** [polymath](mailto:polymath@localhost)  
**License:** BSD 2-Clause  

`xgit` is its own standalone Python project: a static git page generator
(inspired by [stagit](https://git.codemadness.org/stagit/)). Point it at git
repositories (local demos or remotes), and it builds a browsable site — commit
logs, files, refs, Markdown, syntax-colored code, author profiles, and stats.

```
xgit/                     ← this repository (the product)
├── build  serve  sync  demo   ← run from here
├── config.toml                ← which repos to publish
├── xgit/                      ← Python package
├── LICENSE  README.md  pyproject.toml
├── data/   (generated, gitignored)
└── html/   (generated, gitignored)
```

## Requirements

- Python 3.10+
- `git` on your `PATH`
- No pip dependencies

## Quick start

```bash
cd /path/to/xgit          # this repository root
chmod +x build serve sync demo   # once
./demo                    # seed 2 demos → build → serve :3121
```

Open **http://127.0.0.1:3121/**

You should see two demo repos: **hello** and **notes** (both by polymath).

## Run files (project root)

| Command | Purpose |
|---------|---------|
| `./demo` | Wipe generated data, seed demos, fetch, build, serve |
| `./sync` | Seed demos if needed + fetch remotes + build `html/` |
| `./build` | Generate static pages only (`./build --fetch` to update remotes first) |
| `./serve` | Build then serve on `0.0.0.0:3121` |
| `./serve --no-build` | Serve existing `html/` without rebuilding |
| `config.toml` | Site name, ports/URLs, and **repository list** |

Same via module API:

```bash
python -m xgit seed
python -m xgit sync
python -m xgit build
python -m xgit serve --port 3121
```

## Adding remote git repositories

1. Edit **`config.toml`** in this repo’s root.
2. Add a `[[repos]]` block with a clone URL.
3. Run `./sync` (clones/updates mirrors under `data/repos/`, rebuilds `html/`).
4. Open or refresh the site (`./serve --no-build` if the server is already up).

### HTTPS (GitHub / GitLab / Codeberg / …)

```toml
[[repos]]
name = "myproject"
url = "https://github.com/you/myproject.git"
description = "short description"
owner = "polymath"
```

### `git://` protocol

```toml
[[repos]]
name = "sbase"
url = "git://git.suckless.org/sbase"
description = "suckless unix tools"
owner = "suckless"
```

### SSH

```toml
[[repos]]
name = "private-app"
url = "git@github.com:you/private-app.git"
description = "private work"
owner = "polymath"
```

Needs your SSH agent / keys available to the machine running xgit.

### Local filesystem checkout (`path:`)

Publish this xgit project (or any other checkout on disk):

```toml
[[repos]]
name = "xgit"
url = "path:."
description = "this project — static git page generator by polymath"
owner = "polymath"
```

`path:.` is relative to the directory that contains `config.toml`.  
Absolute paths work too: `path:/home/you/code/myapp`.

### Local seed demos

```toml
[[repos]]
name = "workdir"
url = "local:workdir"
description = "from data/seed/workdir"
owner = "polymath"
```

Put a normal git checkout at `data/seed/workdir/` (or use `./demo` / `seed` for the built-in demos).

### After config changes

```bash
./sync                 # fetch all [[repos]] + rebuild
./serve --no-build     # if already serving
```

Mirrors live in `data/repos/<name>.git`. Generated pages live in `html/<name>/`.

## What the site includes

**Per repository**

- Log, Files, Refs  
- Commit pages (diffstat + diff)  
- Markdown render + Raw + Download  
- Syntax-colored code + Raw + Download  
- Atom feeds  

**Site-wide**

- Index of all repos (owner links to author profile)  
- Authors (same email → same profile + stats)  
- Stats (totals, leaderboard, per-repo)  

## Develop / use as a project

This directory **is** the xgit git repository:

```bash
git clone <your-xgit-remote>
cd xgit
./demo
```

Optional install as a console script:

```bash
pip install -e .
xgit sync
xgit serve
```

## Layout

| Path | Role |
|------|------|
| `xgit/` | Library + CLI (`python -m xgit`) |
| `config.toml` | Your published repo list |
| `build` `serve` `sync` `demo` | Root runners |
| `data/` | Seeds + bare mirrors (ignored) |
| `html/` | Generated static site (ignored) |

## License

BSD 2-Clause © polymath