Robotics- vcstool 用法速查

vcstool 的用法很直接，核心就是围绕一个 .repos 文件做批量操作。

安装

pip install vcstool
# 或
sudo apt install python3-vcstool

核心概念：.repos 文件

YAML 格式，描述要管理的仓库：

repositories:
  pkg_a:
    type: git
    url: https://github.com/user/pkg_a.git
    version: main          # 分支、tag 或 commit 都可
  pkg_b:
    type: git
    url: https://github.com/user/pkg_b.git
    version: v1.2.0
  pkg_c:
    type: hg               # 也支持 svn、hg、bzr
    url: https://bitbucket.org/user/pkg_c
    version: default

version 可省略，默认用仓库的默认分支。

最常用的 4 个命令

1. 导入（克隆）

vcs import src < my.repos

把 .repos 里的所有仓库克隆到 src/ 目录。

2. 拉取更新

vcs pull src

批量 git pull 所有仓库。加 -n 可并行加速。

3. 查看状态

vcs status src     # 各仓库有无改动
vcs diff src       # 查看具体改动
vcs log src        # 查看提交历史

4. 导出当前版本

vcs export --exact src > my.repos

把 src/ 下所有仓库的精确 commit 导出成 .repos，用于锁定版本、保证可复现。

其他实用命令

vcs validate < my.repos      # 校验 .repos 文件格式
vcs custom src -- git stash  # 对所有仓库执行自定义 git 命令
vcs branch src               # 查看各仓库当前分支

典型工作流

ROS 2 工作空间

mkdir -p ws/src && cd ws
vcs import src < my.repos
colcon build

CI/CD 可复现构建

# 开发时导出精确版本
vcs export --exact src > locked.repos

# CI 里用锁定文件
vcs import src < locked.repos

几个注意点

• 目录参数 src 必须已存在，或先 mkdir
• vcs import 默认跳过已存在的仓库，加 --force 可强制覆盖
• -n 参数开启并行，仓库多时明显更快
• 加 -j4 指定并行数

一句话记住

import 拉取、pull 更新、status 查看、export 锁定——这四个就够了。