Web Git Graph

为浏览器、本地仓库与 VS Code 打造的零框架、可嵌入 Git 历史图。
A framework-free, embeddable Git history graph for browsers, local repositories, and VS Code.

中文 · English · 在线演示 / Live demo · 全屏图 / Fullscreen graph · For coding agents · 架构 / Architecture · 安全 / Security

中文

Web Git Graph 把桌面 Git 客户端的提交历史界面做成一个 Web Component，可以直接放进网页。泳道布局是确定性的，数据来源可替换，本地仓库由一个只读的 Node 后端提供。渲染器不绑定前端框架，协议也不限定服务端语言。

它能做什么

<web-git-graph> 是标准自定义元素，原生 HTML、React、Vue、Svelte、Angular 都能直接用。
数据来自 Provider：公开 GitHub 仓库、任意 HTTP v1 后端，或本地仓库（经 Node 包）。
交互对齐桌面客户端：搜索、ref 过滤、虚拟滚动、原位展开提交详情、提交比较、按需加载文件 diff。
协议层（DTO、JSON Schema、OpenAPI）独立于浏览器和 Node 运行时。
只读。不暴露 checkout、merge、rebase、reset。
给 coding agent 备好了 llms.txt、AGENTS.md、任务 recipes 和可安装 skill，不必自己造一套可视化。

在线演示与全屏图

演示站首页：内置 react/react 的离线示例历史、可选的公开 GitHub 仓库加载（未认证触达速率限制时可粘贴 personal access token）、提交详情、比较、搜索、中英文切换与深色/浅色主题。

全屏图页面：整页只有一张图。仓库写在 URL 里，因此一个链接就能直接打开某个仓库的提交历史：

https://gis-info.github.io/web-git-graph/graph.html?repo=owner/name
https://gis-info.github.io/web-git-graph/graph.html?repo=owner/name&ref=release/2.x

查询参数	含义
`repo`	`owner/name`，也接受完整的 GitHub 链接或克隆地址
`ref`	起始分支/标签，逗号分隔可同时走多个 tip（可省略）
`backend` + `repository`	改用任意 HTTP v1 后端而非 GitHub

演示站首页的「分享这张图」区块会根据输入框里的仓库自动拼好这些链接，直接复制即可。

在 README 里放一个图标

把徽章放进任意仓库的 README，读者点一下就能看到这个仓库的提交历史图：

