# PHP API

## `Pitmaster\Pitmaster`

Klase `Pitmaster\Pitmaster` ir statisks sākumpunkts. Tā nodrošina rūpnīcas metodes repozitoriju atvēršanai, izveidei un klonēšanai, kā arī noteikšanas palīgmetodes.

```php
use Pitmaster\Pitmaster;
```

### `open`

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

Atveriet esošu repozitoriju šeit: `$path`. Ceļam jābūt darba koka saknei (kurā atrodas `.git/`). Tiek atbalstīti arī saistīti darba koki (kuros `.git` ir fails ar `gitdir: <path>`) un tukši repozitoriji (kuros `$path` ir pati `.git` direktorija).

`$options` pieņem divas Būla vērtības, kuru noklusējums ir `true`:

- `hooks`: palaist `.git/hooks` skriptus. Lai tos izlaistu šim apstrādes objektam, norādiet `false`.
- `processes`: atļaut darbības, kas palaiž procesu vai atver tīkla transportu. Lai atspējotu āķus, fsmonitor āķi, klonēšanu, izgūšanu, nosūtīšanu un SSH procesa transportu, norādiet `false`. Lokālā lasīšana un rakstīšana joprojām darbojas.

Ja ceļš nav git repozitorijs, tiek izraisīts `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
```

Inicializē jaunu repozitoriju vietā `$path`. Izveido `.git` direktoriju struktūru ar `objects/`, `refs/heads/`, `refs/tags/`, `hooks/`, `info/`, `HEAD` (kas norāda uz `refs/heads/main`) un noklusējuma `config`.

`$objectFormat` ir `'sha1'` vai `'sha256'`. SHA-256 repozitorijam konfigurācijā tiek iestatīti `repositoryformatversion = 1` un `extensions.objectformat = sha256`. Jebkura cita vērtība izraisa `InvalidArgumentException`. `$options` pieņem tos pašus atslēgas parametrus kā `open()`.

Izraisa `RuntimeException`, ja norādītajā ceļā jau pastāv repozitorijs.

```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
```

Klonē attālo repozitoriju. Inicializē jaunu repozitoriju, atrod attālās atsauces, lejupielādē pakotnes failu, iestata attālās izsekošanas zarus un izveido darba koka saturu. SSH URL (`ssh://...` vai `user@host:path`) izmanto SSH transportu; pārējie URL izmanto viedo HTTP un, ja viedā apmaiņa neizdodas, pāriet uz vienkāršo HTTP. Seklai klonēšanai nododiet `$depth`.

Izraisa `RuntimeException`, ja `$options['processes']` ir `false`. Ja klonēšana neizdodas un `$path` iepriekš nepastāvēja, daļēji izveidotā direktorija tiek dzēsta.

```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
```

Atgriež `['processes' => false, 'hooks' => false]` izpildvidēm, kurās nedrīkst palaist resursdatora procesus. Nododiet to funkcijai `open()` vai `init()`.

### `isRepository`

```php
public static function isRepository(string $path): bool
```

Pārbauda, vai ceļš ir git repozitorijs. Atgriež `true` parastiem repozitorijiem (direktorija `.git/`), saistītām darba koka kopijām (fails `.git`) un tukšiem repozitorijiem (ja ir fails `HEAD`).

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

### `isWorktree`

```php
public static function isWorktree(string $path): bool
```

Pārbauda, vai ceļš ir saistīta darba koka kopija (nevis galvenais repozitorijs). Atgriež `true` tikai tad, ja `.git` ir fails, kurā ir atsauce `gitdir:`.

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

### `commonGitDir`

```php
public static function commonGitDir(string $path): ?string
```

Atrod kopīgo git direktoriju no jebkura izrakstījuma ceļa. Parastiem repozitorijiem tas ir direktorija `.git`. Saistītām darba koka kopijām tas ir koplietotais git direktorijs, kurā atrodas objekti, konfigurācija un packed-refs. Atgriež `null`, ja ceļš nav repozitorijs.

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

---

## `Pitmaster\Repository`

Klase `Pitmaster\Repository` ir galvenais interfeiss visām git darbībām. Iegūstiet tās instanci, izmantojot `Pitmaster::open()`, `Pitmaster::init()` vai `Pitmaster::clone()`.

