Documentation

Selaginella 是基于 Fossil SCM 的极简、坚固的代码仓库托管平台 — 每个仓库均独立存储于单个 SQLite 数据库，具备完整的代码版本、时间线、Wiki、工单与内置 Web 界面，本平台提供组织命名空间、集中目录与路由托管服务。

客户端安装 · Client Installation

Fossil SCM 客户端跨平台支持 Linux、macOS 与 Windows。它是一个无需任何外部依赖的独立单一二进制程序：

macOS (Homebrew)brew install fossil

Ubuntu / Debiansudo apt install fossil

Fedora / RHELsudo dnf install fossil

Windows (Scoop)scoop install fossil

安装完成后，在终端运行 fossil version 即可验证版本。

快速上手 · Quickstart

1. 克隆代码仓库 · Clone a repository

Every public repository can be cloned with the Fossil CLI. 克隆操作会将远程仓库的历史记录完整下载为一个本地 SQLite 数据库文件（如 REPO.fossil）：

$ fossil clone https://1wt.in/REPO REPO.fossil

提示：若仓库属于组织（例如 DeepMind/AlphaFold），URL 路径为 https://1wt.in/DeepMind/AlphaFold；若为未分组项目，路径为 https://1wt.in/AlphaFold。

2. 打开工作目录 (Open workspace)

从 .fossil 数据库文件向工作目录检出源代码，并生成轻量级检出记号 .fslckout：

$ mkdir REPO && cd REPO
$ fossil open ../REPO.fossil

日常开发工作流 · Development Workflow

Fossil 的操作简单自然，版本追踪与提交非常直观：

# 1. 查看本地修改与变更状态
$ fossil status

# 2. 查看当前修改的代码差异
$ fossil diff

# 3. 添加新文件或移除文件
$ fossil add src/main.rs
$ fossil rm old_file.txt

# 4. 提交更改（Fossil 默认开启 autosync 自动同步至远端）
$ fossil commit -m "feat: 增加新功能"

Autosync 自动同步特性

Fossil 默认启用 autosync。执行 fossil commit 时，若处于联网状态，会自动先执行 pull 合并最新远端变更，并在本地提交成功后即刻 push 到远端；若处于离线状态，提交会在本地数据库保存，联网后执行 fossil sync 即可自动双向同步。

分支与合并 · Branching & Merging

Fossil 的分支是一等公民，分支名称持久记录在提交中，无需担心分支指针丢失：

# 从主干创建新分支
$ fossil branch new feature-auth trunk

# 切换当前工作区到指定分支
$ fossil update feature-auth

# 列出所有分支
$ fossil branch list

# 将分支合并回主干
$ fossil update trunk
$ fossil merge feature-auth
$ fossil commit -m "merge: 合并 feature-auth 到 trunk"

本地内置 Web UI · Local Web Interface

Fossil 拥有自包含的完整 Web 管理界面。无需配置任何外部服务，在工作区执行：

$ fossil ui

该命令会自动启动本地轻量 HTTP 服务并在浏览器中打开。你可以离线完整查看：

时间线 (Timeline)：分支演进图谱、修改记录与彩色提交历史。
文件树 (Files)：完整目录树浏览、代码高亮与 Annotate (Blame)。
Wiki & 工单 (Tickets)：内置完整的离线知识库与 Bug 跟踪系统。

组织与仓库路径 · Organizations & URLs

Selaginella 提供了清晰的双层命名空间架构：

独立项目 (Unassigned Repositories)：直接挂载于根路径，格式为 https://1wt.in/<repo-slug>。
组织项目 (Organization Repositories)：归属于指定组织，格式为 https://1wt.in/<org-slug>/<repo-slug>。

从 Explore 仓库列表或直接在浏览器访问任意仓库 URL，平台会自动代理至对应 Fossil 独立服务，呈现该仓库的原生 Web 界面。

账号体系与权限 · Authentication & Security

为保障平台独立性与安全隔离，Selaginella 采用分层权限设计：

平台管理员账号 (Platform Admin)

位于站点顶部的 Sign In 仅用于平台管理员登录后台控制台 (/admin)。管理员负责配置全站参数、创建组织以及新建托管仓库。

仓库级用户账号 (Repository Users)

每个 Fossil 仓库具备完全独立的用户权限数据库（存储于各自的 .fossil 中）。团队协作、提交授权与工单权限直接在各仓库的 Web 页面 (/login) 或通过 CLI fossil user 进行管理，与平台管理员隔离。

单文件架构与极简备份 · Single-File Architecture

Fossil 采用基于 SQLite 的单文件存储架构。一个项目的所有历史、版本快照、Wiki 页面、工单和元数据均严格封装在单个 .fossil 文件中：

原子可靠：无复杂微服务依赖，不存在外部数据库连接断开或 schema 不一致问题。
秒级冷备：直接将 .fossil 文件复制到任意备份介质即完成全量冷备份。
在线热备：通过 fossil backup target.fossil 命令可实现在线一致性热备份。
极低开销：数十个活跃仓库日常内存占用仅数兆字节，重启立即可用。

常用命令速查 · CLI Cheat Sheet

命令 (Command)	说明 (Description)
`fossil clone <url> <file.fossil>`	克隆远程仓库到本地 SQLite 文件
`fossil open <file.fossil>`	在当前目录检出仓库文件并开启工作区
`fossil close`	关闭当前检出工作区（不影响 .fossil 数据库）
`fossil status`	查看工作区状态、当前分支与未提交变更
`fossil diff`	对比当前工作区与基础版本的代码差异
`fossil add <file>`	将新文件纳入版本追踪
`fossil rm <file>`	将文件从版本追踪中移除
`fossil commit -m "..."`	提交变更（默认自动同步远程仓库）
`fossil branch new <name> <base>`	基于指定分支或标签创建新分支
`fossil update <target>`	切换或更新工作区到指定分支、标签或版本
`fossil merge <branch>`	将指定分支合并到当前工作区
`fossil sync`	与远程仓库进行双向同步 (pull + push)
`fossil ui`	在本地启动 Web 管理服务并自动打开浏览器
`fossil help <cmd>`	查看指定命令的详细使用帮助

官方参考资源 · Official Resources

深入探索 Fossil SCM 的设计哲学与完整特性：