# Kezdő lépések

## Telepítés

Telepítse az Pitmaster csomagot a(z) Composer használatával:

```bash
composer require pitmaster/pitmaster
```

## Követelmények

- **PHP 8.2+** readonly osztályokkal, enumokkal és konstruktorparaméterek előléptetésével
- **ext-zlib** objektumok tömörítéséhez és kicsomagolásához (a legtöbb telepítésben beépített)
- **ext-json** műveleti állapotfájlokhoz és Git LFS API adatokhoz
- **ext-mbstring**, az `composer.json` csomagban deklarálva, ezért az Composer telepítéskor megköveteli
- **ext-ctype** hash-ellenőrzéshez (a legtöbb PHP buildben engedélyezve, de az `composer.json` csomagban nincs deklarálva)

Az alapvető tárolóműveletekhez nincs szükség a `git` binárisra, FFI-re vagy külső segédprogramokra. Az opcionális funkciók további futásidejű követelményekkel járnak: a hookok végrehajtása a `proc_open()` használatával történik, a SSH átvitel pedig a `ext-ssh2`-t használja, ha az be van töltve; egyébként a rendszer `ssh` binárisát indítja el a `proc_open()` segítségével.

## Meglévő tároló megnyitása

```php
use Pitmaster\Pitmaster;

$repo = Pitmaster::open('/path/to/project');
```

Ez megnyitja a megadott útvonalon található tárolót. Az Pitmaster megkeresi az `.git` könyvtárat (vagy összekapcsolt munkafák esetén felold egy `.git` fájlt), majd inicializálja az objektum-adatbázist, a hivatkozás-adatbázist és a konfigurációt.

Az `open()`, az `init()` és az `clone()` utolsó argumentumként beállításokat tartalmazó tömböt fogad el:

```php
// Do not run .git/hooks scripts for this handle
$repo = Pitmaster::open('/path/to/project', ['hooks' => false]);

// Do not start any process: no hooks, no fsmonitor hook, no clone/fetch/push, no SSH
$repo = Pitmaster::open('/path/to/project', Pitmaster::processFreeOptions());
```

A hookok alapértelmezés szerint lefutnak. Az `Pitmaster::processFreeOptions()` `['processes' => false, 'hooks' => false]` értéket ad vissza; az ilyen kezelővel a helyi olvasások és írások továbbra is működnek.

## Útvonalról eldönteni, hogy tároló-e

```php
if (Pitmaster::isRepository('/path/to/project')) {
    $repo = Pitmaster::open('/path/to/project');
}
```

## Új tároló inicializálása

```php
$repo = Pitmaster::init('/path/to/new-project');
```

Ez létrehozza az `.git` könyvtárszerkezetét az objektumokkal, hivatkozásokkal, HEAD-del (amely az `refs/heads/main` értékre mutat) és az alapértelmezett konfigurációval.

SHA-256 tároló létrehozásához második argumentumként adja meg az objektumformátumot:

```php
$repo = Pitmaster::init('/path/to/new-project', 'sha256');
```

Az ilyen tárolóban az objektumazonosítók 64 hexadecimális karakterből állnak, a konfiguráció pedig rögzíti az `extensions.objectformat = sha256` értéket. A később megnyitott tárolók a konfigurációs bejegyzésből veszik át a formátumot.

## A HEAD commit beolvasása

```php
$head = $repo->head();

echo "Commit: {$head->id->hex}\n";
echo "Author: {$head->author}\n";
echo "Message: {$head->message}\n";
```

Az `head()` metódus feloldja a HEAD-et (követve a szimbolikus hivatkozásokat), és egy `Commit` objektumot ad vissza.

## Ágak és címkék listázása

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

// Current branch name (null if detached)
$current = $repo->branch();
// 'main'

// All tag names
$tags = $repo->tags();
// ['v1.0.0', 'v1.1.0']
```

## Commitelőzmények bejárása

```php
// Last 20 commits from HEAD
$commits = $repo->log(20);

foreach ($commits as $commit) {
    echo substr($commit->id->hex, 0, 7) . " {$commit->message}\n";
}
```

Kiindulhat egy adott commitból is:

```php
$from = $repo->resolve('feature/login');
$commits = $repo->log(10, $from);
```

## Munkafa állapotának ellenőrzése

```php
use Pitmaster\Status\FileStatus;

$entries = $repo->status();

