# PHP API

## `Pitmaster\Pitmaster`

A `Pitmaster\Pitmaster` osztály a statikus belépési pont. Gyári metódusokat biztosít tárolók megnyitásához, létrehozásához és klónozásához, továbbá felismerő segédfüggvényeket is kínál.

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

### `open`

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

Meglévő tároló megnyitása itt: `$path`. Az elérési útnak a munkafa gyökérkönyvtárára kell mutatnia (amely tartalmazza a `.git/` elemet). Az összekapcsolt munkafák is támogatottak (ahol a `.git` egy `gitdir: <path>` értéket tartalmazó fájl), ahogy a bare tárolók is (ahol a `$path` maga a `.git` könyvtár).

A `$options` két logikai értéket fogad el, mindkettő alapértelmezése `true`:

- `hooks`: `.git/hooks` szkriptek futtatása. Adja át a `false` értéket a kihagyásukhoz ennél a fogantyúnál.
- `processes`: minden olyan művelet engedélyezése, amely folyamatot indít vagy hálózati átvitelt nyit. Adja át a `false` értéket a hookok, az fsmonitor hook, a klónozás, a letöltés, a push és a SSH folyamatátvitel letiltásához. A helyi olvasás és írás továbbra is működik.

`InvalidArgumentException` kivételt dob, ha az elérési út nem git tároló.

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

Új tároló inicializálása itt: `$path`. Létrehozza a `.git` könyvtárstruktúrát a következőkkel: `objects/`, `refs/heads/`, `refs/tags/`, `hooks/`, `info/`, `HEAD` (amely erre mutat: `refs/heads/main`), valamint egy alapértelmezett `config`.

A `$objectFormat` értéke `'sha1'` vagy `'sha256'` lehet. A SHA-256 tároló `repositoryformatversion = 1` és `extensions.objectformat = sha256` beállítást kap a konfigurációban. Minden más érték esetén `InvalidArgumentException` kivételt dob. A `$options` ugyanazokat a kulcsokat fogadja el, mint a `open()`.

`RuntimeException` kivételt dob, ha az elérési úton már létezik tároló.

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

Távoli tároló klónozása. Inicializál egy új tárolót, felderíti a távoli refeket, letölti a pack fájlt, beállítja a távoli követő ágakat, majd előállítja a munkafát. A SSH URL-ek (`ssh://...` vagy `user@host:path`) a SSH átvitelt használják; más URL-ek smart HTTP átvitelt használnak, és visszaváltanak dumb HTTP módra, ha a smart adatcsere sikertelen. Sekély klónozáshoz adja át a `$depth` értéket.

`RuntimeException` kivételt dob, ha a `$options['processes']` értéke `false`. Ha a klónozás sikertelen, és a `$path` korábban nem létezett, a részben létrehozott könyvtárat eltávolítja.

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

Olyan futtatókörnyezetekhez `['processes' => false, 'hooks' => false]` értéket ad vissza, amelyek nem indíthatnak gazdagép-folyamatokat. Adja át a `open()` vagy a `init()` számára.

### `isRepository`

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

Ellenőrzi, hogy egy elérési út git tároló-e. `true` értéket ad vissza hagyományos tárolók esetén (`.git/` könyvtár), összekapcsolt munkafák esetén (`.git` fájl), valamint bare tárolók esetén (a `HEAD` fájl jelen van).

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

### `isWorktree`

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

Ellenőrzi, hogy egy elérési út összekapcsolt munkafára (nem a fő tárolóra) mutat-e. Csak akkor ad vissza `true` értéket, ha a `.git` egy `gitdir:` hivatkozást tartalmazó fájl.

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

### `commonGitDir`

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

Feloldja a közös git könyvtárat bármely checkout elérési útból. Hagyományos tárolóknál ez a `.git` könyvtár. Összekapcsolt munkafáknál ez a megosztott git könyvtár, amely az objektumokat, a konfigurációt és a packed-refs állományt tartalmazza. `null` értéket ad vissza, ha az elérési út nem tároló.

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

