# Въведение
Pitmaster е библиотека на PHP без външни зависимости, която чете и записва хранилища Git директно. Основните операции с хранилището не стартират двоичния файл `git` и не използват FFI. Моделът на обектите Git, форматът на pack файловете, форматът на индекса и smart транспортът HTTP са реализирани на PHP.

## Защо съществува Pitmaster

PHP приложенията, които работят с хранилища Git, обикновено стартират двоичния файл `git` от командния ред. Това работи, но създава твърда зависимост от инсталирането на `git`, поражда опасения за сигурността във връзка с `exec()` и `proc_open()` и затруднява разгръщането на приложението в ограничени среди (контейнери без git, споделен хостинг, безсървърни функции).

Pitmaster премахва зависимостта от `git` за основната работа с хранилища. Вашето приложение PHP може да чете историята на комитите, да създава комити, да изчислява разлики, да проверява състоянието и да изпраща към отдалечени хранилища чрез smart HTTP, използвайки само вградените функции на PHP. Изключенията са hook-овете и транспортът SSH: и двете стартират процеси и могат да бъдат изключени за всеки обект на хранилище (вижте [Hooks](https://pitmaster.inline0.dev/bg/docs/advanced/hooks)).

## Какво прави

- Чете и записва свободни обекти (blob, tree, commit, tag)
- Чете pack файлове и разрешава вериги delta (OFS_DELTA и REF_DELTA)
- Записва pack файлове за мрежови операции
- Чете и записва индекса/областта за подготовка (формати v2, v3, v4)
- Чете и записва препратки (клонове, етикети, HEAD, packed-refs, reftable)
- Изчислява разлики във формата unified на git (алгоритми Myers, Patience, Histogram и Minimal)
- Извършва тристранни сливания с откриване на конфликти
- Обхожда графи на комитите (log, ancestry, merge base)
- Използва протокола Git smart HTTP (clone, fetch, push)
- Поддържа работни дървета, подмодули, stash, hook-ове и Git LFS

## Какви са изискванията

- PHP 8.2 или по-нова версия
- Разширението `zlib` (вградено в почти всички инсталации на PHP)
- Разширението `json`
- Разширението `mbstring` (декларирано в `composer.json`, затова Composer го изисква при инсталиране)
- Разширението `ctype` (използва се за проверка на хешовете на обектите; активно в повечето компилации на PHP, но не е декларирано в `composer.json`)

Основните операции с хранилището не изискват двоичния файл `git`. Незадължителните функции може да изискват допълнителни възможности по време на изпълнение: изпълнението на hook използва `proc_open()`, а транспортът SSH използва `ext-ssh2`, когато е зареден, и в противен случай стартира системния двоичен файл `ssh` чрез `proc_open()`.

## Кратък пример

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

Започнете с [Първи стъпки](https://pitmaster.inline0.dev/bg/docs/getting-started), след което разгледайте [API](https://pitmaster.inline0.dev/bg/docs/api), [CLI](https://pitmaster.inline0.dev/bg/docs/cli) и [Операции](https://pitmaster.inline0.dev/bg/docs/operations/read) за останалите възможности. В [Тестване](https://pitmaster.inline0.dev/bg/docs/testing) е обяснено как Pitmaster се проверява спрямо `git`.