# Working with Public Repositories

Several parts of the Kangaroo software stack are open source and hosted as public repositories on GitHub. Instead of cloning each one manually, PAL Robotics uses [`vcstool`](https://github.com/dirk-thomas/vcstool) together with a `.repos` file to fetch a consistent set of repositories with a single command — the same approach used by the ROS 2 source build itself.

## Prerequisites

`vcstool` is already included in the [PAL Docker image](docker.md). If you are working outside the container, install it with:

```bash
sudo apt-get install python3-vcstool
```

## The `.repos` File

A `.repos` file is a YAML file that lists a set of git repositories, their URL and the branch or tag to check out. Create a workspace `src` folder and add a file, for example `kangaroo.repos`, with the following content:

```yaml
repositories:
  launch_pal:
    type: git
    url: https://github.com/pal-robotics/launch_pal.git
    version: master

  pal_urdf_utils:
    type: git
    url: https://github.com/pal-robotics/pal_urdf_utils.git
    version: humble-devel

  pal_sea_arm:
    type: git
    url: https://github.com/pal-robotics/pal_sea_arm.git
    version: humble-devel

  kangaroo_moveit_config:
    type: git
    url: https://github.com/pal-robotics/kangaroo_moveit_config.git
    version: humble-devel

  play_motion2:
    type: git
    url: https://github.com/pal-robotics/play_motion2.git
    version: humble-devel

  urdf_test:
    type: git
    url: https://github.com/pal-robotics/urdf_test.git
    version: humble-devel

  kangaroo_simulation:
    type: git
    url: https://github.com/pal-robotics/kangaroo_simulation.git
    version: humble-devel
```

Each entry maps a package name to the git repository that provides it and the branch to check out. `humble-devel` tracks the development branch for ROS 2 Humble, while `launch_pal` is versioned independently and tracks `master`.

## Importing the Repositories

From the `src` folder of your workspace, run `vcs import` and pass it the `.repos` file:

```bash
mkdir -p ~/exchange/kangaroo_ws/src
cd ~/exchange/kangaroo_ws/src
vcs import < kangaroo.repos
```

`vcs import` clones any repository that is not yet present and leaves existing clones untouched. Each repository is checked out at the branch declared in the `version` field.

## Keeping the Workspace Up to Date

To pull the latest changes for every repository declared in the `.repos` file, run `vcs pull` from the same `src` folder:

```bash
vcs pull
```

You can also check the status of all repositories at once — useful for spotting local modifications before pulling:

```bash
vcs status
```

## Building the Workspace

Once the repositories are imported, install any missing dependencies with `rosdep` and build the workspace with `colcon`, from the workspace root:

```bash
cd ~/exchange/kangaroo_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
```

See [Deploying Software to the Robot](../management/deploy_software.md) for how to install the resulting packages onto the robot.