gitprotocol-capabilities - Fähigkeiten von Protokoll v0 und v1

Server SOLLTEN alle in diesem Dokument definierten Fähigkeiten unterstützen.

In der allerersten Zeile der ersten Serverantwort von receive-pack und upload-pack folgt die erste Referenz auf ein NUL-Byte und dann eine Liste von durch Leerzeichen getrennten Serverfähigkeiten. Diese ermöglichen es dem Server, dem Client mitzuteilen, was er unterstützen kann und was nicht.

Der Client sendet dann eine durch Leerzeichen getrennte Liste von Fähigkeiten, die er aktiviert haben möchte. Der Client DARF keine Fähigkeiten anfordern, die der Server nicht als unterstützt angegeben hat.

Der Server MUSS analysieren und abbrechen, wenn ihm unbekannte Fähigkeiten gesendet wurden. Der Server DARF keine vom Client angeforderten und vom Server beworbenen Fähigkeiten ignorieren. Infolgedessen MUSS der Server keine Fähigkeiten bewerben, die er nicht versteht.

Die Fähigkeiten atomic, report-status, report-status-v2, delete-refs, quiet und push-cert werden vom receive-pack (Push zum Server) Prozess gesendet und erkannt.

Die Fähigkeiten ofs-delta und side-band-64k werden sowohl von den upload-pack- als auch von den receive-pack-Protokollen gesendet und erkannt. Die Fähigkeiten agent und session-id können optional in beiden Protokollen gesendet werden.

Alle anderen Fähigkeiten werden nur vom upload-pack (Abruf vom Server) Prozess erkannt.

Die Fähigkeit multi_ack erlaubt es dem Server, "ACK obj-id continue" zurückzugeben, sobald er einen Commit findet, der als gemeinsame Basis zwischen den Wünschen des Clients und den vorhandenen Objekten des Clients verwendet werden kann.

Durch diese frühzeitige Rückgabe kann der Server den Client potenziell daran hindern, weiter in diesem speziellen Zweig der Repository-Historie des Clients zu navigieren. Der Client muss möglicherweise immer noch andere Zweige durchlaufen und dafür "have"-Zeilen senden, bis der Server einen vollständigen Schnitt über den DAG hat oder der Client "done" gesagt hat.

Ohne multi_ack sendet ein Client "have"-Zeilen in --date-order, bis der Server eine gemeinsame Basis gefunden hat. Das bedeutet, dass der Client "have"-Zeilen sendet, die dem Server bereits als gemeinsam bekannt sind, weil sie zeitlich mit einem anderen Zweig überlappen, für den der Server noch keine gemeinsame Basis gefunden hat.

Betrachten wir beispielsweise, dass der Client Commits in Großbuchstaben hat, die der Server nicht hat, und der Server Commits in Kleinbuchstaben hat, die der Client nicht hat, wie im folgenden Diagramm:

Wenn der Client x,y möchte und mit "have F,S" beginnt, weiß der Server nicht, was F,S ist. Schließlich sagt der Client "have d" und der Server sendet "ACK d continue", um dem Client mitzuteilen, dass er diese Zeile stoppen soll (also nicht c-b-a sendet), aber er ist noch nicht fertig, er braucht eine Basis für x. Der Client fährt mit S-R-Q fort, bis a erreicht ist, an dem Punkt der Server eine klare Basis hat und alles endet.

Ohne multi_ack hätte der Client diese c-b-a-Kette ohnehin gesendet, verschachtelt mit S-R-Q.

Dies ist eine Erweiterung von multi_ack, die es dem Client ermöglicht, den Speicherzustand des Servers besser zu verstehen. Weitere Informationen finden Sie in gitprotocol-pack[5], Abschnitt "Packfile Negotiation".

Diese Fähigkeit sollte nur mit dem Smart-HTTP-Protokoll verwendet werden. Wenn sowohl multi_ack_detailed als auch no-done vorhanden sind, kann der Sender sofort nach seiner ersten "ACK obj-id ready"-Nachricht ein Pack senden.

Ohne no-done im Smart-HTTP-Protokoll würde die Serversitzung enden und der Client müsste einen weiteren Roundtrip machen, um "done" zu senden, bevor der Server das Pack senden kann. no-done eliminiert den letzten Roundtrip und reduziert somit leicht die Latenz.

Ein Thin-Pack ist ein Pack mit Deltas, die sich auf Basisobjekte beziehen, die nicht im Pack enthalten sind (aber bekanntermaßen am Empfangsort existieren). Dies kann den Netzwerkverkehr erheblich reduzieren, erfordert jedoch, dass der Empfangsort weiß, wie diese Packs "verdünnt" werden können, indem die fehlenden Basen zum Pack hinzugefügt werden.

