ru

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RU - Repo Updater

RU - 仓库更新工具

A comprehensive Bash CLI for synchronizing dozens or hundreds of GitHub repositories. Beyond basic sync, RU includes a full AI-assisted code review system and agent-sweep capability for automatically processing uncommitted changes across your entire projects directory.

这是一款功能全面的Bash命令行工具，用于同步数十个乃至数百个GitHub仓库。除了基础同步功能外，RU还内置了完整的AI辅助代码评审系统，以及Agent扫描功能，可自动处理你所有项目目录中的未提交更改。

Why This Exists

开发背景

When you work with 47+ repos (personal projects, forks, dependencies), keeping them synchronized manually is tedious. But synchronization is just the beginning—RU also orchestrates AI coding agents to review issues, process PRs, and commit uncommitted work at scale.

The problem it solves:

Manual
```
cd ~/project && git pull
```
for each repo
Missing updates that accumulate into merge conflicts
Dirty repos that never get committed
Issues and PRs that pile up across repositories
No coordination for AI agents working across repos

当你同时维护47个以上的仓库（个人项目、复刻仓库、依赖库）时，手动同步这些仓库会非常繁琐。但同步只是基础——RU还能编排AI编码Agent来评审问题、处理PR（拉取请求），并批量提交未完成的工作。

它解决的问题：

手动执行
```
cd ~/project && git pull
```
来同步每个仓库
遗漏更新导致合并冲突累积
存在未提交更改的脏仓库一直得不到处理
跨仓库的问题和PR堆积
缺乏对跨仓库工作的AI Agent协调机制

Critical Concepts

核心概念

Git Plumbing, Not Porcelain

使用Git底层命令，而非上层命令

RU uses git plumbing commands exclusively—never parses human-readable output:

bash

undefined

RU仅使用Git底层（plumbing）命令——从不解析人类可读的输出：

bash

undefined

WRONG: Locale-dependent, version-fragile

错误示例：依赖本地化环境，版本兼容性差

git pull 2>&1 | grep "Already up to date"

RIGHT: Machine-readable plumbing

正确示例：机器可读的底层命令

git rev-list --left-right --count HEAD...@{u} git status --porcelain git rev-parse HEAD

undefined

git rev-list --left-right --count HEAD...@{u} git status --porcelain git rev-parse HEAD

undefined

Stream Separation

流分离

Human-readable output goes to stderr; data to stdout:

bash

ru sync --json 2>/dev/null | jq '.summary'

人类可读的输出会发送到stderr；数据则发送到stdout：

bash

ru sync --json 2>/dev/null | jq '.summary'

Progress shows in terminal, JSON pipes to jq

进度信息显示在终端，JSON数据通过管道传给jq

undefined

undefined

No Global

cd

无全局目录切换

All git operations use

git -C

. Never changes working directory.

所有Git操作都使用

git -C

命令，绝不会更改当前工作目录。

Essential Commands

核心命令

Sync (Primary Use Case)

同步（主要使用场景）

bash

undefined

bash

undefined

Sync all configured repos

同步所有已配置的仓库

ru sync

Parallel sync (much faster)

并行同步（速度更快）

ru sync -j8

Dry run - see what would happen

试运行：查看会执行哪些操作

ru sync --dry-run

Resume interrupted sync

恢复中断的同步任务

ru sync --resume

JSON output for scripting

输出JSON格式结果用于脚本处理

ru sync --json 2>/dev/null | jq '.summary'

undefined

ru sync --json 2>/dev/null | jq '.summary'

undefined

Status (Read-Only Check)

状态检查（只读）

bash

undefined

bash

undefined

Check all repos without modifying

检查所有仓库状态，不做任何修改

ru status

JSON output

输出JSON格式结果

ru status --json

undefined

ru status --json

undefined

Repo Management

仓库管理

bash

undefined

bash

undefined

Initialize configuration

初始化配置

ru init

Add repos to sync list

添加仓库到同步列表

ru add owner/repo ru add https://github.com/owner/repo ru add owner/repo@branch as custom-name

Remove from list

从列表中移除仓库

ru remove owner/repo

List configured repos

列出已配置的仓库

ru list

Detect orphaned repos (in projects dir but not in list)