---

## `Pitmaster\Repository`

A `Pitmaster\Repository` osztály a fő kezelőfelület minden git művelethez. Példányt a `Pitmaster::open()`, a `Pitmaster::init()` vagy a `Pitmaster::clone()` segítségével szerezhet.

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

### Elérésiút-lekérdezők

#### `gitDir`

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

Visszaadja a munkafánkénti git könyvtárat. Hagyományos tárolóknál ez a `.git/`. Összekapcsolt munkafáknál ez a `.git/worktrees/<name>/`.

#### `commonGitDir`

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

Visszaadja a megosztott git könyvtárat. Hagyományos tárolóknál megegyezik ezzel: `gitDir()`. Összekapcsolt munkafáknál ez a fő tároló `.git/` könyvtára, ahol az objektumok, a konfiguráció és a packed-refs található.

#### `workDir`

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

Visszaadja a munkafa gyökérkönyvtárának elérési útját.

#### `isLinkedWorktree`

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

`true` értéket ad vissza, ha ez a tárolókezelő egy összekapcsolt munkafához tartozik.

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

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

Jelzi, hogy a tárolónak nincs-e munkafája, és hogy ehhez a kezelőhöz a `hooks` / `processes` beállítások közül melyik van érvényben. A `hooksEnabled()` értéke `false`, ha a folyamatok le vannak tiltva.

---

### Objektumok

#### `readObject`

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

Bármely objektumot beolvashat a teljes hexadecimális hash alapján (40 karakter, SHA-256 tárolóban pedig 64). Rövidített hash nem fogadható el. `Blob`, `Tree`, `Commit` vagy `Tag` példányt ad vissza. Először a laza objektumokban, majd a pack fájlokban keres.

`ObjectNotFoundException` kivételt dob, ha a hash nem található.

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

#### `writeObject`

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

Objektumot ír a laza objektumtárolóba. Visszaadja a kiszámított `ObjectId` értéket.

