整体说明
vcstool 是一个命令行工具，支持 Git、Mercurial、Subversion 和 Bazaar 等多种版本控制系统，能让用户能基于单一的工作区定义文件（
.repos或.rosinstall）来批量管理多个代码仓库注：vcs 是 Version Control System 的简称
vcstool 的安装建议使用 conda（亲测好用）
1
conda install -c conda-forge vcstool
安装后，使用
vcs命令访问工具，而不是vcstoolvcstool 是无状态的
- 它不维护自己的状态文件，完全依赖于：
- 文件系统中真实存在的仓库目录
- 一个
.repos配置文件（YAML 格式）
- 它不维护自己的状态文件，完全依赖于：
.repos 配置文件格式（YAML）
- 所有导入导出操作都基于此格式，标准写法是（一般不用自己手动编辑）：
1
2
3
4
5
6
7
8
9
10
11repositories:
# 相对路径（克隆后存放的文件夹名）
path/to/repo1:
type: git
url: https://github.com/user/repo1.git
version: master # 分支名 / tag名 / commit哈希（可选，缺省则拉取默认分支）
path/to/repo2:
type: tar # 特殊类型：下载压缩包并解压
url: https://example.com/archive.tar.gz
# version: 可选
vcs 子命令全解
vcs export 导出仓库信息
vcs export扫描当前或指定路径下的所有仓库，输出.repos格式的 YAML 信息（含路径、类型、URL、版本）1
2
3
4
5
6
7
8# 按照分支名导出
vcs export > my.repos
# 按照 精确 Commit Hash 导出（若要存储精确使用版本时最推荐）
vcs export --exact > my.repos
# 优先 Tag 名 ，若无则用 Commit Hash，语义化版本发布，易读且精确，但这里可能比较慢
vcs export --exact-with-tags > my.repos
vcs import 导入/克隆仓库
vcs import根据定义文件（通过标准输入或--input）批量克隆仓库到指定目录1
2
3
4
5
6
7
8
9
10
11# 读取 `my.repos`，将仓库克隆到 当前目录
vcs import < my.repos
# 读取文件，将所有仓库克隆到 `src` 子文件夹内
vcs import src < my.repos
# 指定 `--input` 读取文件，目标路径为当前目录（`.`）
vcs import --input my.repos .
# 直接传入 URL ，vcstool 会下载该文件并按此导入
vcs import http://example.com/repos.yaml .注：
tar和zip类型的条目也会被自动下载并解压到对应路径
vcs pull/vcs push 拉取更新 或推送代码
vcs pull/vcs push使用示例：1
2
3
4
5
6
7
8
9
10# `vcs pull` 会进入每一个仓库，执行拉取最新代码（如 `git pull`）
# 更新当前目录下所有仓库
vcs pull
# 更新 src 目录下所有仓库
vcs pull src
# `vcs push` 批量推送所有仓库的本地更改到远程
# 批量推送
vcs push
其他常用命令：查看状态与信息
- 其他常用命令汇总：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# 批量查看各仓库的本地修改状态（相当于挨个执行 `git status`）
vcs status
# 批量查看各仓库的代码差异（相当于 `git diff`）
vcs diff
# 批量查看各仓库的提交历史
vcs log
# 只显示各仓库**自上一个 Tag 以来的提交**（非常实用，用于生成版本发布日志）
vcs log --limit-untagged
# 批量查看各仓库的当前分支信息
vcs branch
# 批量查看各仓库配置的远程仓库地址（如 `git remote -v`）
vcs remotes
# 检查 YAML 格式文件（`.repos` 或 `.rosinstall`）的语法和格式是否正确
# 若文件无错误，终端无输出（静默退出）；若有错误，会报错提示
vcs validate < my.repos
vcs custom 自定义命令
vcs custom对所有仓库执行你自定义的原生 VCS 命令- 强烈建议 通过
--git、--svn等限定仓库类型，避免执行到不支持的仓库上1
2
3
4
5
6
7
8# 给所有 git 仓库添加文件
vcs custom --git --args add .
# 给所有 git 仓库提交，并附带信息
vcs custom --git --args commit -m "Batch update from vcs"
# 给所有 git 仓库抓取远程更新（不合并）
vcs custom --git --args fetch --all
附录：通用参数（大部分子命令都支持）
- 在命令后添加以下参数可以改变行为：
参数 说明 示例 path位置参数 ，指定搜索仓库的根路径；若省略，默认为当前目录 .vcs status src--workers N或-w N并行处理的线程数；默认 12 ，可根据机器性能调整 vcs import src -w 8 < my.repos--nested或-n递归搜索子文件夹中的嵌套仓库（如 Git 子模块内的仓库） vcs pull --nested--skip-empty或-s隐藏那些没有输出内容的仓库（让结果更清爽） vcs status -s--debug显示详细的调试信息，用于排查错误 vcs pull --debug--repos列出当前命令实际操作了哪些仓库（不执行具体操作） vcs pull --repos
附录：实操工作流
- 以搭建新环境为例
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# 准备空间
mkdir my_workspace && cd my_workspace
# 导入所有依赖（假设团队给了 `team.repos`）
# 从远程拉取所有项目源码，所有源码会被克隆到 `src` 目录下
vcs import src -w 8 < team.repos
# [导入时可选下面方法]
# 从远程拉取时跳过本地已经存在的项目（常用命令），转而直接切换到指定的版本
# 当版本在本地不存在时，它会自动与远程仓库交互来获取
vcs import src --skip-existing < my.repos
# 日常更新代码
vcs pull src
# 修改代码后，批量检查状态
vcs status src
# 项目发布前，锁定精确版本
# 把这个文件提交到仓库，方便后续彻底复现
vcs export --exact > release_v1.0.repos
实用技巧与避坑指南
tar/zip的妙用 ：- 如果依赖项是预编译的库压缩包，可以在
.repos中将其type设为tar或zip，vcs import会自动下载解压，无需手动操作
- 如果依赖项是预编译的库压缩包，可以在
- 关于
path参数（解答你的疑问） ：- 所有命令末尾的路径（如
src）指的就是搜索根目录 vcs pull src意思是“在src文件夹里找所有仓库并更新”- 如果省略，就是当前目录
- 所有命令末尾的路径（如
- 配合 Shell 自动补全（已支持 bash/zsh/tcsh/fish）：
- 安装完 vcstool 后，在 shell 配置文件中
source对应的补全脚本，输入vcs后按 Tab 键即可提示子命令和参数，极大提升效率
- 安装完 vcstool 后，在 shell 配置文件中
- 混用多种 VCS 无压力 ：
- 如果
src下既有 Git 仓库又有 SVN 仓库，直接运行vcs status会同时检测并显示两者的状态，vcstool 会自动识别类型
- 如果