Der upload-pack-Server wirbt für thin-pack, wenn er einen Thin-Pack generieren und senden kann. Ein Client fordert die thin-pack-Fähigkeit an, wenn er weiß, wie er sie "verdünnt", und teilt dem Server mit, dass er ein solches Pack empfangen kann. Ein Client DARF die thin-pack-Fähigkeit nicht anfordern, wenn er einen Thin-Pack nicht in einen in sich geschlossenen Pack umwandeln kann.

Receive-pack hingegen wird standardmäßig so behandelt, dass es Thin-Packs verarbeiten kann, kann aber den Client auffordern, die Funktion nicht zu verwenden, indem es die Fähigkeit no-thin bewirbt. Ein Client DARF kein Thin-Pack senden, wenn der Server die Fähigkeit no-thin bewirbt.

Die Gründe für diese Asymmetrie sind historisch bedingt. Das Programm receive-pack existierte erst nach der Erfindung von Thin-Packs, daher verstand die Referenzimplementierung von receive-pack historisch immer Thin-Packs. Das spätere Hinzufügen von no-thin ermöglichte es receive-pack, die Funktion abwärtskompatibel zu deaktivieren.

Diese Fähigkeit bedeutet, dass der Server Fortschrittsberichte und Fehlerinformationen, die mit dem Packfile selbst verschachtelt sind, senden und der Client sie verstehen kann.

Diese beiden Optionen schließen sich gegenseitig aus. Ein moderner Client bevorzugt immer side-band-64k.

Jeder Modus zeigt an, dass die Packfile-Daten in Pakete von bis zu entweder 1000 Bytes im Fall von side_band oder 65520 Bytes im Fall von side_band_64k gestreamt werden. Jedes Paket besteht aus einer führenden 4-Byte-Pkt-Zeilenlänge, die angibt, wie viele Daten sich im Paket befinden, gefolgt von einem 1-Byte-Stream-Code und dann den eigentlichen Daten.

Der Stream-Code kann einer der folgenden sein:

Die Fähigkeit "side-band-64k" entstand als Möglichkeit für neuere Clients, die viel größere Pakete verarbeiten können, Pakete anzufordern, die tatsächlich fast voll sind, während die Abwärtskompatibilität für ältere Clients erhalten bleibt.

Außerdem sind bei side-band und seinen bis zu 1000-Byte-Nachrichten tatsächlich 999 Bytes Nutzdaten und 1 Byte für den Stream-Code. Bei side-band-64k dasselbe: Sie haben bis zu 65519 Bytes an Daten und 1 Byte für den Stream-Code.

Der Client MUSS nur eines von "side-band" und "side-band-64k" senden. Der Server MUSS einen Fehler diagnostizieren, wenn der Client beide anfordert.

Der Server kann PACKv2 mit Deltas senden und der Client kann diese verstehen, wobei die Delta-Referenz auf ihre Basis nach Position im Pack anstatt nach obj-id erfolgt. Das heißt, sie können OBJ_OFS_DELTA (auch Typ 6 genannt) in einer Packfile senden/lesen.

Der Server kann optional eine Fähigkeit der Form agent=X senden, um dem Client mitzuteilen, dass der Server Version X ausführt. Der Client kann optional seinen eigenen Agent-String zurückgeben, indem er mit einer Fähigkeit agent=Y antwortet (er darf dies jedoch NICHT tun, wenn der Server die Agent-Fähigkeit nicht erwähnt hat). Die Strings X und Y können beliebige druckbare ASCII-Zeichen außer Leerzeichen enthalten (d.h. der Bytebereich 32 < x < 127) und sind typischerweise im Format "Paket/Version" (z.B. "git/1.8.3.1"). Die Agent-Strings dienen ausschließlich informativen Zwecken für Statistiken und zur Fehlerbehebung und dürfen NICHT verwendet werden, um programmatisch die An- oder Abwesenheit bestimmter Funktionen anzunehmen.

Diese Fähigkeit, die einen Hash-Algorithmus als Argument nimmt, zeigt an, dass der Server die gegebenen Hash-Algorithmen unterstützt. Sie kann mehrmals gesendet werden; in diesem Fall ist die erste angegebene diejenige, die in der Referenzanzeige verwendet wird.

Wenn sie vom Client bereitgestellt wird, zeigt sie an, dass er beabsichtigt, den gegebenen Hash-Algorithmus zur Kommunikation zu verwenden. Der angegebene Algorithmus muss einer sein, den der Server unterstützt.