```php
use Pitmaster\Object\Blob;

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

#### `catFile`

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

Visszaadja egy objektum nyers tartalmát; ez a `git cat-file -p` művelettel egyenértékű.

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

#### `objectExists`

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

Ellenőrzi, hogy létezik-e az objektum a tárolóban (lazán vagy csomagolva).

#### `listObjects`

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

Listázza a tároló összes objektumhash-ét. Hexadecimális karakterláncok tömbjét adja vissza.

---

### Refek

#### `head`

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

Visszaadja az aktuális HEAD commitot. Követi a szimbolikus refeket (HEAD -> refs/heads/main -> commit hash).

`RuntimeException` kivételt dob, ha a HEAD nem érvényes commitra mutat (e.g, üres tároló).

#### `branch`

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

Argumentumok nélkül az aktuális ág nevét (e.g, `'main'`), leválasztott HEAD esetén pedig `null` értéket ad vissza.

Ágnévvel megadva feloldja annak commit hash-ét (hexadecimális karakterlánc), vagy `null` értéket ad vissza, ha az ág nem létezik.

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

#### `branches`

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

Az összes ág nevét tartalmazó, rendezett tömböt ad vissza (a `refs/heads/` előtag nélkül).

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

#### `tags`

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

Az összes címke nevét tartalmazó, rendezett tömböt ad vissza (a `refs/tags/` előtag nélkül).

#### `resolve`

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

Egy revíziós kifejezést `ObjectId` értékké old fel. A következőket támogatja:
- Teljes hexadecimális hash-ek (40 karakter, SHA-256 esetén 64). A rövidített hash-eket, például a `abc1234` értéket, nem oldja fel.
- `HEAD`
- Ágnevek (`main`, `feature/login`)
- Címkenevek (`v1.0.0`)
- Teljes ref-elérési utak (`refs/heads/main`)
- Revíziós kifejezések (`HEAD~3`, `main^2`)

`RuntimeException` kivételt dob, ha a revízió nem oldható fel.

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

#### `allRefs`

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

Az összes refet refnév és hexadecimális hash szerinti asszociatív tömbként adja vissza.

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

#### `updateRef`

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

Frissít egy refet, hogy egy új célra mutasson.

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

#### `createBranch`

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

Új ágat hoz létre. Ha a `$from` értéke null, az aktuális HEAD-ből ágazik le.

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

#### `deleteBranch`

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

Név alapján töröl egy ágat. `RuntimeException` kivételt dob, ha az ág checkoutolva van, vagy nem létezik. A `git branch -d` művelettel ellentétben nem ellenőrzi, hogy az ág egyesült-e.

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

#### `createLightweightTag`

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

Könnyű címkét hoz létre. Ha a `$target` értéke null, közvetlenül az aktuális HEAD-et címkézi meg.

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

Annotált címke létrehozása. Ha `$target` null, az aktuális HEAD-et címkézi meg. Visszaadja a címkeobjektum `ObjectId` értékét.

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

#### `deleteTag`

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

Címke törlése név alapján.

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

#### `packRefs`

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

A megosztott `packed-refs` fájl újraírása az aktuális laza hivatkozáskészletből, és a hozzá tartozó megosztott laza hivatkozások ritkítása. Kapcsolt munkafák esetén ez a közös git könyvtárba ír.

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

#### `defaultBranch`

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

A tároló alapértelmezett ágának feloldása. Először a távoli HEAD szimbolikus hivatkozását ellenőrzi, majd a helyi HEAD-et, végül a `main` vagy `master` értéket használja.

#### `isBranchMerged`

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

Ellenőrzi, hogy egy ág teljesen beolvadt-e egy másik ágba (alapértelmezés szerint az alapértelmezett ágba).

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

#### `checkout`

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

Ágak közötti váltás vagy a HEAD leválasztása. Frissíti a HEAD-et, az indexet és a munkafát. A `$target` lehet ág neve, címke, teljes hash vagy revíziókifejezés; ami nem ág, leválasztja a HEAD-et.

`RuntimeException` hibát dob, ha a jelenlegi és a célfában eltérő útvonalon helyi módosítás (staged vagy nem staged) vagy nem követett fájl található.

A többi követett fájl nem véglegesített módosításai nem maradnak meg: az index és a munkafa a célfából épül újra, ezért elvesznek azoknak a fájloknak a módosításai, amelyek mindkét oldalon azonosak, miközben a git megtartaná őket ([#2](https://github.com/inline0/pitmaster/issues/2)). Előbb véglegesítse vagy tegye félre ezeket. A `merge()`, `cherryPick()`, `revert()`, `rebase()` és a bisect metódusok ugyanígy építik újra a munkafát.

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

---

### Index

#### `index`

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

Az aktuális index (staging terület) beolvasása és visszaadása innen: `.git/index`.

#### `add`

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

Fájlok stage-elése. Minden fájlt beolvas a munkafából, blob objektumot hoz létre, majd frissíti az indexet. Minden argumentumnak a munkafa gyökeréhez viszonyított fájl- (vagy szimbolikus hivatkozás-) útvonalnak kell lennie; a könyvtárak és glob minták nem kerülnek kibontásra, a hiányzó fájl pedig `RuntimeException` hibát okoz.

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

#### `remove`

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

Követett útvonalak eltávolítása az indexből és a munkafából. Az argumentumlistában támogatja a `--cached` és a `-r` / `--recursive` értékeket, a Git-hoz hasonló működéshez.

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

Fájl áthelyezése/átnevezése a munkafában és az indexben.

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

---

### Véglegesítések

#### `commit`

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

Véglegesítés létrehozása az aktuális indexből. Az indexbejegyzésekből fa-hierarchiát épít, létrehozza a véglegesítési objektumot a HEAD-del szülőként (ha van), majd frissíti a HEAD-et. Visszaadja az új véglegesítés `ObjectId` értékét.

A `$message` csak akkor lehet `null`, ha egy merge, cherry-pick, revert vagy rebase konfliktus miatt megállt; ilyenkor az előkészített üzenetet használja. Egyébként az `null` üzenet `RuntimeException('Commit message required')` hibát okoz. A véglegesítés akkor is hibát dob, ha az indexben feloldatlan útvonalak vannak, ha a véglegesítés nélküli tároló indexe üres, vagy ha a fa nem változott a HEAD-hez képest.

A `$author` paraméter teljes git szerzői karakterlánc (`Name <email> timestamp timezone`). Ha null, a környezeti változókból, konstansokból és a `.git/config` értékből oldja fel, a [Kezdő lépések](https://pitmaster.inline0.dev/hu/docs/getting-started) részben ismertetett sorrendben.

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

#### `show`

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

Commit-szerű objektum és annak diffje az első szülőhöz képest. Ha a revízió annotált címkére oldódik fel, a visszatérési érték tartalmazza a `['tag' => Tag]` értéket is, a `commit` pedig a címke feloldott célvéglegesítése.

```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 visszaállítása egy véglegesítésre. Módok:
- `'soft'`: csak a HEAD mozgatása
- `'mixed'`: HEAD mozgatása + index visszaállítása (alapértelmezett)
- `'hard'`: HEAD mozgatása + index visszaállítása + munkafa visszaállítása

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

