[!NOTE] 中文说明 远程资料拉取：把 GitHub / GitCode / Gitee 仓库里的笔记和资料一键下载到手机、平板的 Obsidian 中查看，全量覆盖与限速增量两种模式任选，只下载不回传。
典型用法：电脑端把 Obsidian 笔记持续推送到远程仓库（GitHub / GitCode / Gitee），手机和平板只负责看。本插件不做双向同步、不在移动端维护长期 git 仓库，而是通过 git smart HTTP 对远程仓库做一次浅克隆（depth=1，约 2 个请求拉全仓），按过滤规则把文件覆盖写入 vault 后即清理克隆数据——移动端不受 API 限流影响。另提供限速增量模式：与上次下载底账对比，只下载远端有变更的文件，按每分钟 N 个限速、支持断点续传，内存占用极小，适合超大仓库或平台限流场景；两种模式随时切换。
English description below for review purposes. / 以下为英文说明，用于过审。
XU Git Pull downloads notes one-way from a GitHub / GitCode / Gitee repository (public or private) into a phone or tablet vault for reading. It performs a shallow git clone (depth=1, roughly 2 HTTP requests for the whole repo) over smart HTTP, then writes the fetched files into the vault according to your filter rules and cleans up afterwards — immune to hosting-platform API rate limits, and built for the "write on desktop, read on mobile" one-way scenario. A throttled incremental mode is also available: it compares against the last-sync ledger and downloads only files changed on the remote, throttled to N files per minute with resume support and a tiny memory footprint.
- 移动端查看优先：电脑端推送远程仓库，手机/平板点一下即可获得最新资料，无需电脑、无需 git 客户端
- 双下载模式：全量覆盖（整仓克隆，最快）与限速增量（逐文件限速 + 断点续传，内存占用极小）下拉二选一，随时切换，桌面/手机各自记忆
- 整仓克隆、不限流：git 浅克隆约 2 个请求拉全仓，数千文件也不再触发平台 API 限流；克隆完成后按规则过滤写入
- 进度可见、随时取消：克隆阶段显示计时心跳，写盘阶段显示精确进度；点击状态栏 ⬇ 或设置页「停止下载」按钮即可中断，限速增量每 20 个文件落盘断点、中断续传
- 手机锁屏保护：下载期间自动保持屏幕常亮（Wake Lock），防止自动锁屏中断限速下载；手动锁屏仍会暂停，解锁后重新拉取自动续传
- 数据安全：全量覆盖模式只写入有变化的文件（本地内容哈希一致即跳过），不删除任何本地文件；限速增量模式会同步清理远程已删除的文件；两种模式都永远不会上传任何内容
- 私有库支持：填写平台 Token 即可拉取私有仓库（GitHub 推荐 fine-grained 只读令牌，Gitee/GitCode 用私人令牌）
- 响应式级联下拉：填入 Token 后仓库、分支、子目录全部自动实时加载；切换仓库或分支，下游列表自动跟着刷新；加载失败时下拉内点击重试，全程只选不填
- 本地目录建议：本地目标目录支持点击弹出库内目录建议列表（输入过滤、点击回填），也保留手动输入新目录
- 安全过滤：始终排除
.git/、.trash/、community-plugins.json、workspace.json，.obsidian/可开关，支持自定义 glob 排除规则 - 全平台可用：桌面、手机、平板均可使用，中英双语
- Built for reading on phones and tablets: pull the latest notes from GitHub / GitCode / Gitee with one tap, no git client required
- Shallow git clone fetches the whole repo in roughly 2 requests — no more platform API rate limits even with thousands of files; files are filtered into the vault after cloning
- Two download modes in a single dropdown: full clone (fastest) or throttled incremental (per-file rate limit with resume, tiny memory footprint); remembered separately on desktop and mobile
- Visible progress with instant cancel: heartbeat during clone, precise file count during write-out; cancel via the status bar or the "Stop download" button in settings; incremental mode checkpoints every 20 files with resume
- Screen-awake protection on mobile: the screen stays on during downloads (Wake Lock) so auto-lock can't interrupt a throttled sync; a manual lock still pauses it — pull again to resume
- Data safety: full-clone mode writes only changed files (hash-checked locally, nothing is deleted); incremental mode also removes files deleted on the remote; nothing is ever uploaded
- Private repositories supported via a fine-grained read-only token
- Reactive cascading dropdowns: repository, branch and subfolder load automatically and refresh in real time; switching a repo or branch re-fetches the lists below; a failed load offers a retry entry inside the dropdown — pick, don't type
- Folder suggestions for the local target path: tap to pick from vault folders with type-to-filter, manual input still supported
- Always excludes
.git/,.trash/,community-plugins.jsonandworkspace.json;.obsidian/is toggleable; custom glob patterns supported - Works on desktop, iOS/iPadOS and Android; bilingual Chinese/English UI
| 这个插件做 | 这个插件不做 |
|---|---|
| 把远程仓库（GitHub / GitCode / Gitee）的资料拉到本地查看 | 不上传、不回传本地修改 |
| 整仓克隆后一键覆盖更新 | 不做三方合并、不处理冲突 |
| 全量模式只增改不删除；增量模式同步远程删除 | 不提供提交历史、分支管理 |
克隆数据写盘后即清理，不留 .git 目录 |
不提供指定历史提交回退 |
| 适合：电脑端写、移动端看 | 不适合：移动端也要编辑并同步回电脑（请用 obsidian-git 等双向同步方案） |
建议把移动设备定位为只读终端：所有编辑在电脑端完成并推送，移动端只负责拉取和阅读。
- 打开 Obsidian 设置 → 社区插件
- 点击「浏览」，搜索 "XU Git Pull"
- 点击「安装」，然后「启用」
- 从 最新 Release 下载
main.js、manifest.json、styles.css三个文件（国内网络可在链接前加https://gh-proxy.com/加速） - 在 vault 中创建目录
.obsidian/plugins/xu-git-pull/ - 将三个文件放入该目录
- 打开 Obsidian 设置 → 社区插件，找到 XU Git Pull 并开启
手机端也可使用 BRAT 插件，添加仓库 xcloud-ai/xu-git-pull 完成安装。
From Obsidian Community Directory:
- Open Obsidian Settings → Community Plugins
- Click "Browse" and search for "XU Git Pull"
- Click "Install", then "Enable"
Manual Installation (Beta):
- Download
main.js,manifest.json,styles.cssfrom the latest release - Put them in
<vault>/.obsidian/plugins/xu-git-pull/ - Enable in Settings → Community Plugins
You can also install the beta with BRAT using xcloud-ai/xu-git-pull.
电脑端（资料来源）：正常用 Obsidian 写作，把 vault（或其中的笔记目录）推送到远程仓库（GitHub / GitCode / Gitee），公开或私有均可。
手机/平板（只看）：
- 新建或打开一个用于阅读的 vault，安装并启用插件
- 设置 → XU Git Pull：选择平台并粘贴对应 Token（私有库必填，旁有「创建 Token」按钮，点击自动复制创建页链接），输入框失焦后自动加载
- 仓库：下拉选择要阅读的仓库
- 分支：下拉选择分支（默认分支 = 最新内容）
- 仓库子目录（可选）：只拉某个文件夹；本地目标目录（可选）：在 vault 中的存放位置
- 下载模式：下拉二选一——全量覆盖（桌面推荐）/ 限速增量（手机、超大仓库推荐）
- 点击左侧边栏下载图标（或命令面板搜索「拉取远程仓库文件」）
- 插件按所选模式拉取：全量覆盖 = 验证 + 整仓克隆 + 哈希对账写盘（内容未变的文件自动跳过）；限速增量 = 与上次底账对比只下载变更文件（首次无底账时逐文件全量下载并建账，不使用克隆）。完成后通知汇总，即可阅读
日常使用只有一步：打开 vault → 点下载图标 → 等完成通知。
各平台私有库均需 Token（设置页「创建 Token」按钮点击后自动复制创建页链接，手机端可把链接转发到电脑打开）：
- GitHub：https://github.com/settings/personal-access-tokens/new（fine-grained，推荐）→ Repository access 勾选笔记仓库 → Contents 选 Read-only（其余权限一律不给）→ 生成
github_pat_开头令牌 - GitCode：设置 → 安全设置 → 私人令牌（classic）：https://gitcode.com/setting/token-classic/create → 生成令牌
- Gitee：设置 → 安全设置 → 私人令牌：https://gitee.com/profile/personal_access_tokens → 生成令牌
安全须知：Token 只保存在本机 data.json 中；若 vault 开启了 iCloud 等同步，请使用短期、只读、可随时吊销的令牌，且不要把 data.json 提交到任何仓库。
- Push notes from your computer to a remote repository (GitHub / GitCode / Gitee, public or private)
- On the phone/tablet, open XU Git Pull settings, pick the platform and paste a token (required for private repos; the button copies the token-creation link), then pick the repository, branch and optional subfolder from the dropdowns
- Pick a download mode in the dropdown: full clone (desktop) or throttled incremental (mobile / very large repos)
- Tap the download ribbon icon (or run "Pull remote repository files" from the command palette)
- The plugin pulls according to the selected mode: full clone = verify + shallow clone + hash-checked write-out (unchanged files skipped); throttled incremental = downloads only changed files against the last-sync ledger (first run downloads file-by-file to build the ledger, no clone). A summary notice appears when done
The plugin is one-way: it only adds or updates local files, never uploads.
| 设置项 | 说明 |
|---|---|
| 界面语言 | 中文 / English，默认中文 |
| 平台 | 🇨🇳 GitCode / 🌐 GitHub / Gitee；切换平台后，令牌、仓库、分支、子目录、本地目录整组配置跟随平台切换，各平台独立记忆，无需二次配置 |
| 访问令牌（Token） | 私有库必填，公开库可不填；各平台令牌独立保存、切换互不影响；「创建 Token」按钮点击后复制创建页链接；填入后下方仓库、分支、子目录自动变为下拉选择 |
| 仓库 | 有 Token 时为下拉选择（令牌可访问的全部仓库，打开设置页自动实时加载）；无 Token 时手动输入 owner/repo（仅公开库），支持嵌套命名空间 |
| 分支 | 下拉选择远程分支；「默认分支（最新）」跟随仓库默认分支；切换仓库后自动重拉 |
| 仓库子目录 | 下拉选择后只拉取该目录；「/（整个仓库）」为默认；切换仓库/分支后自动重拉 |
| 本地目标目录 | 下载到 vault 中的位置，留空为 vault 根目录；点击输入框可弹出库内目录建议（输入过滤、点击回填），也支持手动输入尚不存在的新目录（下载时自动逐级创建） |
| 下载模式 | 下拉单选：全量覆盖（整仓克隆，最快）/ 限速增量（逐文件限速 + 断点续传，内存占用极小）；桌面与手机各自记忆 |
| 每分钟请求数 | 仅限速增量模式显示；GitCode 建议 40、GitHub 60、Gitee 50，0 = 全速 |
| 停止下载 | 中断插件正在进行的下载（克隆/增量全程生效，点击即停） |
| 下载时保持屏幕常亮 | 默认开启；下载期间保持屏幕常亮（Wake Lock）防自动锁屏中断，手动锁屏仍会暂停（断点续传兜底） |
| 下载 .obsidian 配置目录 | 默认开启，同步 .obsidian/（插件与外观配置跟随仓库）；不希望覆盖本机配置时手动关闭 |
| 额外排除规则 | 每行一条 glob，** 匹配任意层级、* 单级；.git/、.trash/、community-plugins.json、workspace.json 始终排除 |
| 命令 | 作用 |
|---|---|
| 拉取远程仓库文件 | 按当前设置（平台/仓库/模式）从远程同步到本地 |
- 通过 git smart HTTP 对远程仓库做浅克隆（depth=1）：
info/refs?service=git-upload-pack+upload-pack两个请求拉全仓，与 REST API 是两套独立配额，实测 GitCode 连发多次零限流 - 三平台（GitHub / GitCode / Gitee）git 协议认证统一为 Basic
oauth2:<令牌>，克隆链路完全一致；GitCode 275MB / 6014 文件大仓与 Gitee 真实仓库均已实测通过 - 克隆由内置的 isomorphic-git（v1.44.2）+ LightningFS 完成，全部打包进 main.js，零外部 require 依赖，桌面/移动端行为一致；克隆数据写入内存级 IndexedDB 文件系统，写盘完成后清理
- 写盘按过滤规则执行：始终排除
.git/、.trash/、community-plugins.json、workspace.json（设备本地状态），.obsidian/默认同步（可开关关闭），支持自定义 glob - 写盘哈希对账：本地文件逐个计算 git blob SHA-1 与远端比对，内容一致直接跳过（省读省写），本地改过或新增的文件才写入；全量模式不删除任何本地文件
- 限速增量链路：tree API 拉全量清单（GitCode 自动翻页，单页失败自动退避重试、仍失败立即中止，绝不因残缺清单误删本地文件）→ 与底账对比 → blobs API 逐文件下载（限流自动等待重试）→ 每 20 个文件落盘断点、中断续传；单文件超过 20MB 自动跳过（移动端内存保护）；远程已删除文件自动同步清理
- 设置加载采用逐字段类型校验（v2.0）：旧版本/异常格式的 data.json 在加载时自动归位为合法值，杜绝格式穿透导致的设置失效
- 设置页为经典
display()API（v2.0）：单下拉单值、无联动控件，模式/平台切换后全量重绘，从根上避免开关联动竞态 - 设置页级联下拉（仓库/分支/子目录）实时响应：打开设置页或切换 Token/平台/仓库/分支时自动按依赖顺序重拉（仓库 → 分支 → 子目录），轮次编号守卫防快速连续切换乱序，30 秒节流防重绘循环；列表加载中与加载失败均在下拉内以占位项呈现（失败项点击即重试）
- 本地目标目录采用官方 AbstractInputSuggest 目录建议弹层：点击/输入弹出库内全部目录（不限量、大小写过滤），点击回填；保留手动输入能力以支持新目录
- 手机端下载期间通过 Screen Wake Lock API 保持屏幕常亮（仅移动端生效，不支持该 API 的设备提示降级），结束/取消/出错自动释放，切后台回前台自动重取
- 克隆超时 5 分钟；拉取中点击状态栏 ⬇ 即可取消（克隆完成后跳过写入）；401/403/404 等验证失败均有本地化错误提示
- 无 Node/Electron 专有 API，
isDesktopOnly: false，支持 iOS/iPadOS/Android
MIT License - Copyright (c) 2026 旭说