English ▾ Themen ▾ Neueste Version ▾ gitprotocol-http zuletzt aktualisiert in 2.52.0

NAME

gitprotocol-http - Git HTTP-basierte Protokolle

SYNOPSIS

<over-the-wire-protocol>

BESCHREIBUNG

Git unterstützt zwei HTTP-basierte Übertragungsprotokolle. Ein "dummes" Protokoll, das nur einen Standard-HTTP-Server am Serverende der Verbindung erfordert, und ein "smartes" Protokoll, das eine Git-fähige CGI (oder ein Servermodul) erfordert. Dieses Dokument beschreibt beide Protokolle.

Als Designmerkmal können Smart-Clients "dumme" Protokoll-URLs automatisch auf Smart-URLs aktualisieren. Dies ermöglicht es allen Benutzern, dieselbe veröffentlichte URL zu haben, und die Peers wählen automatisch den effizientesten Transport, der ihnen zur Verfügung steht.

URL-Format

URLs für Git-Repositories, auf die über HTTP zugegriffen wird, verwenden die Standard-HTTP-URL-Syntax, die von RFC 1738 dokumentiert ist, sodass sie die Form haben

http://<host>:<port>/<path>?<searchpart>

Innerhalb dieser Dokumentation steht der Platzhalter $GIT_URL für die vom Endbenutzer eingegebene http://-Repository-URL.

Server SOLLTEN alle Anfragen an Standorte bearbeiten, die $GIT_URL entsprechen, da sowohl die "smarten" als auch die "dummen" HTTP-Protokolle, die von Git verwendet werden, durch Anhängen zusätzlicher Pfadkomponenten am Ende des vom Benutzer bereitgestellten $GIT_URL-Strings funktionieren.

Ein Beispiel für einen dummen Client, der ein loses Objekt anfordert

$GIT_URL:     http://example.com:8080/git/repo.git
URL request:  http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355

Ein Beispiel für eine smarte Anfrage an ein Catch-All-Gateway

$GIT_URL:     http://example.com/daemon.cgi?svc=git&q=
URL request:  http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack

Ein Beispiel für eine Anfrage an ein Submodul

$GIT_URL:     http://example.com/git/repo.git/path/submodule.git
URL request:  http://example.com/git/repo.git/path/submodule.git/info/refs