foreach ($entries as $entry) {
    if ($entry->index === FileStatus::Untracked) {
        echo "?? {$entry->path}\n";
    } elseif ($entry->index === FileStatus::Modified) {
        echo "M  {$entry->path}\n";
    } elseif ($entry->worktree === FileStatus::Modified) {
        echo " M {$entry->path}\n";
    }
}
```

## Fájlok előkészítése és commit létrehozása

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

// Create a commit
$commitId = $repo->commit('Add new feature with tests');

echo "Created commit: {$commitId->hex}\n";
```

A szerző nevét és e-mail-címét a rendszer a következő sorrendben oldja fel: az `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL` környezeti változók, a `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL` környezeti változók, az `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL` konstansok, a tároló saját `.git/config` beállításai (`user.name` és `user.email`), végül pedig az `Pitmaster <pitmaster@localhost>`. A rendszer csak a tároló konfigurációs fájlját (és az általa bevont fájlokat) olvassa be, az `~/.gitconfig` fájlt nem. A beküldő feloldása ugyanígy történik a `*_COMMITTER_*` nevek alapján, és hiányukban a szerzői konstansokra esik vissza.

## Különbségek kiszámítása

```php
// Unstaged changes (worktree vs index)
$diffs = $repo->diff();

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

// Staged changes (index vs HEAD)
$staged = $repo->diffStaged();
```

## Távoli tároló klónozása

```php
$repo = Pitmaster::clone('https://github.com/user/repo.git', '/path/to/destination');
```

Ez felderíti a hivatkozásokat, letölti a pack fájlt, beállítja a távoli követő ágakat, és kijelenti az alapértelmezett ágat. A HTTP(S) URL-ek intelligens HTTP protokollt használnak, és visszaváltanak a buta HTTP protokollra; a SSH URL-ek a SSH átvitelt használják. Sekély klónozáshoz harmadik argumentumként adja meg a mélységet: `Pitmaster::clone($url, $path, 1)`.

## Tetszőleges objektum beolvasása hash alapján

```php
$object = $repo->readObject($fullHash); // full 40-character (or 64 for SHA-256) hex hash

if ($object instanceof \Pitmaster\Object\Blob) {
    echo $object->content;
} elseif ($object instanceof \Pitmaster\Object\Commit) {
    echo $object->message;
}
```

## Konfiguráció

Az Pitmaster figyelembe veszi a tároló `.git/config` beállításait a szerzői adatokhoz és a távoli URL-ekhez. Globális alapértékeket is megadhat az PHP konstansokkal, az Pitmaster futása előtt:

```php
define('PITMASTER_AUTHOR_NAME', 'Your Name');
define('PITMASTER_AUTHOR_EMAIL', 'you@example.com');
define('PITMASTER_HTTP_TIMEOUT', 60);        // Seconds
define('PITMASTER_MAX_DELTA_CHAIN', 50);     // Max delta chain depth
define('PITMASTER_OBJECT_CACHE_BYTES', '64M');
```

| Konstans | Alapérték | Hatás |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | none | Szerzői identitás (lásd a fenti sorrendet) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | szerzői értékek | Beküldői identitás |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Intelligens HTTP időkorlát másodpercben (egész szám) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | A packek olvasásakor megengedett maximális delta-láncmélység (egész szám) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | A memóriabeli objektum-gyorsítótárban megtartott objektumok |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Az objektum-gyorsítótár bájtkerete |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Gyorsítótárban tárolt feloldott deltaobjektumok packenként |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | Az adott pack-gyorsítótár bájtkerete |
| `PITMASTER_MAX_PACK_MEMORY` | none | A pack-gyorsítótár bájtkeretének korábbi neve; csak akkor használatos, ha az `PITMASTER_PACK_RESOLVED_CACHE_BYTES` nincs megadva |

A bájtérték megadható egész számként, vagy `k`, `m`, illetve `g` utótagot tartalmazó karakterláncként (`'256M'`). Érvénytelen érték esetén az alapérték lép életbe.

A környezeti változók felülírják az identitáskonstansokat: `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`, `PITMASTER_AUTHOR_DATE`, a `PITMASTER_COMMITTER_*` megfelelői, valamint a git saját `GIT_AUTHOR_*` és `GIT_COMMITTER_*` változói. A SSH átvitel az `PITMASTER_SSH_*` változókat olvassa be, amelyeket a [Protokollok](https://pitmaster.inline0.dev/hu/docs/network/protocols) ismertet.

A hashalgoritmushoz nincs konstans. Az objektumformátumot a tároló létrehozásakor választja ki (`Pitmaster::init($path, 'sha256')` vagy `init --object-format=sha256` az CLI esetében), majd később a tároló konfigurációjából olvassa be.