检测孤立仓库（存在于项目目录但未在同步列表中）

ru prune # Preview ru prune --delete # Actually remove ru prune --archive # Move to archive directory

undefined

ru prune # 预览 ru prune --delete # 实际移除 ru prune --archive # 移动到归档目录

undefined

Diagnostics

诊断工具

bash

ru doctor      # System health check
ru self-update # Update ru itself

bash

ru doctor      # 系统健康检查
ru self-update # 更新RU本身

AI-Assisted Review System

AI辅助评审系统

RU includes a powerful review orchestration system for managing AI-assisted code review across your repositories.

RU内置了强大的评审编排系统，用于跨仓库管理AI辅助代码评审。

Two-Phase Review Workflow

两阶段评审工作流

Phase 1: Discovery (
--plan
)

Queries GitHub for open issues and PRs across all repos
Scores items by priority using label analysis and age
Creates isolated git worktrees for safe review
Spawns Claude Code sessions in terminal multiplexer

Phase 2: Application (
--apply
)

Reviews proposed changes from discovery phase
Runs quality gates (ShellCheck, tests, lint)
Optionally pushes approved changes (
```
--push
```
)

bash

undefined

阶段1：发现（
--plan
）

查询所有仓库在GitHub上的未解决问题和PR
通过标签分析和存在时长对项目进行优先级评分
创建独立的Git工作树以安全开展评审
在终端复用器中启动Claude Code会话

阶段2：执行（
--apply
）

评审发现阶段提出的更改建议
运行质量检查门（ShellCheck、测试、代码扫描）
可选择推送已批准的更改（
```
--push
```
）

bash

undefined

Discover and plan reviews

发现并规划评审任务

ru review --plan

After reviewing AI suggestions

评审AI建议后执行

ru review --apply --push

undefined

ru review --apply --push

undefined

Priority Scoring Algorithm

优先级评分算法

Factor	Points	Logic
Type	0-20	PRs: +20, Issues: +10, Draft PRs: -15
Labels	0-50	security/critical: +50, bug/urgent: +30
Age (bugs)	0-50	>60 days: +50, >30 days: +30
Recency	0-15	Updated <3 days: +15, <7 days: +10
Staleness	-20	Recently reviewed: -20

Priority levels: CRITICAL (≥150), HIGH (≥100), NORMAL (≥50), LOW (<50)

因素	分值	逻辑
类型	0-20	PR：+20，问题：+10，草稿PR：-15
标签	0-50	security/critical（安全/严重）：+50，bug/urgent（Bug/紧急）：+30
存在时长（Bug）	0-50	超过60天：+50，超过30天：+30
更新时间	0-15	3天内更新：+15，7天内更新：+10
陈旧度	-20	近期已评审：-20

优先级等级：CRITICAL（≥150）、HIGH（≥100）、NORMAL（≥50）、LOW（<50）

Session Drivers

会话驱动

Driver	Description	Best For
`auto`	Auto-detect best available	Default
`ntm`	Named Tmux Manager integration	Multi-agent workflows
`local`	Direct tmux sessions	Simple setups

bash

ru review --mode=ntm --plan
ru review -j 4 --plan  # Parallel sessions

驱动	描述	最佳适用场景
`auto`	自动检测最佳可用驱动	默认选项
`ntm`	集成Named Tmux Manager	多Agent工作流
`local`	直接使用tmux会话	简单部署场景

bash

ru review --mode=ntm --plan
ru review -j 4 --plan  # 并行会话

Cost Budgets

成本预算控制

bash

ru review --max-repos=10 --plan
ru review --max-runtime=30 --plan  # Minutes
ru review --skip-days=14 --plan    # Skip recently reviewed
ru review --analytics              # View past review stats

bash

ru review --max-repos=10 --plan
ru review --max-runtime=30 --plan  # 分钟
ru review --skip-days=14 --plan    # 跳过近期已评审的仓库
ru review --analytics              # 查看过往评审统计数据

Agent Sweep (Automated Dirty Repo Processing)

Agent扫描（脏仓库自动处理）

The

ru agent-sweep

command orchestrates AI coding agents to automatically process repositories with uncommitted changes.

ru agent-sweep

