# Obiekty Git Wszystko w repozytorium git jest przechowywane jako obiekt. Istnieją cztery typy: bloby (zawartość plików), drzewa (listy katalogów), commity (migawki z metadanymi) i tagi (adnotowane odwołania). Każdy obiekt jest identyfikowany przez skrót SHA-1 swojej zawartości. ## Typy obiektów ### Blob Blob przechowuje surową zawartość pliku bez metadanych (bez nazwy pliku i uprawnień). ```php use Pitmaster\Object\Blob; // Create from content $blob = Blob::fromContent('Hello, world!'); echo $blob->content; // 'Hello, world!' echo $blob->size(); // 13 echo $blob->id->hex; // SHA-1 hash echo $blob->type->value; // 'blob' (the property is ObjectType::Blob) ``` ### Drzewo Drzewo to lista katalogu. Każdy wpis zawiera tryb, nazwę i skrót wskazujący na blob lub poddrzewo. ```php use Pitmaster\Object\Tree; use Pitmaster\Object\TreeEntry; // Read a tree $tree = $repo->readObject($treeHash); foreach ($tree->entries as $entry) { echo "{$entry->mode} {$entry->name} {$entry->hash->hex}\n"; } // Look up a specific entry $entry = $tree->entry('README.md'); // Create a tree (entries already in git's sort order) $entries = [ new TreeEntry('100644', 'README.md', $blobId), new TreeEntry('100755', 'deploy.sh', $execBlobId), new TreeEntry('40000', 'src', $subtreeId), ]; $tree = Tree::fromEntries($entries); ``` `Tree::fromEntries()` zapisuje wpisy w podanej kolejności i ciągi trybu dokładnie w podanej postaci, dlatego najpierw je posortuj, a tryby katalogów zapisuj jako `40000`. Drzewo zapisane za pomocą `040000` lub w innej kolejności otrzymuje inny skrót niż w git, a `git fsck --strict` podaje tryb z zerami wiodącymi. #### TreeEntry `TreeEntry` jest obiektem wartości tylko do odczytu: ```php use Pitmaster\Object\TreeEntry; $entry->mode; // '100644', '100755', '40000', '120000', '160000' $entry->name; // Filename $entry->hash; // ObjectId // Type checks $entry->isBlob(); // regular or executable file (mode 10xxxx) $entry->isExecutable(); // mode 100755 $entry->isTree(); // mode 40000 (also accepts 040000) $entry->isSymlink(); // mode 120000 $entry->isGitlink(); // mode 160000 (submodule) ``` Wartości trybu: | Tryb | Znaczenie | |------|---------| | `100644` | Zwykły plik | | `100755` | Plik wykonywalny | | `40000` | Katalog (drzewo); wyświetlany jako `040000` przez `git ls-tree` | | `120000` | Dowiązanie symboliczne | | `160000` | Gitlink (submoduł) | Wpisy drzewa są sortowane według nazwy, przy czym na potrzeby porównania nazwy katalogów traktuje się tak, jakby kończyły się na `/`. ### Commit Commit łączy drzewo z jego historią i metadanymi. ```php use Pitmaster\Object\Commit; $commit = $repo->head(); $commit->id; // ObjectId $commit->tree; // ObjectId of the tree $commit->parents; // array of ObjectId (zero for root, one for normal, two+ for merge) $commit->author; // 'Name timestamp timezone' $commit->committer; // 'Name timestamp timezone' $commit->message; // Full commit message $commit->isMerge(); // true if two or more parents ``` #### Budowanie zawartości commita ```php $content = Commit::buildContent( tree: $treeId, parents: [$parentId], author: 'Jane 1700000000 +0000', committer: 'Jane 1700000000 +0000', message: "Add feature\n", ); ``` Surowy format commita: ``` tree \n parent \n (zero or more) author <> \n committer <> \n \n ``` ### Tag Tagi z adnotacjami to obiekty z metadanymi. ```php use Pitmaster\Object\Tag; $tag = $repo->readObject($tagHash); $tag->object; // ObjectId of the target $tag->objectType; // ObjectType enum (ObjectType::Commit, ...) $tag->name; // Tag name $tag->tagger; // 'Name timestamp timezone' $tag->message; // Tag message ``` Surowy format taga: ``` object \n type commit\n tag \n tagger <> \n \n ``` ## ObjectId `ObjectId` jest obiektem wartości tylko do odczytu, reprezentującym skrót SHA-1 (lub SHA-256). ```php use Pitmaster\Object\ObjectId; use Pitmaster\Object\ObjectType; // From hex string $id = ObjectId::fromHex('a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2'); // From binary (20 bytes for SHA-1, 32 for SHA-256) $id = ObjectId::fromBinary($rawBytes); // Compute from content $id = ObjectId::compute(ObjectType::Blob, 'Hello, world!'); $id = ObjectId::compute(ObjectType::Blob, 'Hello, world!', 'sha256'); // Zero hash $id = ObjectId::zero(); $id = ObjectId::zero('sha256'); // Properties $id->hex; // 40-character hex string (64 for SHA-256) $id->binary; // 20-byte raw binary (32 for SHA-256) $id->algo; // 'sha1' or 'sha256' $id->isSha256(); $id->isZero(); // Comparison $id->equals($otherId); ``` Skrót jest obliczany na podstawie nieskompresowanych danych: `sha1("{type} {size}\0{content}")` lub SHA-256 tych samych bajtów. `fromHex()` i `fromBinary()` wybierają algorytm na podstawie długości. ## Typ wyliczeniowy ObjectType ```php use Pitmaster\Object\ObjectType; ObjectType::Blob; // 'blob' ObjectType::Tree; // 'tree' ObjectType::Commit; // 'commit' ObjectType::Tag; // 'tag' ``` ## Format luźnego obiektu Luźne obiekty są przechowywane jako osobne pliki w `.git/objects/`, uporządkowane według dwóch pierwszych znaków szesnastkowych ich skrótu. ``` .git/objects/a1/b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 ``` Zawartość pliku jest skompresowana zlib. Nieskompresowana zawartość to: ``` \0 ``` Na przykład blob zawierający „Hello” jest przechowywany jako: ``` zlib_encode("blob 5\0Hello") ``` ### Odczytywanie luźnych obiektów ```php use Pitmaster\Storage\LooseObjectStore; $store = new LooseObjectStore('/path/to/.git/objects'); $object = $store->read($objectId); ``` `LooseObjectStore`: 1. Oblicza ścieżkę pliku na podstawie skrótu 2. Odczytuje i dekompresuje plik zlib 3. Analizuje nagłówek, aby wyodrębnić typ i rozmiar 4. Przekazuje dane do odpowiedniego parsera (`Blob`, `Tree`, `Commit`, `Tag`) ### Zapisywanie luźnych obiektów ```php $store->write($object); ``` Proces zapisu: 1. Serializacja: `"{type} {size}\0{content}"` 2. Użycie `id` obiektu, obliczonego podczas jego tworzenia (odczyt weryfikuje skrót) 3. Kompresja: `zlib_encode(serialized)` 4. Zapis do `.git/objects/{hash[0..1]}/{rest of hash}` 5. Zapis atomowy (zapis do pliku tymczasowego, a następnie zmiana nazwy) ## ObjectSerializer `ObjectSerializer` obsługuje kodowanie i dekodowanie formatu przewodowego obiektu. ```php use Pitmaster\Storage\ObjectSerializer; // Encode $raw = ObjectSerializer::encodeRaw($object); // "blob 5\0Hello" $compressed = ObjectSerializer::encode($object); // zlib-compressed form, as stored in a loose object file // Decode $object = ObjectSerializer::decodeRaw($raw); $object = ObjectSerializer::decode($compressed, $expectedHex); // throws CorruptObjectException on a hash mismatch ``` ## ObjectDatabase `ObjectDatabase` to złożony magazyn, który najpierw przeszukuje luźne obiekty, a następnie pliki pakietów. ```php use Pitmaster\Storage\ObjectDatabase; $db = new ObjectDatabase('/path/to/.git/objects'); $object = $db->read($objectId); // Search loose, then packs $db->write($object); // Always writes to loose $exists = $db->exists($objectId); // Check loose, then packs $all = $db->listAll(); // All hashes from loose + packs ``` Zapis bezpośrednio do luźnego magazynu jest zamierzony. Pozwól `git gc` przepakować obiekty do plików pakietów. ## Obsługa SHA-256 Pitmaster abstrahuje algorytm skrótu za pomocą `ObjectId`. Domyślnie używane jest SHA-1. SHA-256 jest wybierany dla każdego repozytorium podczas jego tworzenia: ```php $repo = Pitmaster::init('/path/to/project', 'sha256'); ``` ```bash ./vendor/bin/pitmaster init --object-format=sha256 ``` Zapisuje to `extensions.objectformat = sha256` w konfiguracji. Repozytoria otwierane później odczytują format z tego wpisu, a każda operacja na obiektach, drzewach, indeksie i odwołaniach używa wtedy 64-znakowych ciągów szesnastkowych i 32-bajtowych skrótów binarnych. Nie ma globalnego przełącznika ani stałej określającej algorytm. Podczas samodzielnego tworzenia obiektów klasy obiektów przyjmują algorytm jako argument: `Blob::fromContent($content, 'sha256')`, `Tree::fromEntries($entries, 'sha256')`, `ObjectId::compute($type, $content, 'sha256')`. `Pitmaster::clone()` tworzy repozytoria SHA-1. ## Binarny format wpisu drzewa W zawartości obiektu drzewa każdy wpis jest kodowany jako: ``` \0 ``` Uwaga: w odróżnieniu od szesnastkowych skrótów w obiektach commitów i tagów, skrót jest surowymi danymi binarnymi, a nie zapisem szesnastkowym. Wpisy są sortowane przez porównanie nazw tak, jakby nazwy katalogów kończyły się na `/`. Kolejność sortowania musi być dokładna, aby skrót drzewa odpowiadał wynikowi obliczeń git.