|
1 | 1 | # JSS Git |
2 | 2 |
|
3 | | -Web-based git browser for Solid pods. Browse any pod-hosted git repository (or any git remote) in a recognizable UI. |
| 3 | + |
| 4 | + |
| 5 | + |
4 | 6 |
|
5 | | -Live: https://jss.live/git/ |
| 7 | +**Web-based git browser for Solid pods.** A GitHub-style frontend that runs entirely in the browser against any git remote — including [JSS](https://jss.live)-hosted repositories on Solid pods. |
6 | 8 |
|
7 | | -## Architecture |
| 9 | +🔗 **Live:** [jss.live/git/](https://jss.live/git/) |
| 10 | +📖 **Companion guide:** [Git on Solid](https://jss.live/docs/guides/git-on-solid) |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +## Try it |
8 | 15 |
|
9 | | -- **Preact + HTM** standalone (no build step, ESM imports from CDN) |
10 | | -- **isomorphic-git** for browser-side git operations |
11 | | -- Single `index.html` — view source to read the whole app |
| 16 | +Browse any JSS-hosted git repository: |
12 | 17 |
|
13 | | -JSS pods expose git smart-HTTP (`/info/refs`, `/git-upload-pack`, `/git-receive-pack`) so any pod is a git remote. This frontend is the UI layer. |
| 18 | +``` |
| 19 | +https://jss.live/git/?repo=https://your.pod/path/to/repo |
| 20 | +``` |
14 | 21 |
|
15 | | -## Usage |
| 22 | +Demo repo: |
16 | 23 |
|
17 | 24 | ``` |
18 | | -https://jss.live/git/?repo=https://your.pod/path/repo |
| 25 | +https://jss.live/git/?repo=https://melvin.me/public/git/test/ |
19 | 26 | ``` |
20 | 27 |
|
| 28 | +## Features |
| 29 | + |
| 30 | +- **File tree** with folder navigation and file-type icons |
| 31 | +- **File content view** with syntax highlighting (JS, TS, HTML, CSS, JSON, Markdown, Python, Rust, Go, Java, YAML, Bash, ...) |
| 32 | +- **Markdown rendering** for `README.md` and other `.md` files (with shields.io badge support) |
| 33 | +- **Commits view** — full history with author, message, date, SHA |
| 34 | +- **Commit detail view** — full message, parent commits, changed files (added / modified / deleted badges) |
| 35 | +- **Branch dropdown** for multi-branch repos |
| 36 | +- **Tags display** in sidebar |
| 37 | +- **Clone box** with copy button |
| 38 | +- **Repo header** with breadcrumb, visibility badge, Watch / Fork / Star action buttons (Solid-native impl planned) |
| 39 | +- **About sidebar** with branch / refs / commits / files counts |
| 40 | +- **OGP / Twitter Card** support — sharing a repo URL renders a clean preview |
| 41 | + |
| 42 | +## Architecture |
| 43 | + |
| 44 | +> *"Let Solid be Solid, and let Git be Git."* — [Git on Solid](https://jss.live/docs/guides/git-on-solid) |
| 45 | +
|
| 46 | +JSS Git is the browser-side companion to JSS's protocol-gateway git architecture (Pattern B in the guide above). It speaks the **real git smart-HTTP protocol (v2)** — not raw HTTP-fetching of `.git/objects/` paths. |
| 47 | + |
| 48 | +| Component | What it does | |
| 49 | +|---|---| |
| 50 | +| **JSS server** | Exposes git smart-HTTP at any pod URL via `--git` flag (forwards to `git-http-backend`) | |
| 51 | +| **JSS Git frontend** | Browser SPA that fetches refs and clones repos via standard git smart-HTTP, then renders a GitHub-style UI | |
| 52 | + |
| 53 | +Why this matters: |
| 54 | + |
| 55 | +- **Works on any compliant git remote** — JSS pods, GitHub, Gitea, custom servers |
| 56 | +- **Handles packed refs and pack files** — the real git wire format, not just loose objects |
| 57 | +- **No server changes needed** beyond JSS's standard `--git` flag |
| 58 | +- **Future-proof for auth / push / branches** — uses the canonical git protocol |
| 59 | + |
| 60 | +## Stack |
| 61 | + |
| 62 | +- **[Preact](https://preactjs.com)** + **[HTM](https://github.com/developit/htm)** — lightweight UI without JSX |
| 63 | +- **[isomorphic-git](https://isomorphic-git.org)** — pure-JS git implementation (handles smart-HTTP v2, pack files, delta compression) |
| 64 | +- **[@isomorphic-git/lightning-fs](https://github.com/isomorphic-git/lightning-fs)** — IndexedDB-backed in-memory filesystem |
| 65 | +- **[marked](https://marked.js.org)** — Markdown rendering |
| 66 | +- **[Prism](https://prismjs.com)** — syntax highlighting |
| 67 | + |
| 68 | +Bundled with [esbuild](https://esbuild.github.io/) into a single `app.js` (~1MB minified, includes browser polyfills for Node `crypto` / `stream`). |
| 69 | + |
| 70 | +## Develop |
| 71 | + |
| 72 | +```bash |
| 73 | +git clone https://github.com/JavaScriptSolidServer/git.git |
| 74 | +cd git |
| 75 | +npm install |
| 76 | +npm run build # build app.js |
| 77 | +python3 -m http.server # serve locally |
| 78 | +``` |
| 79 | + |
| 80 | +Edit `src/app.js`, then `npm run build` to regenerate the bundle. |
| 81 | + |
| 82 | +## CORS requirements |
| 83 | + |
| 84 | +Browser-side git clients must be able to send the `Git-Protocol` header for smart-HTTP v2. JSS allows this in CORS preflight responses since [#372](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/pull/372). Other servers may need configuration. |
| 85 | + |
21 | 86 | ## Roadmap |
22 | 87 |
|
23 | | -- [x] List refs (branches, tags) — v0 |
24 | | -- [ ] File tree view (HEAD) |
25 | | -- [ ] README rendering |
26 | | -- [ ] Branches dropdown |
27 | | -- [ ] Commit history |
28 | | -- [ ] File content view |
29 | | -- [ ] Optional: did:nostr signature display, git-mark verification |
| 88 | +- [ ] Per-file last commit info in the file tree |
| 89 | +- [ ] File diff viewer in commit detail |
| 90 | +- [ ] Solid-native stars / watch / fork (LDP container of WebID resources) |
| 91 | +- [ ] RDF metadata reading (description, tags from pod's `.well-known/`) |
| 92 | +- [ ] Markdown table-of-contents and anchor links |
| 93 | +- [ ] Search |
30 | 94 |
|
31 | | -## Tracking |
| 95 | +## License |
32 | 96 |
|
33 | | -- Issue: [JavaScriptSolidServer/JavaScriptSolidServer#370](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/370) |
| 97 | +[AGPL-3.0](LICENSE) |
0 commit comments