Git——vcstool使用笔记

整体说明

vcstool 是一个命令行工具，支持 Git、Mercurial、Subversion 和 Bazaar 等多种版本控制系统，能让用户能基于单一的工作区定义文件（.repos 或 .rosinstall）来批量管理多个代码仓库
注：vcs 是 Version Control System 的简称
vcstool 的安装建议使用 conda（亲测好用）
1
conda install -c conda-forge vcstool
安装后，使用 vcs 命令访问工具，而不是 vcstool
vcstool 是无状态的
- 它不维护自己的状态文件，完全依赖于：
  - 文件系统中真实存在的仓库目录
  - 一个 .repos 配置文件（YAML 格式）

`.repos` 配置文件格式（YAML）

所有导入导出操作都基于此格式，标准写法是（一般不用自己手动编辑）：

repositories:
    # 相对路径（克隆后存放的文件夹名）
    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、版本）

# 按照分支名导出
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）批量克隆仓库到指定目录

# 读取 `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 使用示例：

# `vcs pull` 会进入每一个仓库，执行拉取最新代码（如 `git pull`）
# 更新当前目录下所有仓库
vcs pull          

# 更新 src 目录下所有仓库
vcs pull src      

# `vcs push` 批量推送所有仓库的本地更改到远程
# 批量推送
vcs push

其他常用命令：查看状态与信息

其他常用命令汇总：

# 批量查看各仓库的本地修改状态（相当于挨个执行 `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 等限定仓库类型，避免执行到不支持的仓库上

# 给所有 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`

附录：实操工作流

以搭建新环境为例

# 准备空间
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 键即可提示子命令和参数，极大提升效率
混用多种 VCS 无压力 ：
- 如果 src 下既有 Git 仓库又有 SVN 仓库，直接运行 vcs status 会同时检测并显示两者的状态，vcstool 会自动识别类型

整体说明

.repos 配置文件格式（YAML）