```php
use Pitmaster\Repository;
```

### Ceļu piekļuves metodes

#### `gitDir`

```php
public function gitDir(): string
```

Atgriež konkrētās darba koka kopijas git direktoriju. Parastiem repozitorijiem tas ir `.git/`. Saistītām darba koka kopijām tas ir `.git/worktrees/<name>/`.

#### `commonGitDir`

```php
public function commonGitDir(): string
```

Atgriež kopīgo git direktoriju. Parastiem repozitorijiem tas ir tas pats, kas `gitDir()`. Saistītām darba koka kopijām tas ir galvenā repozitorija direktorija `.git/` (kur atrodas objekti, konfigurācija un packed-refs).

#### `workDir`

```php
public function workDir(): string
```

Atgriež darba koka saknes ceļu.

#### `isLinkedWorktree`

```php
public function isLinkedWorktree(): bool
```

Atgriež `true`, ja šis repozitorija interfeiss ir saistīta darba koka kopija.

#### `isBare`, `hooksEnabled`, `processesEnabled`

```php
public function isBare(): bool
public function hooksEnabled(): bool
public function processesEnabled(): bool
```

Norāda, vai repozitorijam nav darba koka un kuras no opcijām `hooks` / `processes` ir aktīvas šim interfeisam. `hooksEnabled()` ir `false` ikreiz, kad procesi ir atspējoti.

---

### Objekti

#### `readObject`

```php
public function readObject(string $hash): GitObject
```

Nolasa jebkuru objektu pēc tā pilnā heksadecimālā jaucējkoda (40 rakstzīmes vai 64 rakstzīmes SHA-256 repozitorijā). Saīsināti jaucējkodi netiek pieņemti. Atgriež `Blob`, `Tree`, `Commit` vai `Tag` instanci. Vispirms meklē atsevišķos objektus, pēc tam pakotņu failos.

Izraisa `ObjectNotFoundException`, ja jaucējkods nav atrasts.

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

#### `writeObject`

```php
public function writeObject(GitObject $object): ObjectId
```

Ieraksta objektu atsevišķo objektu krātuvē. Atgriež aprēķināto `ObjectId`.

```php
use Pitmaster\Object\Blob;

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

#### `catFile`

```php
public function catFile(string $hash): string
```

Atgriež objekta neapstrādāto saturu; tas atbilst `git cat-file -p`.

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

#### `objectExists`

```php
public function objectExists(string $hash): bool
```

Pārbauda, vai repozitorijā pastāv objekts (atsevišķi vai pakotnē).

#### `listObjects`

```php
public function listObjects(): array
```

Uzskaita visus repozitorija objektu jaucējkodus. Atgriež heksadecimālu virkņu masīvu.

---

### Atsauces

#### `head`

```php
public function head(): Commit
```

Atgriež pašreizējo HEAD commit. Izseko simboliskās atsauces (HEAD -> refs/heads/main -> commit jaucējkods).

Izraisa `RuntimeException`, ja HEAD nenorāda uz derīgu commit (e.g., tukšs repozitorijs).

#### `branch`

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

Bez argumentiem atgriež pašreizējā zara nosaukumu (e.g., `'main'`) vai `null`, ja HEAD ir atvienots.

Ar zara nosaukumu to atrisina līdz tā commit jaucējkoda heksadecimālajai virknei vai atgriež `null`, ja zars neeksistē.

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

#### `branches`

```php
public function branches(): array
```

Atgriež sakārtotu visu zaru nosaukumu masīvu (bez prefiksa `refs/heads/`).

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

#### `tags`

```php
public function tags(): array
```

Atgriež sakārtotu visu tagu nosaukumu masīvu (bez prefiksa `refs/tags/`).

#### `resolve`

```php
public function resolve(string $revision): ObjectId
```

Atrisina redakcijas izteiksmi līdz `ObjectId`. Atbalstītie formāti:
- Pilni heksadecimālie jaucējkodi (40 rakstzīmes vai 64 rakstzīmes priekš SHA-256). Saīsināti jaucējkodi, piemēram, `abc1234`, netiek atrisināti.
- `HEAD`
- Zaru nosaukumi (`main`, `feature/login`)
- Tagu nosaukumi (`v1.0.0`)
- Pilni atsauču ceļi (`refs/heads/main`)
- Redakciju izteiksmes (`HEAD~3`, `main^2`)

Izraisa `RuntimeException`, ja redakciju neizdodas atrisināt.

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

#### `allRefs`

```php
public function allRefs(): array
```

Atgriež visas atsauces kā asociatīvu masīvu, kurā atsauces nosaukumi atbilst heksadecimāliem jaucējkodiem.

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

#### `updateRef`

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

Atjaunina atsauci, lai tā norādītu uz jaunu mērķi.

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

#### `createBranch`

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

Izveido jaunu zaru. Ja `$from` ir null, atzarojas no pašreizējā HEAD.

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

#### `deleteBranch`

```php
public function deleteBranch(string $name): void
```

Dzēš zaru pēc nosaukuma. Izraisa `RuntimeException`, ja zars ir izrakstīts vai neeksistē. Atšķirībā no `git branch -d` šī metode nepārbauda, vai zars ir sapludināts.

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

#### `createLightweightTag`

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

Izveido vieglu tagu. Ja `$target` ir null, tagu pievieno tieši pašreizējam 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
```

