| 1 | gitprotocol-common(5) |
| 2 | ===================== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | gitprotocol-common - Things common to various protocols |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [verse] |
| 11 | <over-the-wire-protocol> |
| 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
| 15 | |
| 16 | This document defines things common to various over-the-wire |
| 17 | protocols and file formats used in Git. |
| 18 | |
| 19 | ABNF Notation |
| 20 | ------------- |
| 21 | |
| 22 | ABNF notation as described by RFC 5234 is used within the protocol documents, |
| 23 | except the following replacement core rules are used: |
| 24 | |
| 25 | ---- |
| 26 | HEXDIG = DIGIT / "a" / "b" / "c" / "d" / "e" / "f" |
| 27 | ---- |
| 28 | |
| 29 | We also define the following common rules: |
| 30 | |
| 31 | ---- |
| 32 | NUL = %x00 |
| 33 | zero-id = 40*"0" |
| 34 | obj-id = 40*(HEXDIGIT) |
| 35 | |
| 36 | refname = "HEAD" |
| 37 | refname /= "refs/" <see discussion below> |
| 38 | ---- |
| 39 | |
| 40 | A refname is a hierarchical octet string beginning with "refs/" and |
| 41 | not violating the 'git-check-ref-format' command's validation rules. |
| 42 | More specifically, they: |
| 43 | |
| 44 | . They can include slash `/` for hierarchical (directory) |
| 45 | grouping, but no slash-separated component can begin with a |
| 46 | dot `.`. |
| 47 | |
| 48 | . They must contain at least one `/`. This enforces the presence of a |
| 49 | category like `heads/`, `tags/` etc. but the actual names are not |
| 50 | restricted. |
| 51 | |
| 52 | . They cannot have two consecutive dots `..` anywhere. |
| 53 | |
| 54 | . They cannot have ASCII control characters (i.e. bytes whose |
| 55 | values are lower than \040, or \177 `DEL`), space, tilde `~`, |
| 56 | caret `^`, colon `:`, question-mark `?`, asterisk `*`, |
| 57 | or open bracket `[` anywhere. |
| 58 | |
| 59 | . They cannot end with a slash `/` or a dot `.`. |
| 60 | |
| 61 | . They cannot end with the sequence `.lock`. |
| 62 | |
| 63 | . They cannot contain a sequence `@{`. |
| 64 | |
| 65 | . They cannot contain a `\\`. |
| 66 | |
| 67 | |
| 68 | pkt-line Format |
| 69 | --------------- |
| 70 | |
| 71 | Much (but not all) of the payload is described around pkt-lines. |
| 72 | |
| 73 | A pkt-line is a variable length binary string. The first four bytes |
| 74 | of the line, the pkt-len, indicates the total length of the line, |
| 75 | in hexadecimal. The pkt-len includes the 4 bytes used to contain |
| 76 | the length's hexadecimal representation. |
| 77 | |
| 78 | A pkt-line MAY contain binary data, so implementors MUST ensure |
| 79 | pkt-line parsing/formatting routines are 8-bit clean. |
| 80 | |
| 81 | A non-binary line SHOULD BE terminated by an LF, which if present |
| 82 | MUST be included in the total length. Receivers MUST treat pkt-lines |
| 83 | with non-binary data the same whether or not they contain the trailing |
| 84 | LF (stripping the LF if present, and not complaining when it is |
| 85 | missing). |
| 86 | |
| 87 | The maximum length of a pkt-line's data component is 65516 bytes. |
| 88 | Implementations MUST NOT send pkt-line whose length exceeds 65520 |
| 89 | (65516 bytes of payload + 4 bytes of length data). |
| 90 | |
| 91 | Implementations SHOULD NOT send an empty pkt-line ("0004"). |
| 92 | |
| 93 | A pkt-line with a length field of 0 ("0000"), called a flush-pkt, |
| 94 | is a special case and MUST be handled differently than an empty |
| 95 | pkt-line ("0004"). |
| 96 | |
| 97 | ---- |
| 98 | pkt-line = data-pkt / flush-pkt |
| 99 | |
| 100 | data-pkt = pkt-len pkt-payload |
| 101 | pkt-len = 4*(HEXDIG) |
| 102 | pkt-payload = (pkt-len - 4)*(OCTET) |
| 103 | |
| 104 | flush-pkt = "0000" |
| 105 | ---- |
| 106 | |
| 107 | Examples (as C-style strings): |
| 108 | |
| 109 | ---- |
| 110 | pkt-line actual value |
| 111 | --------------------------------- |
| 112 | "0006a\n" "a\n" |
| 113 | "0005a" "a" |
| 114 | "000bfoobar\n" "foobar\n" |
| 115 | "0004" "" |
| 116 | ---- |
| 117 | |
| 118 | GIT |
| 119 | --- |
| 120 | Part of the linkgit:git[1] suite |