Protokoll

Pitmaster stöder flera nätverkstransportprotokoll för kommunikation med git-servrar. Smart HTTP är den primära transporten. Ytterligare protokoll finns för bredare kompatibilitet.

Smart HTTP (primär)

Den rekommenderade transporten. Den fungerar över HTTPS och är det mest spridda protokollet. Det finns ingen API för anpassade headers eller autentiseringsuppgifter; dessa kan bara skickas i URL (https://user:token@host/repo.git), som PHP skickar med Basic-autentisering. clone() lagrar URL, inklusive autentiseringsuppgifter, som remote.origin.url i .git/config. Förfrågningar använder strömomslagen i PHP, så allow_url_fopen måste vara aktiverat.

use Pitmaster\Protocol\SmartHttpClient;

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

Se Smart HTTP för fullständig information.

Protokoll v1

Det traditionella smarta HTTP-protokollet. Alla referenser skickas under upptäckten, och förhandlingen använder want/have/done-rader.

use Pitmaster\Protocol\ProtocolV1;

Protokoll v2

Det nyare protokollet med strukturerade kommandon (ls-refs, fetch). Effektivare för repon med många referenser eftersom klienten kan filtrera referenslistan.

clone() och fetch() använder alltid protokoll v1. Protokoll v2 kan användas uttryckligen över smart HTTP via SmartHttpClient::discoverRefsV2() och UploadPackClient::fetchV2().

Dumb HTTP

Reservlösning för servrar som inte stöder smart HTTP-protokoll. Dumb-protokollet hämtar objekt och pack-filer separat via vanliga HTTP GET-förfrågningar.

use Pitmaster\Protocol\DumbHttpClient;

$client = new DumbHttpClient();

Begränsningar för dumb HTTP:

• Ingen förhandling (klienten måste ladda ned allt)
• Ingen deltakomprimering under överföringen
• Betydligt långsammare än smart HTTP
• Vissa servrar (GitHub, GitLab) stöder det inte

Dumb-protokollet hämtar:

1. GET /info/refs (vanlig text, inga pkt-line)
2. GET /HEAD (standardgren)
3. GET /objects/info/packs (lista över tillgängliga pack-filer)
4. GET /objects/pack/pack-<hash>.pack och .idx (varje listad pack-fil och dess index)
5. GET /objects/<xx>/<rest> (enskilda lösa objekt, genomgångna från referenstopparna)

Steg 5 körs endast när servern inte listar några pack-filer. När pack-filer listas hämtas inte objekt som bara finns som lösa filer på servern (#18). Dumb-klienten godtar endast objekts-ID:n med 40 tecken (SHA-1). clone() och fetch() faller tillbaka på dumb HTTP när den smarta HTTP-kommunikationen misslyckas.

SSH

Transporten SSH använder tillägget ssh2 PHP när det är laddat. Annars startar den systemets ssh-klient via proc_open(). I båda fallen körs git-upload-pack eller git-receive-pack på fjärrservern.

use Pitmaster\Protocol\SshClient;

$client = new SshClient();

URL:er av typen SSH:

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

Inget tillägg krävs. De två sökvägarna fungerar olika:

Systemets ssh-klient (används när ssh2 inte är laddat). Pitmaster kör ssh -o BatchMode=yes -o ConnectTimeout=30 -p <port> <user>@<host> <command>, så autentisering och kontroll av värdnyckel följer din SSH-konfiguration och agent. Dessa miljövariabler justerar kommandot:

Den här sökvägen startar en process och är därför inte tillgänglig för handtag som öppnats med ['processes' => false].

Tillägget ssh2 (prioriteras alltid när det är laddat). Pitmaster autentiserar med ~/.ssh/id_rsa, därefter med ~/.ssh/id_ed25519 om RSA-nyckeln finns men avvisas, och annars med agenten SSH. Variablerna PITMASTER_SSH_* ignoreras, och serverns värdnyckel verifieras inte med den här metoden (#22).

Transporten SSH kör git-upload-pack eller git-receive-pack som ett fjärrkommando och kommunicerar via kanalen SSH med samma pkt-line-protokoll som smart HTTP.

Protokollet Git (TCP)

Det inbyggda protokollet git kommunicerar via TCP-port 9418 med PHP-sockets. GitProtocolClient implementerar referensupptäckt och upload-pack (hämtning); det kan inte skicka ändringar. clone() och fetch() dirigerar inte URL:er av typen git:// till det, så använd klienten direkt.

use Pitmaster\Protocol\GitProtocolClient;

$client = new GitProtocolClient();

URL:er av typen Git:

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

Egenskaper:

• Ingen autentisering (i praktiken skrivskyddat)
• Ingen kryptering
• Föråldrat hos de flesta hosting-leverantörer
• Använder samma pkt-line-inramning som smart HTTP

Protokollet git skickar tjänstenamnet och sökvägen till repot som den första begäran och fortsätter sedan med standardiserad referensupptäckt och packförhandling via pkt-line.

Paketfiler

Git-paketfiler är pack-filer för offlinebruk med referensinformation. De gör det möjligt att överföra repodata utan nätverksanslutning.

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 läser rubriker för paketfiler av typen v2 och v3. Det finns ingen Repository-metod för att importera en paketfil: skriv packData() till .git/objects/pack/, skapa dess index med PackIndexer::writeIndex() och uppdatera referenserna själv.

Paketfilformat:

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

Paketfiler är användbara för:

• Överföring utan nätverk (USB-enheter)
• Inkrementella säkerhetskopior
• Förberedelse av kloner i isolerade miljöer

Ytliga kloner

Pitmaster stöder ytliga kloner, där endast en begränsad del av commithistoriken hämtas.

use Pitmaster\Protocol\ShallowClone;

Ange ett djup för Pitmaster::clone($url, $path, $depth) eller $repo->fetch($remote, $depth). Begäran lägger till funktionen shallow och en rad med deepen:

want <hash>
deepen <depth>

Servern svarar med shallow <hash>-rader som anger var historiken trunkerades. Pitmaster beräknar den grunda gränsen utifrån själva djupet och använder serverns shallow-rader när beräkningen inte hittar något; resultatet sparas i .git/shallow. ShallowClone::readShallow(), writeShallow() och isShallow() arbetar direkt med den filen.

Protokolljämförelse

Val av transport

Pitmaster::clone(), $repo->fetch() och $repo->push() väljer transport utifrån URL:

git://-URL:er och lokala sökvägar stöds inte av dessa metoder: de skickas till smart HTTP-klienten och misslyckas. Använd GitProtocolClient direkt för git://. En HTTPS URL som innehåller både en användare och en port (https://user@host:8443/repo.git) misstas för närvarande för en SSH URL (#17).