Izveido anotētu tagu. Ja `$target` ir null, tagu pievieno pašreizējam HEAD. Atgriež taga objekta `ObjectId`.

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

#### `deleteTag`

```php
public function deleteTag(string $name): void
```

Dzēš tagu pēc nosaukuma.

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

#### `packRefs`

```php
public function packRefs(): void
```

Pārraksta koplietoto failu `packed-refs` no pašreizējās atsevišķo atsauču kopas un dzēš atbilstošās koplietotās atsevišķās atsauces. Saistītām darba koka kopijām raksta kopīgajā git direktorijā.

```php
$repo->packRefs();
```

#### `defaultBranch`

```php
public function defaultBranch(): string
```

Nosaka repozitorija noklusējuma zaru. Vispirms pārbauda attālo HEAD simbolisko atsauci, pēc tam lokālo HEAD un, ja vajadzīgs, izmanto `main` vai `master`.

#### `isBranchMerged`

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

Pārbauda, vai zars ir pilnībā sapludināts citā zarā (pēc noklusējuma — noklusējuma zarā).

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

#### `checkout`

```php
public function checkout(string $target): void
```

Pārslēdz zarus vai atvieno HEAD. Atjaunina HEAD, indeksu un darba koku. `$target` var būt zara nosaukums, tags, pilns jaucējkods vai redakcijas izteiksme; ja tā nav zars, HEAD tiek atvienots.

Izraisa `RuntimeException`, ja ceļā, kas atšķiras starp pašreizējo un mērķa koku, atrodas lokālas izmaiņas (indeksētas vai neindeksētas) vai nesekots fails.

