wstool

Command-line tools for maintaining a workspace of projects from multiple version-control systems.

Maintainer status: unmaintained
Maintainer: none
License: BSD
Bug / feature tracker: https://github.com/vcstools/wstool/issues
Source: git https://github.com/vcstools/wstool.git (branch: master)

wstool provides commands to manage several local SCM repositories (supports git, mercurial, subversion, bazaar) based on a single workspace definition file (.rosinstall).

wstool replaces the rosws tool for catkin workspaces. As catkin workspaces create their own setup file and environment, wstool is reduced to version control functions only. So wstool does not have a "regenerate" command, and does not allow adding non-version controlled elements to workspaces. In all other respects, it behaves the same as rosws.

wstool is not a rewrite. It is intended to reuse most of the rosws tool code and thus also produce .rosinstall files that are compatible with those used by rosws.

wstool depends on the vcstools package, and for a transitional period it will also depend on the rosinstall package (later that dependency will be inverted).

Installation

To install, use

$ sudo apt-get install python-wstool

or when that is not possible, fall back to pip:

$ sudo pip install -U wstool

Changes from rosws and rosbuild

rosbuild and rosws used the ROS_WORKSPACE environment variable to determine what workspace you are working in. catkin determines this from the current working directory. wstool's workspace is specified with the -t parameter

The root of the wstool workspace is the root of the catkin source directory:

~/ros_catkin_ws/      <-- Invoke catkin_make from here
├── src/              <-- Use this path for wstool -t
│   ├── repository1/
│   │   ├── .git/
│   │   └── my_files
│   ├── repository2/
│   │   ├── .git/
│   │   └── my_other_files
│   └── .rosinstall
├── devel/
└── build/

rosws generated setup.*sh files when called with commands "init" or "regenerate", and a CMakeLists.txt instead when also passed the option "--catkin". Both had implicit dependencies to the ROS ecosystem. wstool avoids those dependencies and leaves it to the user or other tools (e.g. catkin) to create such environment setup files.
Similarly, workspace overlaying is managed by catkin rather than wstool. This means you shouldn't put your workspace underlay in your rosinstall file or use the underlay to initialize your workspace.

Using wstool

Create a catkin Workspace with wstool

First, create a catkin workspace:

$ mkdir ~/ros_catkin_ws
$ cd ~/ros_catkin_ws

Initialize the Workspace Without a rosinstall file

This will initialize an empty workspace. If you have a rosinstall file that you want to base your workspace on, skip to Initialize the Workspace from a rosinstall File below.

```
$ wstool init src
```

If you have rosinstall files to add to the workspace, proceed to Merge in Additional rosinstall Files below.

Initialize the Workspace from a rosinstall File

If you have already initialized your workspace, skip this step. If you have rosinstall files to add to the workspace, proceed to Merge in Additional rosinstall Files below.

$ wstool init src PATH_TO_ROSINSTALL_FILE.rosinstall

If you have rosinstall files to add to the workspace, proceed to Merge in Additional rosinstall Files below.

Merge in Additional rosinstall Files

For each rosinstall file you want to add to your workspace, run this command

$ wstool merge -t src PATH_TO_ROSINSTALL_FILE.rosinstall

Updating the Workspace

After you've created your workspace and added repositories, you should update it to download the latest versions.

wstool update -t src

Further Documentation

Since the syntax and semantics are the same as for rosws, for the time being use the rosws syntax docs at:

doc/independent/api/rosinstall/html/