ros-ws

A command-line tool for managing ROS 2 colcon workspaces. It lets you create, register, and switch between multiple workspaces with ease.

Table of Contents

• Installation
  • Installation from source
  • Requirements
  • Shell Integration
• Usage
  • create
  • switch
  • save
  • list
  • locate
  • name
• Configuration
• License

Installation

Install from PyPI using pip:

pip install ros-ws

Installation from source

If you like to both use and hack ros-ws, you can install the software by pointing the installation to the development code.

1. Clone the repository:

   git clone https://github.com/Rayman/ros-ws.git

2. Install using pip with the editable option -e DIR.

   cd ros-ws
   pip install --user -e .

   The final . says that pip should redirect the ws command relative to this directory (to ./src/ros-ws).

Requirements

• Python >= 3.10
• colcon-common-extensions
• ROS 2 (e.g. jazzy, Iron, Jazzy) installed on the system

Shell Integration

To automatically source the active workspace in every new shell, add the following snippet to your ~/.bashrc:

source "$(ws locate)/install/setup.bash"

Usage

ws [-h] [-v] [--version] {create,switch,save,list,locate,name} ...

create

Create a new colcon workspace that extends an existing ROS result-space. The workspace is built with colcon build and then registered automatically.

ws create [-h] [--dir DIR] [--name NAME] extend

Example:

mkdir ~/ros2_workspace && cd ~/ros2_workspace
ws create /opt/ros/jazzy

switch

Switch the active workspace to a previously registered one.

ws switch [-h] name

Example:

ws switch ros2_workspace

save

Register an existing workspace directory without building it. Useful for importing a workspace that was created outside of ws. If no workspace is currently active, the saved workspace also becomes the active one.

ws save [-h] [--name NAME] dir

Example:

ws save ~/ros2_workspace

list

List all registered workspaces. The currently active workspace is marked with (active). Workspaces whose directory no longer exists are highlighted in red.

ws list [-h]

Example output:

- jazzy => /home/user/ws_jazzy (active)
- iron  => /home/user/ws_iron

locate

Print the absolute path of the active workspace. Returns exit code 1 if no workspace is currently active. Useful in scripts:

ws locate [-h]

Example:

cd "$(ws locate)"

name

Print the name of the active workspace. Returns exit code 1 if no workspace is currently active.

ws name [-h]

Example:

echo "Current workspace: $(ws name)"

Configuration

Workspace registrations are stored as symlinks under the XDG_CONFIG_HOME directory (defaults to ~/.config):

~/.config/ros-ws/
├── workspace          # symlink → workspaces/<active-name>
└── workspaces/
    ├── jazzy         # symlink → /home/user/ws_jazzy
    └── iron           # symlink → /home/user/ws_iron

License

MIT — see LICENSE for details.