# Wprowadzenie
Pitmaster to czysta biblioteka PHP, która natywnie odczytuje i zapisuje repozytoria Git. Podstawowe operacje na repozytorium nie uruchamiają zewnętrznego pliku binarnego `git` ani nie korzystają z FFI. Model obiektów Git, format pliku pakietu, format indeksu oraz inteligentny transport HTTP są zaimplementowane w PHP.

## Dlaczego istnieje Pitmaster

Aplikacje PHP współpracujące z repozytoriami Git zazwyczaj uruchamiają zewnętrzny plik binarny `git`. To działa, ale tworzy twardą zależność od zainstalowanego `git`, budzi obawy o bezpieczeństwo związane z `exec()` i `proc_open()` oraz utrudnia wdrażanie aplikacji w środowiskach o ograniczeniach (kontenery bez gita, hosting współdzielony, funkcje bezserwerowe).

Pitmaster eliminuje zależność od `git` przy podstawowych operacjach na repozytorium. Aplikacja PHP może odczytywać historię zatwierdzeń, tworzyć zatwierdzenia, obliczać różnice, sprawdzać stan i wysyłać zmiany do zdalnych repozytoriów przez inteligentny HTTP, korzystając wyłącznie z wbudowanych funkcji PHP. Wyjątki stanowią hooki i transport SSH: oba uruchamiają procesy i oba można wyłączyć dla danego uchwytu repozytorium (zob. [Hooki](https://pitmaster.inline0.dev/pl/docs/advanced/hooks)).

## Funkcje

- Odczytuje i zapisuje luźne obiekty (blob, tree, commit, tag)
- Odczytuje pliki pakietów i rozwiązuje łańcuchy delt (OFS_DELTA i REF_DELTA)
- Zapisuje pliki pakietów na potrzeby operacji sieciowych
- Odczytuje i zapisuje indeks/obszar przejściowy (formaty v2, v3, v4)
- Odczytuje i zapisuje referencje (gałęzie, tagi, HEAD, packed-refs, reftable)
- Oblicza różnice (algorytmy Myers, Patience, Histogram i Minimal) w ujednoliconym formacie gita
- Wykonuje scalanie trójstronne z wykrywaniem konfliktów
- Przechodzi przez grafy zatwierdzeń (log, pochodzenie, wspólna baza scalania)
- Obsługuje inteligentny protokół Git HTTP (clone, fetch, push)
- Obsługuje worktree, submoduły, stash, hooki i Git LFS

## Wymagania

- PHP 8.2 lub nowszy
- Rozszerzenie `zlib` (wbudowane w niemal wszystkie instalacje PHP)
- Rozszerzenie `json`
- Rozszerzenie `mbstring` (zadeklarowane w `composer.json`, więc Composer wymaga go podczas instalacji)
- Rozszerzenie `ctype` (używane do weryfikacji skrótów obiektów; włączone w większości kompilacji PHP, ale niezadeklarowane w `composer.json`)

Podstawowe operacje na repozytorium nie wymagają pliku binarnego `git`. Funkcje opcjonalne mogą wymagać dodatkowych możliwości środowiska uruchomieniowego: wykonywanie hooków korzysta z `proc_open()`, a transport SSH używa `ext-ssh2`, jeśli jest załadowane; w przeciwnym razie uruchamia systemowy plik binarny `ssh` za pośrednictwem `proc_open()`.

## Szybki przykład

```php
use Pitmaster\Pitmaster;

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

// Read the current HEAD commit
$head = $repo->head();
echo $head->message;

// List branches
foreach ($repo->branches() as $branch) {
    echo $branch . "\n";
}

// Check status
foreach ($repo->status() as $entry) {
    echo "{$entry->path}: {$entry->index->value}{$entry->worktree->value}\n";
}

// Create a commit
$repo->add('src/Feature.php');
$commitId = $repo->commit('Add new feature');
```

Zacznij od sekcji [Pierwsze kroki](https://pitmaster.inline0.dev/pl/docs/getting-started), a następnie zapoznaj się z sekcjami [API](https://pitmaster.inline0.dev/pl/docs/api), [CLI](https://pitmaster.inline0.dev/pl/docs/cli) i [Operacje](https://pitmaster.inline0.dev/pl/docs/operations/read), aby poznać pozostałe funkcje. Sekcja [Testowanie](https://pitmaster.inline0.dev/pl/docs/testing) wyjaśnia, jak Pitmaster jest sprawdzane względem `git`.