# Začínáme

## Instalace

Nainstalujte Pitmaster pomocí Composer:

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

## Požadavky

- **PHP 8.2+** s třídami readonly, výčtovými typy a propagací konstruktoru
- **ext-zlib** pro kompresi a dekompresi objektů (součástí většiny instalací)
- **ext-json** pro soubory stavu operací a datové části Git LFS API
- **ext-mbstring**, deklarované v `composer.json`, takže Composer je při instalaci vyžaduje
- **ext-ctype** pro ověření hashů (povoleno ve většině sestavení PHP, ale není deklarováno v `composer.json`)

Základní operace s úložištěm nevyžadují binární soubor `git`, FFI ani externí pomocné nástroje. Volitelné funkce mají další požadavky na běhové prostředí: spouštění hooků používá `proc_open()` a přenos SSH používá `ext-ssh2`, pokud je načteno, jinak spouští systémový binární soubor `ssh` přes `proc_open()`.

## Otevření existujícího úložiště

```php
use Pitmaster\Pitmaster;

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

Tím se otevře úložiště v zadané cestě. Pitmaster vyhledá adresář `.git` (nebo vyřeší soubor `.git` u propojených pracovních stromů) a inicializuje databázi objektů, databázi odkazů a konfiguraci.

`open()`, `init()` a `clone()` přijímají jako poslední argument pole voleb:

```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 se spouštějí ve výchozím nastavení. `Pitmaster::processFreeOptions()` vrací `['processes' => false, 'hooks' => false]`; místní čtení a zápisy s takovým objektem nadále fungují.

## Ověření, zda je cesta úložištěm

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

## Inicializace nového úložiště

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

Tím se vytvoří struktura adresářů `.git` s objekty, odkazy, HEAD (ukazující na `refs/heads/main`) a výchozí konfigurací.

Chcete-li vytvořit úložiště SHA-256, předejte jako druhý argument formát objektů:

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

ID objektů v tomto úložišti mají 64 hexadecimálních znaků a konfigurace zaznamenává `extensions.objectformat = sha256`. Později otevřená úložiště načtou formát z této položky konfigurace.

## Načtení commitu HEAD

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

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

Metoda `head()` vyhodnotí HEAD (následuje symbolické odkazy) a vrátí objekt `Commit`.

## Výpis větví a štítků

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

## Procházení historie commitů

```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 také začít od konkrétního commitu:

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

## Přidání souborů do indexu a vytvoření commitu

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

Jméno a e-mail autora se určují v tomto pořadí: proměnné prostředí `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, proměnné prostředí `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL`, konstanty `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, vlastní `.git/config` úložiště (`user.name` a `user.email`) a nakonec `Pitmaster <pitmaster@localhost>`. Čte se pouze konfigurační soubor úložiště (a soubory, které zahrnuje), nikoli `~/.gitconfig`. Autor commitu se určuje stejně z názvů `*_COMMITTER_*` a jako záložní možnost se použijí konstanty autora.

## Výpočet rozdílů

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

## Klonování vzdáleného úložiště

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

Tím se vyhledají odkazy, stáhne soubor pack, nastaví vzdálené sledovací větve a provede checkout výchozí větve. Adresy URL HTTP(S) používají chytrý přenos HTTP a při jeho selhání přecházejí na jednoduchý přenos HTTP; adresy URL SSH používají přenos SSH. Při mělkém klonování zadejte hloubku jako třetí argument: `Pitmaster::clone($url, $path, 1)`.

## Načtení libovolného objektu podle hashe

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

## Konfigurace

Pitmaster respektuje nastavení `.git/config` úložiště pro informace o autorovi a vzdálené adresy URL. Výchozí globální hodnoty můžete nastavit také pomocí konstant PHP definovaných před spuštění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');
```

| Konstanta | Výchozí hodnota | Účinek |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | žádná | Identita autora (viz výše uvedené pořadí) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | hodnoty autora | Identita autora commitu |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Časový limit chytrého přenosu HTTP v sekundách (celé číslo) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | Maximální hloubka řetězce rozdílů při čtení packů (celé číslo) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | Objekty uchovávané v mezipaměti objektů v paměti |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Limit velikosti mezipaměti objektů v bajtech |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Vyřešené objekty rozdílů ukládané do mezipaměti pro každý pack |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | Limit velikosti této mezipaměti packů v bajtech |
| `PITMASTER_MAX_PACK_MEMORY` | žádná | Starší název limitu velikosti mezipaměti packů, používaný pouze tehdy, když není definováno `PITMASTER_PACK_RESOLVED_CACHE_BYTES` |

Hodnoty v bajtech přijímají celé číslo nebo řetězec s příponou `k`, `m` nebo `g` (`'256M'`). Neplatné hodnoty se nahradí výchozí hodnotou.

Proměnné prostředí mají přednost před konstantami identity: `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`, `PITMASTER_AUTHOR_DATE`, odpovídajícími proměnnými `PITMASTER_COMMITTER_*` a také vlastními proměnnými gitu `GIT_AUTHOR_*` a `GIT_COMMITTER_*`. Přenos SSH čte proměnné `PITMASTER_SSH_*`, popsané v [Protokolech](https://pitmaster.inline0.dev/cs/docs/network/protocols).

Pro hashovací algoritmus neexistuje žádná konstanta. Formát objektů se zvolí při vytvoření úložiště (`Pitmaster::init($path, 'sha256')` nebo `init --object-format=sha256` na CLI) a poté se načítá z konfigurace úložiště.