Neapstiprinātās izmaiņas citos izsekotos failos netiek pārnestas: indekss un darba koks tiek izveidots no jauna no mērķa koka, tāpēc izmaiņas failos, kas abās pusēs ir identiski, tiek zaudētas, lai gan git tās saglabātu ([pārslēgšana](https://github.com/inline0/pitmaster/issues/2)#2). Vispirms apstipriniet vai noglabājiet izmaiņas. `merge()`, `cherryPick()`, `revert()`, `rebase()` un bisekcijas metodes tādā pašā veidā izveido darba koku no jauna.

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

---

### Indekss

#### `index`

```php
public function index(): Index
```

Nolasa un atgriež pašreizējo indeksu (sagatavošanas apgabalu) no `.git/index`.

#### `add`

```php
public function add(string ...$paths): void
```

Pievieno failus sagatavošanai. Nolasa katru failu no darba koka, izveido blob objektu un atjaunina indeksu. Katram argumentam jābūt faila (vai simboliskās saites) ceļam attiecībā pret darba koka sakni; direktorijas un glob izteiksmes netiek izvērstas, bet neesošs fails izraisa `RuntimeException`.

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

#### `remove`

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

Noņem izsekotos ceļus gan no indeksa, gan darba koka. Argumentu sarakstā atbalsta `--cached` un `-r` / `--recursive`, lai nodrošinātu Git tipa darbību.

```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
```

Pārvieto vai pārdēvē failu gan darba kokā, gan indeksā.

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

---

### Commit

#### `commit`

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

Izveido commit no pašreizējā indeksa. Izveido koka hierarhiju no indeksa ierakstiem, izveido commit objektu ar HEAD kā vecāku (ja tāds ir) un atjaunina HEAD. Atgriež jaunā commit `ObjectId`.

`$message` var būt `null` tikai tad, ja sapludināšana, cherry-pick, atgriešana vai pārveidošana ir apturēta konfliktu dēļ; tad tiek izmantots sagatavotais ziņojums. Pretējā gadījumā `null` ziņojums izraisa `RuntimeException('Commit message required')`. Commit arī izraisa kļūdu, ja indeksā ir nesapludināti ceļi, ja indeksā nav ierakstu repozitorijā bez commit vai ja koks nav mainījies kopš HEAD.

Parametrs `$author` ir pilna git autora virkne (`Name <email> timestamp timezone`). Ja tas ir null, vērtība tiek iegūta no vides mainīgajiem, konstantēm un `.git/config` tādā secībā, kā aprakstīts sadaļā [Darba sākšana](https://pitmaster.inline0.dev/lv/docs/getting-started).

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

#### `show`

```php
public function show(string $revision): array
```

Parāda commit un tā atšķirības salīdzinājumā ar pirmo vecāku. Ja redakcija atrisinās līdz anotētam tagam, atgrieztajā vērtībā ir arī `['tag' => Tag]`, un `commit` ir atzīmētais mērķa 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
```

Atiestata HEAD uz commit. Režīmi:
- `'soft'`: pārvieto tikai HEAD
- `'mixed'`: pārvieto HEAD un atiestata indeksu (noklusējums)
- `'hard'`: pārvieto HEAD, atiestata indeksu un darba koku

```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
```

Atjauno ceļu no indeksa vai norādītas avota redakcijas. Ja nav iestatīts neviens karodziņš, Pitmaster atjauno darba koku no indeksa (vai no `$source`, ja tas norādīts). `staged: true` atjauno indeksu no HEAD (vai `$source`), darba koku atstājot nemainītu; lai atjaunotu abus, nododiet `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
```

Piemēro commit kā jaunu commit pašreizējā zarā, saglabājot sākotnējo autoru. Ja konfliktu dēļ darbība tiek apturēta, atrisiniet konfliktus, pievienojiet ceļus sagatavošanai un pēc tam izsauciet `cherryPickContinue()` vai `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
```

Izveido commit, kas atceļ citu commit. Ja konfliktu dēļ atcelšana tiek apturēta, atrisiniet konfliktus, pievienojiet ceļus sagatavošanai un pēc tam izsauciet `revertContinue()` vai `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
```

Pārveido pašreizējo zaru, novietojot to virs citas redakcijas. Pitmaster pašlaik atbalsta lineāru pārveidošanu ar Git formas apturēšanas stāvokli konfliktu gadījumā, kā arī turpināšanu, pārtraukšanu un izlaišanu. HEAD ir jānorāda uz zaru.

`rebase()`, `rebaseContinue()` un `rebaseSkip()` atgriež `['success' => bool, 'commits' => int, 'conflicts' => list<string>]`: vai pārveidošana ir pabeigta, cik commit ir piemēroti un kuri ceļi izraisīja konfliktu, ja darbība tika apturēta.

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

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

---

### Statuss

#### `status`

```php
public function status(): array
```

Aprēķina darba koka statusu. Atgriež objektu `StatusEntry` masīvu, kur katrā objektā ir:
- `path`: faila ceļš
- `index`: enum `FileStatus` izmaiņām no HEAD līdz indeksam
- `worktree`: enum `FileStatus` izmaiņām no indeksa līdz darba kokam
- `origPath`, `renameScore`: iestatīti pārdēvētiem ierakstiem, citādi `null`

Nesekotiem failiem abās kolonnās ir `FileStatus::Untracked`. Ignorētie faili netiek uzrādīti.

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

#### `statusPorcelainV2`

```php
public function statusPorcelainV2(): string
```

Statusa izvade mašīnlasāmā git porcelain v2 formātā.

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

---

### Atšķirības

#### `diff`

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

Salīdzina darba koku ar indeksu (nesagatavotās izmaiņas). Atgriež objektu `DiffResult` masīvu. `$pathspec` filtrē pēc viena precīza faila ceļa. `$algorithm` ir `'myers'` (noklusējums), `'patience'`, `'histogram'` vai `'minimal'`; jebkura cita vērtība izraisa `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
```

Salīdzina indeksu ar HEAD (sagatavotās izmaiņas). Atgriež `DiffResult[]` un nosaka pārdēvēšanu starp dzēstajiem un pievienotajiem failiem.

Arguments `$pathspec` pašlaik tiek ignorēts, tāpēc tiek atgriezti visi sagatavotie faili. Pirms pirmā commit metode atgriež tukšu masīvu ([darbība](https://github.com/inline0/pitmaster/issues/5)#5).

```php
$staged = $repo->diffStaged();
```

#### `diffTree`

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

Salīdzina divus kokus pēc to `ObjectId`. Atgriež `DiffResult[]`. Nododiet koku ID, nevis commit ID: commit ID netiek nolasīts kā koks, tāpēc rezultāts ir tukšs.

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

---

### Vēsture

#### `log`

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

Pārskata commit vēsturi, sākot ar jaunāko pēc iesniedzēja laika zīmoga. Atgriež `Commit[]`. Ja `$from` ir null, sāk no HEAD. Ja HEAD vēl nav commit, atgriež tukšu masīvu.

```php
$commits = $repo->log(10);
```

#### `logAll`

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

Pārskata commit, kas sasniedzami no katras atsauces un HEAD, sākot ar jaunāko. Atgriež `Commit[]`.

#### `logOneline`

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

Atgriež žurnāla rindas `git log --oneline` formātā (`abc1234 Subject`), sākot no HEAD, no visām atsaucēm (`$all`) vai filtrējot pēc ceļa.

#### `logPath`

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

Žurnāls, filtrēts pēc faila ceļa. Atgriež tikai tos commit, kuru atšķirības salīdzinājumā ar pirmo vecāku pievieno, maina, dzēš vai pārdēvē tieši šo failu. Direktoriju ceļi netiek ņemti vērā.

Tiek pārbaudīti tikai jaunākie `5 * $limit` commit, tāpēc rezultātā var nebūt iekļauti vecāki commit, kas skar šo failu ([darbība](https://github.com/inline0/pitmaster/issues/7)#7).

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

---

### Sapludināšana

#### `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
```

Sapludina zaru (vai jebkuru redakciju) ar HEAD. Automātiski nosaka ātro pārtīšanu. Ja ātra pārtīšana nav iespējama, nosaka konfliktus koka līmenī un, ja konfliktu nav, izveido sapludināšanas commit. Konflikta gadījumā ieraksta indeksā un darba kokā sapludināšanas stāvokli Git formātā; atrisiniet konfliktus, pievienojiet ceļus sagatavošanai un pēc tam izsauciet `mergeContinue()` vai `mergeAbort()`.

`$strategy` `'ours'` reģistrē sapludināšanas commit, kas saglabā HEAD koku; jebkura cita vērtība izmanto noklusējuma rekursīvo sapludināšanu. `mergeOctopus()` sapludina divus vai vairākus zarus vienā commit. Ja kādā zarā ir konflikti, metode atgriež neveiksmīgu rezultātu, neierakstot sapludināšanas stāvokli un neveidojot commit.

Sapludinot zaru, kas jau ir ietverts HEAD, tiek izveidots vēl viens sapludināšanas commit, nevis paziņots “Already up to date” ([darbība](https://github.com/inline0/pitmaster/issues/6)#6). Neapstiprinātās izmaiņas izsekotos failos tiek pārrakstītas, kā aprakstīts sadaļā `checkout()`.

Atgriež `MergeResult` ar šādiem laukiem:
- `clean`: vai sapludināšana izdevās bez konfliktiem
- `commitId`: sapludināšanas commit ID (ja konfliktu nav)
- `conflictPaths`: konfliktējošo failu ceļu masīvs (ja ir konflikti)
- `mergedContents`: konfliktējošā ceļa un faila satura atbilstība, tostarp konfliktu marķieri (ja ir konflikti)

```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
```

Atrod divu commit sapludināšanas bāzi (zemāko kopīgo priekšteci). Atgriež null, ja kopīga priekšteča nav.

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

### Bisekcija

```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
```

Ar bināro meklēšanu atrod commit, kurā ieviestas izmaiņas. `bisectStart()` reģistrē sliktās un labās redakcijas, izraksta pirmo kandidātu un atgriež to. `bisectGood()` un `bisectBad()` atzīmē pašreizējo HEAD (vai `$revision`), izraksta nākamo kandidātu un atgriež to. Kad palicis viens aizdomās turamais, attiecīgais commit tiek atgriezts un paliek kandidāts: tas ir pirmais sliktais commit. `bisectReset()` beidz sesiju un atgriežas pie zara vai commit, no kura tā sākās.

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

---

### Tīkls

#### `fetch`

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

Iegūst datus no attālā repozitorija. Lejupielādē jaunus objektus un atjaunina attālās izsekošanas atsauces. Nododiet `$depth`, lai padziļinātu vai ierobežotu seklu vēsturi.

`fetch()` un metodes `push*()` izraisa `RuntimeException`, ja interfeiss ir atvērts ar `['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
```

Nosūta pašreizējo zaru (vai norādītu zaru) uz attālo repozitoriju. Pieejamas piespiedu atjaunināšanas ar izsekošanas pārbaudi, atomiskas un spoguļošanas variācijas stingrākai vai plašākai atsauču atjaunināšanai.

```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();
```

---

### Darba koka kopijas

#### `addWorktree`

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

Pievieno saistītu darba koka kopiju. Izveido zaru, ja tāda nav, iestata darba koka metadatus un izveido darba koka failus. Nododiet `$name`, ja nepieciešama noteikta metadatu identifikatora daļa, kas atšķiras no izrakstījuma direktorijas pamatnosaukuma.

```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
```

Noņem saistītu darba koka kopiju. Izmantojiet `$force = true`, lai to noņemtu arī tad, ja tā ir bloķēta.

#### `worktrees`

```php
public function worktrees(): array
```

Uzskaita visas darba koka kopijas (galveno un saistītās). Atgriež `Worktree[]`.

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

---

### Konfigurācija

#### `config`

```php
public function config(): GitConfig
```

Piekļūst repozitorija git konfigurācijai. Nolasa un raksta konfigurācijas vērtības.

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

---

### Iekšējā piekļuve

Šīs metodes nodrošina piekļuvi iekšējiem komponentiem īpašiem lietošanas gadījumiem.

#### `objectDatabase`

```php
public function objectDatabase(): ObjectDatabase
```

Piekļūst neapstrādāto objektu datubāzei (atsevišķo objektu un pakotņu krātuvēm).

#### `refDatabase`

```php
public function refDatabase(): RefDatabase
```

Piekļūst neapstrādāto atsauču datubāzei (atsevišķām un pakotnē glabātām atsaucēm).

---

## Zemāka līmeņa klases

Šīs klases neietver iesaiņojums `Repository`; tās tiek veidotas no tā iekšējiem komponentiem.

### `Pitmaster\Graph\Blame`

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

Atgriež vienu ierakstu katrai `$path` rindai pozīcijā `$headId`: `['line' => int, 'hash' => string, 'author' => string, 'content' => string]`. `author` ir pilna identitātes virkne (`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
```

Meklē koka blob objektos. Atgriež `['path' => string, 'line' => int, 'content' => string]` katrai atrastajai rindai. Opcijas: `regex` (uztver rakstu kā PCRE rakstu) un `ignore_case`. Nederīga regulārā izteiksme izraisa `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
```

Nolasa un raksta git piezīmes, kas glabātas zem piezīmju atsauces. `listAll()` atgriež commit jaucējkoda un piezīmes satura atbilstību.

```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'));
```