Hoppa till innehåll

Git LFS

Visa som Markdown Redigera på GitHub Dokumentation på bfe242f

Git Large File Storage (LFS) ersätter stora filer i ditt arkiv med små pekarfiler. Det faktiska filinnehållet lagras på en separat LFS-server. Pitmaster kan tolka och skapa LFS-pekare och kommunicera med LFS-servrar via batch-API. Den läser inte .gitattributes och kör inte LFS-filtren clean och smudge: add() lagrar filer som de är och checkout() skriver pekarfiler. Din kod ansvarar för att hämta det faktiska innehållet, som visas nedan.

LFS-pekarfiler

När en fil spåras av LFS lagrar git en pekarfil i stället för det faktiska innehållet:

Kod
version https://git-lfs.github.com/spec/v1
oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
size 12345

Pekaren innehåller:

  • version: LFS-specifikationsversionen URL
  • oid: SHA-256-hash för det faktiska filinnehållet (med prefixet sha256:)
  • size: filens faktiska storlek i byte

Tolka pekare

PHP
use Pitmaster\Lfs\LfsPointer;

$content = file_get_contents('.git-lfs-tracked-file');
$pointer = LfsPointer::parse($content);

if ($pointer !== null) {
    echo "OID: {$pointer->oid}\n";
    echo "Size: {$pointer->size}\n";
    echo "Version: {$pointer->version}\n";
}

parse() returnerar null om raden version, oid sha256: eller size saknas. Den validerar inte värdena (ett OID som inte är hexadecimalt eller en storlek som inte är numerisk godtas).

Identifiera pekare

PHP
if (LfsPointer::isPointer($blobContent)) {
    // This blob is an LFS pointer, not actual file content
    $pointer = LfsPointer::parse($blobContent);
}

isPointer() kontrollerar om fälten för versionen URL, oid sha256: och size finns, utan att göra en fullständig tolkning.

Skapa pekare

PHP
// From known OID and size
$pointer = new LfsPointer(
    oid: '4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393',
    size: 12345,
);

// From file content (computes SHA-256 hash)
$pointer = LfsPointer::forContent($actualFileContent);

echo $pointer->oid;   // SHA-256 hash
echo $pointer->size;  // Content length

Serialisera pekare

PHP
$content = $pointer->serialize();
// "version https://git-lfs.github.com/spec/v1\noid sha256:4d7a21...\nsize 12345\n"

LFS-klient

LfsClient kommunicerar med LFS-servrar via batch-API (POST till <url>/objects/batch).

Skapa en klient

PHP
use Pitmaster\Lfs\LfsClient;

// From a git remote URL (appends /info/lfs)
$client = LfsClient::fromRemoteUrl('https://github.com/user/repo.git');
// LFS URL: https://github.com/user/repo.git/info/lfs

// Direct URL
$client = new LfsClient('https://lfs.example.com/repo', timeout: 60);

Metoden fromRemoteUrl() följer standardkonventionen: lägg till /info/lfs till git-URL (lägg till .git om det saknas). Endast HTTP(S)-URL:er för fjärrarkiv ger en användbar LFS-URL; fjärrarkiv i SCP-format, SSH (git@host:repo.git), gör det inte.

LfsClient använder PHPs strömomslagare för HTTP (allow_url_fopen måste vara aktiverat). Den skickar inga autentiseringsuppgifter och ignorerar header-mappningen som returneras med varje åtgärd, så den fungerar bara med LFS-servrar och lagrings-URL:er som inte kräver autentisering. Den är inte knuten till ett arkivhandtag, så den gör nätverksförfrågningar även när du arbetar med ett arkiv som öppnats med Pitmaster::processFreeOptions().

Ladda ned filer

PHP
// Single file download
$content = $client->download($pointer->oid, $pointer->size);
file_put_contents('large-file.bin', $content);

Under huven download():

  1. Skickar en batchförfrågan för åtgärden download
  2. Tar emot en hämtnings-URL från servern
  3. Hämtar filinnehållet från den URL

De hämtade byten kontrolleras inte mot OID eller storlek.

Batchhämtning

PHP
$results = $client->batchDownload([
    ['oid' => 'abc123...', 'size' => 12345],
    ['oid' => 'def456...', 'size' => 67890],
]);

foreach ($results as $result) {
    if ($result['error'] !== null) {
        echo "Error: {$result['error']}\n";
        continue;
    }

    if ($result['href'] !== null) {
        // Download from $result['href']
    }
}

Ladda upp filer

PHP
$client->upload($pointer->oid, $pointer->size, $fileContent);

Uppladdningen skickar en batchförfrågan för åtgärden upload. Om servern redan har objektet returneras inget uppladdnings-URL och åtgärden gör ingenting. Resultatet av själva uppladdningsförfrågan kontrolleras inte, så en misslyckad uppladdning rapporteras inte och åtgärden verify anropas inte.

Batchuppladdning

PHP
$results = $client->batchUpload([
    ['oid' => 'abc123...', 'size' => 12345],
]);

foreach ($results as $result) {
    if ($result['href'] !== null) {
        // Server needs this object, upload to $result['href']
    }
    // No href means server already has it
}

Batchprotokollet API

LFS-batchprotokollet API använder JSON över HTTP:

Förfrågan

Kod
POST <lfs-url>/objects/batch
Content-Type: application/vnd.git-lfs+json
Accept: application/vnd.git-lfs+json

{
    "operation": "download",
    "transfers": ["basic"],
    "objects": [
        {"oid": "abc123...", "size": 12345}
    ]
}

Svar

JSON
{
    "objects": [
        {
            "oid": "abc123...",
            "size": 12345,
            "actions": {
                "download": {
                    "href": "https://storage.example.com/abc123...",
                    "header": {
                        "Authorization": "Bearer token"
                    }
                }
            }
        }
    ]
}

Integrera LFS med arkivoperationer

När du läser ett arkiv som använder LFS kan blobinnehållet vara LFS-pekare i stället för faktiska fildata. Så här hämtar du det faktiska innehållet:

PHP
$blob = $repo->readObject($hash);

if (LfsPointer::isPointer($blob->content)) {
    $pointer = LfsPointer::parse($blob->content);
    $remoteUrl = $repo->config()->get('remote.origin.url');
    $client = LfsClient::fromRemoteUrl($remoteUrl);
    $realContent = $client->download($pointer->oid, $pointer->size);
} else {
    $realContent = $blob->content;
}

Felhantering

En misslyckad eller ogiltig batchförfrågan och en misslyckad hämtningsförfrågan utlöser ProtocolException. download() utlöser också ett fel när servern inte returnerar någon hämtnings-URL för objektet, utan serverns felmeddelande. batchDownload() och batchUpload() utlöser inte fel för fel per objekt; de returnerar dem i fältet error.

PHP
use Pitmaster\Exceptions\ProtocolException;

try {
    $content = $client->download($oid, $size);
} catch (ProtocolException $e) {
    // Server unreachable, invalid response, no download URL
    echo "LFS error: {$e->getMessage()}\n";
}

Egenskaper för LFS-pekare

Klassen LfsPointer är skrivskyddad:

PHP
$pointer->oid;      // string: SHA-256 hash (hex)
$pointer->size;     // int: file size in bytes
$pointer->version;  // string: spec version URL