Require git 1.8.4, and mark the "ffi" driver as experimental

git 1.8.4 is the oldest version the whole suite passes with: before, git
simplifies the log of a range filtered by path differently, and git 1.7.1
can't count commits (`rev-list --count` comes with 1.7.2).
test-git-versions.php now tests 1.8.4 instead of 1.7.1 and 1.8.3.1.

The range test failed with git 1.8.4 too, but because of its setup: git
1.8 adds a line break when it merges a file without one, so the merge
differed from both parents. Committed files now end with one.

The "ffi" driver isn't covered by the backward compatibility promise: it
reimplements git's behavior on top of libgit2, and may still differ from
git where its tests don't look.

Author: lyrixx

CHANGELOG.md

@@ -9,8 +9,8 @@ Changes since [v1.6.0](https://github.com/gitonomy/gitlib/releases/tag/v1.6.0).
 
 ### Features
 
-- Add an in-process `'ffi'` driver, backed by libgit2 1.9 through PHP's FFI extension, as an
-  alternative to the default `'cli'` driver: select it with the `'driver' => 'ffi'` option of
+- Add an experimental in-process `'ffi'` driver, backed by libgit2 1.9 through PHP's FFI
+  extension, as an alternative to the default `'cli'` driver: select it with the `'driver' => 'ffi'` option of
   `Repository`/`Admin`. It avoids spawning a `git` process for every operation; see
   ["Choosing a driver"](doc/repository.md#choosing-a-driver) for its requirements, its
   differences with the `'cli'` driver, and when it is faster. `benchmark.php` compares both
@@ -77,6 +77,10 @@ Changes since [v1.6.0](https://github.com/gitonomy/gitlib/releases/tag/v1.6.0).
 
 ### Minor
 
+- Require git 1.8.4 or later, the oldest version the test suite passes with: it simplifies the
+  log of a range filtered by path like the current versions, and `Log::count()` needs git
+  1.7.2. **Breaking:** git 1.7 and 1.8 before 1.8.4 are no longer supported.
+  ([#253](https://github.com/gitonomy/gitlib/pull/253))
 - Replace `Gitonomy\Git\Util\StringHelper` with `symfony/string`'s `CodePointString`, which
   covers the same UTF-8-aware `strlen`/`substr`/`strpos`/`strrpos` operations.
   **Breaking:** `StringHelper` is removed, along with its configurable encoding

README.md

@@ -3,9 +3,10 @@ Gitlib for Gitonomy
 
 This library provides methods to access Git repository from PHP 8.4+.
 
-By default, it runs the `git` binary for every operation: convenient, and it doesn't need anything
-built to use. It can instead run [libgit2](https://libgit2.org/) in-process via PHP's `FFI`
-extension, which is faster for small reads but slower on long histories: see
+By default, it runs the `git` binary (1.8.4 or later) for every operation: convenient, and it
+doesn't need anything built to use. It can instead run [libgit2](https://libgit2.org/) in-process
+via PHP's `FFI` extension, an experimental driver which is faster for small reads but slower on
+long histories: see
 ["Choosing a driver"](doc/repository.md#choosing-a-driver) and
 ["Performance"](doc/repository.md#performance).
 

UPGRADE-2.0.md

@@ -2,15 +2,18 @@ UPGRADE FROM 1.x to 2.0
 =======================
 
 gitlib 2.0 runs every git operation through a driver: `'cli'`, the default,
-runs the `git` binary like 1.x did, and `'ffi'` runs libgit2 in-process (see
-["Choosing a driver"](doc/repository.md#choosing-a-driver)). Code reading
+runs the `git` binary like 1.x did, and the experimental `'ffi'` runs libgit2
+in-process (see ["Choosing a driver"](doc/repository.md#choosing-a-driver)). Code reading
 repositories through `Repository`, `Commit`, `Log`... mostly keeps working:
 check the points below, starting with errors, dates and classes you extend.
 
 Requirements
 ------------
 
  * PHP 8.4 or later is required.
+ * git 1.8.4 or later is required by the default `'cli'` driver: before,
+   git simplifies the log of a range filtered by path differently, and it
+   can't count commits (`Log::count()`) before 1.7.2.
  * `symfony/process` must be `^6.4`, `^7.4` or `^8.1`.
  * `symfony/string` `^7.4.6` or `^8.0.6` is a new dependency.
 

composer.json

@@ -48,7 +48,7 @@
         "symfony/console": "^8.1"
     },
     "suggest": {
-        "ext-ffi": "To use the \"ffi\" driver (in-process libgit2, via Repository's 'driver' option) instead of the default \"cli\" driver — also requires libgit2 1.9 to be installed on the system."
+        "ext-ffi": "To use the experimental \"ffi\" driver (in-process libgit2, via Repository's 'driver' option) instead of the default \"cli\" driver — also requires libgit2 1.9 to be installed on the system."
     },
     "config": {
         "preferred-install": "dist",

doc/repository.md

@@ -85,13 +85,21 @@ Options for repository
 ### Choosing a driver
 
 By default, gitlib spawns a `git` process for every operation (the `'cli'`
-driver). You can instead run [libgit2](https://libgit2.org/) in-process,
-through PHP's `FFI` extension, by passing the `'ffi'` driver:
+driver), which requires git 1.8.4 or later. You can instead run
+[libgit2](https://libgit2.org/) in-process, through PHP's `FFI` extension,
+by passing the `'ffi'` driver:
 
 ```php
 $repository = new Repository('/path/to/repo', ['driver' => 'ffi']);
 ```
 
+> **warning**
+>
+> The `'ffi'` driver is experimental: it isn't covered by the backward
+> compatibility promise, and can change in a minor version. It reproduces
+> git's behavior with libgit2, and may still differ from git in cases its
+> tests don't cover.
+
 This avoids spawning a process for every operation. The `'ffi'` driver
 requires the `ext-ffi` PHP extension and libgit2 1.9: libgit2 changes its
 binary interface with every minor version, so any other version is refused.

src/Gitonomy/Git/Driver/Ffi/LibGit2DriverFactory.php

@@ -23,6 +23,8 @@
  * Runs libgit2 1.9 in-process, through PHP's FFI extension.
  *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
+ *
+ * @experimental
  */
 final readonly class LibGit2DriverFactory implements DriverFactoryInterface
 {

test-git-versions.php

@@ -25,11 +25,11 @@
 const GIT_URL = 'https://github.com/git/git.git';
 const BUILDS_PATH = __DIR__.'/git-builds';
 
-// One v1.x and several v2.y releases, picked for how long and how widely each
-// shipped as the default git on a major distro, rather than for a spread across
-// git's history: v1.7.1 (RHEL/CentOS 6), v1.8.3.1 (RHEL/CentOS 7), v2.17.1 (Ubuntu
-// 18.04), v2.25.1 (Ubuntu 20.04), v2.34.1 (Ubuntu 22.04), v2.43.0 (Ubuntu 24.04).
-const DEFAULT_VERSIONS = ['v1.7.1', 'v1.8.3.1', 'v2.17.1', 'v2.25.1', 'v2.34.1', 'v2.43.0'];
+// v1.8.4, the oldest version gitlib supports, and v2.y releases picked for how
+// long and how widely each shipped as the default git on a major distro, rather
+// than for a spread across git's history: v2.17.1 (Ubuntu 18.04), v2.25.1 (Ubuntu
+// 20.04), v2.34.1 (Ubuntu 22.04), v2.43.0 (Ubuntu 24.04).
+const DEFAULT_VERSIONS = ['v1.8.4', 'v2.17.1', 'v2.25.1', 'v2.34.1', 'v2.43.0'];
 
 function sh(array $args, ?string $cwd = null, ?string $logfile = null): Process
 {

tests/Gitonomy/Git/Tests/LogTest.php

@@ -78,8 +78,7 @@ public function testFirstMessageEmpty(): void
     {
         $repository = self::createEmptyRepository();
         $tree = self::writeObject($repository, 'tree', '');
-        // Edge case: first commit lacks a message. Written by hand: git only
-        // has --allow-empty-message since 1.7.2.
+        // Edge case: first commit lacks a message.
         $commit = self::writeObject($repository, 'commit', "tree {$tree}\nauthor Unit Test <unit_test@unit-test.com> 1000000000 +0000\ncommitter Unit Test <unit_test@unit-test.com> 1000000000 +0000\n\n");
         self::git($repository, 'update-ref', ['refs/heads/master', $commit]);
 
@@ -246,7 +245,8 @@ private static function createRepositoryToCommitTo(): Repository
      */
     private static function commit(Repository $repository, string $file, string $content): string
     {
-        file_put_contents($repository->getWorkingDir().'/'.$file, $content);
+        // Ends with a line break: git 1.8 adds one when it merges a file without.
+        file_put_contents($repository->getWorkingDir().'/'.$file, $content."\n");
         self::git($repository, 'add', [$file]);
         self::git($repository, 'commit', ['-m', $content]);