Protokollid

Pitmaster toetab git-serveritega suhtlemiseks mitut võrgutranspordi protokolli. Peamine transport on nutikas HTTP. Laiema ühilduvuse jaoks on saadaval lisaprotokollid.

Nutikas HTTP (peamine)

Soovitatav transport. Töötab üle HTTPS ja on kõige laiemalt kasutatav protokoll. Kohandatud päiste ega mandaadi jaoks pole API-i; mandaati saab edastada ainult URL-is (https://user:token@host/repo.git), mille PHP saadab Basic-autentimisena. clone() salvestab URL-i koos mandaatidega kujul remote.origin.url asukohas .git/config. Päringud kasutavad PHP vooümbriseid, seega peab allow_url_fopen olema lubatud.

use Pitmaster\Protocol\SmartHttpClient;

$http = new SmartHttpClient(timeout: 30);
$discovery = $http->discoverRefs('https://github.com/user/repo.git');

Üksikasju vt jaotisest Nutikas HTTP.

Protokoll v1

Traditsiooniline nutikas HTTP-protokoll. Tuvastamisel saadetakse kõik viited ning läbirääkimisel kasutatakse ridu want/have/done.

use Pitmaster\Protocol\ProtocolV1;

Protokoll v2

Uuem protokoll struktureeritud käskudega (ls-refs, fetch). See on tõhusam paljude viidetega hoidlates, sest klient saab viidete loendit filtreerida.

clone() ja fetch() kasutavad alati protokolli v1. Protokoll v2 on nutika HTTP kaudu selgesõnaliselt saadaval transpordiga SmartHttpClient::discoverRefsV2() ja UploadPackClient::fetchV2().

Lihtsustatud HTTP

Varuvariant serveritele, mis ei toeta nutikat HTTP-protokolli. Lihtsustatud protokoll hangib objektid ja pakifailid ükshaaval tavaliste HTTP GET-päringutega.

use Pitmaster\Protocol\DumbHttpClient;

$client = new DumbHttpClient();

Lihtsustatud HTTP-i piirangud:

• Läbirääkimisi pole (klient peab kõik alla laadima)
• Edastuse ajal delta-tihendust ei kasutata
• Oluliselt aeglasem kui nutikas HTTP
• Mõned serverid (GitHub, GitLab) ei toeta seda

Lihtsustatud protokoll hangib:

1. GET /info/refs (lihttekst, pkt-line-vorminguta)

2. GET /HEAD (vaikimisi haru)

3. GET /objects/info/packs (saadaolevate pakifailide loend)

4. GET /objects/pack/pack-<hash>.pack ja .idx (iga loendis oleva pakifaili ja selle indeks)

5. GET /objects/<xx>/<rest> (üksikud lahtised objektid, mida läbitakse viidete tippude põhjal)

6. sammu tehakse ainult siis, kui server ei loetle pakifaile. Kui server loetleb pakifaile, ei laadita alla objekte, mis on serveris olemas ainult lahtiste failidena (#18). Lihtsustatud klient aktsepteerib ainult 40-kohalisi (SHA-1) objektitunnuseid. clone() ja fetch() lähevad nutika HTTP andmevahetuse nurjumisel üle lihtsustatud HTTP-ile.

SSH

Transport SSH kasutab laiendust ssh2 PHP, kui see on laaditud. Muul juhul käivitab see süsteemi ssh kliendi programmi proc_open() kaudu. Mõlemal juhul käivitatakse kaugserveris git-upload-pack või git-receive-pack.

use Pitmaster\Protocol\SshClient;

$client = new SshClient();

SSH URL-id:

git@github.com:user/repo.git
ssh://git@github.com/user/repo.git

Laiendust pole vaja. Need kaks teed toimivad erinevalt:

Süsteemi klient ssh (kasutatakse siis, kui ssh2 pole laaditud). Pitmaster käivitab käsu ssh -o BatchMode=yes -o ConnectTimeout=30 -p <port> <user>@<host> <command>, seega järgivad autentimine ja hostivõtme kontroll teie SSH seadistust ja agenti. Käsku saab muuta järgmiste keskkonnamuutujatega:

See tee käivitab protsessi, seega pole see saadaval käepidemetel, mis avati valikuga ['processes' => false].

Laiendus ssh2 (laadimise korral alati eelistatud). Pitmaster autendib ~/.ssh/id_rsa abil ja proovib siis ~/.ssh/id_ed25519-i, kui RSA-võti on olemas, kuid tagasi lükatud; muul juhul kasutab see agenti SSH. Muutujaid PITMASTER_SSH_* eiratakse ja selle tee puhul serveri hostivõtit ei kontrollita (#22).

Transport SSH käivitab kaugkäsklusena programmi git-upload-pack või git-receive-pack ning suhtleb SSH kanali kaudu, kasutades sama pkt-line-protokolli mis nutikas HTTP.

Protokoll Git (TCP)

Algne git-protokoll suhtleb TCP-pordi 9418 kaudu, kasutades sokleid PHP. GitProtocolClient teostab viidete tuvastamise ja upload-pack (toomise); sellega ei saa muudatusi saata. clone() ja fetch() ei suuna URL-e git:// selle protokollini, seega kasutage seda kliendilt otse.

use Pitmaster\Protocol\GitProtocolClient;

$client = new GitProtocolClient();

Git URL-id:

git://github.com/user/repo.git

Omadused:

• Autentimine puudub (praktikas kirjutuskaitstud)
• Krüpteerimine puudub
• Enamik majutusteenuse pakkujaid on selle kasutusest kõrvaldanud
• Kasutab sama pkt-line-vormingut mis nutikas HTTP

git-protokoll saadab teenuse nime ja hoidla tee algse päringuna, seejärel jätkub töö tavalise pkt-line-vormingus viidete tuvastamise ja pakifaili läbirääkimisega.

Paketid

Git-paketid on viiteteabega võrguühenduseta pakifailid. Need võimaldavad hoidlaandmeid edastada võrguühenduseta.

use Pitmaster\Protocol\Bundle;

// Read a bundle file
$bundle = Bundle::open('/path/to/repo.bundle');
$refs = $bundle->refs();
$packData = $bundle->packData();
$prerequisites = $bundle->prerequisites();

// Create one
$bundle = Bundle::create(['refs/heads/main' => $commitId], $packData);
$bundle->writeTo('/path/to/out.bundle');

Pitmaster loeb pakettide päiseid v2 ja v3. Paketi importimiseks pole meetodit Repository: kirjutage packData() asukohta .git/objects/pack/, koostage selle register käsuga PackIndexer::writeIndex() ja uuendage viited ise.

Paketi vorming:

# v2 git bundle\n
-<prerequisite hash>\n    (zero or more)
<hash> <refname>\n        (one or more)
\n
<pack data>               (standard pack file format)

Pakettidest on kasu järgmistes olukordades:

• Andmete edastamine eemaldatava andmekandjaga (USB-draivid)
• Järk-järgulised varukoopiad
• Kloonide ettevalmistamine internetita keskkondades

Madala ajaloosügavusega kloonid

Pitmaster toetab madala ajaloosügavusega kloone, mille puhul tuuakse ainult piiratud sügavusega sissekannete ajalugu.

use Pitmaster\Protocol\ShallowClone;

Edastage sügavus argumendina funktsioonile Pitmaster::clone($url, $path, $depth) või $repo->fetch($remote, $depth). Päring lisab võimaluse shallow ja rea deepen:

want <hash>
deepen <depth>

Server vastab ridadega shallow <hash>, mis näitavad, kus ajalugu kärbiti. Pitmaster arvutab pinnapealse piiri sügavuse põhjal ja kasutab serveri ridu shallow, kui arvutus tulemust ei anna; tulemus salvestatakse faili .git/shallow. ShallowClone::readShallow(), writeShallow() ja isShallow() töötavad selle failiga otse.

Protokollide võrdlus

Edastusviisi valik

Pitmaster::clone(), $repo->fetch() ja $repo->push() valivad edastusviisi URL põhjal:

git:// URL-id ja kohalikud teed pole nende meetoditega toetatud: need edastatakse nutikale HTTP kliendile ja toiming nurjub. Kasutage GitProtocolClient otse git:// jaoks. HTTPS URL, mis sisaldab nii kasutajat kui porti (https://user@host:8443/repo.git), peetakse praegu ekslikult SSH URL-ks (#17).