XU Git Pull
xcloud-ai8 downloads远程资料拉取：从 GitHub 公开/私有仓库拉取指定分支或提交的文件到本地 vault，差异预览后一键覆盖，手机平板单向同步资料.
- Overview
- Scorecard
- Updates3
[!NOTE] 中文说明 远程资料拉取：把 GitHub / GitCode / Gitee 仓库里的笔记和资料一键下载到手机、平板的 Obsidian 中查看，差异可见、一键覆盖，只下载不回传。
典型用法：电脑端把 Obsidian 笔记持续推送到远程仓库（GitHub / GitCode / Gitee），手机和平板只负责看。本插件不做双向同步、不在移动端维护 git 仓库，而是直接调用托管平台 API 逐文件比对、按需下载——没有 .git 目录、不解包 packfile，移动端内存占用小，专为「电脑推、移动看」的单向场景设计。
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 calls the hosting platform's API to list files, compares git blob SHAs, previews added/modified files, and overwrites with one tap. It never uploads, never deletes local files, and keeps no .git folder — a lightweight, mobile-friendly alternative to full git sync plugins for read-only mobile devices.
功能特性
- 移动端查看优先：电脑端推送远程仓库，手机/平板点一下即可获得最新资料，无需电脑、无需 git 客户端
- 差异预览、一键覆盖：自动比对远程与本地，按「新增 / 修改 / 无变化」分类展示，确认后一次下载，差异文件直接覆盖
- 只增改、不删除：远程删掉的文件本地保留；移动端本地文件不会被误删，也永远不会上传任何内容
- 私有库支持：填写平台 Token 即可拉取私有仓库（GitHub 推荐 fine-grained 只读令牌，Gitee/GitCode 用私人令牌）
- Token 级联下拉：填入 Token 后，仓库、分支、提交、子目录全部自动加载为下拉框，全程只选不填，避免输错
- 版本回退：可在设置中下拉选择某一次提交，始终拉取该版本（默认跟随分支最新）
- 安全过滤：默认排除
.obsidian/配置目录（可开关），始终排除.git/、.trash/，支持自定义 glob 排除规则 - 全平台可用：桌面、手机、平板均可使用，中英双语
Features
- Built for reading on phones and tablets: pull the latest notes from GitHub / GitCode / Gitee with one tap, no git client required
- Preview added / modified / unchanged files via git blob SHA comparison, then overwrite in one tap
- One-way only: files are added or updated, never deleted, and nothing is ever uploaded
- Private repositories supported via a fine-grained read-only token
- Cascading dropdowns for repository, branch, commit and subfolder after entering a token — pick, don't type
- Optionally pin a specific commit from a dropdown; follows the branch latest by default
- Excludes
.obsidian/by default (toggleable), always excludes.git/and.trash/, custom glob patterns supported - Works on desktop, iOS/iPadOS and Android; bilingual Chinese/English UI
适用场景与边界
| 这个插件做 | 这个插件不做 |
|---|---|
| 把远程仓库（GitHub / GitCode / Gitee）的资料拉到本地查看 | 不上传、不回传本地修改 |
| 差异预览后一键覆盖更新 | 不做三方合并、不处理冲突 |
| 只增改文件，不删除本地文件 | 不同步删除操作 |
无 .git 目录，移动端轻量 |
不提供提交历史、分支管理 |
| 适合：电脑端写、移动端看 | 不适合：移动端也要编辑并同步回电脑（请用 obsidian-git 等双向同步方案） |
建议把移动设备定位为只读终端：所有编辑在电脑端完成并推送，移动端只负责拉取和阅读。
安装
方式一：从 Obsidian 社区目录安装（推荐）
- 打开 Obsidian 设置 → 社区插件
- 点击「浏览」，搜索 "XU Git Pull"
- 点击「安装」，然后「启用」
方式二：手动安装（Beta）
- 从 最新 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 完成安装。
Installation
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 提交到任何仓库。
Usage
- 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; buttons copy the link and open the docs/creation page), then pick the repository, branch and optional subfolder from the dropdowns
- Tap the download ribbon icon (or run "Pull remote files" from the command palette)
- Review added / modified / unchanged files, then tap "Download all"
The plugin is one-way: it only adds or updates local files, never uploads or deletes.
设置说明
| 设置项 | 说明 |
|---|---|
| 界面语言 | 中文 / English，默认中文 |
| 代码托管平台 | 国内（🇨🇳 GitCode、Gitee）与国外（🌍 GitHub）分组下拉；当前版本已适配 GitHub、GitCode 与 Gitee（三平台 API 同构），其他平台后续按需添加。切换平台后，仓库、分支、提交、子目录、本地目录整组配置跟随平台切换，各平台独立记忆（未配置则为空），无需二次配置 |
| 平台 Token（如 GitHub Token） | 名称与帮助文档跟随所选平台，各平台令牌独立保存、切换互不影响；私有库必填，填入后下方仓库、分支、提交、子目录自动变为下拉选择；公开库可不填。「如何创建 / 直接创建」按钮点击后复制链接并打开，手机端可把链接转发到电脑操作 |
| 仓库地址 | 有 Token 时为下拉选择（令牌可访问的全部仓库）；无 Token 时手动输入 owner/repo（仅公开库） |
| 分支 | 下拉选择远程分支；留空项「默认分支（最新）」跟随仓库默认分支 |
| 指定提交 | 默认「跟随分支最新」；下拉选择某次提交后始终拉取该版本（列出所选分支最近 30 次），适合推送出错后回退 |
| 仓库内子目录 | 下拉选择后只拉取该目录；「/（整个仓库）」为默认 |
| 本地目标目录 | 下载到 vault 中的位置，留空为 vault 根目录 |
| 下载 .obsidian 配置目录 | 默认关闭，避免移动端配置被仓库覆盖；需要同步插件配置时手动开启 |
| 额外排除规则 | 每行一条 glob，** 匹配任意层级；.git/、.trash/ 始终排除 |
命令列表
| 命令 | 作用 |
|---|---|
| 拉取远程文件（比对后覆盖） | 获取远程文件清单，比对本地并弹出差异预览，确认后一键下载覆盖 |
技术说明
- 不使用 isomorphic-git，不执行 clone/fetch/merge：文件清单走 Tree API（
/git/trees/{ref}?recursive=1），本地文件按 git 规则计算 blob SHA-1（blob <大小>\0<内容>）与清单逐文件比对，无变化的文件零流量 - 文件下载双通道：配置 Token 时走 blob API（
/git/blobs/{sha}，base64 解码，支持私有库与大文件）；匿名时 GitHub 走 raw 域名，GitCode/Gitee 公开库匿名走 blob API（已实测） - 级联下拉数据分页获取并按令牌缓存（仓库、分支、提交、目录树），切换仓库/分支自动清空下游选择，过期请求自动丢弃
- 频率限额由各平台决定（GitHub 匿名 60 次/小时、带 Token 5000 次/小时）；401/403/404 均有中文错误提示
- 配置 Token 后运行时只访问对应平台 API 域名（
api.github.com/api.gitcode.com/gitee.com）；符号链接自动跳过，含..的路径一律拒绝以防越界 - 无 Node/Electron 专有 API，
isDesktopOnly: false，支持 iOS/iPadOS/Android
许可证
MIT License - Copyright (c) 2026 旭说