Spooky 由两个 target 组成:
- 核心库
SpookyKit:在本机或服务器上执行 Git、读写仓库文件并解析输出 - App
Spooky:AppKit 管理窗口、分栏、工具栏和菜单,SwiftUI 承载内容
下文的 A 指运行 Spooky 的 Mac,B 指服务器仓库所在的机器。
本文只写模块的划分与跨模块的设计;单个功能的实现细节写在对应代码的注释里。
| 目录 | 职责 |
|---|---|
Execution/ |
Git 命令执行、异步子进程与取消、命令结果与错误分类、仓库写队列、只读结果缓存 |
Remote/ |
SSH 主连接、连接体检、断线重连与写入核对、远端取消、包装器安装、远端输出的解析与脱敏、服务器目录在本机的挂载位置、SMB 与 sshfs 挂载 |
Host/ |
仓库还不存在时在目标机器上的操作:列目录、检查目标路径、新建、克隆与扫描 |
Callback/ |
口令、密码、签名口令与编辑器的回调服务,以及本机 Git 的凭据回调与 sshfs 挂载时的口令询问 |
Environment/ |
本机执行 Git 时的程序与环境:Git 程序、登录 shell 的环境变量、SSH agent |
Configuration/ |
全局与仓库本地的 Git 配置 |
Repository/ |
仓库位置、本机仓库识别、文件读写、交给本机程序的文件副本、仓库概况 |
ExternalTools/ |
交给外部比较与合并工具、编辑器的文件,以及写回前的版本核对 |
WorkingCopy/ |
工作区状态、Diff 与选区补丁、暂存与丢弃、文件操作、冲突,以及提交的身份、签名与信息 |
History/ |
历史分页与查询、提交图、提交详情、签名校验、版本比较与导出、Reflog |
FileViews/ |
文件历史、Blame 与原文 |
References/ |
引用快照、分支、标签、远端、分支元数据与分支比较 |
Sync/ |
Fetch、Pull、Push、Sync、合并与更新分支 |
Rewrite/ |
反转、摘取、重置、检出版本、变基与交互式变基 |
Undo/ |
撤销记录与恢复 |
Stash/ |
储藏与 Auto Stash |
Hosting/ |
托管服务的实例与账号、REST 接口、Pull Request 与 Merge Request |
Submodules/、Worktrees/、LFS/ |
子模块、工作树与 Git LFS |
Resources/ |
远端包装器 spooky-remote.pl |
| 目录 | 职责 |
|---|---|
App/ |
入口、窗口与菜单协调、本地化与错误说明、外观、命名色与文本区主题、链接解析、系统通知 |
AppIcon/ |
App 图标:图标组的选择,随图标样式、深浅与连接状态切换,写入 App 包的自定义图标;Icons/ 下每组一个文件夹,放这一组的 icns |
Components/ |
对话框骨架与呈现它的 sheet 或模态窗口,空状态、错误详情、连接状态、头像等共用视图 |
RepositoryManager/、Launch/、Clone/ |
仓库管理与书签、启动窗口,新建、克隆与扫描 |
RepositoryWindow/ |
仓库窗口与菜单动作、侧边栏、搜索、操作对话框与拖放 |
Navigation/ |
后退 / 前进记录、视图引用与窗口恢复 |
QuickActions/ |
快捷操作面板 |
Session/ |
仓库会话:状态与刷新、操作可用性、仓库写队列、视图状态、文件监听与自动获取 |
WorkingCopy/、Diff/、Text/ |
工作区与提交区、Diff、文本渲染与语法着色 |
History/、FileViews/ |
历史与提交详情、文件历史、Blame 与原文 |
Sidebar/、References/、BranchesReview/ |
侧边栏、分支 / 标签 / 远端的管理、分支整理 |
Rewrite/、Reflog/、Undo/、Stash/ |
改写历史、Reflog、撤销与重做、储藏 |
Activity/ |
Activity 窗口、按 Remote / Repository / Service 分页的操作与读取记录、读取的增减计数与它的基准、Remote 记录与增减基准的本机保存 |
ExternalTools/ |
外部比较与合并工具、Open With 与远程编辑 |
Settings/、RepositorySettings/ |
设置窗口与仓库设置 |
LocalLocation/ |
服务器仓库的本机位置对话框与 Show in Finder 的流程 |
Accounts/、PullRequests/ |
托管账号、Pull Request 与 Merge Request |
Submodules/、Worktrees/、LFS/ |
子模块、工作树与 Git LFS 的视图与对话框 |
Help/ |
关于窗口、Help 菜单、对话框帮助按钮指向的官网文章、What's New 与新功能卡片、诊断报告与崩溃报告 |
Updates/ |
Sparkle 更新器与更新通道 |
HighlightJS/ |
随 App 打包的 highlight.js 与它的许可证 |
Resources/ |
各语言文案、系统权限说明、命名色与内置主题 |
- Git 调用一律经
GitRunner,本机与服务器仓库共用一套接口:run(_:input:)只返回 stdout;execute(_:input:acceptedExitCodes:onOutput:)返回完整结果并提供流式数据块;operation提供有界的进度事件流、完整结果与主动取消stream(_:to:)把导出、归档与补丁这类可能很大的输出边读边写进本机文件,不收进内存;失败或取消时删掉写了一半的文件- 例外是快速保存补丁:在仓库所在的机器上用
git format-patch -o直接写进仓库根目录,服务器仓库写在服务器上
- 例外是快速保存补丁:在仓库所在的机器上用
immutableRun缓存只由对象哈希决定的读取,如历史分页、提交变更集与补丁、双向计数、指定提交的信息- 每条调用都带上
--no-pager、--no-optional-locks、color.ui=never与core.quotepath=off
- 本机执行 Settings → Git Config 所选的 Git 程序,默认
/usr/bin/gitopenLocalRepository()先检查最低版本2.41.0,再由 Git 识别工作区根目录- Git 程序、登录 shell 与自定义环境变量、SSH agent 集中在
LocalExecutionSettings.current,作用于本机的每条 Git 调用
- 服务器仓库经
/usr/bin/ssh在 B 上执行,用 B 自己的环境,Settings → Environment 只能检查 - 远端命令使用非交互模式:需要标准输入时(如
commit -F -的提交信息)经input传入;交互式变基的提交序列与信息由内联在命令里的编辑器写入,在仓库所在的机器上运行
-
写命令经
RepositoryOperationQueue按仓库串行;纯读取命令登记在RepositoryOperationQueue.isReadOnly -
组合操作用
GitRunner.writeTransaction持有仓库锁 -
工作区的写入经
WorkingCopyOperations发起:补丁以原始字节生成并核对快照,文件级操作的路径列表经字面 NUL 输入传递- 单文件 Diff 用字面包含与子项排除,只比较真实新旧路径;新旧路径互为祖先时,从当前完整状态确定旁支排除范围,每轮重新计算,路径比较使用 UTF-8 字节
- 状态展示与快照共用严格记录解析;先验证完整输出再过滤,保留原始字段、重命名双 NUL 路径、记录顺序及同路径重复条目。旧重命名条目须匹配当前新旧路径和同一暂存侧
- 一轮采样中的两侧逐字节补丁和忽略空白的显示补丁共用范围。前后目标状态不同立即拒绝;仅排除范围改变时丢弃整轮结果,最多完整重读一次。指纹只包含选项、所选原始状态及补丁,不包含旁支状态或排除计划
- 重命名后旧路径新建的独立未跟踪文件,其出现、消失或暂存使旧快照失效;只改内容不改变重命名指纹。按块 / 行写入只生成新路径补丁,不覆盖该独立文件
- 按块 / 行写入在仓库锁内两次核对快照,并经
git apply --check与正式写入检查。此锁只串行 App 内的写操作;外部 Git 和编辑器仍可改动仓库,因此属于乐观校验,不是跨进程原子快照
-
App 内每个仓库一条写队列(
RepositoryWriteQueue),全部窗口共用,只在内存里:同一时刻只执行一个写操作,其余的按提交的先后等待performGit在仓库空闲时立即执行;正有写操作时排进队列并返回真,调用方照 “已接受” 处理,排队期间在 Activity 列出等待中的记录,它的停止按钮把这一项移出队列- 等待中的记录不论哪一页都列在侧边栏底部的活动区(
SidebarActivityView.items),接在进行中与刚结束的行下面,按排队的先后;Repository 页的记录开始执行后离开活动区,在队列里取消或跳过的记下endedWhileWaiting,与结束的远程操作一样再列 4 s - 前一项结束后,等它与下一项的会话都刷新完,再用入口所用的同一条
can…规则(performGit(available:))按当时的状态核对:不通过的不执行 Git,记为已跳过并写明原因,撤回先显示的目标状态(performGit(withdrawn:)) - 点的时候就要确认的操作(删除、强推、检出到同名的本地分支等)确认后才排队,轮到时不再问;排进队列的检出不在点的时候询问储藏,轮到时按刷新后的状态判断,需要时带着轮次询问(
performGit(asksToStash:)),询问期间不算执行中,后面的照样等着;答复后在这个轮次上执行(performGit(turn:)),中止时连同轮次一起取消 - 对话框提交时排进队列与立即执行一样关闭表单;错误区的
dialog.blocked只在服务器已断开时出现,主按钮随之不可用 - 执行中的用户写操作失败时,后面排着的全部取消,记录写明是哪个操作失败;被停止的只停这一个,后面的照常轮到
- 服务器仓库从已连上变为没连上,或执行中的写操作因断线中断时,排着的全部取消,记录写明连接断开,重连后不执行;执行中的照断线中断的规则等重连后核对
- 窗口关闭或换仓库时取消这个会话排着的写操作,别的窗口提交的照常;App 退出时先取消全部排着的,再取消并等待各窗口执行中的
- 仓库管理详情区的写入不排队:仓库有执行中或排队的写操作时不可用,执行时同样占着队列
-
入口的可用性分两层:
canWrite只看仓库能否接受写入(服务器仓库已连上),其上的can…规则只看各入口的前提,正在写入时入口照样可用,点了排队;hasUserWrite表示有用户发起的写操作在执行或排队,撤销与重做据此禁用,只有自动获取在执行时照样可用;菜单、工具栏、右键菜单与拖放统一使用这些规则 -
文件列表勾选框的暂存与取消暂存只锁住受影响的行:排队与执行期间这些行按
stagingOverrides显示目标状态并禁用,其它行仍可勾选(canToggleStaging),点下的请求排进queuedStaging,在同一个写操作里依次执行,写入仍然串行- 会话的
staging分排队与执行两段:排队期间刷新不撤回stagingOverrides,轮到时(performGit(started:))才算执行;在队列里取消或轮到时没有执行,撤回目标状态并丢弃queuedStaging - 失败或取消时丢弃
queuedStaging,行按刷新后的真实索引恢复;改动工作区或索引的写操作执行期间(isWorkingCopyLocked,含别的窗口提交的)整个文件列表变灰,获取、推送这类写操作(performGit(touchesWorkingCopy: false))执行或排队期间不变灰 - 文件动作(勾选、丢弃、删除、忽略等)按
canWriteFiles:文件列表没有变灰、本会话的暂存又不在执行时可用,点了排队
- 会话的
-
提交被接受(立即执行或排队)就进入
isCommitting:信息与选项只读、不再接受提交,过了commitProgressDelay才转圈;开始执行后等写操作结束收起,在队列里取消或轮到时没有执行时恢复,草稿不变;别的写操作执行或排队时提交区照样可以编辑 -
检出、合并、拉取、变基、重置这类改动当前工作区的写操作经
performGit(progress:)带上标题,会话发布workspaceProgress:工作区视图整块换成WorkspaceProgressView(标题、进度条、停止按钮与 Git 的最后一行输出,行里有百分比时按比例),侧边栏 Working Copy 行转圈;停止按钮取消writeTask,写操作结束时清空- 同步只在拉取那一步显示,获取与推送开始时撤下
-
写操作经
RepositorySession.performGit(target:)声明记在 Activity 的哪一页:传了连接的对象(ActivityTarget:传输方向、远端名与 refspec)就记在 Remote 页,记录的标题与图标由它写出;没传的记在 Repository 页- 一次写操作连接几个对象时分成几条记录,如获取全部远端时每个远端一条,同步的拉取与推送各一条:动作里经 task-local 的
ActivityRecording另起记录,这些事件与 Git 输出走同一个流,先后不乱 - 核心库不知道 Activity,只报出分界:
RepositorySync.fetch获取全部远端时在每个远端开始前经onRemote报出远端名,RepositorySync.sync在每一步开始前经onStep报出步骤;App 据此为每个远端、为同步的推送另起记录
- 一次写操作连接几个对象时分成几条记录,如获取全部远端时每个远端一条,同步的拉取与推送各一条:动作里经 task-local 的
-
写操作经
RepositorySession.performGit(undo:)声明与撤销记录的关系:.reversible:只改仓库自己的引用、索引、工作区、储藏与branch.*配置- 操作经 task-local 的
UndoSteps可以把先做完的部分单独记一步(新建并检出分支记成新建与检出两步),或按实际结果改写名称(多选删除只删掉一部分时按删掉的个数命名) - 操作前后有进行中的操作时不能撤销;合并与反转停在冲突上时除外,记成放弃它的反向操作,仓库停在这个操作上也可以撤销,重做再执行一次原操作
- 操作经 task-local 的
.inverse:快照记不住的改动,如远端设置、assume-unchanged 标记、Git LFS 的启用,发布的分支与标签、重命名的远端分支、连同远端分支一起删除的本地分支,以及子模块的增删、移动、改名、本地设置与子模块里检出的版本;操作前读出撤销要用的内容,撤销时执行反向操作、先核对前提,重做时再执行一次原操作(添加子模块的重做复用撤销时留下的 Git 目录);要推送的撤销与重做记在 Activity 的 Remote 页.irreversible(默认):删除远端引用这类其余改动服务器的操作,以及提交身份、exclude 规则或其它配置.unrecorded:获取、拉取、推送、强推与同步,自动获取这类不由用户直接发起的操作,以及撤销、重做本身;更早的快照记录在执行前核对仓库状态,不需要这些操作挡住
-
撤销的快照建在仓库所在的机器上,写进仓库自己的对象库;恢复前核对仓库仍与记录一致
-
移进废纸篓的文件不进快照:写操作期间由
TrashLog记下它们在废纸篓里的位置,撤销时移回原处,重做时重新移进废纸篓;废纸篓程序不报告位置时这次操作不能撤销 -
删除工作区文件同时暂存删除:写事务里先用
ls-files -s -v -z记下要删除的路径下的已跟踪文件(目录展开成文件),移走后对它们执行update-index -z --force-remove --stdin;未跟踪与被忽略的只移走- 撤销是反向操作(
UndoRecording.deletingFiles):先核对这些路径仍不在索引里,再移回文件(废纸篓经TrashLog,永久删除从删除前工作区快照的树写回),经update-index -z --index-info恢复索引项(含已暂存的内容),最后补回 assume-unchanged 标记,--index-info不保留它 - 移走中途或索引更新失败时抛
FileDeletionError,错误框先列已移走的项,再接 Git 或废纸篓的原始错误
- 撤销是反向操作(
-
发布分支与标签只连接一次远端:写操作期间由
PushLog记下push --porcelain的逐条结果,新建了远端引用才登记撤销,已是最新时不碰撤销记录,快进了远端已有的分支与推送一样不能撤销 -
本机与服务器的 Git 子进程都清除
GIT_LITERAL_PATHSPECS、GIT_GLOB_PATHSPECS、GIT_NOGLOB_PATHSPECS、GIT_ICASE_PATHSPECS;文件补丁通过字面包含与子项排除限定实际新旧路径,目录历史查询仍递归匹配。
- 不经对话框的获取(快速获取、Fetch All Remotes、自动获取、添加远端后的获取)共用
SyncPreferences.fetchOptions(in:)给出的清理与子模块选项;获取对话框里入口带来的预选只作用于这一次,用户在对话框里切换的选项才写进偏好 - 自动获取由
RepositoryAutoFetch调度,每个远端各自计时:上次获取的时刻按仓库与远端名存在偏好remoteLastFetch,跨重启保留;它是运行状态,不登记为用户数据- 进入仓库视图、换仓库、sheet 结束、远端名单变化与改间隔时重新计时,10 s 后检查,之后每 160 s 检查一次;显示仓库管理或挂着 sheet 时暂停
- 每次检查只获取距上次获取已满设定间隔的远端,一个结束再开始下一个;各获取入口开始获取一个远端时都记下时刻,失败也记
- 自动获取不排队,只在仓库空闲(没有执行中、也没有排队的写操作)时开始;执行期间有用户发起的写操作被接受时,自动获取停下让路,记录写明让给了哪个操作、记为取消,这次检查里还没开始的远端不再获取,用户的操作接着轮到
- 跳过设了
skipFetchAll的远端;本机仓库另跳过解析不出主机的地址(本机路径、file://),系统网络路径不可用时这次不获取;服务器仓库的地址交给 B 上的 Git,A 不判断主机与网络
- 进行中的操作由
OperationProgress一次读出:状态文件经同一次rev-parse --git-path定位、经RepositoryFiles读取,本机与服务器同一路径- 核心库给出分类:变基总是序列,摘取与反转以
sequencer/是否存在为准;停在edit指令且有rebase-merge/amend时是 edit 步。另给出步数、edit 步的父提交、冲突时对方的提交与预填的提交信息 - 横幅、提交区、Skip、空提交确认与冲突向导都读这份结果,不各自判断
- 核心库给出分类:变基总是序列,摘取与反转以
- 提交信息有普通、修补与合并三种编辑模式,共用一份草稿:进入修补前记下草稿,取消或修补成功后恢复;进入合并或序列的下一步时换成预填的信息
- 提交与继续都经
commit -F -传入信息,并加--cleanup=whitespace,注释行先按设置处理;继续序列时先用编辑后的信息提交这一步,再让 Git 继续剩下的步骤 - 合并以
RepositorySync.merge的结果区分是否停在冲突上:退出码为 1 时在同一写事务里核对MERGE_HEAD(压缩合并为SQUASH_MSG)与冲突条目,其余失败照原样抛出 - 冲突向导的两侧版本取自索引的 stage,对方的提交在变基时取
REBASE_HEAD;选择只在视图里,不写仓库;交给本机程序的版本先写进RepositoryFileCache - 旧提交的 Amend 与 Edit 用同一份 todo(目标为 edit、其余为 pick),Amend 停在目标本身;有本地改动时先询问是否储藏,储藏不自动恢复
- 只通过
~/.ssh/config中的主机别名访问;连接、认证、主机指纹与复用交给系统 SSH RemoteConnection为每个工作区管理专属的 ControlMaster,空闲 10 分钟后退出- 控制与中继 socket 位于
0700的会话目录 - 不使用也不关闭用户的其它 SSH 主连接
- 控制与中继 socket 位于
- 远端包装器由资源
spooky-remote.pl按内容摘要版本化,首次体检通过后原子安装到 B 的~/.spooky/bin- 负责远端进程组、回调客户端与签名、校验程序的入口
- 依赖 B 的系统 Perl 核心模块,不安装常驻服务
- 文件读写经
RepositoryFiles;SFTP 经RemoteConnection.sftpCommand()接入同一主连接,读、写分别遵循主机并发与仓库写队列 - 删除文件与丢弃未跟踪文件移进 B 的废纸篓:连接体检找出 B 上的程序,macOS 用系统自带的
/usr/bin/trash,Linux 依次找gio与trash-put;都找不到时界面先确认,再永久删除 - 服务器仓库里删除或覆盖文件前的确认都可以勾选不再提醒,Settings → General 逐项列出
- 本机位置:服务器仓库目录在这台 Mac 上的位置,用于 Show in Finder
- 方式(
ServerLocalLocation):自动查找、SMB 挂载、sshfs 挂载与指定文件夹;按仓库记在这台 Mac 的偏好serverLocalLocations里,以<别名>:<路径>为键,不写进 B 的 Git 配置- 旧偏好
serverLocalFolders里手动指定的文件夹,读到时迁成指定文件夹 - 仓库目录以外的工作树不论方式,都各自自动查找
- 旧偏好
- 自动查找:
RemoteMountLocator在这台 Mac 已挂载的网络卷里找 B 的目录,不论卷由谁、经哪种协议挂载- 找卷:比较
ssh -G <别名>得到的主机与网络卷重新挂载地址里的主机解析出的地址 - 找目录:按远端路径从最长的后缀试起,在卷里找带
.git的目录
- 找卷:比较
- 核对:经 SSH 在 B 的 Git 目录里临时写一个随机命名的空文件,本机看得到才算同一个目录,随后删掉;自动查找、sshfs 挂载与指定文件夹都这样核对
- 挂载经
RemoteMounter,检测与两种挂载各是一个可替换的闭包,测试注入替身,不做真实挂载- 可用条件:
ssh -G的主机解析出的任一地址 2 秒内连得上 445 端口时可以用 SMB;在 Homebrew 的目录与PATH里找得到sshfs时可以用 sshfs - SMB 经 NetFS 挂载记下的共享(重新挂载地址,去掉密码),没有时挂主机的根地址、从共享列表选;账号与密码交给系统的登录框与钥匙串;同一个共享已经挂着时直接沿用;挂上后按自动查找的办法在卷里找仓库
- sshfs 挂到用户选定的空文件夹,远端写
<别名>:<仓库路径>,参数逐个传进进程、不经 shell,严格核对主机密钥;挂上后核对 - 用户发起的挂载允许系统的登录框、共享列表与口令询问;不由用户发起的不允许任何询问
- Spooky 不卸载卷:关闭仓库、退出 App 与改换本机位置时都不卸载
- 可用条件:
RepositoryMountState是会话里的本机位置状态:方式、查找结果、正在挂载、上次失败的原因与方式带的文件夹能否用;结果只在本次运行里保留- 读到工作树清单、这台 Mac 挂载或卸载卷时查找;重新连上 B 后,没有挂载的目录一律重查
- 重新挂载:每次打开仓库只在后台试一次,SMB 要有记下的共享且没挂着,sshfs 要文件夹没挂着,都要这台 Mac 上可用;不询问,失败只记原因
- 方式(
- Show in Finder:服务器仓库的入口一直可用,不能直接打开时提示写原因
- 已知本机位置且这个路径在时直接打开,不需要连着 B
- 否则
ShowInFinderFlow在 sheet 里依次进行,取消只关闭 sheet,已开始的连接、查找与挂载照常结束、结果不采用:- 没连上 B 时连接;会话在等两次重连之间的间隔时,提前再连一次
- 重新查找一次,不沿用之前 “没有挂载” 的结果;查找或后台挂载已在进行时等它的结果
- 方式是 SMB 或 sshfs 挂载时,允许询问地挂载一次
- 仍然没有时换成本机位置表单(
LocalLocationForm),与仓库设置里的对话框相同
- 仓库管理与最近克隆:有窗口开着这个仓库时,交给那个会话的流程;没有时临时读入偏好里的本机位置,需要连接时按添加服务器仓库的体检建立,不打开仓库
- 流程进行期间在
SpookyApplicationController登记这个仓库,releaseConnection不关登记中的连接;流程结束后撤销登记再交还
- 流程进行期间在
- 刷新:
- 服务器仓库按
RemoteConnection的常量轮询,前台 2 秒、后台 10 秒;只读 status 与所选文件的内容哈希,有变化才读取身份、引用、历史与 Diff - 本机仓库由
RepositoryFileMonitor的递归 FSEvents 触发刷新 - 写入完成、重连、窗口重新激活与手动刷新执行完整刷新
- 刷新引起的重读不先清空已显示的内容,读取在后台进行、不显示进度:
- 历史从头重读时至少读回已加载的条数,读完一次替换;选中的提交仍在列表里就保留选择
- 同一提交的变更集,以及展开与选中文件的补丁,读到的与已显示的相同时不替换;不在新变更集里的文件移出展开与选中
- 文件历史在 HEAD 移动后同样处理时间线与所选提交的详情
- 选中的提交不在新的列表里时,选择与详情照常清空
- 服务器仓库按
- 断线:保留上次读取的状态并在后台重连;写入中途断线时不重试,重连后先核对分支、工作区、暂存区锁、远端跟踪分支与进行中的合并或变基,再允许写入
- 取消:先关闭命令通道,再由包装器结束远端的整组进程,发 TERM、2 秒后发 KILL,并确认进程已退出;没能确认时,重连核对之前不能写入
- 同一主机同时执行的命令最多 8 条,取消通道另外最多 1 条:被取消的命令在 B 上结束之前一直占着会话,取消得到确认时那个会话也可能还没释放;三者合计不超过 OpenSSH 默认的每条连接 10 个会话(
MaxSessions)
- 同一主机同时执行的命令最多 8 条,取消通道另外最多 1 条:被取消的命令在 B 上结束之前一直占着会话,取消得到确认时那个会话也可能还没释放;三者合计不超过 OpenSSH 默认的每条连接 10 个会话(
- 新建、克隆、扫描与目录浏览在仓库存在之前进行:
- 服务器经
RemoteConnection.host(_:)的主机连接在 B 上执行,App 先用RemoteConnection.presentingHost(_:)装上询问凭据的处理器 - 本机与服务器执行同一份脚本,扫描只在用户选定的目录里进行
- 克隆先在目标机器上用
ls-remote确认能连上远端,连上之后才关闭对话框、加入书签并开始克隆
- 服务器经
- 口令、密码、签名口令与编辑器的请求经
CallbackRelay回到 A:服务器仓库经当前主连接上的反向 Unix socket,本机仓库经私有的 Unix socket- 每个请求带会话令牌,只能应答一次,120 秒后超时
- 凭据不进入记录、日志或错误对象;用户选择保存时只写 A 的钥匙串
- 不由用户直接发起的操作(如自动获取)放在
RemoteCallbackRequest.$allowsInteraction.withValue(false)里执行:回调只用账号令牌与钥匙串里已存的凭据,取不到按取消处理,不弹出输入框 - HTTPS 远端属于已登录的托管账号时,Git 用账号的令牌认证:
GitCredentialScopes记着交给 Spooky 回答的地址前缀:账号实例的 HTTPS 网页地址,与关联到已登录账号的 HTTPS 远端(去掉用户名);App 在启动与账号、关联变化时写入- 本机与服务器上的每条 Git 命令为每个前缀先清空已有的凭据助手,再加上包装器的
credential入口,并打开credential.useHttpPath,助手与 askpass 都拿到带路径的地址 - 包装器只把
get与erase的地址经中继交给 App,store不交;AccountGitCredentials按手动关联、账号实例的顺序找账号,回答username与password,用户名与密码登录换来的令牌配用户名oauth2;服务器仓库的令牌只经中继回到 B 上助手的标准输出 - 回答的顺序:账号令牌、钥匙串里存过的凭据、弹框询问。对不上账号、账号需要重新认证或令牌被 Git 拒绝过时,助手不输出,Git 接着问 askpass
- 同一操作对刚回答过的地址发来
erase,说明 Git 拒绝了令牌:只在内存里标记这个账号,重新认证或移除后清掉;之后这个账号的地址回到询问,说明里写明账号的令牌没能通过 - 中继只把应答里
password=行的值记进脱敏集合
- 签名:
- 本机会生成提交的命令(
commit、merge、rebase、cherry-pick、revert)经LocalGitAuthentication执行:SSH 签名的私钥口令经回调询问,GPG 交给本机的 pinentry - 服务器仓库在 B 上签名:经包装器的
-gpg、-ssh-keygen入口接入中继,仍执行仓库配置的签名程序;gpg 以 loopback 模式运行,只在确实需要口令时询问 - 身份档案的签名密钥由
SigningKeys.local从 A 的 gpg 钥匙环与 SSH agent 列出;服务器仓库要在 B 上有同一把密钥
- 本机会生成提交的命令(
- 校验签名一律经
SignatureVerification.run:服务器仓库用包装器的-gpg入口,本机仓库为这次校验临时放一份包装器;包装器给--verify加上--no-auto-key-retrieve --no-auto-check-trustdb,校验不访问网络
- 交给 Quick Look、默认程序、比较工具或拖出的文件一律经
RepositoryFileCache- 本机工作区文件用原路径;服务器文件与历史版本写进会话专属的
0700缓存目录,只保留文件名,关闭仓库时删除 - 远端路径不交给本机文件 API
- 本机工作区文件用原路径;服务器文件与历史版本写进会话专属的
- 服务器仓库不在 B 上运行 difftool / mergetool:两侧内容经
ExternalToolFiles取到缓存目录,在 A 上启动工具;合并结果经 SFTP 写回后再git add - 编辑器副本(
EditingCopy)写回前核对 B 上的版本,不一致时询问是否覆盖
- 接口一律经
HostingClient从 A 发起- 令牌只放在请求头:GitHub 与用户名和密码登录的 GitLab 账号用
Authorization: Bearer,其余 GitLab 账号用PRIVATE-TOKEN - 请求不用 URLCache 里的旧响应;失败按
HostingError分类并保留服务端原文
- 令牌只放在请求头:GitHub 与用户名和密码登录的 GitLab 账号用
- 令牌只存在钥匙串,服务名
com.rakuyo.spooky.hosting.<实例网页地址>,账户名是账号 UUID- 个人访问令牌与浏览器授权的令牌存原文
- 私有部署 GitLab 的用户名与密码经
GitLabPasswordGrant换成 OAuth 令牌,钥匙串存访问令牌、刷新令牌与到期时间的 JSON,密码不保存 - 这种账号的客户端在每次请求前经
HostingAccounts.token(for:)取令牌:距到期不到 60 秒时先用刷新令牌续期,同一账号的续期串行进行;刷新令牌被拒时账号标为需要重新认证
- 请求的提交与改动在仓库所在的机器上比较:源分支提交不在仓库里时,从目标远端的
refs/pull/<编号>/head(GitLab 是refs/merge-requests/<编号>/head)取到FETCH_HEAD;合并时带上源分支提交让服务端核对,合并后在仓库所在的机器上获取目标远端
- 仓库书签由
RepositoryBookmarks存在偏好里,全部窗口共用;打开成功的仓库自动加入书签,失效只做标记,从不自动删除 - 删除书签时可以勾选连同仓库文件夹移进废纸篓,经
RepositoryFolderTrash在书签删除后于后台逐个移动,不永久删除- 本机仓库进这台 Mac 的废纸篓(
FileManager.trashItem);服务器仓库经它的连接在服务器上移进那台服务器的废纸篓,程序与 Discard 的相同 - 家目录、它的上级目录与卷或挂载点的顶层不移走:本机按解析后的路径与卷信息判断,服务器在服务器上按它的
$HOME与df判断 - 克隆中的仓库先停止克隆、等它结束,再移走还在的目录;没能移走的全部处理完后在一个错误框里列出
- 本机仓库进这台 Mac 的废纸篓(
- General 页打开列出工作树时,
BookmarkWorktrees在后台读取列表里看得到的仓库的工作树,列出的与仓库窗口侧边栏的 Worktrees 分组同一规则(RepositoryWorktreeState.others(of:))- 本机仓库直接读;服务器仓库经它的主连接不交互地读,读完交还连接;连不上或读取失败时那一行不能展开,不弹框
- 展开了工作树的仓库记在偏好
repositoryListExpandedWorktrees里,下次读到后照样展开
- 仓库设置只写仓库本地配置(
GitRunner.setLocalConfig) - 本地分支的置顶、归档、父分支与分支整理标记由
BranchMetadata写在branch.<名称>.spooky-*,改名时随段移动,删除分支时随段清除 - 引用的公共顺序由
ReferenceOrder定义:侧边栏、恢复版本的候选、Reflog 的引用菜单、合并与拉取的下拉共用,当前分支不提前 - 侧边栏行的拖放落点是
RepositoryDropView承载的 AppKit 视图,只登记拖放类型、点击穿透给所在的行;ReferenceDropAction按来源、落点与 ⌥ 解析出动作,拖动中把动作名作为徽标加到拖动影像上,落下时执行同一个动作 - 侧边栏的展开状态由
SidebarExpansion按仓库记在偏好sidebarExpansion里,以仓库的显示路径为键:收起的分组与展开的远端、文件夹;过滤时的展开与拖动悬停的临时展开不记下 ViewReference是窗口里一个可以回到的视图,同时用于后退 / 前进、窗口恢复与spooky://链接;新增主视图时三处一起覆盖- 链接:
spooky://open?repository=<位置>可带view、branch或commit;服务器仓库的位置写<主机别名>:<远端路径>spooky://clone?url=<地址>- github.com 的 “Open with Desktop” 链接只接受 github.com 的 https 仓库网址
- 解析不了的链接只显示错误,不执行任何动作
- 诊断报告与崩溃报告离开本机前经
DiagnosticRedactor脱敏;崩溃报告只打开预填的 GitHub 新问题页,由用户自己提交 UpdateController按 Settings → Updates 的通道接收更新清单里的条目,只接受 EdDSA 签名的清单与更新包;swift run时更新器不启动
- 键盘焦点只在点击、Tab 与程序化定位时移动:点选侧边栏、历史列表的行或右侧变更文件的行后,焦点移到被点的列表,↑ ↓ 移动的是它的选中,其它列表的选中不变
- 侧边栏与历史列表的行是不接受第一响应者的 SwiftUI 视图,窗口不会因为点击把焦点交给列表;
RepositoryWindow在分发鼠标左键按下之前,把焦点交给点中的、还没有焦点的列表
- 侧边栏与历史列表的行是不接受第一响应者的 SwiftUI 视图,窗口不会因为点击把焦点交给列表;
- 刷新、选中变化与读取完成的代码路径不调用
makeFirstResponder,也不改侧边栏列表的焦点状态,焦点不会被拉回侧边栏;打开或切换仓库时焦点默认在侧边栏 - 历史列表与变更文件行的选中底色随焦点与窗口状态变化:有焦点用强调色,窗口是 key 而列表没有焦点用不强调的选中色,窗口不活跃时再与列表底色混合
- 工作区文件列表、历史列表与变更集的右键菜单在构建时算出实际作用的条目:点在选区里作用于整个选区,点在选区外只作用于被点的一行,选区与右侧详情不变
- 标题、计数、可用性与执行都用这一份,动作闭包捕获条目本身,不在执行时回读选区;目录算一项,执行时再展开成文件
- 入口:工作区的
buildMenu(_:clickedRow:)、历史列表Coordinator.buildMenu(_:clickedRow:)、变更集的ChangesetFileSelection.affected(clicked:order:)
- 文件列表空白处:有选择时作用于原选区,没有时作用于空目标,写操作与单文件视图禁用,Show in Finder 与 Open in Terminal 指向仓库根
- 要另读 Git 才能判断的菜单项(assume-unchanged 标记、Git LFS 是否启用)先禁用,打开菜单时对作用条目读一次再启用;这些读取不进状态轮询
HistorySearchSuggestions每个会话一份,历史与文件历史的搜索框共用- 作者与提交人:会话每次读出新的 HEAD 时在后台非交互地读一次整个仓库的作者与提交人(
RepositoryFileViews.contributors(at:),按首次出现的顺序),同一仓库与 HEAD 只读一次;换 HEAD 时取消旧的读取,关闭仓库时取消并丢弃- 结果随 HEAD 变化,不进
immutableRun;输入时还在读就等这一次读取,读取失败时没有人员建议,失败的结果不缓存
- 结果随 HEAD 变化,不进
- HEAD 中的文件清单在第一次输入文件条件时读取,同样按仓库与 HEAD 缓存
- 人员建议对 “姓名 <邮箱>” 做不区分大小写的子序列匹配,同名不同邮箱各成一项
- 打开后高度会变的弹窗都经
DialogWindow呈现,设置页的账号、身份档案与应用图标也是;高度固定的服务器目录浏览与服务器环境提醒仍是 SwiftUI 的 sheet- 克隆对话框不论从哪里发起都是应用级的模态窗口,不挂在发起的窗口上
- 经
DialogWindow呈现的对话框,窗口尺寸由骨架报上的理想尺寸驱动:DialogLayout量出上面一段的高度加上底栏,交给DialogSizing.fit(_:),窗口不随约束自动变化;挂上之前先排成理想尺寸 - 显示期间的变化是一段 0.2 s ease-out 的动画,窗口与内容同时开始、同时结束:骨架自己的输入(说明、错误区文字、底栏的进度)变化时由骨架带上
DialogAnimation;内容区里会改变高度的状态经DialogAnimation.perform(_:)或Binding.animation(DialogAnimation.current)修改,同一次修改里的几处变化合成一段 - 动画期间窗口高于或矮于内容时,上面一段按理想高度贴顶,底栏贴着窗口底边;挂成 sheet 时系统把 sheet 摆在父窗口的竖直中线上,变高时上下两边各动一半
- 应用级模态窗口里内容与窗口都一次到位
- 骨架各段的间距由骨架给出,各对话框不另留:头部的说明至少高 38、下方留 12,错误区至少高 52;
DialogForm默认上下各留 20,版式不同的表单(只有勾选框的删除确认、储藏、摘取与反转,推送版本与 Push HEAD 的内容区,显示核对状态的安全强推,以父分支下拉开头、顶边留 16 的设置父分支与新建分支的选项区)经insets另定,没有行时整个表单区不占位置;表单末尾随结果出现的状态行(合并可行性预览、强推的核对状态)标上isDialogFormStatus,排在网格之后,没有内容时不占高度,也不多出一份行距 - 表单的输入列默认从 116 开始,标签列更宽的对话框经
DialogLayout的inputColumn另给起点,内容区与选项区的表单都按它排;标签比起点前的位置长时输入列随之右移,头部与错误文字跟着输入列 - 可以拉大的对话框(Git 错误框)尺寸由使用者决定,以内容的最小尺寸为下限,头部的说明按整段文字的高度计入:打开时照记住的尺寸,排不下内容时放大到最小尺寸;之后只在切换选项区时变化:收起时减去选项区的高度,再展开时回到收起前的高度;切换期间暂停按内容的最小尺寸约束窗口
- 输入停顿后才校验或读取的对话框,等待期间保留上一次的错误或结果,新结果出来后一次替换;结果决定能否提交时(Checkout Revision、Reset、Rebase Onto),
RevisionPreview把结果与读取时的输入记在一起,主按钮与提交只认与当前输入对应的结果
- 打开的仓库经
RecentRepositoryDocuments登记进系统的最近文稿,Dock 图标的右键菜单在 App 没运行时也能列出:本机仓库登记仓库文件夹 - 服务器仓库没有本机路径,登记的是
~/Library/Application Support/Spooky/Locations/<带主机前缀的位置的 SHA-256>/<远端路径最后一段>.spookyrepo文件夹,里面的.spookylocation是只记主机别名与远端路径的 JSON;文件夹的导出类型遵从public.folder,在菜单里显示文件夹图标,登记前隐藏扩展名 - 点选这一项时系统把文件夹交给 Spooky,
openFiles(_:)读出里面的位置再打开服务器仓库;直接打开位置文件同样如此 - Clear Menu 清空系统的最近文稿与书签的最近列表,位置文件夹保留,再次打开同一个服务器仓库时沿用
- 测试把登记换成记录器,不碰系统真实的最近文稿
- 图标组:
AppIconGroup有探身、身前、藏身、显形、午夜、栖枝、采撷与满怀八组,前四组属于AppIconSeries的躲猫猫系列,后四组属于 cherry-pick 系列;系列与组声明的先后就是设置页里自上而下、从左到右的顺序,默认的一组(AppIconGroup.defaultGroup)是探身;所选的组存在偏好appIconGroup,键不存在或值不认识时为默认的一组,Reset / Clear User Defaults 之后随之回到默认的一组- 每组四个 icns:默认、连接、深色、深色连接,文件名是
AppIcon<组名>加上Dark、Connected;连接版与灭灯版只差亮起来的部分,运行时的合成依赖这一点 - 默认的一组的默认图标是包里的默认图标(
CFBundleIconFile) - 三十二份 icns 都由
scripts/make-icon.swift在无窗口的 WebKit 里执行scripts/make-icon/下的绘制脚本画出,放在Sources/Spooky/AppIcon/Icons/下各组的文件夹里,文件夹名是这一组的文件名前缀去掉AppIcon,如Rise/;打包时摊平拷进Contents/Resources/;kit.js是各组共用的底板与入口,sticker.js是各组共用的贴纸画法,每组另有一个文件,躲猫猫的四组共用hide-and-seek.js;柔边与投影要用模糊与蒙版,画面先拼成 SVG 再画进 Canvas - 重新生成时,1024 px 一张每次可能有几个像素差一个色阶(WebKit 画 SVG 滤镜时的舍入不固定,macOS 27 实测),看不出差别,没改画法时不必提交这种变化
- 深浅:读全局偏好
AppleIconAppearanceTheme;值以Dark结尾为深色,以Automatic结尾时跟随 App 的外观,其余与键不存在时为浅色 - 壳 App:
- 每组各有一个只装该组默认图标的壳 App,放在
Contents/Resources/<资源名>.app,由scripts/make-icon-shells.sh在打包时写出 - 系统画包内图标时会裁成圆角形状、缩到标准大小并加上亮边;
AppIconController取壳 App 的系统图标作为该组的底;默认的一组也取壳 App 的,Spooky.app 挂着别的组的自定义图标时,系统给出的包图标是那一张
- 每组各有一个只装该组默认图标的壳 App,放在
- 运行中的 Dock:
AppIconController按组、图标样式、深浅与连接状态挑出一版,由AppIconRenderer叠在该组的底上,设为NSApp.applicationIconImage- 默认与深色样式下,连着服务器仓库时只有指示灯不同
- 透明与色调样式下指示灯不亮:默认的一组交还包里的默认图标,其它组用系统按样式处理过的壳 App 图标
- 设置页 “App Icon:” 一行的预览显示同样画法、指示灯灭着的一版,指针或键盘指着列表里另一组时换成那一组的;点一行立即换组,没有确认的一步
- 启动窗口、对话框头部与关于窗口经
AppIconController.displayedIcon(of:)显示applicationIcon,随它更新:设了运行时图标时就是它,交还默认图标时是系统给出的包图标;启动时包上有自定义图标的话,NSApp.applicationIconImage设回 nil 之后仍是启动时的那一张
- 自定义图标:
- 选中其它组时,把当前样式下指示灯灭着的一版以
NSWorkspace.setIcon(_:forFile:options:)写成 Spooky.app 的自定义图标,App 没运行时的 Dock、⌘Tab 与 Finder 都显示所选的组;选回默认的一组时清除- 透明样式与色调浅色下写该组默认图标的原图,由 Dock 按样式处理:Dock 在这几种样式下也处理自定义图标,写进系统已处理过的壳 App 图标会被处理第二遍,没运行时的格子发暗、发黑
- 色调深色下 Dock 不处理自定义图标,与默认、深色样式一样写合成的一版
- 写入会在包的根目录加上
Icon\r与 Finder 信息,此时codesign --verify --strict不通过,不带--strict时仍通过 - 启动、换组、图标样式或深浅变化时重写,Sparkle 更新换掉整个包后由此写回;只有连接状态变化时不写
- Dock 自己缓存固定格子的图标,写完只有重启 Dock 才换:换组与重新套用偏好(启动、Reset / Clear)各算一次请求,写完后包上有没有自定义图标变了时,向 Dock 进程发 SIGTERM,launchd 随即拉起新的 Dock,运行时图标跨重启保留
- 换组、更新后第一次启动写了进去、Reset / Clear 清掉了时重启;选的就是当前的组、包上已是所选的组的平常启动,包上没变,不重启
- 几次请求先后排队时,等全部写完再结算:这期间包上有没有自定义图标变了奇数次才重启一次,如换组还没写完时做了 Reset / Clear;换走又换回时不重启
- 样式与深浅变化的重写只换同一组的另一版,不算请求,不重启 Dock
- 重启由
AppIconController.init的restartDock注入,测试传入记录调用的闭包
- 写入与清除在进程共用的一条串行队列上执行,主线程不等;换组时写成功才存偏好,失败时抛出
AppIconWriteError,偏好与图标都不动;其余时机的失败不提示
- 选中其它组时,把当前样式下指示灯灭着的一版以
- 主题:
- 一个主题一个
.spookythemeJSON,放在~/Library/Application Support/Spooky/Themes - App 启动时由
ThemeStore.installDefaultThemes()从BuiltinThemes.json写入 Default 与 Default (Dark):只在文件缺少或无法加载、且名称没被别的主题占用时写- 同名的主题仍是旧的默认配色时换成
BuiltinThemes.json的配色,旧配色与它不同的几种颜色记在LegacyBuiltinThemeColors.json
- 同名的主题仍是旧的默认配色时换成
- Default 与 Default (Dark) 按名称认出,可以编辑,不能改名、删除
- 浅色与深色外观各选一个主题;找不到时按名称回退到 Default 或 Default (Dark),再退到
BuiltinThemes.json里的版本 - Diff、原文、Blame 与 Themes 页的 Diff 预览取主题一律用
TextTheme.current(dark:);在 SwiftUI 的body里调用,即随主题的编辑、切换与外观变化刷新 - 主题文件的 RGB 分量按 calibrated RGB(Generic RGB)直接构色,正文、背景、选区、语法记号、增删行底色与 Themes 页共用;颜色面板也先转到 Generic RGB 再保存,避免编辑往返改变颜色
- 行号、描边与原文 / Blame 的次要文字、段高亮、分隔线从文件的原始分量按 sRGB 推导;
NamedColors.json的命名色同样保持 sRGB
- 一个主题一个
- 语法着色、Tab 宽度与不可见字符的偏好集中在
TextPreferences;一行文本按TextStyle经TextLineRenderer渲染 - Tab 与源空格的可见符号附在原空格位置,LF 标记附在实际换行字符上,由 Diff、原文与 Blame 共用的 AppKit 布局管理器绘制;符号不参与正文推进和折行。CR 保留到行渲染器,CRLF 只标 CR。
- 原文与 Blame 的末行 LF 都由已读 blob 决定,复制使用 blob 的完整解码源串与 UTF-16 显示映射;显示层对其它 Unicode 分隔符的替代不改变复制内容。Themes 预览跟随既有不可见字符偏好。
- Diff 外层按块懒加载,每块正文是独立的 TextKit 1 文本区,原生字符选择只在块内跨行。行号栏与正文共享实际折行矩形,写入选区仍使用逻辑补丁行标识。
- 每个显示行记录显示 UTF-16 范围、源范围与所属补丁行;无换行提示单独成行但指向所属行。复制从源映射取字符,保留原始 Tab、CR 与已有的末尾 LF,不复制显示替换标记。
- 每块的行选择由独立模型管理,鼠标按下与拖动立即更新正文和行号,块头计数在松开时发布;键盘和辅助功能动作立即完成。范围使用显示行位置,写入只传逻辑行标识,无换行提示不增加选择单位。正文字符选区不受行选择影响。
- 工作区行选择由仓库会话持有,只保存当前文件条目与暂存侧;成功重载时按完整块原文字节复用模型,块序号仅用于当前快照寻址。块头、前缀、内容或无换行标记改变即退役旧模型,文件扩展头和其它块的变化不影响未变块。
- 换文件 / 侧、关闭、阈值变化,以及开启着色时当前主题变化会清空选择;按行写入被接受后只清发起块,取消确认或拒绝入队不清。视图复用同时重绑行号、正文与计数,迟到读取和旧范围事件不能回写新范围。
- 普通重载不按整个快照指纹重建视图;语法任务仍以安全指纹和有效着色开关为身份,并在发布前检查取消。核心补丁写入的快照校验独立于显示选择。
- 选中行号取系统选中色;正文按有效 Diff 语法着色开关选择字色或底色,不能用语法片段是否已读完代替。整块跟踪悬停,只有可操作行号格使用手形光标。
- 组合 Diff 在核心保留全部父范围、逐父前缀与行号向量,App 按父顺序及最后的结果列显示;第一父 / 结果的双侧投影仍供语法着色使用。组合块只读,不能生成按行补丁或匹配可写行。
- 提交详情、储藏详情与文件历史的只读 Diff 共用
ReadOnlyFileDiffView- 工作区、文件历史和整页提交的独立单文件块头吸顶;变更集内嵌的块头随内容滚动
- 块头高 32 pt,使用不透明的系统底色,分隔线绘制在高度内部;每个文件的首块无顶线,后续块仅在正常位置显示顶线,底线始终保留。吸顶状态从正文的自然位置判断,不依赖已浮动块头的位置
- 目录文件历史按完整变更集筛选真实新旧路径,每文件独立读取、放行与重试;当前提交和第一父提交的树条目决定目录范围与内容能力,不从 HEAD 推断历史类型。逐文件请求与可见登记有独立身份,换目标、关闭或重读时旧结果不能覆盖新状态。
- 语法着色经
SyntaxHighlighter借用 highlight.js 的上下文执行- 最多两份上下文,每份是一个
HighlightRuntimeactor,只在自己的串行队列上使用,由全局 actorSyntaxActor负责借还 - 一份被已取消的长任务占着时,新的请求由另一份接手
- 最多两份上下文,每份是一个