命令可编排AI编码Agent，自动处理存在未提交更改的仓库。

Basic Usage

基础用法

bash

undefined

bash

undefined

Process all repos with uncommitted changes

处理所有存在未提交更改的仓库

ru agent-sweep

Dry run - preview what would be processed

试运行：预览会处理哪些内容

ru agent-sweep --dry-run

Process 4 repos in parallel

并行处理4个仓库

ru agent-sweep -j4

Filter to specific repos

筛选特定仓库

ru agent-sweep --repos="myproject*"

Include release step after commit

提交后包含发布步骤

ru agent-sweep --with-release

Resume interrupted sweep

恢复中断的扫描任务

ru agent-sweep --resume

Start fresh

重新开始扫描

ru agent-sweep --restart

undefined

ru agent-sweep --restart

undefined

Three-Phase Agent Workflow

三阶段Agent工作流

Phase 1: Planning (

--phase1-timeout

, default 300s)

Claude Code analyzes uncommitted changes
Determines which files should be staged (respecting denylist)
Generates structured commit message

Phase 2: Commit (

--phase2-timeout

, default 600s)

Validates the plan (file existence, denylist compliance)
Stages approved files, creates commit
Runs quality gates
Optionally pushes to remote

Phase 3: Release (

--phase3-timeout

, default 300s, requires

--with-release

)

Analyzes commit history since last tag
Determines version bump (patch/minor/major)
Creates git tag and optionally GitHub release

阶段1：规划（

--phase1-timeout

，默认300秒）

Claude Code分析未提交的更改
确定哪些文件应被暂存（遵循拒绝列表）
生成结构化的提交信息

阶段2：提交（

--phase2-timeout

，默认600秒）

验证规划（文件存在性、是否符合拒绝列表）
暂存已批准的文件，创建提交
运行质量检查门
可选择推送到远程仓库

阶段3：发布（

--phase3-timeout

，默认300秒，需配合

--with-release

使用）

分析自上次标签以来的提交历史
确定版本升级类型（补丁/小版本/大版本）
创建Git标签，可选创建GitHub发布版本

Execution Modes

执行模式

bash

--execution-mode=agent  # Full AI-driven workflow (default)
--execution-mode=plan   # Phase 1 only: generate plan, stop
--execution-mode=apply  # Phase 2+3: execute existing plan

bash

--execution-mode=agent  # 完整AI驱动工作流（默认）
--execution-mode=plan   # 仅阶段1：生成规划后停止
--execution-mode=apply  # 阶段2+3：执行已有的规划

Preflight Checks

预检检查

Each repo is validated before spawning an agent:

Check	Skip Reason
Is git repository	`not_a_git_repo`
Git email configured	`git_email_not_configured`
Not a shallow clone	`shallow_clone`
No rebase in progress	`rebase_in_progress`
No merge in progress	`merge_in_progress`
Not detached HEAD	`detached_HEAD`
Has upstream branch	`no_upstream_branch`
Not diverged	`diverged_from_upstream`

在启动Agent前，会对每个仓库进行验证：

检查项	跳过原因
是否为Git仓库	`not_a_git_repo`
是否已配置Git邮箱	`git_email_not_configured`
是否为完整克隆（非浅克隆）	`shallow_clone`
是否正在进行变基	`rebase_in_progress`
是否正在进行合并	`merge_in_progress`
是否为分离HEAD状态	`detached_HEAD`
是否存在上游分支	`no_upstream_branch`
是否与上游分支分叉	`diverged_from_upstream`

Security Guardrails

安全防护

File Denylist - Never committed regardless of agent output:

Category	Patterns
Secrets	`.env` , `.pem` , `.key` , `id_rsa*` , `credentials.json`
Build artifacts	`node_modules` , `__pycache__` , `dist` , `build` , `target`
Logs/temp	`.log` , `.tmp` , `*.swp` , `.DS_Store`
IDE files	`.idea` , `.vscode` , `*.iml`

Secret Scanning:

bash

--secret-scan=none   # Disable
--secret-scan=warn   # Warn but continue (default)
--secret-scan=block  # Block push on detection

文件拒绝列表 - 无论Agent输出如何，这些文件绝不会被提交：

