# Začetek

## Namestitev

Namestite Pitmaster prek Composer:

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

## Zahteve

- **PHP 8.2+** z nespremenljivimi razredi, enumi in promocijo konstruktorja
- **ext-zlib** za stiskanje in razširjanje objektov (vgrajen v večino namestitev)
- **ext-json** za datoteke stanja operacij in vsebine Git LFS API
- **ext-mbstring**, naveden v `composer.json`, zato ga Composer zahteva med namestitvijo
- **ext-ctype** za preverjanje zgoščenih vrednosti (omogočen v večini graditev PHP, vendar ni naveden v `composer.json`)

Osnovne operacije repozitorija ne zahtevajo binarne datoteke `git`, FFI ali zunanjih pripomočkov. Izbirne funkcije imajo dodatne zahteve med izvajanjem: izvajanje hookov uporablja `proc_open()`, transport SSH pa uporablja `ext-ssh2`, če je ta naložen, sicer sistemsko binarno datoteko `ssh` zažene prek `proc_open()`.

## Odprite obstoječi repozitorij

```php
use Pitmaster\Pitmaster;

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

To odpre repozitorij na podani poti. Pitmaster poišče imenik `.git` (ali razreši datoteko `.git` za povezana delovna drevesa) in inicializira zbirko objektov, zbirko referenc ter konfiguracijo.

`open()`, `init()` in `clone()` kot zadnji argument sprejmejo polje možnosti:

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

Hooki se privzeto izvajajo. `Pitmaster::processFreeOptions()` vrne `['processes' => false, 'hooks' => false]`; lokalno branje in zapisovanje s takšnim ročajem še naprej delujeta.

## Preverite, ali je pot repozitorij

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

## Inicializirajte nov repozitorij

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

S tem ustvarite strukturo imenika `.git` z objekti, referencami, HEAD (ki kaže na `refs/heads/main`) in privzeto konfiguracijo.

Za ustvarjanje repozitorija SHA-256 podajte obliko objekta kot drugi argument:

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

ID-ji objektov v tem repozitoriju so dolgi 64 šestnajstiških znakov, konfiguracija pa beleži `extensions.objectformat = sha256`. Pozneje odprti repozitoriji prevzamejo obliko iz tega konfiguracijskega vnosa.

## Preberite commit HEAD

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

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

Metoda `head()` razreši HEAD (s sledenjem simbolnim referencam) in vrne objekt `Commit`.

## Izpišite veje in oznake

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

## Sprehodite se po zgodovini commitov

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

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

Začnete lahko tudi z določenim commitom:

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

## Preverite stanje delovnega drevesa

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

## Dodajte datoteke v pripravo in ustvarite 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";
```

Ime in e-poštni naslov avtorja se določita v tem vrstnem redu: spremenljivki okolja `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, spremenljivki okolja `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL`, konstanti `PITMASTER_AUTHOR_NAME` / `PITMASTER_AUTHOR_EMAIL`, lastni `.git/config` repozitorija (`user.name` in `user.email`) ter nazadnje `Pitmaster <pitmaster@localhost>`. Prebere se samo konfiguracijska datoteka repozitorija (in datoteke, ki jih vključuje), ne pa `~/.gitconfig`. Podatki o avtorju commita se razrešijo enako iz imen `*_COMMITTER_*` in se ob neuspehu vrnejo na konstanti avtorja.

## Izračunajte razlike

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

## Klonirajte oddaljeni repozitorij

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

To odkrije reference, prenese datoteko paketa, nastavi oddaljene sledilne veje in prevzame privzeto vejo. HTTP(S) URL-ji uporabljajo pametni HTTP in se ob neuspehu vrnejo na preprosti HTTP; URL-ji SSH uporabljajo prenos SSH. Za plitvo kloniranje kot tretji argument podajte globino: `Pitmaster::clone($url, $path, 1)`.

## Branje poljubnega objekta zgoščene vrednosti

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

## Konfiguracija

Pitmaster upošteva `.git/config` repozitorija za podatke o avtorju in oddaljene URL-je. Globalne privzete vrednosti lahko nastavite tudi s konstantami PHP, definiranimi pred zagonom 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 | Privzeto | Učinek |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL` | nič | Identiteta avtorja (glejte zgornji vrstni red) |
| `PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL` | vrednosti avtorja | Identiteta avtorja objave |
| `PITMASTER_HTTP_TIMEOUT` | `30` | Časovna omejitev pametnega HTTP v sekundah (celo število) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | Največja globina verige delt pri branju paketov (celo število) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | Objekti, shranjeni v predpomnilniku objektov v pomnilniku |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | Omejitev velikosti predpomnilnika objektov v bajtih |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | Razrešeni objekti delta, shranjeni v predpomnilniku posameznega paketa |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | Omejitev velikosti tega predpomnilnika paketov v bajtih |
| `PITMASTER_MAX_PACK_MEMORY` | nič | Starejše ime za omejitev velikosti predpomnilnika paketov v bajtih, uporabljeno le, če `PITMASTER_PACK_RESOLVED_CACHE_BYTES` ni definirana |

Vrednosti v bajtih so lahko celo število ali niz s pripono `k`, `m` ali `g` (`'256M'`). Neveljavne vrednosti se nadomestijo s privzeto vrednostjo.

Spremenljivke okolja preglasijo konstante identitete: `PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`, `PITMASTER_AUTHOR_DATE`, ustreznice `PITMASTER_COMMITTER_*` ter lastni spremenljivki `GIT_AUTHOR_*` in `GIT_COMMITTER_*` za git. Prenos SSH bere spremenljivke `PITMASTER_SSH_*`, opisane v razdelku [Protokoli](https://pitmaster.inline0.dev/sl/docs/network/protocols).

Za zgoščevalni algoritem ni konstante. Oblika objektov se izbere ob ustvarjanju repozitorija (`Pitmaster::init($path, 'sha256')` ali `init --object-format=sha256` v CLI) in se nato prebere iz konfiguracije repozitorija.