[lyrixx]

v1.7.0 is out (#264). It has the API of 2.0 that can be added without breaking 1.x, and it deprecates what 2.0 replaces. 1.x is merged into main with the strategy "ours", so 1.7 is now an ancestor of main.

This pull request aligns 2.0 with 1.7.

No deprecation of its own in 2.0

Like a Symfony major, 2.0 introduces no deprecation: all of them are deprecated since 1.7.

• The trigger_deprecation() and @deprecated of what 1.7 deprecates now say "1.7".
• The lines of a hunk and the entries of a tree get the methods 1.7 has:
  • FileChange::getDiffLines(), which returns DiffLine objects;
  • iterating a Tree, which gives TreeEntry objects;
  • Tree::getBlobs(), getTrees() and getSubmodules().
• FileChange::getLines(), Tree::getEntries(), getBlobEntries(), getTreeEntries() and getCommitReferenceEntries() are deprecated. Until 3.0, they keep returning the arrays of 1.x. Before, they returned objects you could read as arrays, with a deprecation; DiffLine and TreeEntry no longer implement ArrayAccess.
• Lines passed as arrays to the constructor of FileChange and the LINE_* constants are deprecated since 1.7. So is the argument of Repository::getReferences().
• getSubmoduleEntries(), never released, is replaced by getSubmodules().
• UnexpectedValueException is no longer deprecated: 2.0 no longer throws it, but 1.7 has nothing to replace it with.

UPGRADE-2.0.md

• "Upgrade to 1.7 first": 1.7 requires PHP 8.1.
• "Supporting 1.x and 2.x", about requiring ^1.7 || ^2.0 with a single code path:
  • a before/after example;
  • what 1.7 keeps from 1.x to break nothing;
  • what still differs between both versions.
• "Testing code using gitlib": how to test code using the classes that are final in 2.0.
• Other precisions:
  • the environment variables git inherits;
  • the stricter raw line of diffs, and how to generate test fixtures;
  • what ProcessException reads;
  • the directory run() runs git in.

Composer

The branch alias dev-main: 2.0.x-dev lets ^2.0@dev install main before 2.0.0 is tagged.

Checks

• Tests, PHPStan and PHP CS Fixer pass.
• The same code, written with the new API, runs with v1.7.0 and with this branch. It gives the same result, triggers no deprecation, and passes PHPStan level 9 with both.