From d2bc5eaec48c32ece0492dcd8cb5f2a60b2251ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Pineau?= Date: Wed, 14 Oct 2026 17:13:53 +0200 Subject: [PATCH] Rewrite the README around an example The README opened on the drivers, then installing gitlib, before any code. It now starts with a line on what gitlib is, and an example reading a log, a diff and a blame, which runs as it is. Then what gitlib does, with links to the documentation, its site, the two drivers, how to install it, and the license. --- README.md | 125 +++++++++++++++++++++++++++++------------------------- 1 file changed, 67 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 7005d8b..7499784 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,54 @@ -Gitlib for Gitonomy -=================== +gitlib +====== -This library provides methods to access Git repository from PHP 8.4+. +Access git repositories from PHP 8.4+, through the `git` binary or libgit2. -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). - -Quick Start ------------ +```php +use Gitonomy\Git\Repository; -You can install gitlib using [Composer](https://getcomposer.org/). Simply require the version you need: +$repository = new Repository('/path/to/repository'); -```bash -$ composer require gitonomy/gitlib -``` +// The last 5 commits of main that changed src/ +foreach ($repository->getLog('main', 'src', limit: 5) as $commit) { + echo $commit->getShortHash().' '.$commit->getSubjectMessage().PHP_EOL; +} -or edit your `composer.json` file by hand: +// The files the last commit changed +foreach ($repository->getHeadCommit()->getDiff()->getFiles() as $file) { + echo $file->getName().': +'.$file->getAdditions().' -'.$file->getDeletions().PHP_EOL; +} -```json -{ - "require": { - "gitonomy/gitlib": "^2.0" - } +// Who wrote the first lines of README.md +foreach ($repository->getBlame('main', 'README.md', 1, 3)->getLines() as $line) { + echo $line->getCommit()->getAuthorName().': '.$line->getContent().PHP_EOL; } ``` -Upgrading from 1.x? Read [UPGRADE-2.0.md](UPGRADE-2.0.md). - -Example Usage -------------- - -```php -getReferences()->getBranches() as $branch) { - echo '- '.$branch->getName().PHP_EOL; -} +- **Open** a bare repository, a working tree, a linked worktree or a submodule, or + **create** one: init, clone, mirror. See [Opening a repository](doc/repository.md) and + [Creating repositories](doc/admin.md). +- **Read** commits, logs, trees, blobs, diffs, blames, branches and tags, as PHP objects. +- **Change** the working copy: checkout, new branches, merges, and the diffs of what is + pending or staged. See [Working copy](doc/workingcopy.md). +- **Manage** the hooks of a repository: see [Hooks](doc/hooks.md). +- **Run** any other git command: see + [Running git commands](doc/repository.md#running-git-commands). -echo $repository->getHeadCommit()->getSubjectMessage().PHP_EOL; +Two drivers +----------- -// Any git command, with the default driver only -$repository->run('fetch', ['--all']); -``` +`Repository` runs git through a driver, its last argument: -The last argument of `Repository` is the driver running git. It is `CliDriver`, which runs the -`git` binary, by default. To run libgit2 instead, pass a `LibGit2Driver`: everything above works -the same, except `run()`, which needs the `git` binary. +- `CliDriver`, the default, runs the `git` binary, 1.8.4 or later, and needs nothing else; +- `LibGit2Driver`, experimental, runs [libgit2](https://libgit2.org/) 1.9 in-process, through + PHP's `FFI` extension. It is faster for many small reads in a long-running process, and + slower on long histories, like blames: see + ["Choosing a driver"](doc/repository.md#choosing-a-driver). ```php use Gitonomy\Git\Driver\Ffi\LibGit2Driver; @@ -62,22 +57,31 @@ use Gitonomy\Git\Repository; $repository = new Repository('/path/to/repository', driver: new LibGit2Driver()); ``` -API Documentation ------------------ - -+ [Blame](doc/blame.md) -+ [Blob](doc/blob.md) -+ [Branch](doc/branch.md) -+ [Commit](doc/commit.md) -+ [Creating repositories](doc/admin.md) -+ [Diff](doc/diff.md) -+ [Hooks](doc/hooks.md) -+ [Log](doc/log.md) -+ [References](doc/references.md) -+ [Repository](doc/repository.md): opening a repository, drivers, errors -+ [Revision](doc/revision.md) -+ [Tree](doc/tree.md) -+ [Working Copy](doc/workingcopy.md) +Installation +------------ + +```bash +composer require gitonomy/gitlib +``` + +Upgrading from 1.x? Read [UPGRADE-2.0.md](UPGRADE-2.0.md) and the [changelog](CHANGELOG.md). + +Documentation +------------- + +- [Opening a repository](doc/repository.md): paths, drivers, errors, git configuration +- [Creating repositories](doc/admin.md) +- [Revisions](doc/revision.md) +- [Commits](doc/commit.md) +- [Log](doc/log.md) +- [Trees](doc/tree.md) +- [Blobs](doc/blob.md) +- [Diffs](doc/diff.md) +- [Blame](doc/blame.md) +- [Tags and branches](doc/references.md) +- [Branches](doc/branch.md) +- [Working copy](doc/workingcopy.md) +- [Hooks](doc/hooks.md) For Enterprise -------------- @@ -85,3 +89,8 @@ For Enterprise Available as part of the Tidelift Subscription The maintainers of `gitonomy/gitlib` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/packagist-gitonomy-gitlib?utm_source=packagist-gitonomy-gitlib&utm_medium=referral&utm_campaign=enterprise&utm_term=repo) + +License +------- + +gitlib is released under the [MIT license](https://github.com/gitonomy/gitlib/blob/main/LICENSE).