The README documents the .repos format but says nothing about whether multiple files can be combined — via an include: / import: / $ref: directive, recursive resolution, or shell concatenation.
I could not find a documented answer. The closest thread is dirk-thomas/vcstool#282 (recursive .repos imports, filed 2021, still open, no maintainer response). That silence is itself a UX problem — library authors considering whether to ship a .repos file alongside their repo have no signal on whether a composition mechanism is planned, rejected, or just unowned.
Could maintainers clarify the position? I see three plausible directions and would appreciate guidance on which is closest to reality:
-
Flat by design. Composition was considered and rejected (for reproducibility, simplicity, tooling reasons). In that case a one-paragraph docs addition stating this + showing the cat a.repos b.repos | vcs import src pattern would prevent future users asking the same question.
-
Open to a minimal feature. A small additive change — e.g. an optional top-level includes: list that vcs import resolves recursively, with cycle detection and a documented merge policy — would unblock library authors shipping canonical dep sets without changing anything about existing flat .repos files.
-
Compromise: preprocessing. A new vcs flatten a.repos > resolved.repos subcommand that expands includes into a plain flat file. Keeps the on-disk snapshot flat and reproducible (matching whatever the current philosophy is), while letting library authors publish composable pieces. Users commit the resolved output for CI.
I'm happy to open a docs PR if the answer is (1), or a short design-doc PR if (2) or (3) is on the table. Would also gladly help triage / close #282 depending on the outcome.
The README documents the
.reposformat but says nothing about whether multiple files can be combined — via aninclude:/import:/$ref:directive, recursive resolution, or shell concatenation.I could not find a documented answer. The closest thread is dirk-thomas/vcstool#282 (recursive
.reposimports, filed 2021, still open, no maintainer response). That silence is itself a UX problem — library authors considering whether to ship a.reposfile alongside their repo have no signal on whether a composition mechanism is planned, rejected, or just unowned.Could maintainers clarify the position? I see three plausible directions and would appreciate guidance on which is closest to reality:
Flat by design. Composition was considered and rejected (for reproducibility, simplicity, tooling reasons). In that case a one-paragraph docs addition stating this + showing the
cat a.repos b.repos | vcs import srcpattern would prevent future users asking the same question.Open to a minimal feature. A small additive change — e.g. an optional top-level
includes:list thatvcs importresolves recursively, with cycle detection and a documented merge policy — would unblock library authors shipping canonical dep sets without changing anything about existing flat.reposfiles.Compromise: preprocessing. A new
vcs flatten a.repos > resolved.repossubcommand that expands includes into a plain flat file. Keeps the on-disk snapshot flat and reproducible (matching whatever the current philosophy is), while letting library authors publish composable pieces. Users commit the resolved output for CI.I'm happy to open a docs PR if the answer is (1), or a short design-doc PR if (2) or (3) is on the table. Would also gladly help triage / close #282 depending on the outcome.