Wenn diese Fähigkeit nicht bereitgestellt wird, wird angenommen, dass der einzige unterstützte Algorithmus SHA-1 ist.

Diese parametrisierte Fähigkeit wird verwendet, um dem Empfänger mitzuteilen, welche symbolische Referenz auf welche Referenz zeigt; z.B. "symref=HEAD:refs/heads/master" teilt dem Empfänger mit, dass HEAD auf master zeigt. Diese Fähigkeit kann wiederholt werden, um mehrere symbolische Referenzen darzustellen.

Server SOLLTEN diese Fähigkeit für die HEAD-Referenz einschließen, wenn es sich um eine der gesendeten Referenzen handelt.

Clients KÖNNEN die Parameter aus dieser Fähigkeit verwenden, um den richtigen anfänglichen Zweig beim Klonen eines Repositorys auszuwählen.

Diese Fähigkeit fügt die Befehle "deepen", "shallow" und "unshallow" zum fetch-pack/upload-pack-Protokoll hinzu, damit Clients flache Klone anfordern können.

Diese Fähigkeit fügt den Befehl "deepen-since" zum fetch-pack/upload-pack-Protokoll hinzu, damit der Client flache Klone anfordern kann, die zu einer bestimmten Zeit geschnitten sind, anstatt nach Tiefe. Intern ist es äquivalent zu "rev-list --max-age=<Zeitstempel>" auf der Serverseite. "deepen-since" kann nicht mit "deepen" verwendet werden.

Diese Fähigkeit fügt den Befehl "deepen-not" zum fetch-pack/upload-pack-Protokoll hinzu, damit der Client flache Klone anfordern kann, die an einer bestimmten Revision geschnitten sind, anstatt nach Tiefe. Intern ist es äquivalent zu "rev-list --not <rev>" auf der Serverseite. "deepen-not" kann nicht mit "deepen" verwendet werden, kann aber mit "deepen-since" verwendet werden.

Wenn diese Fähigkeit vom Client angefordert wird, ändern sich die Semantiken des "deepen"-Befehls. Das Argument "depth" ist die Tiefe von der aktuellen flachen Grenze anstatt der Tiefe von den entfernten Referenzen.

Der Client wurde mit "git clone -q" oder ähnlichem gestartet und möchte nicht den Sideband 2. Im Grunde sagt der Client einfach: "Ich möchte keinen Stream 2 über Sideband empfangen, also sende ihn mir nicht, und wenn du ihn sendest, werde ich ihn sowieso verwerfen". Der Sideband-Kanal 3 wird jedoch weiterhin für Fehlermeldungen verwendet.

Die Fähigkeit include-tag bezieht sich auf das Senden von annotierten Tags, wenn wir die Objekte senden, auf die sie verweisen. Wenn wir ein Objekt an den Client packen und ein Tag-Objekt genau auf dieses Objekt verweist, packen wir auch das Tag-Objekt. Im Allgemeinen ermöglicht dies einem Client, alle neuen annotierten Tags beim Abrufen eines Zweigs in einer einzigen Netzwerkverbindung zu erhalten.

