# Začíname

## Inštalácia

Nainštalujte Pitmaster pomocou Composer:

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

## Požiadavky

- **PHP 8.2+** s nemennými triedami, enumami a propagáciou argumentov konštruktora
- **ext-zlib** na kompresiu a dekompresiu objektov (súčasťou väčšiny inštalácií)
- **ext-json** pre súbory stavu operácií a payloady Git LFS API
- **ext-mbstring**, deklarované v `composer.json`, takže Composer ho vyžaduje pri inštalácii
- **ext-ctype** na overovanie hashov (povolené vo väčšine zostáv PHP, ale nie je deklarované v `composer.json`)

Základné operácie s repozitárom nevyžadujú binárny súbor `git`, FFI ani externé pomocné nástroje. Voliteľné funkcie majú ďalšie požiadavky na beh: spúšťanie hookov používa `proc_open()` a prenos SSH používa `ext-ssh2`, keď je načítané, inak spustí systémový binárny súbor `ssh` prostredníctvom `proc_open()`.

## Otvorenie existujúceho repozitára

```php
use Pitmaster\Pitmaster;

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

Týmto sa otvorí repozitár na zadanej ceste. Pitmaster nájde adresár `.git` (alebo pri prepojených pracovných stromoch vyrieši súbor `.git`) a inicializuje databázu objektov, databázu odkazov a konfiguráciu.

`open()`, `init()` a `clone()` prijímajú ako posledný argument pole možností:

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

Hooky sa predvolene spúšťajú. `Pitmaster::processFreeOptions()` vracia `['processes' => false, 'hooks' => false]`; lokálne čítanie a zápis s takýmto objektom naďalej fungujú.

## Kontrola, či je cesta repozitárom

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

## Inicializácia nového repozitára

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

Týmto sa vytvorí štruktúra adresárov `.git` s objektmi, odkazmi, HEAD (smerujúcim na `refs/heads/main`) a predvolenou konfiguráciou.

Ak chcete vytvoriť repozitár SHA-256, odovzdajte formát objektov ako druhý argument:

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

ID objektov v tomto repozitári majú 64 hexadecimálnych znakov a konfigurácia zaznamenáva `extensions.objectformat = sha256`. Neskôr otvorené repozitáre prevezmú formát z tejto konfiguračnej položky.

## Čítanie odovzdania HEAD

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

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

Metóda `head()` vyrieši HEAD (nasleduje symbolické odkazy) a vráti objekt `Commit`.

## Zobrazenie vetiev a značiek

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

## Prechádzanie histórie odovzdaní

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

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

Môžete začať aj od konkrétneho odovzdania:

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

## Kontrola stavu pracovného stromu

```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";
    }
}
```

## Pridanie súborov do indexu a odovzdanie zmien

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

Meno a e-mail autora sa určujú v tomto poradí: premenné prostredia `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, premenné prostredia `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL`, konštanty `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, vlastná konfigurácia repozitára `.git/config` (`user.name` a `user.email`) a napokon `Pitmaster <pitmaster@localhost>`. Číta sa iba konfiguračný súbor repozitára (a súbory, ktoré zahŕňa), nie `~/.gitconfig`. Meno odovzdávajúceho sa určuje rovnako z názvov `*_COMMITTER_*` a ako záloha sa použijú konštanty autora.

## Výpočet rozdielov

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

## Klonovanie vzdialeného repozitára

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

Týmto sa zistia odkazy, stiahne súbor balíka, nastavia vetvy sledujúce vzdialený repozitár a skontroluje predvolená vetva. Adresy URL HTTP(S) používajú inteligentný HTTP a pri zlyhaní prejdú na jednoduchý HTTP; adresy URL SSH používajú prenos SSH. Ak chcete vytvoriť plytký klon, zadajte hĺbku ako tretí argument: `Pitmaster::clone($url, $path, 1)`.

## Čítanie ľubovoľného objektu podľa hash kódu

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

Pitmaster rešpektuje nastavenie `.git/config` v repozitári pre informácie o autorovi a vzdialené adresy URL. Globálne predvolené hodnoty môžete nastaviť aj pomocou konštánt PHP definovaných pred spustením Pitmaster:

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

| Konštanta | Predvolená hodnota | Účinok |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | žiadna | Identita autora (pozrite si vyššie uvedené poradie) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | hodnoty autora | Identita odovzdávajúceho |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Časový limit inteligentného HTTP v sekundách (celé číslo) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | Maximálna hĺbka reťazca delta pri čítaní balíkov (celé číslo) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | Počet objektov uchovávaných vo vyrovnávacej pamäti objektov v pamäti |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Limit veľkosti vyrovnávacej pamäte objektov v bajtoch |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Vyriešené objekty delta uložené vo vyrovnávacej pamäti pre každý balík |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | Limit veľkosti vyrovnávacej pamäte balíka v bajtoch |
| `PITMASTER_MAX_PACK_MEMORY` | žiadna | Starší názov pre limit veľkosti vyrovnávacej pamäte balíka, ktorý sa používa iba vtedy, keď nie je definované `PITMASTER_PACK_RESOLVED_CACHE_BYTES` |

Hodnoty v bajtoch môžu byť celé číslo alebo reťazec s príponou `k`, `m` alebo `g` (`'256M'`). Neplatné hodnoty sa nahradia predvolenou hodnotou.

Premenné prostredia majú prednosť pred konštantami identity: `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`, `PITMASTER_AUTHOR_DATE`, ich ekvivalenty `PITMASTER_COMMITTER_*` a vlastné premenné `GIT_AUTHOR_*` a `GIT_COMMITTER_*` pre git. Prenos SSH číta premenné `PITMASTER_SSH_*` opísané v [Protokoly](https://pitmaster.inline0.dev/sk/docs/network/protocols).

Pre hashovací algoritmus neexistuje konštanta. Formát objektov sa vyberá pri vytváraní repozitára (`Pitmaster::init($path, 'sha256')` alebo `init --object-format=sha256` v CLI) a neskôr sa načíta z konfigurácie repozitára.