类别	匹配模式
敏感信息	`.env` , `.pem` , `.key` , `id_rsa*` , `credentials.json`
构建产物	`node_modules` , `__pycache__` , `dist` , `build` , `target`
日志/临时文件	`.log` , `.tmp` , `*.swp` , `.DS_Store`
IDE文件	`.idea` , `.vscode` , `*.iml`

敏感信息扫描：

bash

--secret-scan=none   # 禁用
--secret-scan=warn   # 仅警告但继续执行（默认）
--secret-scan=block  # 检测到敏感信息时阻止推送

Exit Codes

退出码

Code	Meaning
`0`	All repos processed successfully
`1`	Some repos failed (agent error, timeout)
`2`	Quality gate failures (secrets, tests)
`3`	System error (ntm, tmux missing)
`4`	Invalid arguments
`5`	Interrupted (use `--resume` )

代码	含义
`0`	所有仓库处理成功
`1`	部分仓库处理失败（Agent错误、超时）
`2`	质量检查门失败（敏感信息、测试不通过）
`3`	系统错误（缺少ntm、tmux）
`4`	参数无效
`5`	任务被中断（使用 `--resume` 恢复）

Configuration

配置

XDG-Compliant Directory Structure

符合XDG标准的目录结构

~/.config/ru/
├── config               # Main config file
└── repos.d/
    ├── public.list      # Public repos (one per line)
    └── private.list     # Private repos (gitignored)

~/.local/state/ru/
├── logs/
│   └── YYYY-MM-DD/
├── agent-sweep/
│   ├── state.json
│   └── results.ndjson
└── review/
    ├── digests/
    └── results/

~/.config/ru/
├── config               # 主配置文件
└── repos.d/
    ├── public.list      # 公共仓库（每行一个）
    └── private.list     # 私有仓库（已加入git忽略）

~/.local/state/ru/
├── logs/
│   └── YYYY-MM-DD/
├── agent-sweep/
│   ├── state.json
│   └── results.ndjson
└── review/
    ├── digests/
    └── results/

Repo List Format

仓库列表格式

undefined

undefined

~/.config/ru/repos.d/public.list

owner/repo another-owner/another-repo@develop private-org/repo@main as local-name https://github.com/owner/repo.git

undefined

owner/repo another-owner/another-repo@develop private-org/repo@main as local-name https://github.com/owner/repo.git

undefined

Layout Modes

目录布局模式

Layout	Example Path
`flat`	`/data/projects/repo`
`owner-repo`	`/data/projects/owner_repo`
`full`	`/data/projects/github.com/owner/repo`

bash

ru config --set LAYOUT=owner-repo

布局	示例路径
`flat`	`/data/projects/repo`
`owner-repo`	`/data/projects/owner_repo`
`full`	`/data/projects/github.com/owner/repo`

bash

ru config --set LAYOUT=owner-repo

Per-Repo Configuration

仓库级配置

yaml

undefined

yaml

undefined

~/.../your-repo/.ru-agent.yml

agent_sweep: enabled: true max_file_size: 5242880 # 5MB extra_context: "This is a Python project using FastAPI" pre_hook: "make lint" post_hook: "make test" denylist_extra: - ".backup" - "internal/"

undefined

undefined

ntm Integration

ntm集成

When ntm (Named Tmux Manager) is available, RU uses its robot mode API:

Function	Purpose
`ntm --robot-spawn`	Create Claude Code session in new tmux pane
`ntm --robot-send`	Send prompts with chunking for long messages
`ntm --robot-wait`	Block until session completes with timeout
`ntm --robot-activity`	Query real-time session state
`ntm --robot-status`	Get status of all managed sessions
`ntm --robot-interrupt`	Send Ctrl+C to interrupt long operations

当ntm（Named Tmux Manager）可用时，RU会使用其机器人模式API：

功能	用途
`ntm --robot-spawn`	在新的tmux面板中创建Claude Code会话
`ntm --robot-send`	发送带分块的长消息
`ntm --robot-wait`	阻塞等待会话完成，带超时机制
`ntm --robot-activity`	查询实时会话状态
`ntm --robot-status`	获取所有受管会话的状态
`ntm --robot-interrupt`	发送Ctrl+C中断长时间操作