[![git graph](https://gis-info.github.io/web-git-graph/brand/git-graph-badge.svg)](https://gis-info.github.io/web-git-graph/graph.html?repo=OWNER/NAME)

<a href="https://gis-info.github.io/web-git-graph/graph.html?repo=OWNER/NAME">
  <img src="https://gis-info.github.io/web-git-graph/brand/git-graph-badge.svg" alt="git graph" height="20" />
</a>

把 OWNER/NAME 换成自己的仓库即可；本 README 顶部那枚徽章就是这么来的。

快速开始

安装浏览器渲染器和共享协议类型：

npm install @web-git-graph/web @web-git-graph/protocol

注册组件并连接 Provider：

<web-git-graph id="history" theme="dark"></web-git-graph>

<script type="module">
  import "@web-git-graph/web/register";
  import { GitHubGitGraphProvider } from "@web-git-graph/web/providers/github";

  document.querySelector("#history").provider =
    new GitHubGitGraphProvider({
      repository: "GIS-Info/web-git-graph"
    });
</script>

复杂值通过 JavaScript 属性传入。无论宿主使用什么框架，自定义元素名称和 Provider API 都保持一致。

VS Code 插件

仓库内的 packages/vscode 是同一套渲染器的 VS Code 宿主，安装后可在编辑器里查看提交图、提交详情、stash 与工作区改动，并用 VS Code 原生 diff 编辑器打开单个文件的差异。安装方式、设置项与快捷入口见插件说明。

架构

@web-git-graph/protocol
       ▲         ▲
       │         │
@web-git-graph/web   @web-git-graph/node
       ▲         ▲
       └────┬────┘
  web-git-graph (vscode)

模块	职责
`@web-git-graph/protocol`	与传输无关的 DTO、Schema、协议版本、OpenAPI 与错误类型
`@web-git-graph/web`	泳道布局、Web Component、GitHub Provider 与 HTTP Provider
`@web-git-graph/node`	本地 Git 后端、快照分页、HTTP handlers 与只读 CLI
`web-git-graph`（VS Code）	VS Code Webview、类型化 RPC 与 Extension Host 集成
`@web-git-graph/demo`	私有 GitHub Pages 应用（首页、协议参考页、全屏图页）与集成测试样例

依赖方向保持单向：Protocol 不包含 DOM、Node、HTTP 状态码或 VS Code 类型； Web 包不包含 Node builtin；Node 包也不包含任何渲染实现。

显示本地仓库

启动只读 HTTP v1 后端：

npm install @web-git-graph/node
npx @web-git-graph/node serve --repo . \
  --cors-origin http://127.0.0.1:4173

然后在浏览器端连接：

import { HttpGitGraphProvider } from "@web-git-graph/web/providers/http";

graph.provider = new HttpGitGraphProvider({
  baseUrl: "http://127.0.0.1:4174",
  repositoryId: "local"
});

CLI 默认监听 127.0.0.1:4174。浏览器只会接触不透明的 repositoryId，本地文件路径永远不会跨越协议边界。

事件与主题

组件会发出以下事件：

gitgraph-commit-select   gitgraph-commit-open
gitgraph-compare         gitgraph-file-open
gitgraph-load-more       gitgraph-error
gitgraph-refresh         gitgraph-context-menu

gitgraph-refresh 与 gitgraph-context-menu 可以被取消，宿主可借此改用自己的刷新逻辑或右键菜单。

外观由属性驱动：theme、density、columns（date,author,commit）、 date-format（datetime、date、relative）、date-type（committed、 authored）与 avatars，再配合 --wgg-* CSS 自定义属性。头像默认关闭，因为解析头像会把作者邮箱的哈希发送给 Gravatar。

面向 coding agent

当 coding agent / IDE 宿主需要高密度提交历史面板（泳道、搜索、比较、文件 diff）和稳定的只读协议时使用本项目；需要改写 Git 工作区时不要用它。

目标	入口
Agent 集成契约	AGENTS.md
可安装 skill	skills/web-git-graph/SKILL.md
任务 recipes	docs/recipes/
LLM 文档索引	llms.txt · llms-full.txt

决策树： 公开 GitHub → GitHubGitGraphProvider；本地仓库 → npx @web-git-graph/node serve + HttpGitGraphProvider；自有 API/MCP → 实现 GitGraphProvider。三个容易踩的点：provider 要用 JS 属性赋值而不是 HTML 属性；import "@web-git-graph/web/register" 不能漏；别的工具改动工作区之后，要自己调 element.refresh()。

本地开发

需要 Node.js 20+ 与 pnpm 10。

pnpm install
pnpm check:boundaries
pnpm typecheck
pnpm test
pnpm test:coverage
pnpm build
pnpm test:e2e
pnpm pack:check

pnpm test:coverage 在仓库根目录一次性跑完所有单元与 integration 测试，并生成合并后的 coverage/lcov.info（本地查看用，CI 不上传）。它只统计这部分测试。渲染器和 VS Code 宿主的运行时行为由 pnpm test:e2e（Playwright）覆盖，不计入这个数字。

演示站（含全屏图页面）用 pnpm dev 启动，默认地址 http://127.0.0.1:4173/web-git-graph/。

English

Web Git Graph packages the commit-history view of a desktop Git client as a Web Component you can drop into a page. Lane layout is deterministic, the data source is pluggable, and local repositories are served by a read-only Node backend. The renderer is not tied to a frontend framework, and the protocol does not assume a server language.

What it does

<web-git-graph> is a standard custom element. Plain HTML, React, Vue, Svelte, and Angular all work.
Data arrives through a provider: a public GitHub repository, any HTTP v1 backend, or a local repository via the Node package.
Interactions match a desktop client: search, ref filtering, virtual scrolling, inline commit details, commit comparison, lazy file diffs.
The protocol layer (DTOs, JSON Schema, OpenAPI) stays clear of browser and Node runtime concerns.
Read-only. No checkout, merge, rebase, or reset.
Coding agents get llms.txt, AGENTS.md, task recipes, and an installable skill, so they need not invent a graph of their own.

Live demo and fullscreen graph

Demo home — an offline sample of react/react history, optional public GitHub repository loading (paste a personal access token when the unauthenticated rate limit is hit), commit details, comparison, search, bilingual content, and light/dark themes.

Fullscreen graph — the whole page is one graph. The repository lives in the URL, so a single link opens straight into a repository's history:

https://gis-info.github.io/web-git-graph/graph.html?repo=owner/name
https://gis-info.github.io/web-git-graph/graph.html?repo=owner/name&ref=release/2.x

Query	Meaning
`repo`	`owner/name`; a full GitHub or clone URL is accepted too
`ref`	Starting branch/tag; comma-separate several tips (optional)
`backend` + `repository`	Drive the stage from any HTTP v1 backend instead of GitHub

The demo home page assembles these links for whatever repository is in the input box, ready to copy.

A README badge

Drop the badge into any repository's README and readers reach that repository's commit graph in one click:

[![git graph](https://gis-info.github.io/web-git-graph/brand/git-graph-badge.svg)](https://gis-info.github.io/web-git-graph/graph.html?repo=OWNER/NAME)

<a href="https://gis-info.github.io/web-git-graph/graph.html?repo=OWNER/NAME">
  <img src="https://gis-info.github.io/web-git-graph/brand/git-graph-badge.svg" alt="git graph" height="20" />
</a>

Replace OWNER/NAME with your own repository. The badge at the top of this README is exactly that.

Quick start

Install the browser renderer and shared protocol types:

npm install @web-git-graph/web @web-git-graph/protocol

Register the element and connect a provider:

<web-git-graph id="history" theme="dark"></web-git-graph>

<script type="module">
  import "@web-git-graph/web/register";
  import { GitHubGitGraphProvider } from "@web-git-graph/web/providers/github";

  document.querySelector("#history").provider =
    new GitHubGitGraphProvider({
      repository: "GIS-Info/web-git-graph"
    });
</script>

Complex values are assigned as JavaScript properties. The custom element name and provider API stay the same across frameworks.

VS Code extension

packages/vscode hosts the same renderer inside VS Code: commit graph, commit details, stashes, uncommitted changes, and per-file diffs in the native diff editor. Installation, settings, and entry points are documented in the extension README.

Architecture

@web-git-graph/protocol
       ▲         ▲
       │         │
@web-git-graph/web   @web-git-graph/node
       ▲         ▲
       └────┬────┘
  web-git-graph (vscode)

Module	Responsibility
`@web-git-graph/protocol`	Transport-neutral DTOs, schemas, protocol version, OpenAPI, and errors
`@web-git-graph/web`	Lane layout, Web Component, GitHub provider, and HTTP provider
`@web-git-graph/node`	Local Git backend, snapshot pagination, HTTP handlers, and read-only CLI
`web-git-graph` (VS Code)	VS Code Webview, typed RPC, and Extension Host integration
`@web-git-graph/demo`	Private GitHub Pages application (home, protocol reference, fullscreen graph) and integration fixture

The dependency graph is intentionally one-way. The protocol contains no DOM, Node, HTTP-status, or VS Code types. The Web package contains no Node builtin, and the Node package contains no renderer.

Use a local repository

Start the read-only HTTP v1 backend:

npm install @web-git-graph/node
npx @web-git-graph/node serve --repo . \
  --cors-origin http://127.0.0.1:4173

Then connect the browser component:

import { HttpGitGraphProvider } from "@web-git-graph/web/providers/http";

graph.provider = new HttpGitGraphProvider({
  baseUrl: "http://127.0.0.1:4174",
  repositoryId: "local"
});

The CLI binds to 127.0.0.1:4174 by default. Browser clients only receive an opaque repositoryId; local filesystem paths never cross the protocol seam.

Events and theming

The component emits:

gitgraph-commit-select   gitgraph-commit-open
gitgraph-compare         gitgraph-file-open
gitgraph-load-more       gitgraph-error
gitgraph-refresh         gitgraph-context-menu

gitgraph-refresh and gitgraph-context-menu are cancelable: prevent them to refresh the data or show a context menu the host's own way.

Presentation is driven by attributes — theme, density, columns (date,author,commit), date-format (datetime, date, relative), date-type (committed, authored) and avatars — plus the --wgg-* CSS custom properties. Avatars are off by default because resolving them discloses author email hashes to Gravatar.

For coding agents

Use Web Git Graph when a coding agent / IDE host needs a dense commit history panel (lanes, search, compare, file diffs) and a stable read-only protocol. Not when you need to mutate Git.

Goal	Start here
Agent integration contract	AGENTS.md
Installable skill	skills/web-git-graph/SKILL.md
Task recipes	docs/recipes/
LLM doc index	llms.txt · llms-full.txt
Live Pages index	https://gis-info.github.io/web-git-graph/llms.txt

Decision tree: public GitHub → GitHubGitGraphProvider; local repo → npx @web-git-graph/node serve + HttpGitGraphProvider; own API/MCP → implement GitGraphProvider. Three things that trip people up: provider is a JS property, not an HTML attribute; the @web-git-graph/web/register import is required; nothing refreshes on its own, so call element.refresh() after another tool changes the working tree.

Development

Requires Node.js 20+ and pnpm 10.

pnpm install
pnpm check:boundaries
pnpm typecheck
pnpm test
pnpm test:coverage
pnpm build
pnpm test:e2e
pnpm pack:check

pnpm test:coverage runs every unit and integration suite from the repo root in one pass and emits a merged coverage/lcov.info for local inspection (CI does not upload it). It measures those suites only. Renderer and VS Code host runtime behaviour is covered by pnpm test:e2e (Playwright) instead.

pnpm dev serves the demo site — including the fullscreen graph page — at http://127.0.0.1:4173/web-git-graph/.

Clean-room implementation / 独立实现

本项目借鉴桌面 Git 历史工具（包括 VS Code Git Graph）的信息密度与交互模型，但协议、布局、渲染、Provider、后端与宿主集成均为独立实现。

The project is inspired by the density and interaction model of desktop Git history tools, including VS Code Git Graph. Its protocol, layout, rendering, providers, backend, and host integrations are independently implemented.

License / 许可证

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
apps/demo		apps/demo
docs		docs
e2e		e2e
examples/local-server		examples/local-server
integration		integration
packages		packages
scripts		scripts
skills/web-git-graph		skills/web-git-graph
.gitignore		.gitignore
.npmrc		.npmrc
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
llms-full.txt		llms-full.txt
llms.txt		llms.txt
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Uh oh!

Repository files navigation

Web Git Graph

中文

它能做什么

在线演示与全屏图

在 README 里放一个图标

快速开始

VS Code 插件

架构

显示本地仓库

事件与主题

面向 coding agent

本地开发

English

What it does

Live demo and fullscreen graph

A README badge

Quick start

VS Code extension

Architecture

Use a local repository

Events and theming

For coding agents

Development

Clean-room implementation / 独立实现

License / 许可证

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Web Git Graph

中文

它能做什么

在线演示与全屏图

在 README 里放一个图标

快速开始

VS Code 插件

架构

显示本地仓库

事件与主题

面向 coding agent

本地开发

English

What it does

Live demo and fullscreen graph

A README badge

Quick start

VS Code extension

Architecture

Use a local repository

Events and theming

For coding agents

Development

Clean-room implementation / 独立实现

License / 许可证

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages