Перейти до вмісту

PHP API

Переглянути як Markdown Редагувати на GitHub Документація для bfe242f

Pitmaster\Pitmaster

Клас Pitmaster\Pitmaster — це статична точка входу. Він надає фабричні методи для відкриття, створення та клонування репозиторіїв, а також допоміжні методи виявлення.

PHP
use Pitmaster\Pitmaster;

open

PHP
public static function open(string $path, array $options = []): Repository

Відкриває наявний репозиторій за шляхом $path. Шлях має вести до кореня робочого дерева (де міститься .git/). Також підтримуються пов’язані робочі дерева (де .git — файл із gitdir: <path>) і чисті репозиторії (де $path — це сам каталог .git).

$options приймає два логічні значення; для обох типове значення — true:

  • hooks: запускати сценарії .git/hooks. Передайте false, щоб вимкнути їх для цього дескриптора.
  • processes: дозволяти все, що запускає процес або відкриває мережевий транспорт. Передайте false, щоб вимкнути перехоплювачі, перехоплювач fsmonitor, clone, fetch, push і транспорт процесів SSH. Локальне зчитування й запис продовжують працювати.

Якщо шлях не є репозиторієм git, генерується InvalidArgumentException.

PHP
$repo = Pitmaster::open('/home/user/project');
$repo = Pitmaster::open('/home/user/project', ['hooks' => false]);
$repo = Pitmaster::open('/home/user/project', Pitmaster::processFreeOptions());

init

PHP
public static function init(string $path, string $objectFormat = 'sha1', array $options = []): Repository

Ініціалізує новий репозиторій за шляхом $path. Створює структуру каталогів .git із objects/, refs/heads/, refs/tags/, hooks/, info/, HEAD (що вказує на refs/heads/main) і типовим config.

$objectFormat — це 'sha1' або 'sha256'. Репозиторій SHA-256 отримує repositoryformatversion = 1 і extensions.objectformat = sha256 у конфігурації. Будь-яке інше значення спричиняє InvalidArgumentException. $options приймає ті самі ключі, що й open().

Якщо за цим шляхом уже існує репозиторій, генерується RuntimeException.

PHP
$repo = Pitmaster::init('/home/user/new-project');
$repo = Pitmaster::init('/home/user/sha256-project', 'sha256');

clone

PHP
public static function clone(string $url, string $path, ?int $depth = null, array $options = []): Repository

Клонує віддалений репозиторій. Ініціалізує новий репозиторій, знаходить віддалені посилання, завантажує pack-файл, налаштовує гілки відстеження віддалених репозиторіїв і створює робоче дерево. URL SSH (ssh://... або user@host:path) використовують транспорт SSH; для інших URL використовується smart HTTP із переходом на dumb HTTP, якщо smart-обмін завершується помилкою. Передайте $depth для поверхневого клонування.

Якщо $options['processes'] має значення false, генерується RuntimeException. Якщо клонування не вдається, а $path раніше не існував, частково створений каталог видаляється.

PHP
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/repo');
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/shallow', 1);
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/tmp/repo', null, ['hooks' => false]);

processFreeOptions

PHP
public static function processFreeOptions(): array

Повертає ['processes' => false, 'hooks' => false] для середовищ виконання, у яких не можна запускати процеси хоста. Передайте його в open() або init().

isRepository

PHP
public static function isRepository(string $path): bool

Перевіряє, чи є шлях репозиторієм git. Повертає true для звичайних репозиторіїв (каталог .git/), пов’язаних робочих дерев (файл .git) і чистих репозиторіїв (наявний файл HEAD).

PHP
if (Pitmaster::isRepository('/path/to/check')) {
    // It's a git repo
}

isWorktree

PHP
public static function isWorktree(string $path): bool

Перевіряє, чи є шлях пов’язаним робочим деревом (а не основним репозиторієм). Повертає true, лише якщо .git — файл із посиланням gitdir:.

PHP
if (Pitmaster::isWorktree('/path/to/worktree')) {
    // It's a linked worktree
}

commonGitDir

PHP
public static function commonGitDir(string $path): ?string

Визначає спільний каталог git за будь-яким шляхом отриманої копії. Для звичайних репозиторіїв це каталог .git. Для пов’язаних робочих дерев — спільний каталог git, що містить об’єкти, конфігурацію та packed-refs. Повертає null, якщо шлях не є репозиторієм.

PHP
$common = Pitmaster::commonGitDir('/path/to/worktree');
// '/path/to/main-repo/.git'

Pitmaster\Repository

Клас Pitmaster\Repository — основний дескриптор для всіх операцій із git. Отримайте його через Pitmaster::open(), Pitmaster::init() або Pitmaster::clone().

PHP
use Pitmaster\Repository;

Методи доступу до шляхів

gitDir

PHP
public function gitDir(): string

Повертає каталог git для окремого робочого дерева. Для звичайних репозиторіїв це .git/. Для пов’язаних робочих дерев — .git/worktrees/<name>/.

commonGitDir

PHP
public function commonGitDir(): string

Повертає спільний каталог git. Для звичайних репозиторіїв це те саме, що gitDir(). Для пов’язаних робочих дерев це каталог .git/ основного репозиторію (де зберігаються об’єкти, конфігурація та packed-refs).

workDir

PHP
public function workDir(): string

Повертає шлях до кореня робочого дерева.

isLinkedWorktree

PHP
public function isLinkedWorktree(): bool

Повертає true, якщо цей дескриптор репозиторію відповідає пов’язаному робочому дереву.

isBare, hooksEnabled, processesEnabled

PHP
public function isBare(): bool
public function hooksEnabled(): bool
public function processesEnabled(): bool

Повідомляє, чи репозиторій не має робочого дерева, і які параметри hooks / processes діють для цього дескриптора. hooksEnabled() має значення false, коли процеси вимкнено.

Об’єкти

readObject

PHP
public function readObject(string $hash): GitObject

Зчитує об’єкт за повним шістнадцятковим хешем (40 символів або 64 у репозиторії SHA-256). Скорочені хеші не приймаються. Повертає екземпляр Blob, Tree, Commit або Tag. Спершу шукає серед окремих об’єктів, а потім у pack-файлах.

Якщо хеш не знайдено, генерується ObjectNotFoundException.

PHP
$object = $repo->readObject('a1b2c3d4e5f6...');

writeObject

PHP
public function writeObject(GitObject $object): ObjectId

Записує об’єкт у сховище окремих об’єктів. Повертає обчислене значення ObjectId.

PHP
use Pitmaster\Object\Blob;

$blob = Blob::fromContent('Hello, world!');
$id = $repo->writeObject($blob);

catFile

PHP
public function catFile(string $hash): string

Повертає необроблений вміст об’єкта; еквівалент git cat-file -p.

PHP
echo $repo->catFile('a1b2c3d4...');

objectExists

PHP
public function objectExists(string $hash): bool

Перевіряє, чи існує об’єкт у репозиторії (окремо або в pack-файлі).

listObjects

PHP
public function listObjects(): array

Перелічує всі хеші об’єктів у репозиторії. Повертає масив шістнадцяткових рядків.

Посилання

PHP
public function head(): Commit

Повертає поточний коміт HEAD. Переходить за символічними посиланнями (HEAD -> refs/heads/main -> хеш коміту).

Якщо HEAD не вказує на дійсний коміт (e.g, порожній репозиторій), генерується RuntimeException.

branch

PHP
public function branch(?string $name = null): ?string

Без аргументів повертає назву поточної гілки (e.g, 'main') або null, якщо HEAD від’єднано.

Якщо передано назву гілки, повертає хеш її коміту (шістнадцятковий рядок) або null, якщо такої гілки немає.

PHP
$current = $repo->branch();        // 'main'
$hash = $repo->branch('feature');   // 'abc123...' or null

branches

PHP
public function branches(): array

Повертає відсортований масив назв усіх гілок (без префікса refs/heads/).

PHP
$branches = $repo->branches();
// ['bugfix/typo', 'feature/login', 'main']

tags

PHP
public function tags(): array

Повертає відсортований масив назв усіх тегів (без префікса refs/tags/).

resolve

PHP
public function resolve(string $revision): ObjectId

Розв’язує вираз ревізії в ObjectId. Підтримуються:

  • Повні шістнадцяткові хеші (40 символів або 64 для SHA-256). Скорочені хеші, як-от abc1234, не розпізнаються.
  • HEAD
  • Назви гілок (main, feature/login)
  • Назви тегів (v1.0.0)
  • Повні шляхи посилань (refs/heads/main)
  • Вирази ревізій (HEAD~3, main^2)

Якщо ревізію не вдалося розпізнати, генерується RuntimeException.

PHP
$id = $repo->resolve('HEAD~3');
$id = $repo->resolve('v1.0.0');
$id = $repo->resolve('feature/login');

allRefs

PHP
public function allRefs(): array

Повертає всі посилання як асоціативний масив: назва посилання — шістнадцятковий хеш.

PHP
$refs = $repo->allRefs();
// ['refs/heads/main' => 'abc123...', 'refs/tags/v1.0.0' => 'def456...']

updateRef

PHP
public function updateRef(string $name, ObjectId $target): void

Оновлює посилання, щоб воно вказувало на нову ціль.

PHP
$repo->updateRef('refs/heads/main', $commitId);

createBranch

PHP
public function createBranch(string $name, ?ObjectId $from = null): void

Створює нову гілку. Якщо $from має значення null, вона створюється від поточного HEAD.

PHP
$repo->createBranch('feature/new-thing');
$repo->createBranch('hotfix', $repo->resolve('v1.0.0'));

deleteBranch

PHP
public function deleteBranch(string $name): void

Видаляє гілку за назвою. Якщо гілку отримано або її не існує, генерується RuntimeException. На відміну від git branch -d, цей метод не перевіряє, чи виконано злиття гілки.

PHP
$repo->deleteBranch('feature/old');

createLightweightTag

PHP
public function createLightweightTag(string $name, ?ObjectId $target = null): void

Створює легковаговий тег. Якщо $target має значення null, тег безпосередньо додається до поточного HEAD.

PHP
$repo->createLightweightTag('v2.0.0');
$repo->createLightweightTag('hotfix-start', $repo->resolve('main~2'));

createTag

PHP
public function createTag(string $name, string $message, ?ObjectId $target = null, ?string $tagger = null): ObjectId

Створює анотований тег. Якщо $target має значення null, позначає поточний HEAD тегом. Повертає ObjectId об’єкта тегу.

PHP
$tagId = $repo->createTag('v2.0.0', 'Release version 2.0.0');

deleteTag

PHP
public function deleteTag(string $name): void

Видаляє тег за назвою.

PHP
$repo->deleteTag('v1.0.0');

packRefs

PHP
public function packRefs(): void

Перезаписує спільний файл packed-refs на основі поточного набору вільних посилань і видаляє відповідні спільні вільні посилання. Для зв’язаних робочих дерев записує дані в спільний каталог git.

PHP
$repo->packRefs();

defaultBranch

PHP
public function defaultBranch(): string

Визначає гілку репозиторію за замовчуванням. Спочатку перевіряє символьне посилання HEAD віддаленого репозиторію, потім локальний HEAD, а далі використовує main або master.

isBranchMerged

PHP
public function isBranchMerged(string $branch, ?string $target = null): bool

Перевіряє, чи повністю злито гілку з іншою гілкою (за замовчуванням — із гілкою за замовчуванням).

PHP
if ($repo->isBranchMerged('feature/done')) {
    $repo->deleteBranch('feature/done');
}

checkout

PHP
public function checkout(string $target): void

Перемикає гілки або від’єднує HEAD. Оновлює HEAD, індекс і робоче дерево. $target може бути назвою гілки, тегом, повним хешем або виразом ревізії; якщо це не гілка, HEAD від’єднується.

Викидає RuntimeException, якщо локальна зміна (проіндексована чи ні) або невідстежуваний файл є за шляхом, що відрізняється в поточному дереві та цільовому дереві.

Незакомічені зміни в інших відстежуваних файлах не переносяться: індекс і робоче дерево перебудовуються на основі цільового дерева, тому зміни у файлах, однакових в обох деревах, втрачаються; git зберіг би їх (#2). Спочатку створіть коміт або сховайте зміни. merge(), cherryPick(), revert(), rebase() і методи bisect перебудовують робоче дерево так само.

PHP
$repo->checkout('feature/login');
$repo->checkout($repo->resolve('v1.0.0')->hex);  // Detached HEAD

Індекс

index

PHP
public function index(): Index

Читає та повертає поточний індекс (область підготовки) з .git/index.

add

PHP
public function add(string ...$paths): void

Додає файли до індексу. Читає кожен файл із робочого дерева, створює об’єкт blob і оновлює індекс. Кожен аргумент має бути шляхом до файлу (або символічного посилання) відносно кореня робочого дерева; каталоги та шаблони не розгортаються, а якщо файл відсутній, викидається RuntimeException.

PHP
$repo->add('src/Feature.php', 'tests/FeatureTest.php');

remove

PHP
public function remove(string ...$paths): void
public function removeCached(string ...$paths): void

Видаляє відстежувані шляхи і з індексу, і з робочого дерева. Підтримує --cached та -r / --recursive у списку аргументів для поведінки на кшталт Git.

PHP
$repo->remove('old-file.txt');
$repo->remove('-r', 'src');
$repo->remove('--cached', 'old-file.txt');
$repo->removeCached('old-file.txt');

mv

PHP
public function mv(string $source, string $destination): void

Переміщує або перейменовує файл і в робочому дереві, і в індексі.

PHP
$repo->mv('old-name.php', 'new-name.php');

Коміти

commit

PHP
public function commit(?string $message = null, ?string $author = null): ObjectId

Створює коміт із поточного індексу. Будує ієрархію дерева на основі записів індексу, створює об’єкт коміту з HEAD як батьківським комітом (якщо він є) та оновлює HEAD. Повертає ObjectId нового коміту.

$message може мати значення null лише тоді, коли злиття, cherry-pick, скасування коміту або перебазування зупинилося через конфлікт; у такому разі використовується підготовлене повідомлення. В інших випадках повідомлення null спричиняє помилку RuntimeException('Commit message required'). Коміт також спричиняє помилку, якщо індекс містить нерозлиті шляхи, якщо в репозиторії без комітів індекс порожній або якщо дерево не змінилося порівняно з HEAD.

Параметр $author — це повний рядок автора git (Name <email> timestamp timezone). Якщо значення null, його визначають зі змінних середовища, констант і .git/config у порядку, описаному в розділі Початок роботи.

PHP
$id = $repo->commit('Fix null pointer bug');

show

PHP
public function show(string $revision): array

Показує коміт і його різницю з першим батьківським комітом. Якщо ревізія відповідає анотованому тегу, повернене значення також містить ['tag' => Tag], а commit — це цільовий коміт після розіменування тегу.

PHP
$result = $repo->show('HEAD');
echo $result['commit']->message;

foreach ($result['diff'] as $diff) {
    echo $diff->format();
}

reset

PHP
public function reset(string $revision, string $mode = 'mixed'): void

Скидає HEAD до коміту. Режими:

  • 'soft': перемістити лише HEAD
  • 'mixed': перемістити HEAD і скинути індекс (за замовчуванням)
  • 'hard': перемістити HEAD, скинути індекс і робоче дерево
PHP
$repo->reset('HEAD~1', 'soft');
$repo->reset('main', 'hard');

restore

PHP
public function restore(string $path, ?string $source = null, bool $staged = false, bool $worktree = false): void

Відновлює шлях з індексу або вказаної вихідної ревізії. Якщо не встановлено жодного прапорця, Pitmaster відновлює робоче дерево з індексу (або з $source, якщо його вказано). staged: true відновлює індекс із HEAD (або $source), не змінюючи робоче дерево; передайте staged: true, worktree: true, щоб відновити обидва.

PHP
$repo->restore('src/File.php');                                        // Worktree from index
$repo->restore('src/File.php', staged: true);                          // Index from HEAD
$repo->restore('src/File.php', 'HEAD~1');                              // Worktree from another commit
$repo->restore('src/File.php', 'HEAD~1', staged: true, worktree: true); // Index + worktree from another commit

cherryPick

PHP
public function cherryPick(string $revision): ObjectId
public function cherryPickContinue(): ObjectId
public function cherryPickAbort(): void

Застосовує коміт як новий коміт у поточній гілці, зберігаючи початкового автора. Якщо операцію зупинено через конфлікти, усуньте їх, додайте шляхи до індексу, а потім викличте cherryPickContinue() або cherryPickAbort().

PHP
$newId = $repo->cherryPick('feature~2');

// After resolving conflicts:
$repo->add('src/File.php');
$repo->cherryPickContinue();

revert

PHP
public function revert(string $revision): ObjectId
public function revertContinue(): ObjectId
public function revertAbort(): void

Створює коміт, що скасовує інший коміт. Якщо скасування зупинено через конфлікти, усуньте їх, додайте шляхи до індексу, а потім викличте revertContinue() або revertAbort().

PHP
$revertId = $repo->revert('HEAD~1');

// After resolving conflicts:
$repo->add('src/File.php');
$repo->revertContinue();

rebase

PHP
public function rebase(string $onto): array
public function rebaseContinue(): array
public function rebaseAbort(): void
public function rebaseSkip(): array

Перебазовує поточну гілку на іншу ревізію. Наразі Pitmaster підтримує лінійне перебазування зі станом зупинки через конфлікти у форматі Git, а також продовження, переривання та пропуск. HEAD має вказувати на гілку.

rebase(), rebaseContinue() і rebaseSkip() повертають ['success' => bool, 'commits' => int, 'conflicts' => list<string>]: чи завершилося перебазування, скільки комітів застосовано та шляхи з конфліктами, якщо перебазування зупинилося.

PHP
$result = $repo->rebase('main');

if (!$result['success']) {
    // Resolve conflicts, then continue or skip/abort.
    $repo->add('src/File.php');
    $repo->rebaseContinue();
}

Стан

status

PHP
public function status(): array

Обчислює стан робочого дерева. Повертає масив об’єктів StatusEntry, кожен із яких містить:

  • path: шлях до файлу
  • index: перелік FileStatus змін між HEAD та індексом
  • worktree: перелік FileStatus змін між індексом і робочим деревом
  • origPath, renameScore: задаються для перейменованих записів, інакше — null

Для невідстежуваних файлів в обох стовпцях указано FileStatus::Untracked. Ігноровані файли не відображаються.

PHP
foreach ($repo->status() as $entry) {
    echo $entry->shortFormat() . "\n"; // "M  src/File.php", "?? notes.txt"
}

statusPorcelainV2

PHP
public function statusPorcelainV2(): string

Виводить дані про стан у машиночитному форматі porcelain v2 від git.

PHP
echo $repo->statusPorcelainV2();
// 1 M. N... 000000 000000 000000 0000...0000 0000...0000 modified-file.txt
// ? untracked-file.txt

Різниця

diff

PHP
public function diff(?string $pathspec = null, string $algorithm = 'myers'): array

Порівнює робоче дерево з індексом (непроіндексовані зміни). Повертає масив об’єктів DiffResult. $pathspec фільтрує за одним точним шляхом до файлу. $algorithm — це 'myers' (за замовчуванням), 'patience', 'histogram' або 'minimal'; будь-яке інше значення спричиняє помилку InvalidArgumentException.

PHP
$diffs = $repo->diff();

foreach ($diffs as $diff) {
    echo $diff->format();  // Unified diff output
}

diffStaged

PHP
public function diffStaged(?string $pathspec = null, string $algorithm = 'myers'): array

Порівнює індекс із HEAD (проіндексовані зміни). Повертає DiffResult[] з виявленням перейменувань між видаленими та доданими файлами.

Аргумент $pathspec наразі ігнорується, тому повертаються всі проіндексовані файли; до першого коміту метод повертає порожній масив (#5).

PHP
$staged = $repo->diffStaged();

diffTree

PHP
public function diffTree(ObjectId $a, ObjectId $b, string $algorithm = 'myers'): array

Порівнює два дерева за їхнім ObjectId. Повертає DiffResult[]. Передавайте ідентифікатори дерев, а не комітів: ідентифікатор коміту не розпізнається як дерево й повертає порожній результат.

PHP
$old = $repo->readObject($repo->resolve('HEAD~1')->hex);
$new = $repo->head();
$diffs = $repo->diffTree($old->tree, $new->tree);

Журнал

log

PHP
public function log(int $limit = 50, ?ObjectId $from = null): array

Переглядає історію комітів, від найновішого за міткою часу комітера. Повертає Commit[]. Якщо $from має значення null, починає з HEAD. Повертає порожній масив, якщо в HEAD ще немає комітів.

PHP
$commits = $repo->log(10);

logAll

PHP
public function logAll(int $limit = 50): array

Переглядає коміти, досяжні з кожного посилання та HEAD, від найновішого. Повертає Commit[].

logOneline

PHP
public function logOneline(int $limit = 50, bool $all = false, ?string $path = null): array

Повертає рядки журналу у форматі git log --oneline (abc1234 Subject), починаючи з HEAD, з усіх посилань ($all) або з фільтром за шляхом.

logPath

PHP
public function logPath(string $path, int $limit = 50): array

Фільтрує журнал за шляхом до файлу. Повертає лише коміти, у різниці яких із першим батьківським комітом цей точний файл додано, змінено, видалено або перейменовано. Шляхи до каталогів не збігаються.

Перевіряються лише 5 * $limit найновіших комітів, тож старіші коміти, що стосуються файлу, можуть бути відсутні в результаті (#7).

PHP
$commits = $repo->logPath('src/Repository.php', 20);

Злиття

merge

PHP
public function merge(string $branch, string $strategy = 'recursive'): MergeResult
public function mergeOctopus(array $branches): MergeResult
public function mergeContinue(): ObjectId
public function mergeAbort(): void

Зливає гілку (або будь-яку ревізію) в HEAD. Автоматично виявляє злиття перемотуванням уперед. Для інших злиттів перевіряє конфлікти на рівні дерева та створює коміт злиття, якщо конфліктів немає. Якщо виникають конфлікти, записує стан злиття у форматі Git до індексу й робочого дерева; усуньте конфлікти, додайте шляхи до індексу, а потім викличте mergeContinue() або mergeAbort().

Параметр $strategy 'ours' записує коміт злиття, який зберігає дерево HEAD; будь-яке інше значення вмикає стандартне рекурсивне злиття. mergeOctopus() зливає дві або більше гілок в один коміт. Якщо в будь-якій гілці є конфлікти, повертається результат із конфліктами без запису стану злиття та створення коміту.

Злиття гілки, яка вже міститься в HEAD, створює ще один коміт злиття замість повідомлення «Уже актуально» (#6). Незакомічені зміни у відстежуваних файлах перезаписуються, як описано в розділі checkout().

Повертає MergeResult із такими полями:

  • clean: чи виконалося злиття без конфліктів
  • commitId: ідентифікатор коміту злиття (якщо конфліктів немає)
  • conflictPaths: масив шляхів файлів із конфліктами (якщо конфлікти є)
  • mergedContents: шлях із конфліктом до файлу з маркерами конфлікту (якщо конфлікти є)
PHP
$result = $repo->merge('feature/login');

if ($result->clean) {
    echo "Merged: {$result->commitId->hex}\n";
} else {
    echo "Conflicts in: " . implode(', ', $result->conflictPaths) . "\n";
    $repo->add('src/File.php');
    $repo->mergeContinue();
}

mergeBase

PHP
public function mergeBase(ObjectId $a, ObjectId $b): ?ObjectId

Знаходить базу злиття (найближчого спільного предка) двох комітів. Повертає null, якщо спільного предка немає.

PHP
$base = $repo->mergeBase(
    $repo->resolve('main'),
    $repo->resolve('feature/login'),
);

Бісекція

PHP
public function bisectStart(string $bad, string $good): ObjectId
public function bisectGood(?string $revision = null): ?ObjectId
public function bisectBad(?string $revision = null): ?ObjectId
public function bisectReset(): void

Знаходить бінарним пошуком коміт, у якому з’явилася зміна. bisectStart() записує погану та добру ревізії, перемикається на першого кандидата й повертає його. bisectGood() і bisectBad() позначають поточний HEAD (або $revision), перемикаються на наступного кандидата та повертають його. Коли залишається один підозрюваний коміт, він повертається й залишається кандидатом: це перший поганий коміт. bisectReset() завершує сеанс і повертає до гілки або коміту, з якого він почався.

PHP
$candidate = $repo->bisectStart('HEAD', 'v1.0.0');
// test $candidate ...
$candidate = $repo->bisectBad();
$candidate = $repo->bisectGood();
$repo->bisectReset();

Мережа

fetch

PHP
public function fetch(string $remote = 'origin', ?int $depth = null): void

Отримує дані з віддаленого репозиторію. Завантажує нові об’єкти й оновлює віддалені відстежувані посилання. Передайте $depth, щоб поглибити або обмежити неглибоку історію.

fetch() і методи push*() викидають RuntimeException для дескриптора, відкритого з ['processes' => false].

PHP
$repo->fetch();
$repo->fetch('upstream');

push

PHP
public function push(string $remote = 'origin', ?string $branch = null): void
public function pushForceWithLease(string $remote = 'origin', ?string $branch = null, ?ObjectId $expected = null): void
public function pushAtomic(string $remote = 'origin', array $branches = []): void
public function pushMirror(string $remote = 'origin'): void

Надсилає поточну гілку (або вказану гілку) до віддаленого репозиторію. Для суворішого або ширшого оновлення посилань доступні варіанти force-with-lease, atomic і mirror.

PHP
$repo->push();
$repo->push('origin', 'feature/login');
$repo->pushForceWithLease('origin', 'main', $repo->resolve('refs/remotes/origin/main'));
$repo->pushAtomic('origin', ['main', 'release']);
$repo->pushMirror();

Робочі дерева

addWorktree

PHP
public function addWorktree(string $path, string $branch, ?ObjectId $from = null, ?string $name = null): Worktree

Додає зв’язане робоче дерево. Створює гілку, якщо її ще немає, налаштовує метадані робочого дерева й створює файли робочого дерева. Передайте $name, якщо потрібен детермінований ідентифікатор метаданих, відмінний від назви каталогу робочої копії.

PHP
$wt = $repo->addWorktree('/tmp/review', 'feature/review');
$wt = $repo->addWorktree('/tmp/checkouts/review', 'feature/review', name: 'review-wt');

removeWorktree

PHP
public function removeWorktree(string $pathOrName, bool $force = false): void

Видаляє зв’язане робоче дерево. Використовуйте $force = true, щоб видалити його, навіть якщо воно заблоковане.

worktrees

PHP
public function worktrees(): array

Перелічує всі робочі дерева (основне та зв’язані). Повертає Worktree[].

PHP
foreach ($repo->worktrees() as $wt) {
    echo "{$wt->path} [{$wt->branch}]\n";
}

Конфігурація

config

PHP
public function config(): GitConfig

Отримує доступ до конфігурації git репозиторію. Читає та записує значення конфігурації.

PHP
$config = $repo->config();
$name = $config->get('user.name');
$config->set('user.email', 'new@example.com');

Внутрішній доступ

Ці методи відкривають доступ до внутрішніх компонентів для складних випадків використання.

objectDatabase

PHP
public function objectDatabase(): ObjectDatabase

Отримує доступ до бази даних необроблених об’єктів (вільних об’єктів і пакетів).

refDatabase

PHP
public function refDatabase(): RefDatabase

Отримує доступ до бази даних необроблених посилань (вільних і упакованих посилань).

Класи нижчого рівня

Ці класи не обгорнуті в Repository і створюються з його внутрішніх компонентів.

Pitmaster\Graph\Blame

PHP
public function blame(ObjectId $headId, string $path): array

Повертає по одному запису на рядок із $path за адресою $headId: ['line' => int, 'hash' => string, 'author' => string, 'content' => string]. author — це повний рядок ідентифікації (Name <email> timestamp timezone).

PHP
use Pitmaster\Graph\Blame;

$blame = new Blame($repo->objectDatabase());

foreach ($blame->blame($repo->resolve('HEAD'), 'src/File.php') as $line) {
    echo substr($line['hash'], 0, 8) . " {$line['content']}\n";
}

Pitmaster\Graph\Grep

PHP
public function grep(ObjectId $treeId, string $pattern, string $prefix = '', array $options = []): array

Шукає в blob-об’єктах дерева. Повертає ['path' => string, 'line' => int, 'content' => string] для кожного рядка зі збігом. Параметри: regex (трактує шаблон як шаблон PCRE) і ignore_case. Некоректний регулярний вираз спричиняє помилку InvalidArgumentException.

PHP
use Pitmaster\Graph\Grep;

$grep = new Grep($repo->objectDatabase());
$matches = $grep->grep($repo->head()->tree, 'TODO', '', ['ignore_case' => true]);

Pitmaster\Ref\Notes

PHP
public function get(ObjectId $commitId, string $notesRef = 'refs/notes/commits'): ?string
public function set(ObjectId $commitId, string $noteContent, string $notesRef = 'refs/notes/commits'): void
public function remove(ObjectId $commitId, string $notesRef = 'refs/notes/commits'): void
public function listAll(string $notesRef = 'refs/notes/commits'): array
public function merge(string $sourceRef, string $targetRef = 'refs/notes/commits'): void

Читає та записує нотатки git, що зберігаються за посиланням нотаток. listAll() повертає хеш коміту, зіставлений із вмістом нотатки.

PHP
use Pitmaster\Ref\Notes;

$notes = new Notes($repo->objectDatabase(), $repo->refDatabase());
$notes->set($repo->resolve('HEAD'), "Reviewed\n");
echo $notes->get($repo->resolve('HEAD'));