# Darba sākšana

## Instalēšana

Instalējiet Pitmaster, izmantojot Composer:

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

## Prasības

- **PHP 8.2+** ar tikai lasāmām klasēm, uzskaitījumiem un konstruktora parametru veicināšanu
- **ext-zlib** objektu saspiešanai/atspiešanai (iebūvēts lielākajā daļā instalāciju)
- **ext-json** darbību stāvokļa failiem un Git LFS API datu kopām
- **ext-mbstring**, deklarēts `composer.json`, tāpēc Composer tas ir nepieciešams instalēšanas laikā
- **ext-ctype** jaucējvērtību validēšanai (iespējots lielākajā daļā PHP būvējumu, bet nav deklarēts `composer.json`)

Repozitorija pamatdarbībām nav nepieciešams `git` binārais fails, FFI vai ārējie palīgrīki. Izvēles funkcijām ir papildu izpildlaika prasības: āķu izpilde izmanto `proc_open()`, un SSH transports izmanto `ext-ssh2`, ja tas ir ielādēts, bet citādi palaiž sistēmas `ssh` bināro failu ar `proc_open()` palīdzību.

## Atvērt esošu repozitoriju

```php
use Pitmaster\Pitmaster;

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

Tas atver repozitoriju norādītajā ceļā. Pitmaster atrod direktoriju `.git` (vai atrisina failu `.git` saistītām darba kokām) un inicializē objektu datubāzi, atsauču datubāzi un konfigurāciju.

`open()`, `init()` un `clone()` kā pēdējo argumentu pieņem opciju masīvu:

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

Āķi tiek palaisti pēc noklusējuma. `Pitmaster::processFreeOptions()` atgriež `['processes' => false, 'hooks' => false]`; lokālā lasīšana un rakstīšana ar šādu objektu turpina darboties.

## Pārbaudīt, vai ceļš ir repozitorijs

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

## Inicializēt jaunu repozitoriju

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

Tiek izveidota `.git` direktoriju struktūra ar objektiem, atsaucēm, HEAD (kas norāda uz `refs/heads/main`) un noklusējuma konfigurāciju.

Lai izveidotu SHA-256 repozitoriju, kā otro argumentu norādiet objektu formātu:

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

Objektu ID šajā repozitorijā ir 64 heksadecimālās rakstzīmes, un konfigurācijā ir norādīts `extensions.objectformat = sha256`. Vēlāk atvērtie repozitoriji formātu nolasa no šī konfigurācijas ieraksta.

## Nolasīt HEAD commit

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

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

Metode `head()` atrisina HEAD (sekojot simboliskajām atsaucēm) un atgriež objektu `Commit`.

## Uzskaitīt atzarus un tagus

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

## Pārlūkot commit vēsturi

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

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

Varat arī sākt no konkrēta commit:

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

## Pārbaudīt darba koka statusu

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

## Pievienot failus indeksēšanai un izveidot commit

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

Autora vārds un e-pasts tiek noteikts šādā secībā: vides mainīgie `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, vides mainīgie `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL`, konstantes `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, paša repozitorija `.git/config` (`user.name` un `user.email`) un visbeidzot `Pitmaster <pitmaster@localhost>`. Tiek lasīts tikai repozitorija konfigurācijas fails (un tajā iekļautie faili), nevis `~/.gitconfig`. Commit veicējs tiek noteikts tādā pašā veidā, izmantojot `*_COMMITTER_*` nosaukumus, un, ja tie nav norādīti, tiek izmantotas autora konstantes.

## Aprēķināt atšķirības

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

## Klonēt attālinātu repozitoriju

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

Tiek atklātas atsauces, izgūts pakotnes fails, iestatīti attālināto atzaru izsekošanas atzari un pārbaudīts noklusējuma atzars. HTTP(S) URL izmanto viedo HTTP un, ja tas neizdodas, pārslēdzas uz vienkāršo HTTP; SSH URL izmanto SSH transportu. Seklai klonēšanai kā trešo argumentu norādiet dziļumu: `Pitmaster::clone($url, $path, 1)`.

## Nolasīt jebkuru objektu pēc jaucējvērtības

```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ācija

Pitmaster ievēro repozitorija `.git/config` autora informācijai un attālināto repozitoriju URL. Varat arī iestatīt globālās noklusējuma vērtības ar konstantēm PHP, kas definētas pirms Pitmaster izpildes:

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

| Konstante | Noklusējuma vērtība | Ietekme |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | none | Autora identitāte (skatiet secību iepriekš) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | autora vērtības | Commit veicēja identitāte |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Viedā HTTP taimauts sekundēs (vesels skaitlis) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | Maksimālais delta ķēdes dziļums, nolasot pakotnes (vesels skaitlis) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | Objektu skaits atmiņā esošajā objektu kešatmiņā |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Objektu kešatmiņas baitu ierobežojums |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Katrā pakotnē kešoto atrisināto delta objektu skaits |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | Šīs pakotnes kešatmiņas baitu ierobežojums |
| `PITMASTER_MAX_PACK_MEMORY` | none | Vecāks nosaukums pakotnes kešatmiņas baitu ierobežojumam; izmantots tikai tad, ja `PITMASTER_PACK_RESOLVED_CACHE_BYTES` nav definēts |

Baitu vērtībām pieņem veselu skaitli vai virkni ar sufiksu `k`, `m` vai `g` (`'256M'`). Nederīgas vērtības aizstāj noklusējuma vērtība.

Vides mainīgie aizstāj identitātes konstantes: `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`, `PITMASTER_AUTHOR_DATE`, to `PITMASTER_COMMITTER_*` ekvivalenti un paša git mainīgie `GIT_AUTHOR_*` un `GIT_COMMITTER_*`. SSH transports nolasa `PITMASTER_SSH_*` mainīgos, kas aprakstīti sadaļā [Protokoli](https://pitmaster.inline0.dev/lv/docs/network/protocols).

Jaucējalgoritmam nav konstantes. Objektu formātu izvēlas, izveidojot repozitoriju (`Pitmaster::init($path, 'sha256')` vai `init --object-format=sha256` sistēmā CLI), un pēc tam nolasa no repozitorija konfigurācijas.