Clients MÜSSEN ein nachgestelltes /, falls vorhanden, vom vom Benutzer bereitgestellten $GIT_URL-String entfernen, um zu verhindern, dass leere Pfad-Tokens (//) in einer an den Server gesendeten URL erscheinen. Kompatible Clients MÜSSEN $GIT_URL/info/refs als foo/info/refs und nicht als foo//info/refs erweitern.

Authentifizierung

Standard-HTTP-Authentifizierung wird verwendet, wenn zur Zugriff auf ein Repository eine Authentifizierung erforderlich ist, und KANN von der HTTP-Server-Software konfiguriert und erzwungen werden.

Da auf Git-Repositories über Standard-Pfadkomponenten zugegriffen wird, KÖNNEN Serveradministratoren verzeichnisbasierte Berechtigungen innerhalb ihres HTTP-Servers verwenden, um den Repository-Zugriff zu steuern.

Clients SOLLTEN die Basisauthentifizierung gemäß RFC 2617 unterstützen. Server SOLLTEN die Basisauthentifizierung unterstützen, indem sie sich auf den HTTP-Server verlassen, der vor der Git-Server-Software platziert ist.

Server SOLLTEN keine HTTP-Cookies zu Authentifizierungs- oder Zugriffskontrollzwecken erfordern.

Clients und Server KÖNNEN andere gängige Formen der HTTP-basierten Authentifizierung unterstützen, wie z. B. Digest-Authentifizierung.

SSL

Clients und Server SOLLTEN SSL unterstützen, insbesondere zum Schutz von Passwörtern bei der Nutzung der Basis-HTTP-Authentifizierung.

Sitzungsstatus

Das Git-über-HTTP-Protokoll (ähnlich wie HTTP selbst) ist aus Sicht der HTTP-Serverseite zustandslos. Der gesamte Status MUSS vom Clientprozess beibehalten und verwaltet werden. Dies ermöglicht eine einfache Round-Robin-Lastverteilung auf der Serverseite, ohne sich um die Statusverwaltung kümmern zu müssen.

Clients DÜRFEN keine Statusverwaltung auf der Serverseite benötigen, um korrekt zu funktionieren.

Server DÜRFEN keine HTTP-Cookies benötigen, um korrekt zu funktionieren. Clients KÖNNEN HTTP-Cookies während der Anforderungsverarbeitung gemäß RFC 2616 (HTTP/1.1) speichern und weiterleiten. Server SOLLTEN alle von einem Client gesendeten Cookies ignorieren.

Allgemeine Anforderungsverarbeitung

Sofern nicht anders angegeben, SOLLTE von Client und Server jedes Standard-HTTP-Verhalten angenommen werden. Dies beinhaltet (ist aber nicht unbedingt darauf beschränkt)

Wenn kein Repository unter $GIT_URL vorhanden ist oder die Ressource, auf die sich ein Speicherort mit $GIT_URL bezieht, nicht existiert, darf der Server NICHT mit einer 200 OK-Antwort antworten. Ein Server SOLLTE mit 404 Not Found, 410 Gone oder einem anderen geeigneten HTTP-Statuscode antworten, der nicht impliziert, dass die Ressource wie angefordert existiert.

Wenn ein Repository unter $GIT_URL vorhanden ist, aber der Zugriff derzeit nicht gestattet ist, MUSS der Server mit dem HTTP-Statuscode 403 Forbidden antworten.

Server SOLLTEN sowohl HTTP 1.0 als auch HTTP 1.1 unterstützen. Server SOLLTEN Chunked Encoding sowohl für Anfrage- als auch für Antwortkörper unterstützen.

Clients SOLLTEN sowohl HTTP 1.0 als auch HTTP 1.1 unterstützen. Clients SOLLTEN Chunked Encoding sowohl für Anfrage- als auch für Antwortkörper unterstützen.

Server KÖNNEN ETag- und/oder Last-Modified-Header zurückgeben.

Clients KÖNNEN gecachte Entitäten neu validieren, indem sie If-Modified-Since und/oder If-None-Match-Anfrage-Header einfügen.

Server KÖNNEN 304 Not Modified zurückgeben, wenn die entsprechenden Header in der Anfrage erscheinen und die Entität nicht geändert wurde. Clients MÜSSEN 304 Not Modified identisch mit 200 OK behandeln, indem sie die gecachte Entität wiederverwenden.

Clients KÖNNEN eine gecachte Entität ohne erneute Validierung wiederverwenden, wenn die Cache-Control- und/oder Expires-Header das Caching erlauben. Clients und Server MÜSSEN RFC 2616 für Caching-Kontrollen befolgen.

Referenzen entdecken

Alle HTTP-Clients MÜSSEN entweder einen Fetch- oder einen Push-Austausch durch die Entdeckung der verfügbaren Referenzen im Remote-Repository beginnen.

Dumme Clients

HTTP-Clients, die nur das "dumme" Protokoll unterstützen, MÜSSEN Referenzen entdecken, indem sie eine Anfrage an die spezielle Datei info/refs des Repositories stellen.

Dumme HTTP-Clients MÜSSEN eine GET-Anfrage an $GIT_URL/info/refs stellen, ohne Such-/Query-Parameter.

C: GET $GIT_URL/info/refs HTTP/1.0
S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31	refs/heads/maint
S: d049f6c27a2244e12041955e262a404c7faba355	refs/heads/master
S: 2cb58b79488a98d2721cea644875a8dd0026b115	refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c	refs/tags/v1.0^{}

Der Content-Type der zurückgegebenen info/refs-Entität SOLLTE text/plain; charset=utf-8 sein, KANN aber jeder Content-Type sein. Clients DÜRFEN den zurückgegebenen Content-Type nicht validieren. Dumme Server DÜRFEN keinen Rückgabetyp zurückgeben, der mit application/x-git- beginnt.

Cache-Control-Header KÖNNEN zurückgegeben werden, um das Caching der zurückgegebenen Entität zu deaktivieren.

Bei der Prüfung der Antwort SOLLTEN Clients nur den HTTP-Statuscode prüfen. Gültige Antworten sind 200 OK oder 304 Not Modified.

Der zurückgegebene Inhalt ist eine UNIX-formatierte Textdatei, die jeden Ref und seinen bekannten Wert beschreibt. Die Datei SOLLTE nach Namen sortiert sein, gemäß der C-Locale-Sortierung. Die Datei SOLLTE NICHT den Standard-Ref namens HEAD enthalten.

info_refs   =  *( ref_record )
ref_record  =  any_ref / peeled_ref
any_ref     =  obj-id HTAB refname LF
peeled_ref  =  obj-id HTAB refname LF
 obj-id HTAB refname "^{}" LF

Smarte Clients

HTTP-Clients, die das "smarte" Protokoll unterstützen (oder sowohl das "smarte" als auch das "dumme" Protokoll), MÜSSEN Referenzen entdecken, indem sie eine parametrisierte Anfrage an die info/refs-Datei des Repositories stellen.

Die Anfrage MUSS genau einen Query-Parameter enthalten: service=$servicename, wobei $servicename der Dienstname sein MUSS, mit dem der Client die Operation abschließen möchte. Die Anfrage darf KEINE zusätzlichen Query-Parameter enthalten.

C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0

Antwort eines dummen Servers

S: 200 OK
S:
S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31	refs/heads/maint
S: d049f6c27a2244e12041955e262a404c7faba355	refs/heads/master
S: 2cb58b79488a98d2721cea644875a8dd0026b115	refs/tags/v1.0
S: a3c2e2402b99163d1d59756e5f207ae21cccba4c	refs/tags/v1.0^{}

Antwort eines smarten Servers

S: 200 OK
S: Content-Type: application/x-git-upload-pack-advertisement
S: Cache-Control: no-cache
S:
S: 001e# service=git-upload-pack\n
S: 0000
S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
S: 0000

Der Client kann zusätzliche Parameter (siehe gitprotocol-pack[5]) als durch Doppelpunkte getrennten String im Git-Protocol-HTTP-Header senden.

Verwendet die Option --http-backend-info-refs für git-upload-pack[1].

Antwort eines dummen Servers

Dumme Server MÜSSEN mit dem Antwortformat des dummen Servers antworten.

Siehe den vorherigen Abschnitt unter dumme Clients für eine detailliertere Beschreibung der Antwort des dummen Servers.

Antwort eines smarten Servers

Wenn der Server den angeforderten Dienstnamen nicht erkennt oder der angeforderte Dienstname vom Serveradministrator deaktiviert wurde, MUSS der Server mit dem HTTP-Statuscode 403 Forbidden antworten.

Andernfalls MÜSSEN smarte Server mit dem Antwortformat des smarten Servers für den angeforderten Dienstnamen antworten.

Cache-Control-Header SOLLTEN verwendet werden, um das Caching der zurückgegebenen Entität zu deaktivieren.

Der Content-Type MUSS application/x-$servicename-advertisement sein. Clients SOLLTEN zum dummen Protokoll zurückfallen, wenn ein anderer Content-Type zurückgegeben wird. Beim Zurückfallen auf das dumme Protokoll SOLLTEN Clients keine zusätzliche Anfrage an $GIT_URL/info/refs stellen, sondern die bereits vorhandene Antwort verwenden. Clients DÜRFEN nicht fortfahren, wenn sie das dumme Protokoll nicht unterstützen.

Clients MÜSSEN validieren, dass der Statuscode entweder 200 OK oder 304 Not Modified ist.

Clients MÜSSEN validieren, dass die ersten fünf Bytes der Antwortentität dem regulären Ausdruck ^[0-9a-f]{4}# entsprechen. Wenn dieser Test fehlschlägt, dürfen Clients nicht fortfahren.

Clients MÜSSEN die gesamte Antwort als eine Reihe von pkt-line-Datensätzen parsen.

Clients MÜSSEN überprüfen, ob die erste pkt-line # service=$servicename ist. Server MÜSSEN $servicename auf den Wert des Anfrageparameters setzen. Server SOLLTEN am Ende dieser Zeile ein LF einfügen. Clients SOLLTEN ein LF am Ende der Zeile ignorieren.

Server MÜSSEN die Antwort mit dem magischen End-pkt-line-Marker 0000 beenden.

Die zurückgegebene Antwort ist ein pkt-line-Stream, der jeden Ref und seinen bekannten Wert beschreibt. Der Stream SOLLTE nach Namen gemäß der C-Locale-Sortierung sortiert sein. Der Stream SOLLTE den Standard-Ref namens HEAD als ersten Ref enthalten. Der Stream MUSS Fähigkeitsdeklarationen hinter einem NUL auf dem ersten Ref enthalten.

Die zurückgegebene Antwort enthält "version 1", wenn "version=1" als zusätzlicher Parameter gesendet wurde.

smart_reply     =  PKT-LINE("# service=$servicename" LF)
     "0000"
     *1("version 1")
     ref_list
     "0000"
ref_list        =  empty_list / non_empty_list
empty_list      =  PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)
non_empty_list  =  PKT-LINE(obj-id SP name NUL cap_list LF)
     *ref_record