Clients KÖNNEN immer include-tag senden und es fest in eine Anfrage kodieren, wenn der Server diese Fähigkeit bewirbt. Die Entscheidung eines Clients, include-tag anzufordern, hängt nur von den Wünschen des Clients nach Tag-Daten ab, unabhängig davon, ob ein Server Objekte im Namespace refs/tags/* beworben hat.

Server MÜSSEN die Tags packen, wenn ihr Referent gepackt ist und der Client include-tags angefordert hat.

Clients MÜSSEN auf den Fall vorbereitet sein, dass ein Server include-tag ignoriert hat und keine Tags im Pack gesendet hat. In solchen Fällen SOLLTE der Client einen nachfolgenden Abruf ausgeben, um die Tags zu erwerben, die include-tag dem Client ansonsten gegeben hätte.

Der Server SOLLTE include-tag senden, wenn er es unterstützt, unabhängig davon, ob Tags verfügbar sind oder nicht.

Der receive-pack-Prozess kann die Fähigkeit report-status empfangen, die ihm mitteilt, dass der Client einen Bericht darüber wünscht, was nach dem Hochladen eines Packfiles und der Aktualisierung von Referenzen passiert ist. Wenn der push-ende Client diese Fähigkeit anfordert, antwortet der Server nach dem Entpacken und Aktualisieren der Referenzen damit, ob das Packfile erfolgreich entpackt wurde und ob jede Referenz erfolgreich aktualisiert wurde. Wenn einer dieser Vorgänge nicht erfolgreich war, sendet er eine Fehlermeldung zurück. Siehe gitprotocol-pack[5] für Beispielnachrichten.

Die Fähigkeit report-status-v2 erweitert die Fähigkeit report-status um neue "option"-Direktiven, um Referenzen zu unterstützen, die vom "proc-receive"-Hook umgeschrieben wurden. Der "proc-receive"-Hook kann einen Befehl für eine Pseudo-Referenz verarbeiten, der eine Referenz mit einem anderen Namen, einer neuen OID und einer alten OID erstellen oder aktualisieren kann. Während die Fähigkeit report-status diesen Fall nicht melden kann. Siehe gitprotocol-pack[5] für Details.

Wenn der Server die Fähigkeit delete-refs zurücksendet, bedeutet dies, dass er in der Lage ist, einen Null-ID-Wert als Zielwert einer Referenzaktualisierung zu akzeptieren. Sie wird nicht vom Client gesendet, sondern informiert den Client lediglich, dass ihm Null-ID-Werte zum Löschen von Referenzen gesendet werden können.

Wenn der receive-pack-Server die Fähigkeit quiet bewirbt, ist er in der Lage, menschenlesbare Fortschrittsausgaben zu unterdrücken, die andernfalls bei der Verarbeitung des empfangenen Packs angezeigt werden könnten. Ein send-pack-Client sollte mit der Fähigkeit quiet antworten, um die serverseitige Fortschrittsmeldung zu unterdrücken, wenn die lokale Fortschrittsmeldung ebenfalls unterdrückt wird (z.B. über push -q oder wenn stderr nicht an ein TTY geht).

Wenn der Server die Fähigkeit atomic sendet, ist er in der Lage, atomare Pushes zu akzeptieren. Wenn der push-ende Client diese Fähigkeit anfordert, aktualisiert der Server die Referenzen in einer einzigen atomaren Transaktion. Entweder werden alle Referenzen aktualisiert oder keine.

Wenn der Server die Fähigkeit push-options sendet, ist er in der Lage, Push-Optionen nach dem Senden der Update-Befehle, aber vor dem Streamen des Packfiles zu akzeptieren. Wenn der push-ende Client diese Fähigkeit anfordert, gibt der Server die Optionen an die Pre- und Post-Receive-Hooks weiter, die diese Push-Anfrage verarbeiten.

Wenn der upload-pack-Server diese Fähigkeit bewirbt, kann fetch-pack "want"-Zeilen mit Objektnamen senden, die auf dem Server existieren, aber nicht von upload-pack beworben werden. Aus historischen Gründen enthält der Name dieser Fähigkeit "sha1". Objektnamen werden immer unter Verwendung des über die Fähigkeit object-format ausgehandelten Objektformats angegeben.

Wenn der upload-pack-Server diese Fähigkeit bewirbt, kann fetch-pack "want"-Zeilen mit Objektnamen senden, die auf dem Server existieren, aber nicht von upload-pack beworben werden. Aus historischen Gründen enthält der Name dieser Fähigkeit "sha1". Objektnamen werden immer unter Verwendung des über die Fähigkeit object-format ausgehandelten Objektformats angegeben.

Der receive-pack-Server, der diese Fähigkeit bewirbt, ist bereit, ein signiertes Push-Zertifikat zu akzeptieren und bittet darum, dass die <nonce> in das Push-Zertifikat aufgenommen wird. Ein send-pack-Client DARF kein Push-Cert-Paket senden, es sei denn, der receive-pack-Server bewirbt diese Fähigkeit.

Wenn der upload-pack-Server die Fähigkeit filter bewirbt, kann fetch-pack "filter"-Befehle senden, um einen teilweisen Klon oder einen teilweisen Abruf anzufordern und zu verlangen, dass der Server verschiedene Objekte aus dem Packfile weglässt.

Der Server kann eine Sitzungs-ID bewerben, die verwendet werden kann, um diesen Prozess über mehrere Anfragen hinweg zu identifizieren. Der Client kann auch seine eigene Sitzungs-ID an den Server zurückgeben.

Sitzungs-IDs sollten eindeutig für einen bestimmten Prozess sein. Sie müssen in eine Paketzeile passen und dürfen keine nicht druckbaren Zeichen oder Leerzeichen enthalten. Die aktuelle Implementierung verwendet trace2-Sitzungs-IDs (siehe api-trace2 für Details), dies kann sich jedoch ändern, und Benutzer der Sitzungs-ID sollten sich nicht darauf verlassen.

Teil der git[1] Suite