Útvonal visszaállítása az indexből vagy egy megadott forrásrevízióból. Ha egyik jelző sincs beállítva, a Pitmaster a munkafát az indexből állítja vissza (vagy `$source` értékből, ha meg van adva). A `staged: true` a HEAD-ből (vagy `$source` értékből) állítja vissza az indexet, a munkafát pedig érintetlenül hagyja; a kettő visszaállításához adja meg a `staged: true, worktree: true` értéket.

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

Véglegesítés alkalmazása új véglegesítésként az aktuális ágon, az eredeti szerző megőrzésével. Ha konfliktus miatt megáll a művelet, oldja fel a konfliktusokat, stage-elje az útvonalakat, majd hívja meg a `cherryPickContinue()` vagy `cherryPickAbort()` metódust.

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

Véglegesítés visszavonására szolgáló véglegesítés létrehozása. Ha konfliktus miatt megáll a revert, oldja fel a konfliktusokat, stage-elje az útvonalakat, majd hívja meg a `revertContinue()` vagy `revertAbort()` metódust.

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

Az aktuális ág újraalapozása egy másik revízióra. A Pitmaster jelenleg lineáris újraalapozást támogat a konfliktusok esetén Git-szerű megállási állapottal, valamint a folytatást, megszakítást és kihagyást. A HEAD-nek egy ágra kell mutatnia.

A `rebase()`, `rebaseContinue()` és `rebaseSkip()` a `['success' => bool, 'commits' => int, 'conflicts' => list<string>]` értéket adják vissza: hogy befejeződött-e az újraalapozás, hány véglegesítés került alkalmazásra, és mely útvonalaknál volt konfliktus a megálláskor.

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

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

---

### Állapot

#### `status`

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

A munkafa állapotának kiszámítása. `StatusEntry` objektumok tömbjét adja vissza, amelyek mindegyike tartalmazza:
- `path`: a fájl útvonala
- `index`: `FileStatus` enum a HEAD és az index közötti változásokhoz
- `worktree`: `FileStatus` enum az index és a munkafa közötti változásokhoz
- `origPath`, `renameScore`: átnevezett bejegyzések esetén beállítva, egyébként `null`

A nem követett fájlok mindkét oszlopban `FileStatus::Untracked` értéket kapnak. A figyelmen kívül hagyott fájlok nem jelennek meg.

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

#### `statusPorcelainV2`

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

Géppel feldolgozható állapotkimenet a git porcelain v2 formátumában.

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

---

### Diff

#### `diff`

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