cap-list        =  capability *(SP capability)
capability      =  1*(LC_ALPHA / DIGIT / "-" / "_")
LC_ALPHA        =  %x61-7A
ref_record      =  any_ref / peeled_ref
any_ref         =  PKT-LINE(obj-id SP name LF)
peeled_ref      =  PKT-LINE(obj-id SP name LF)
     PKT-LINE(obj-id SP name "^{}" LF

Smart Service git-upload-pack

Dieser Dienst liest aus dem von $GIT_URL referenzierten Repository.

Clients MÜSSEN zuerst die Referenzentdeckung mit $GIT_URL/info/refs?service=git-upload-pack durchführen.

C: POST $GIT_URL/git-upload-pack HTTP/1.0
C: Content-Type: application/x-git-upload-pack-request
C:
C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n
C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n
C: 0000
S: 200 OK
S: Content-Type: application/x-git-upload-pack-result
S: Cache-Control: no-cache
S:
S: ....ACK %s, continue
S: ....NAK

Clients DÜRFEN eine gecachte Antwort nicht wiederverwenden oder neu validieren. Server MÜSSEN ausreichende Cache-Control-Header enthalten, um das Caching der Antwort zu verhindern.

Server SOLLTEN alle hier definierten Fähigkeiten unterstützen.

Clients MÜSSEN mindestens einen "want"-Befehl im Anfragekörper senden. Clients DÜRFEN keine ID in einem "want"-Befehl referenzieren, die nicht in der Antwort aus der Referenzentdeckung erschienen ist, es sei denn, der Server wirbt die Fähigkeit allow-tip-sha1-in-want oder allow-reachable-sha1-in-want an.

compute_request   =  want_list
       have_list
       request_end
request_end       =  "0000" / "done"
want_list         =  PKT-LINE(want SP cap_list LF)
       *(want_pkt)
want_pkt          =  PKT-LINE(want LF)
want              =  "want" SP id
cap_list          =  capability *(SP capability)
have_list         =  *PKT-LINE("have" SP id LF)

TODO: Weiter dokumentieren.

Der Verhandlungsalgorithmus

Die Berechnung zur Auswahl des minimalen Packs erfolgt wie folgt (C = Client, S = Server)

Initialisierungsschritt

C: Verwende die Referenzentdeckung, um die beworbenen Referenzen zu erhalten.

C: Platziere jedes gesehene Objekt in der Menge advertised.

C: Erstelle eine leere Menge, common, um die Objekte zu speichern, die später als auf beiden Seiten befindlich ermittelt werden.

C: Erstelle eine Menge, want, der Objekte aus advertised, die der Client abrufen möchte, basierend auf dem, was er während der Referenzentdeckung gesehen hat.

C: Starte eine Warteschlange, c_pending, sortiert nach Commit-Zeit (neueste zuerst herausnehmen). Füge alle Client-Referenzen hinzu. Wenn ein Commit aus der Warteschlange genommen wird, SOLLTEN seine Eltern automatisch wieder eingefügt werden. Commits MÜSSEN die Warteschlange nur einmal betreten.

Ein Berechnungsschritt

C: Sende eine $GIT_URL/git-upload-pack-Anfrage

C: 0032want <want-#1>...............................
C: 0032want <want-#2>...............................
....
C: 0032have <common-#1>.............................
C: 0032have <common-#2>.............................
....
C: 0032have <have-#1>...............................
C: 0032have <have-#2>...............................
....
C: 0000

Der Stream ist in "Befehle" unterteilt, wobei jeder Befehl allein in einer pkt-line erscheint. Innerhalb einer Befehlszeile ist der Text vor dem ersten Leerzeichen der Befehlsname und der Rest der Zeile bis zum ersten LF ist der Wert. Befehlszeilen werden mit einem LF als letztes Byte des pkt-line-Werts beendet.

Befehle MÜSSEN in der folgenden Reihenfolge erscheinen, falls sie überhaupt im Anfrage-Stream vorkommen

  • "want"

  • "have"

Der Stream wird durch einen pkt-line-Flush (0000) beendet.

Ein einzelner "want"- oder "have"-Befehl MUSS einen hexadezimal formatierten Objekt-Namen als Wert haben. Mehrere Objektnamen MÜSSEN durch Senden mehrerer Befehle gesendet werden. Objektnamen MÜSSEN unter Verwendung des Objektformats über die object-format-Fähigkeit (standardmäßig SHA-1) verhandelt werden.

Die have-Liste wird erstellt, indem die ersten 32 Commits aus c_pending entnommen werden. Weniger können geliefert werden, wenn c_pending leer wird.

Wenn der Client 256 "have"-Commits gesendet hat und noch keinen davon von s_common zurückerhalten hat, oder der Client c_pending geleert hat, SOLLTE er einen "done"-Befehl einfügen, um dem Server mitzuteilen, dass er nicht fortfahren wird.

C: 0009done

S: Verarbeitet die git-upload-pack-Anfrage

Überprüft, ob alle Objekte in want direkt von Referenzen erreichbar sind.

Der Server KANN rückwärts durch die Historie oder das Reflog gehen, um leicht veraltete Anfragen zuzulassen.

Wenn keine "want"-Objekte empfangen werden, Sende einen Fehler: TODO: Fehler definieren, wenn keine "want"-Zeilen angefordert werden.

Wenn ein "want"-Objekt nicht erreichbar ist, Sende einen Fehler: TODO: Fehler definieren, wenn ein ungültiges "want" angefordert wird.

Erstellt eine leere Liste, s_common.

Wenn "have" gesendet wurde

Durchläuft die Objekte in der vom Client bereitgestellten Reihenfolge.

Wenn der Server das Objekt von einer Referenz aus erreichen kann, füge es zu s_common hinzu. Wenn ein Commit zu s_common hinzugefügt wird, füge keine Vorfahren hinzu, auch wenn sie ebenfalls in have vorkommen.

S: Sendet die git-upload-pack-Antwort

Wenn der Server einen geschlossenen Objektsatz zum Packen gefunden hat oder die Anfrage mit "done" endet, antwortet er mit dem Pack. TODO: Die pack-basierte Antwort dokumentieren

S: PACK...

Der zurückgegebene Stream ist das Side-Band-64k-Protokoll, das vom git-upload-pack-Dienst unterstützt wird, und das Pack ist in Stream 1 eingebettet. Fortschrittsnachrichten von der Serverseite KÖNNEN in Stream 2 erscheinen.

Hier ist ein "geschlossener Objektsatz" definiert als mindestens ein Pfad von jedem "want" zu mindestens einem "common" Objekt.

Wenn der Server weitere Informationen benötigt, antwortet er mit einer Status-Continue-Antwort: TODO: Die Nicht-Pack-Antwort dokumentieren

C: Verarbeitet die upload-pack-Antwort: TODO: Verarbeiten der Antwort dokumentieren

Führt einen weiteren Berechnungsschritt durch.

Smart Service git-receive-pack

Dieser Dienst liest aus dem von $GIT_URL referenzierten Repository.

Clients MÜSSEN zuerst die Referenzentdeckung mit $GIT_URL/info/refs?service=git-receive-pack durchführen.

C: POST $GIT_URL/git-receive-pack HTTP/1.0
C: Content-Type: application/x-git-receive-pack-request
C:
C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
C: 0000
C: PACK....
S: 200 OK
S: Content-Type: application/x-git-receive-pack-result
S: Cache-Control: no-cache
S:
S: ....

Clients DÜRFEN eine gecachte Antwort nicht wiederverwenden oder neu validieren. Server MÜSSEN ausreichende Cache-Control-Header enthalten, um das Caching der Antwort zu verhindern.

Server SOLLTEN alle hier definierten Fähigkeiten unterstützen.

Clients MÜSSEN mindestens einen Befehl im Anfragekörper senden. Innerhalb des Befehls-Teils des Anfragekörpers SOLLTEN Clients die über die Referenzentdeckung erhaltene ID als old_id senden.

update_request  =  command_list
     "PACK" <binary-data>
command_list    =  PKT-LINE(command NUL cap_list LF)
     *(command_pkt)
command_pkt     =  PKT-LINE(command LF)
cap_list        =  *(SP capability) SP
command         =  create / delete / update
create          =  zero-id SP new_id SP name
delete          =  old_id SP zero-id SP name
update          =  old_id SP new_id SP name

TODO: Weiter dokumentieren.

REFERENZEN

RFC 1738: Uniform Resource Locators (URL) RFC 2616: Hypertext Transfer Protocol — HTTP/1.1

SIEHE AUCH

gitprotocol-pack[5] gitprotocol-capabilities[5]

GIT

Teil der git[1] Suite