Output Modes

输出模式

JSON Mode (

--json

)

JSON模式（

--json

）

bash

ru sync --json 2>/dev/null

json

{
  "version": "1.2.0",
  "timestamp": "2025-01-03T14:30:00Z",
  "summary": {
    "total": 47,
    "cloned": 8,
    "updated": 34,
    "current": 3,
    "conflicts": 2
  },
  "repos": [...]
}

bash

ru sync --json 2>/dev/null

json

{
  "version": "1.2.0",
  "timestamp": "2025-01-03T14:30:00Z",
  "summary": {
    "total": 47,
    "cloned": 8,
    "updated": 34,
    "current": 3,
    "conflicts": 2
  },
  "repos": [...]
}

NDJSON Results Logging

NDJSON结果日志

json

{"repo":"mcp_agent_mail","action":"pull","status":"updated","duration":2}
{"repo":"beads_viewer","action":"clone","status":"cloned","duration":5}

json

{"repo":"mcp_agent_mail","action":"pull","status":"updated","duration":2}
{"repo":"beads_viewer","action":"clone","status":"cloned","duration":5}

jq Examples

jq使用示例

bash

undefined

bash

undefined

Get paths of all cloned repos

获取所有已克隆仓库的路径

ru sync --json 2>/dev/null | jq -r '.repos[] | select(.action=="clone") | .path'

Count by status

按状态统计数量

cat ~/.local/state/ru/logs/latest/results.ndjson | jq -s 'group_by(.status) | map({status: .[0].status, count: length})'

undefined

cat ~/.local/state/ru/logs/latest/results.ndjson | jq -s 'group_by(.status) | map({status: .[0].status, count: length})'

undefined

Update Strategies

更新策略

bash

ru sync                        # Default: ff-only (safest)
ru sync --rebase               # Rebase local commits
ru sync --autostash            # Auto-stash before pull
ru sync --force                # Force update (use with caution)

Strategy	Behavior
`ff-only`	Fast-forward only; fails if diverged
`rebase`	Rebase local commits on top of remote
`merge`	Create merge commit if needed

bash

ru sync                        # 默认：ff-only（最安全）
ru sync --rebase               # 变基本地提交
ru sync --autostash            # 拉取前自动暂存
ru sync --force                # 强制更新（谨慎使用）

策略	行为
`ff-only`	仅快进合并；若分支分叉则失败
`rebase`	将本地提交变基到远程分支之上
`merge`	必要时创建合并提交

Quality Gates

质量检查门

Before applying changes, RU runs automated quality gates:

Auto-detection by project type:

Project Type	Test Command	Lint Command
npm/yarn	`npm test`	`npm run lint`
Cargo (Rust)	`cargo test`	`cargo clippy`
Go	`go test ./...`	`golangci-lint run`
Python	`pytest`	`ruff check`
Makefile	`make test`	`make lint`
Shell scripts	(none)	`shellcheck *.sh`

在应用更改前，RU会自动运行质量检查：

按项目类型自动检测：

项目类型	测试命令	代码扫描命令
npm/yarn	`npm test`	`npm run lint`
Cargo（Rust）	`cargo test`	`cargo clippy`
Go	`go test ./...`	`golangci-lint run`
Python	`pytest`	`ruff check`
Makefile	`make test`	`make lint`
Shell脚本	无	`shellcheck *.sh`

Rate Limiting

速率限制

RU includes an adaptive parallelism governor:

Condition	Action
GitHub remaining < 100	Reduce parallelism to 1
GitHub remaining < 500	Reduce parallelism by 50%
Model 429 detected	Pause new sessions for 60s
Error rate > 50%	Open circuit breaker

RU包含自适应并行度调节机制：

条件	操作
GitHub剩余请求数 < 100	将并行度降低至1
GitHub剩余请求数 < 500	将并行度降低50%
检测到模型429错误	暂停新会话60秒
错误率 > 50%	触发断路机制

Exit Codes (Sync)

同步功能退出码

Code	Meaning
`0`	Success - all repos synced or current
`1`	Partial failure - some repos failed
`2`	Conflicts exist
`3`	Dependency error (gh missing, auth failed)
`4`	Invalid arguments
`5`	Interrupted (use `--resume` )