A munkafa összehasonlítása az indexszel (nem stage-elt módosítások). `DiffResult` objektumok tömbjét adja vissza. A `$pathspec` egy pontos fájlútvonalra szűr. A `$algorithm` értéke `'myers'` (alapértelmezett), `'patience'`, `'histogram'` vagy `'minimal'` lehet; minden más érték `InvalidArgumentException` hibát okoz.

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

Az index összehasonlítása a HEAD-del (stage-elt módosítások). `DiffResult[]` értéket ad vissza, a törölt és hozzáadott fájlok közötti átnevezések felismerésével.

A `$pathspec` argumentumot jelenleg figyelmen kívül hagyja, ezért minden stage-elt fájlt visszaad, és az első véglegesítés előtt üres tömböt ad vissza ([#5](https://github.com/inline0/pitmaster/issues/5)).

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

#### `diffTree`

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

Két fát hasonlít össze az `ObjectId` értékük alapján. `DiffResult[]` értéket ad vissza. Faazonosítókat adjon meg, ne véglegesítésazonosítókat: a véglegesítésazonosítót nem faként olvassa be, ezért üres eredményt ad.

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

---

### Napló

#### `log`

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

Véglegesítési előzmények bejárása, a véglegesítő időbélyege szerint a legújabbtól kezdve. `Commit[]` értéket ad vissza. Ha a `$from` null, a HEAD-ről indul. Üres tömböt ad vissza, ha a HEAD-hez még nem tartozik véglegesítés.

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

#### `logAll`

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

Az összes hivatkozásból és a HEAD-ből elérhető véglegesítések bejárása, a legújabbtól kezdve. `Commit[]` értéket ad vissza.

#### `logOneline`

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

Naplósorok visszaadása `git log --oneline` formában (`abc1234 Subject`), a HEAD-ből, az összes hivatkozásból (`$all`), vagy útvonal szerint szűrve.

#### `logPath`

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

Napló szűrése fájlútvonal alapján. Csak azokat a véglegesítéseket adja vissza, amelyek első szülőjükhöz viszonyított diffje hozzáadja, módosítja, törli vagy átnevezi a pontosan megadott fájlt. A könyvtárútvonalak nem egyeznek.

Csak a legújabb `5 * $limit` véglegesítést vizsgálja, így előfordulhat, hogy a fájlt érintő régebbi véglegesítések hiányoznak az eredményből ([#7](https://github.com/inline0/pitmaster/issues/7)).

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

---

### Összefésülés

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

Ág (vagy bármely revízió) beolvasztása a HEAD-be. Automatikusan felismeri a gyors előrecsévéléssel végzett beolvasztást. Ha erre nincs lehetőség, fa szintű konfliktusfelismerést végez, és ütközésmentes esetben merge véglegesítést hoz létre. Konfliktus esetén megáll, és Git alakú merge-állapotot ír az indexbe és a munkafába; oldja fel a konfliktusokat, stage-elje az érintett útvonalakat, majd hívja meg a `mergeContinue()` vagy `mergeAbort()` metódust.

A `$strategy` `'ours'` merge-véglegesítést rögzít, amely megtartja a HEAD fáját; minden más érték az alapértelmezett rekurzív merge-et használja. A `mergeOctopus()` két vagy több ágat olvaszt össze egy véglegesítéssé. Ha bármelyik ágon konfliktus van, tisztátalan eredményt ad vissza merge-állapot írása és véglegesítés létrehozása nélkül.

Ha a HEAD-ben már benne lévő ágat olvaszt be, a művelet újabb merge-véglegesítést hoz létre az „Already up to date” jelzés helyett ([#6](https://github.com/inline0/pitmaster/issues/6)). A követett fájlok nem véglegesített módosításai felülíródnak a `checkout()` részben leírtak szerint.

`MergeResult` értéket ad vissza, amely tartalmazza:
- `clean`: hogy a merge konfliktus nélkül sikerült-e
- `commitId`: a merge-véglegesítés azonosítója (ha ütközésmentes)
- `conflictPaths`: a konfliktusos fájlútvonalak tömbje (ha nem ütközésmentes)
- `mergedContents`: a konfliktusos útvonalak és a konfliktusjelölőket tartalmazó fájltartalom párosításai (ha nem ütközésmentes)

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

Két véglegesítés merge-alapjának (legalacsonyabb közös ősének) megkeresése. Null értéket ad vissza, ha nincs közös ős.

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

### Bisect

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

Bináris keresés annak a véglegesítésnek a megkeresésére, amely bevezette a változást. A `bisectStart()` rögzíti a hibás és a jó revíziókat, majd kiválasztja és visszaadja az első jelöltet. A `bisectGood()` és a `bisectBad()` az aktuális HEAD-et (vagy `$revision` értéket) jelöli meg, majd kiválasztja és visszaadja a következő jelöltet. Ha már csak egy gyanúsított marad, azt a véglegesítést adja vissza, és jelöltként hagyja meg: ez az első hibás véglegesítés. A `bisectReset()` lezárja a munkamenetet, és visszatér ahhoz az ághoz vagy véglegesítéshez, ahonnan indult.

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

---

### Hálózat

#### `fetch`

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

Lekérés távoli tárolóból. Letölti az új objektumokat, és frissíti a távoli követő hivatkozásokat. A sekély előzmények mélyítéséhez vagy korlátozásához adja meg a `$depth` értéket.

A `fetch()` és a `push*()` metódusok `RuntimeException` hibát dobnak olyan kezelőn, amelyet `['processes' => false]` értékkel nyitottak meg.

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

Az aktuális (vagy egy megadott) ág feltöltése távoli tárolóba. Szigorúbb vagy szélesebb körű hivatkozásfrissítéshez force-with-lease, atomic és mirror változatok is rendelkezésre állnak.

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

---

### Munkafák

#### `addWorktree`

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

Kapcsolt munkafa hozzáadása. Létrehozza az ágat, ha még nem létezik, beállítja a munkafa metaadatait, majd létrehozza a munkafa fájljait. Adja meg a `$name` értéket, ha a checkout könyvtárának alapnevétől eltérő, determinisztikus metaadat-slugra van szüksége.

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

Kapcsolt munkafa eltávolítása. A zárolás ellenére történő eltávolításhoz használja a `$force = true` értéket.

#### `worktrees`

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

Az összes munkafa (fő és kapcsolt) listázása. `Worktree[]` értéket ad vissza.

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

---

### Konfiguráció

#### `config`

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

A tároló git konfigurációjának elérése. Konfigurációs értékek olvasása és írása.

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

---

### Belső hozzáférés

Ezek a metódusok belső komponenseket tesznek elérhetővé speciális felhasználási esetekhez.

#### `objectDatabase`

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

A nyers objektum-adatbázis elérése (laza és csomagolt tárolók).

#### `refDatabase`

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

A nyers hivatkozás-adatbázis elérése (laza és csomagolt hivatkozások).

---

## Alacsonyabb szintű osztályok

Ezeket az osztályokat nem csomagolja körül a `Repository`; azok belső komponenseiből készülnek.

### `Pitmaster\Graph\Blame`

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

Soroként egy bejegyzést ad vissza a `$path` fájl `$headId` helyén: `['line' => int, 'hash' => string, 'author' => string, 'content' => string]`. A `author` a teljes azonosító karakterlánc (`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
```

Egy fa blob objektumaiban keres. Találatonként `['path' => string, 'line' => int, 'content' => string]` értéket ad vissza. Beállítások: `regex` (a mintát PCRE-mintaként kezeli) és `ignore_case`. Érvénytelen reguláris kifejezés esetén `InvalidArgumentException` hibát dob.

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

Notes ref alatt tárolt git jegyzetek beolvasása és írása. A `listAll()` véglegesítés-hashek és jegyzettartalom közötti leképezést ad vissza.

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