Protokol

Pitmaster mendukung beberapa protokol transport jaringan untuk berkomunikasi dengan server git. Smart HTTP adalah transport utama. Protokol tambahan tersedia untuk kompatibilitas yang lebih luas.

Smart HTTP (utama)

Transport yang direkomendasikan. Berfungsi melalui HTTPS dan merupakan protokol yang paling banyak digunakan. Tidak ada API untuk header atau kredensial kustom; kredensial hanya dapat dikirim di URL (https://user:token@host/repo.git), yang dikirim PHP sebagai autentikasi Basic. clone() menyimpan URL, termasuk kredensial, sebagai remote.origin.url di .git/config. Permintaan menggunakan pembungkus stream milik PHP, jadi allow_url_fopen harus diaktifkan.

use Pitmaster\Protocol\SmartHttpClient;

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

Lihat Smart HTTP untuk detail lengkap.

Protokol v1

Protokol smart HTTP tradisional. Semua ref dikirim saat discovery, dan negosiasi menggunakan baris want/have/done.

use Pitmaster\Protocol\ProtocolV1;

Protokol v2

Protokol yang lebih baru dengan perintah terstruktur (ls-refs, fetch). Lebih efisien untuk repositori dengan banyak ref karena klien dapat memfilter daftar ref.

clone() dan fetch() selalu menggunakan protokol v1. Protokol v2 tersedia secara eksplisit melalui smart HTTP menggunakan SmartHttpClient::discoverRefsV2() dan UploadPackClient::fetchV2().

Dumb HTTP

Fallback untuk server yang tidak mendukung protokol smart HTTP. Protokol dumb mengambil objek dan pack satu per satu melalui permintaan GET HTTP biasa.

use Pitmaster\Protocol\DumbHttpClient;

$client = new DumbHttpClient();

Keterbatasan dumb HTTP:

• Tidak ada negosiasi (klien harus mengunduh semuanya)
• Tidak ada kompresi delta selama transfer
• Jauh lebih lambat daripada smart HTTP
• Beberapa server (GitHub, GitLab) tidak mendukungnya

Protokol dumb mengambil:

1. GET /info/refs (teks biasa, tanpa pkt-line)
2. GET /HEAD (cabang default)
3. GET /objects/info/packs (daftar pack yang tersedia)
4. GET /objects/pack/pack-<hash>.pack dan .idx (setiap pack yang tercantum dan indeksnya)
5. GET /objects/<xx>/<rest> (objek lepas satu per satu, ditelusuri dari tip ref)

Langkah 5 hanya dijalankan jika server tidak mencantumkan pack. Jika server mencantumkan pack, objek yang hanya tersedia sebagai file lepas di server tidak diunduh (#18). Klien dumb hanya menerima ID objek 40 karakter (SHA-1). clone() dan fetch() beralih ke dumb HTTP jika pertukaran smart HTTP gagal.

SSH

Transport SSH menggunakan ekstensi ssh2 PHP jika ekstensi tersebut dimuat. Jika tidak, transport ini menjalankan klien ssh sistem melalui proc_open(). Keduanya menjalankan git-upload-pack atau git-receive-pack pada remote.

use Pitmaster\Protocol\SshClient;

$client = new SshClient();

URL SSH:

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

Tidak diperlukan ekstensi. Kedua jalur bekerja secara berbeda:

Klien ssh sistem (digunakan saat ssh2 tidak dimuat). Pitmaster menjalankan ssh -o BatchMode=yes -o ConnectTimeout=30 -p <port> <user>@<host> <command>, sehingga autentikasi dan pemeriksaan kunci host mengikuti konfigurasi SSH dan agent Anda. Variabel lingkungan ini menyesuaikan perintah:

Jalur ini memulai proses, jadi tidak tersedia pada handle yang dibuka dengan ['processes' => false].

Ekstensi ssh2 (selalu diprioritaskan jika dimuat). Pitmaster melakukan autentikasi dengan ~/.ssh/id_rsa, lalu ~/.ssh/id_ed25519 jika kunci RSA tersedia tetapi ditolak, dan jika tidak, menggunakan agent SSH. Variabel PITMASTER_SSH_* diabaikan, dan kunci host server tidak diverifikasi pada jalur ini (#22).

Transport SSH menjalankan git-upload-pack atau git-receive-pack sebagai perintah remote dan berkomunikasi melalui kanal SSH menggunakan protokol pkt-line yang sama dengan smart HTTP.

Protokol Git (TCP)

Protokol git native berkomunikasi melalui port TCP 9418 menggunakan socket PHP. GitProtocolClient menerapkan discovery ref dan upload-pack (pengambilan); protokol ini tidak dapat melakukan push. clone() dan fetch() tidak mengarahkan URL git:// ke protokol ini, jadi gunakan kliennya secara langsung.

use Pitmaster\Protocol\GitProtocolClient;

$client = new GitProtocolClient();

URL Git:

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

Karakteristik:

• Tidak ada autentikasi (dalam praktiknya hanya baca)
• Tidak ada enkripsi
• Tidak digunakan lagi oleh sebagian besar penyedia hosting
• Menggunakan framing pkt-line yang sama dengan smart HTTP

Protokol git mengirim nama layanan dan jalur repositori sebagai permintaan awal, lalu melanjutkan dengan discovery ref pkt-line standar dan negosiasi pack.

Bundle

Bundle Git adalah file pack offline yang berisi informasi ref. Bundle memungkinkan transfer data repositori tanpa koneksi jaringan.

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 membaca header bundle v2 dan v3. Tidak ada metode Repository untuk mengimpor bundle: tulis packData() ke .git/objects/pack/, buat indeksnya dengan PackIndexer::writeIndex(), lalu perbarui ref sendiri.

Format bundle:

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

Bundle berguna untuk:

• Transfer sneakernet (drive USB)
• Cadangan inkremental
• Menyiapkan clone di lingkungan terisolasi dari jaringan

Clone dangkal

Pitmaster mendukung clone dangkal, yaitu hanya mengambil riwayat commit hingga kedalaman tertentu.

use Pitmaster\Protocol\ShallowClone;

Berikan kedalaman ke Pitmaster::clone($url, $path, $depth) atau $repo->fetch($remote, $depth). Permintaan menambahkan kapabilitas shallow dan baris deepen:

want <hash>
deepen <depth>

Server merespons dengan baris shallow <hash> yang menunjukkan di mana riwayat dipotong. Pitmaster menghitung batas kedalaman dari kedalaman itu sendiri dan menggunakan baris shallow server jika perhitungan tersebut tidak menemukan apa pun; hasilnya disimpan di .git/shallow. ShallowClone::readShallow(), writeShallow(), dan isShallow() bekerja langsung dengan file itu.

Perbandingan protokol

Pemilihan transport

Pitmaster::clone(), $repo->fetch(), dan $repo->push() memilih transport dari URL:

URL git:// dan jalur lokal tidak didukung oleh metode ini: keduanya dikirim ke klien smart HTTP dan gagal. Gunakan GitProtocolClient secara langsung untuk git://. HTTPS URL yang berisi pengguna dan port (https://user@host:8443/repo.git) saat ini keliru dianggap sebagai SSH URL (#17).