Proposal: resolve the search paths from a ".repos" specification (by default)

[caioaamaral]

Feature Request

Description

Resolve the search paths a command operates on from an existing .repos file (by default), rather than scanning the working directory.

• Further establishes commands' dependency on an existing .repos file.
• The search paths a command looks for would be extracted from the .repos file.
• Setting custom base paths would still be possible via the --paths argument.
• This would promote --file to the Common parameters.

Motivation

Today each command discovers repositories by scanning paths. If the workspace already declares its repositories in a .repos file, that file is the authoritative list — resolving search paths from it makes command behavior consistent and predictable across all subcommands, while --paths remains available for ad-hoc use.

Proposed Solution

usage: vcs <command> [-h] [--context N] [--debug] [-s] [-n] [-w N] [--file] [--repos] [--paths]

Common parameters:
  --debug               Show debug messages (default: False)
  -s, --hide-empty, --skip-empty
                        Hide repositories with empty output (default: False)
  -n, --nested          Search for nested repositories (default: False)
  -w N, --workers N     Number of parallel worker threads (default: 20)
  --file FILE_OR_URL    Where to read the .repos file (default: "$(cwd)/.repos"). Incompatible with `--paths`
  --repos               List repositories which the command operates on (default: False)
  --paths               Base paths to look for repositories (default: the paths on the `.repos` file).
                        Incompatible with `--file`, setting this would overlook an existent `.repos` file

Typical use-cases

• Perform the command on the repositories listed in the .repos file:

vcs diff --file ros2.repos

• Perform the command on a subset of the repositories listed in the .repos file:

vcs diff --file ros2.repos --repos my_package_description

• Perform the command on a custom path:

vcs status --paths [~/ros2_ws/src/]

• Perform the command on specific repositories (search paths resolved from default $(cwd)/.repos):

vcs branch --repos my_package_bringup # uses the filename of the package that must exist on the search paths

Notes

• This sets a dependency on a .repos file for all commands (which can be overridden via --paths).
• Related to Proposal: Allow default ".repos" file (similar to how Docker handles Dockerfile) #113 (establishes --file to locate the .repos file).

---

Moved from dirk-thomas/vcstool#296

[asherikov]

One of the key features of vcstool as opposed to legacy wstool was to eliminate local state file: "vcstool doesn't use any state beside the repository working copies available in the filesystem." This approach targets short-lived workspaces that is more suitable for ROS developers -- they work on a feature that spans a few repos and throw it away when done. Persistent workspaces are more common for application developers, which IMO was overlooked by the original author, so this is why I maintain my own tool that uses the "stateful" approach -> https://github.com/asherikov/wshandler.