代码	含义
`0`	成功：所有仓库已同步或已是最新状态
`1`	部分失败：部分仓库同步失败
`2`	存在冲突
`3`	依赖错误（缺少gh、认证失败）
`4`	参数无效
`5`	任务被中断（使用 `--resume` 恢复）

Environment Variables

环境变量

Variable	Description	Default
`RU_PROJECTS_DIR`	Base directory for repos	`/data/projects`
`RU_LAYOUT`	Path layout	`flat`
`RU_PARALLEL`	Parallel workers	`1`
`RU_TIMEOUT`	Network timeout (seconds)	`30`
`RU_UPDATE_STRATEGY`	Pull strategy	`ff-only`
`GH_TOKEN`	GitHub token	(from gh CLI)

变量	描述	默认值
`RU_PROJECTS_DIR`	仓库基础目录	`/data/projects`
`RU_LAYOUT`	目录布局	`flat`
`RU_PARALLEL`	并行工作进程数	`1`
`RU_TIMEOUT`	网络超时（秒）	`30`
`RU_UPDATE_STRATEGY`	拉取策略	`ff-only`
`GH_TOKEN`	GitHub令牌	来自gh CLI

Troubleshooting

故障排查

Common Issues

常见问题

Issue	Fix
`gh: command not found`	`brew install gh && gh auth login`
`gh: auth required`	`gh auth login` or set `GH_TOKEN`
`Cannot fast-forward`	Use `--rebase` or push first
`dirty working tree`	Commit changes or use `--autostash`
`diverged_from_upstream`	`git fetch && git rebase origin/main`

问题	解决方法
`gh: command not found`	`brew install gh && gh auth login`
`gh: auth required`	`gh auth login` 或设置 `GH_TOKEN`
`Cannot fast-forward`	使用 `--rebase` 或先推送本地更改
`dirty working tree`	提交更改或使用 `--autostash`
`diverged_from_upstream`	`git fetch && git rebase origin/main`

Debug Mode

调试模式

bash

undefined

bash

undefined

View latest run log

查看最新运行日志

cat ~/.local/state/ru/logs/latest/run.log

View specific repo log

查看特定仓库的日志

cat ~/.local/state/ru/logs/latest/repos/mcp_agent_mail.log

Run with verbose output

启用详细输出运行

ru agent-sweep --verbose --debug

undefined

ru agent-sweep --verbose --debug

undefined

Preflight Failure Debugging

预检失败调试

bash

undefined

bash

undefined

View why repos were skipped

查看仓库被跳过的原因

ru agent-sweep --json 2>/dev/null | jq '.repos[] | select(.status == "skipped")'

undefined

ru agent-sweep --json 2>/dev/null | jq '.repos[] | select(.status == "skipped")'

undefined

Installation

安装

bash

undefined

bash

undefined

One-liner

一键安装

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/repo_updater/main/install.sh | bash

Verify

验证安装

ru doctor

undefined

ru doctor

undefined

Architecture Notes

架构说明

~17,700 LOC pure Bash, no external dependencies beyond git, curl, gh
Work-stealing queue for parallel sync with atomic dequeue
Portable locking via
```
mkdir
```
(works on all POSIX systems)
Path security validation prevents traversal attacks
Retry with exponential backoff for network operations

约17700行代码：纯Bash编写，除git、curl、gh外无其他外部依赖
工作窃取队列：用于并行同步，支持原子出队
可移植锁机制：通过
```
mkdir
```
实现（兼容所有POSIX系统）
路径安全验证：防止路径遍历攻击
指数退避重试：针对网络操作

Integration with Flywheel

与Flywheel集成

Tool	Integration
Agent Mail	Notify agents when repos are updated; coordinate reviews
BV	Track repo sync as recurring beads
CASS	Search past sync sessions and agent-sweep logs
NTM	Robot mode API for session orchestration
DCG	RU runs inside DCG sandbox protection

工具	集成方式
Agent Mail	仓库更新时通知Agent；协调评审任务
BV	将仓库同步作为重复任务跟踪
CASS	搜索过往同步会话和Agent扫描日志
NTM	机器人模式API用于会话编排
DCG	RU在DCG沙箱保护下运行