[Trusted97]

Adds a --branch option to the build command that filters selected
packages to only versions matching a given branch name (e.g. dev-main)
or version constraint (e.g. 1.x). When combined with a package filter,
other packages and non-matching versions are preserved from the existing
repository dump, enabling fast partial rebuilds on branch push.

php bin/satis build --branch main satis.json web/ acme/pkg
php bin/satis build --branch 1.x satis.json web/ acme/pkg

Validation ensures --branch requires at least one package and is mutually
exclusive with --repository-url.

[alcohol]

Just wondering, why did you change the visibility of a range of methods from private to protected?

[Trusted97]

@alcohol

That was a leftover from an earlier approach where I tried a separate update-branch command extending BuildCommand and needed those methods accessible.
In the final implementation i've put everything directly into BuildCommand via --branch, subclass access isn't needed.
I've reverted all to private in the follow-up commit.

[Copilot]

🟡 Changes recommended

Cleaning discards the branch filter, and merging can restore stale target versions from the existing dump.

2 open issues

• Preserve branch filtering when cleaning package selections · New
• Exclude filtered old versions before merging preserved packages · New

What changed in this PR

Adds --branch to Satis builds to support targeted branch or version-range updates while preserving existing repository content outside the requested scope.

Changes:

• Adds branch matching and validation requiring package names and rejecting --repository-url.
• Adjusts partial-update merging to retain existing versions.
• Documents usage and adds command tests for filtering, preservation, and validation.

File	Description
tests/​Console/​Command/​BuildCommandTest.php	Adds branch-update and option-validation tests.
src/​Console/​Command/​BuildCommand.php	Implements the option, version matching, and merge changes.
docs/​using.md	Documents branch and version-range update commands.

_{Review effort: Balanced}

[JellyBellyDev]

Great job!
I'd maybe add a few tests with some weird branch names, like ones with special characters, to cover more edge cases, e.g. "feat/super-power-feature", "3.x" or "my.new-feat-&-power".
What do you think?

[Copilot]

🔵 Needs a closer look

The preservation tests need version-level metadata assertions to verify that targeted versions update while non-matching versions remain unchanged.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Verify only the requested branch reference changes

tests/​Console/​Command/​BuildCommandTest.php:1256

This assertion checks only the package name, so the test still passes if dev-feature-x or 1.0.0 is deleted or unexpectedly refreshed. Because both builds use identical metadata, it also cannot show that the requested branch was updated. Change the versions' source references between builds and inspect the generated version metadata, asserting that dev-main has the new reference while the other versions retain their old references.

2 resolved since last review

• Preserve branch filtering when cleaning package selections
• Exclude filtered old versions before merging preserved packages

_{Review effort: Balanced}

[alcohol]

Thank you for contributing 🥳