{ "mode": "man", "parameter": "gitprotocol-pack", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/gitprotocol-pack/5/json", "generated": "2026-11-08T13:32:45Z", "synopsis": "", "sections": { "NAME": { "content": "gitprotocol-pack - How packs are transferred over-the-wire\n", "subsections": [] }, "SYNOPSIS": { "content": "\n\n", "subsections": [] }, "DESCRIPTION": { "content": "Git supports transferring data in packfiles over the ssh://, git://, http:// and file://\ntransports. There exist two sets of protocols, one for pushing data from a client to a server\nand another for fetching data from a server to a client. The three transports (ssh, git,\nfile) use the same protocol to transfer data. http is documented in gitprotocol-http(5).\n\nThe processes invoked in the canonical Git implementation are upload-pack on the server side\nand fetch-pack on the client side for fetching data; then receive-pack on the server and\nsend-pack on the client for pushing data. The protocol functions to have a server tell a\nclient what is currently on the server, then for the two to negotiate the smallest amount of\ndata to send in order to fully update one or the other.\n", "subsections": [] }, "PKT-LINE FORMAT": { "content": "The descriptions below build on the pkt-line format described in gitprotocol-common(5). When\nthe grammar indicates PKT-LINE(...), unless otherwise noted the usual pkt-line LF rules\napply: the sender SHOULD include a LF, but the receiver MUST NOT complain if it is not\npresent.\n\nAn error packet is a special pkt-line that contains an error string.\n\nerror-line = PKT-LINE(\"ERR\" SP explanation-text)\n\n\nThroughout the protocol, where PKT-LINE(...) is expected, an error packet MAY be sent. Once\nthis packet is sent by a client or a server, the data transfer process defined in this\nprotocol is terminated.\n", "subsections": [] }, "TRANSPORTS": { "content": "There are three transports over which the packfile protocol is initiated. The Git transport\nis a simple, unauthenticated server that takes the command (almost always upload-pack, though\nGit servers can be configured to be globally writable, in which receive- pack initiation is\nalso allowed) with which the client wishes to communicate and executes it and connects it to\nthe requesting process.\n\nIn the SSH transport, the client just runs the upload-pack or receive-pack process on the\nserver over the SSH protocol and then communicates with that invoked process over the SSH\nconnection.\n\nThe file:// transport runs the upload-pack or receive-pack process locally and communicates\nwith it over a pipe.\n", "subsections": [] }, "EXTRA PARAMETERS": { "content": "The protocol provides a mechanism in which clients can send additional information in its\nfirst message to the server. These are called \"Extra Parameters\", and are supported by the\nGit, SSH, and HTTP protocols.\n\nEach Extra Parameter takes the form of = or .\n\nServers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently,\nthe only Extra Parameter recognized is \"version\" with a value of 1 or 2. See gitprotocol-\nv2(5) for more information on protocol version 2.\n", "subsections": [] }, "GIT TRANSPORT": { "content": "The Git transport starts off by sending the command and repository on the wire using the\npkt-line format, followed by a NUL byte and a hostname parameter, terminated by a NUL byte.\n\n0033git-upload-pack /project.git\\0host=myserver.com\\0\n\nThe transport may send Extra Parameters by adding an additional NUL byte, and then adding one\nor more NUL-terminated strings:\n\n003egit-upload-pack /project.git\\0host=myserver.com\\0\\0version=1\\0\n\ngit-proto-request = request-command SP pathname NUL\n[ host-parameter NUL ] [ NUL extra-parameters ]\nrequest-command = \"git-upload-pack\" / \"git-receive-pack\" /\n\"git-upload-archive\" ; case sensitive\npathname = *( %x01-ff ) ; exclude NUL\nhost-parameter = \"host=\" hostname [ \":\" port ]\nextra-parameters = 1*extra-parameter\nextra-parameter = 1*( %x01-ff ) NUL\n\nhost-parameter is used for the git-daemon name based virtual hosting. See --interpolated-path\noption to git daemon, with the %H/%CH format characters.\n\nBasically what the Git client is doing to connect to an upload-pack process on the server\nside over the Git protocol is this:\n\n$ echo -e -n \\\n\"003agit-upload-pack /schacon/gitbook.git\\0host=example.com\\0\" |\nnc -v example.com 9418\n", "subsections": [] }, "SSH TRANSPORT": { "content": "Initiating the upload-pack or receive-pack processes over SSH is executing the binary on the\nserver via SSH remote execution. It is basically equivalent to running this:\n\n$ ssh git.example.com \"git-upload-pack '/project.git'\"\n\nFor a server to support Git pushing and pulling for a given user over SSH, that user needs to\nbe able to execute one or both of those commands via the SSH shell that they are provided on\nlogin. On some systems, that shell access is limited to only being able to run those two\ncommands, or even just one of them.\n\nIn an ssh:// format URI, it’s absolute in the URI, so the / after the host name (or port\nnumber) is sent as an argument, which is then read by the remote git-upload-pack exactly as\nis, so it’s effectively an absolute path in the remote filesystem.\n\ngit clone ssh://user@example.com/project.git\n|\nv\nssh user@example.com \"git-upload-pack '/project.git'\"\n\nIn a \"user@host:path\" format URI, it’s relative to the user’s home directory, because the Git\nclient will run:\n\ngit clone user@example.com:project.git\n|\nv\nssh user@example.com \"git-upload-pack 'project.git'\"\n\nThe exception is if a ~ is used, in which case we execute it without the leading /.\n\nssh://user@example.com/~alice/project.git,\n|\nv\nssh user@example.com \"git-upload-pack '~alice/project.git'\"\n\nDepending on the value of the protocol.version configuration variable, Git may attempt to\nsend Extra Parameters as a colon-separated string in the GITPROTOCOL environment variable.\nThis is done only if the ssh.variant configuration variable indicates that the ssh command\nsupports passing environment variables as an argument.\n\nA few things to remember here:\n\n• The \"command name\" is spelled with dash (e.g. git-upload-pack), but this can be\noverridden by the client;\n\n• The repository path is always quoted with single quotes.\n", "subsections": [] }, "FETCHING DATA FROM A SERVER": { "content": "When one Git repository wants to get data that a second repository has, the first can fetch\nfrom the second. This operation determines what data the server has that the client does not\nthen streams that data down to the client in packfile format.\n", "subsections": [] }, "REFERENCE DISCOVERY": { "content": "The reference discovery phase is done nearly the same way as it is in the fetching protocol.\nEach reference obj-id and name on the server is sent in packet-line format to the client,\nfollowed by a flush-pkt. The only real difference is that the capability listing is different\n- the only possible values are report-status, report-status-v2, delete-refs, ofs-delta,\natomic and push-options.\n", "subsections": [] }, "PACKFILE NEGOTIATION": { "content": "After reference and capabilities discovery, the client can decide to terminate the connection\nby sending a flush-pkt, telling the server it can now gracefully terminate, and disconnect,\nwhen it does not need any pack data. This can happen with the ls-remote command, and also can\nhappen when the client already is up to date.\n\nOtherwise, it enters the negotiation phase, where the client and server determine what the\nminimal packfile necessary for transport is, by telling the server what objects it wants, its\nshallow objects (if any), and the maximum commit depth it wants (if any). The client will\nalso send a list of the capabilities it wants to be in effect, out of what the server said it\ncould do with the first want line.\n\nupload-request = want-list\n*shallow-line\n*1depth-request\n[filter-request]\nflush-pkt\n\nwant-list = first-want\n*additional-want\n\nshallow-line = PKT-LINE(\"shallow\" SP obj-id)\n\ndepth-request = PKT-LINE(\"deepen\" SP depth) /\nPKT-LINE(\"deepen-since\" SP timestamp) /\nPKT-LINE(\"deepen-not\" SP ref)\n\nfirst-want = PKT-LINE(\"want\" SP obj-id SP capability-list)\nadditional-want = PKT-LINE(\"want\" SP obj-id)\n\ndepth = 1*DIGIT\n\nfilter-request = PKT-LINE(\"filter\" SP filter-spec)\n\n\nClients MUST send all the obj-ids it wants from the reference discovery phase as want lines.\nClients MUST send at least one want command in the request body. Clients MUST NOT mention an\nobj-id in a want command which did not appear in the response obtained through ref discovery.\n\nThe client MUST write all obj-ids which it only has shallow copies of (meaning that it does\nnot have the parents of a commit) as shallow lines so that the server is aware of the\nlimitations of the client’s history.\n\nThe client now sends the maximum commit history depth it wants for this transaction, which is\nthe number of commits it wants from the tip of the history, if any, as a deepen line. A depth\nof 0 is the same as not making a depth request. The client does not want to receive any\ncommits beyond this depth, nor does it want objects needed only to complete those commits.\nCommits whose parents are not received as a result are defined as shallow and marked as such\nin the server. This information is sent back to the client in the next step.\n\nThe client can optionally request that pack-objects omit various objects from the packfile\nusing one of several filtering techniques. These are intended for use with partial clone and\npartial fetch operations. An object that does not meet a filter-spec value is omitted unless\nexplicitly requested in a want line. See rev-list for possible filter-spec values.\n\nOnce all the want’s and 'shallow’s (and optional 'deepen) are transferred, clients MUST send\na flush-pkt, to tell the server side that it is done sending the list.\n\nOtherwise, if the client sent a positive depth request, the server will determine which\ncommits will and will not be shallow and send this information to the client. If the client\ndid not request a positive depth, this step is skipped.\n\nshallow-update = *shallow-line\n*unshallow-line\nflush-pkt\n\nshallow-line = PKT-LINE(\"shallow\" SP obj-id)\n\nunshallow-line = PKT-LINE(\"unshallow\" SP obj-id)\n\n\nIf the client has requested a positive depth, the server will compute the set of commits\nwhich are no deeper than the desired depth. The set of commits starts at the client’s wants.\n\nThe server writes shallow lines for each commit whose parents will not be sent as a result.\nThe server writes an unshallow line for each commit which the client has indicated is\nshallow, but is no longer shallow at the currently requested depth (that is, its parents will\nnow be sent). The server MUST NOT mark as unshallow anything which the client has not\nindicated was shallow.\n\nNow the client will send a list of the obj-ids it has using have lines, so the server can\nmake a packfile that only contains the objects that the client needs. In multiack mode, the\ncanonical implementation will send up to 32 of these at a time, then will send a flush-pkt.\nThe canonical implementation will skip ahead and send the next 32 immediately, so that there\nis always a block of 32 \"in-flight on the wire\" at a time.\n\nupload-haves = have-list\ncompute-end\n\nhave-list = *have-line\nhave-line = PKT-LINE(\"have\" SP obj-id)\ncompute-end = flush-pkt / PKT-LINE(\"done\")\n\n\nIf the server reads have lines, it then will respond by ACKing any of the obj-ids the client\nsaid it had that the server also has. The server will ACK obj-ids differently depending on\nwhich ack mode is chosen by the client.\n\nIn multiack mode:\n\n• the server will respond with ACK obj-id continue for any common commits.\n\n• once the server has found an acceptable common base commit and is ready to make a\npackfile, it will blindly ACK all have obj-ids back to the client.\n\n• the server will then send a NAK and then wait for another response from the client -\neither a done or another list of have lines.\n\nIn multiackdetailed mode:\n\n• the server will differentiate the ACKs where it is signaling that it is ready to send\ndata with ACK obj-id ready lines, and signals the identified common commits with ACK\nobj-id common lines.\n\nWithout either multiack or multiackdetailed:\n\n• upload-pack sends \"ACK obj-id\" on the first common object it finds. After that it says\nnothing until the client gives it a \"done\".\n\n• upload-pack sends \"NAK\" on a flush-pkt if no common object has been found yet. If one has\nbeen found, and thus an ACK was already sent, it’s silent on the flush-pkt.\n\nAfter the client has gotten enough ACK responses that it can determine that the server has\nenough information to send an efficient packfile (in the canonical implementation, this is\ndetermined when it has received enough ACKs that it can color everything left in the\n--date-order queue as common with the server, or the --date-order queue is empty), or the\nclient determines that it wants to give up (in the canonical implementation, this is\ndetermined when the client sends 256 have lines without getting any of them ACKed by the\nserver - meaning there is nothing in common and the server should just send all of its\nobjects), then the client will send a done command. The done command signals to the server\nthat the client is ready to receive its packfile data.\n\nHowever, the 256 limit only turns on in the canonical client implementation if we have\nreceived at least one \"ACK %s continue\" during a prior round. This helps to ensure that at\nleast one common ancestor is found before we give up entirely.\n\nOnce the done line is read from the client, the server will either send a final ACK obj-id or\nit will send a NAK. obj-id is the object name of the last commit determined to be common. The\nserver only sends ACK after done if there is at least one common base and multiack or\nmultiackdetailed is enabled. The server always sends NAK after done if there is no common\nbase found.\n\nInstead of ACK or NAK, the server may send an error message (for example, if it does not\nrecognize an object in a want line received from the client).\n\nThen the server will start sending its packfile data.\n\nserver-response = *ackmulti ack / nak\nackmulti = PKT-LINE(\"ACK\" SP obj-id ackstatus)\nackstatus = \"continue\" / \"common\" / \"ready\"\nack = PKT-LINE(\"ACK\" SP obj-id)\nnak = PKT-LINE(\"NAK\")\n\n\nA simple clone may look like this (with no have lines):\n\nC: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multiack \\\nside-band-64k ofs-delta\\n\nC: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\\n\nC: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\\n\nC: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\\n\nC: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\\n\nC: 0000\nC: 0009done\\n\n\nS: 0008NAK\\n\nS: [PACKFILE]\n\n\nAn incremental update (fetch) response might look like this:\n\nC: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multiack \\\nside-band-64k ofs-delta\\n\nC: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\\n\nC: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\\n\nC: 0000\nC: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\\n\nC: [30 more have lines]\nC: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\\n\nC: 0000\n\nS: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\\n\nS: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\\n\nS: 0008NAK\\n\n\nC: 0009done\\n\n\nS: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\\n\nS: [PACKFILE]\n\n", "subsections": [] }, "PACKFILE DATA": { "content": "Now that the client and server have finished negotiation about what the minimal amount of\ndata that needs to be sent to the client is, the server will construct and send the required\ndata in packfile format.\n\nSee gitformat-pack(5) for what the packfile itself actually looks like.\n\nIf side-band or side-band-64k capabilities have been specified by the client, the server will\nsend the packfile data multiplexed.\n\nEach packet starting with the packet-line length of the amount of data that follows, followed\nby a single byte specifying the sideband the following data is coming in on.\n\nIn side-band mode, it will send up to 999 data bytes plus 1 control code, for a total of up\nto 1000 bytes in a pkt-line. In side-band-64k mode it will send up to 65519 data bytes plus 1\ncontrol code, for a total of up to 65520 bytes in a pkt-line.\n\nThe sideband byte will be a 1, 2 or a 3. Sideband 1 will contain packfile data, sideband 2\nwill be used for progress information that the client will generally print to stderr and\nsideband 3 is used for error information.\n\nIf no side-band capability was specified, the server will stream the entire packfile without\nmultiplexing.\n", "subsections": [] }, "PUSHING DATA TO A SERVER": { "content": "Pushing data to a server will invoke the receive-pack process on the server, which will allow\nthe client to tell it which references it should update and then send all the data the server\nwill need for those new references to be complete. Once all the data is received and\nvalidated, the server will then update its references to what the client specified.\n", "subsections": [] }, "AUTHENTICATION": { "content": "The protocol itself contains no authentication mechanisms. That is to be handled by the\ntransport, such as SSH, before the receive-pack process is invoked. If receive-pack is\nconfigured over the Git transport, those repositories will be writable by anyone who can\naccess that port (9418) as that transport is unauthenticated.\n", "subsections": [] }, "REFERENCE UPDATE REQUEST AND PACKFILE TRANSFER": { "content": "Once the client knows what references the server is at, it can send a list of reference\nupdate requests. For each reference on the server that it wants to update, it sends a line\nlisting the obj-id currently on the server, the obj-id the client would like to update it to\nand the name of the reference.\n\nThis list is followed by a flush-pkt.\n\nupdate-requests = *shallow ( command-list | push-cert )\n\nshallow = PKT-LINE(\"shallow\" SP obj-id)\n\ncommand-list = PKT-LINE(command NUL capability-list)\n*PKT-LINE(command)\nflush-pkt\n\ncommand = create / delete / update\ncreate = zero-id SP new-id SP name\ndelete = old-id SP zero-id SP name\nupdate = old-id SP new-id SP name\n\nold-id = obj-id\nnew-id = obj-id\n\npush-cert = PKT-LINE(\"push-cert\" NUL capability-list LF)\nPKT-LINE(\"certificate version 0.1\" LF)\nPKT-LINE(\"pusher\" SP ident LF)\nPKT-LINE(\"pushee\" SP url LF)\nPKT-LINE(\"nonce\" SP nonce LF)\n*PKT-LINE(\"push-option\" SP push-option LF)\nPKT-LINE(LF)\n*PKT-LINE(command LF)\n*PKT-LINE(gpg-signature-lines LF)\nPKT-LINE(\"push-cert-end\" LF)\n\npush-option = 1*( VCHAR | SP )\n\n\nIf the server has advertised the push-options capability and the client has specified\npush-options as part of the capability list above, the client then sends its push options\nfollowed by a flush-pkt.\n\npush-options = *PKT-LINE(push-option) flush-pkt\n\n\nFor backwards compatibility with older Git servers, if the client sends a push cert and push\noptions, it MUST send its push options both embedded within the push cert and after the push\ncert. (Note that the push options within the cert are prefixed, but the push options after\nthe cert are not.) Both these lists MUST be the same, modulo the prefix.\n\nAfter that the packfile that should contain all the objects that the server will need to\ncomplete the new references will be sent.\n\npackfile = \"PACK\" 28*(OCTET)\n\n\nIf the receiving end does not support delete-refs, the sending end MUST NOT ask for delete\ncommand.\n\nIf the receiving end does not support push-cert, the sending end MUST NOT send a push-cert\ncommand. When a push-cert command is sent, command-list MUST NOT be sent; the commands\nrecorded in the push certificate is used instead.\n\nThe packfile MUST NOT be sent if the only command used is delete.\n\nA packfile MUST be sent if either create or update command is used, even if the server\nalready has all the necessary objects. In this case the client MUST send an empty packfile.\nThe only time this is likely to happen is if the client is creating a new branch or a tag\nthat points to an existing obj-id.\n\nThe server will receive the packfile, unpack it, then validate each reference that is being\nupdated that it hasn’t changed while the request was being processed (the obj-id is still the\nsame as the old-id), and it will run any update hooks to make sure that the update is\nacceptable. If all of that is fine, the server will then update the references.\n", "subsections": [] }, "PUSH CERTIFICATE": { "content": "A push certificate begins with a set of header lines. After the header and an empty line, the\nprotocol commands follow, one per line. Note that the trailing LF in push-cert PKT-LINEs is\nnot optional; it must be present.\n\nCurrently, the following header fields are defined:\n\npusher ident\nIdentify the GPG key in \"Human Readable Name \" format.\n\npushee url\nThe repository URL (anonymized, if the URL contains authentication material) the user who\nran git push intended to push into.\n\nnonce nonce\nThe nonce string the receiving repository asked the pushing user to include in the\ncertificate, to prevent replay attacks.\n\nThe GPG signature lines are a detached signature for the contents recorded in the push\ncertificate before the signature block begins. The detached signature is used to certify that\nthe commands were given by the pusher, who must be the signer.\n", "subsections": [] }, "REPORT STATUS": { "content": "After receiving the pack data from the sender, the receiver sends a report if report-status\nor report-status-v2 capability is in effect. It is a short listing of what happened in that\nupdate. It will first list the status of the packfile unpacking as either unpack ok or unpack\n[error]. Then it will list the status for each of the references that it tried to update.\nEach line is either ok [refname] if the update was successful, or ng [refname] [error] if the\nupdate was not.\n\nreport-status = unpack-status\n1*(command-status)\nflush-pkt\n\nunpack-status = PKT-LINE(\"unpack\" SP unpack-result)\nunpack-result = \"ok\" / error-msg\n\ncommand-status = command-ok / command-fail\ncommand-ok = PKT-LINE(\"ok\" SP refname)\ncommand-fail = PKT-LINE(\"ng\" SP refname SP error-msg)\n\nerror-msg = 1*(OCTET) ; where not \"ok\"\n\n\nThe report-status-v2 capability extends the protocol by adding new option lines in order to\nsupport reporting of reference rewritten by the proc-receive hook. The proc-receive hook may\nhandle a command for a pseudo-reference which may create or update one or more references,\nand each reference may have different name, different new-oid, and different old-oid.\n\nreport-status-v2 = unpack-status\n1*(command-status-v2)\nflush-pkt\n\nunpack-status = PKT-LINE(\"unpack\" SP unpack-result)\nunpack-result = \"ok\" / error-msg\n\ncommand-status-v2 = command-ok-v2 / command-fail\ncommand-ok-v2 = command-ok\n*option-line\n\ncommand-ok = PKT-LINE(\"ok\" SP refname)\ncommand-fail = PKT-LINE(\"ng\" SP refname SP error-msg)\n\nerror-msg = 1*(OCTET) ; where not \"ok\"\n\noption-line = *1(option-refname)\n*1(option-old-oid)\n*1(option-new-oid)\n*1(option-forced-update)\n\noption-refname = PKT-LINE(\"option\" SP \"refname\" SP refname)\noption-old-oid = PKT-LINE(\"option\" SP \"old-oid\" SP obj-id)\noption-new-oid = PKT-LINE(\"option\" SP \"new-oid\" SP obj-id)\noption-force = PKT-LINE(\"option\" SP \"forced-update\")\n\n\nUpdates can be unsuccessful for a number of reasons. The reference can have changed since the\nreference discovery phase was originally sent, meaning someone pushed in the meantime. The\nreference being pushed could be a non-fast-forward reference and the update hooks or\nconfiguration could be set to not allow that, etc. Also, some references can be updated while\nothers can be rejected.\n\nAn example client/server communication might look like this:\n\nS: 006274730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\\0report-status delete-refs ofs-delta\\n\nS: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\\n\nS: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\\n\nS: 003d74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\\n\nS: 0000\n\nC: 00677d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\\n\nC: 006874730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\\n\nC: 0000\nC: [PACKDATA]\n\nS: 000eunpack ok\\n\nS: 0018ok refs/heads/debug\\n\nS: 002ang refs/heads/master non-fast-forward\\n\n\n", "subsections": [] }, "GIT": { "content": "Part of the git(1) suite\n", "subsections": [] }, "NOTES": { "content": "1. email@address\nmailto:email@address\n\nGit 2.43.0 07/02/2025 GITPROTOCOL-PACK(5)", "subsections": [] } }, "summary": "gitprotocol-pack - How packs are transferred over-the-wire", "flags": [], "examples": [], "see_also": [] }