diff options
Diffstat (limited to 'Documentation/technical')
| -rw-r--r-- | Documentation/technical/api-hashmap.txt | 5 | ||||
| -rw-r--r-- | Documentation/technical/api-parse-options.txt | 8 | ||||
| -rw-r--r-- | Documentation/technical/api-sha1-array.txt | 8 | ||||
| -rw-r--r-- | Documentation/technical/pack-protocol.txt | 12 | ||||
| -rw-r--r-- | Documentation/technical/protocol-capabilities.txt | 9 | ||||
| -rw-r--r-- | Documentation/technical/protocol-common.txt | 6 | ||||
| -rw-r--r-- | Documentation/technical/signature-format.txt | 186 |
7 files changed, 222 insertions, 12 deletions
diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt index ad7a5bddd2..28f5a8b715 100644 --- a/Documentation/technical/api-hashmap.txt +++ b/Documentation/technical/api-hashmap.txt @@ -104,6 +104,11 @@ If `free_entries` is true, each hashmap_entry in the map is freed as well `entry` points to the entry to initialize. + `hash` is the hash code of the entry. ++ +The hashmap_entry structure does not hold references to external resources, +and it is safe to just discard it once you are done with it (i.e. if +your structure was allocated with xmalloc(), you can just free(3) it, +and if it is on stack, you can just let it go out of scope). `void *hashmap_get(const struct hashmap *map, const void *key, const void *keydata)`:: diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 695bd4bf43..27bd701c0d 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -144,8 +144,12 @@ There are some macros to easily define options: `OPT_COUNTUP(short, long, &int_var, description)`:: Introduce a count-up option. - `int_var` is incremented on each use of `--option`, and - reset to zero with `--no-option`. + Each use of `--option` increments `int_var`, starting from zero + (even if initially negative), and `--no-option` resets it to + zero. To determine if `--option` or `--no-option` was encountered at + all, initialize `int_var` to a negative value, and if it is still + negative after parse_options(), then neither `--option` nor + `--no-option` was seen. `OPT_BIT(short, long, &int_var, description, mask)`:: Introduce a boolean option. diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-sha1-array.txt index 3e75497a37..dcc52943a5 100644 --- a/Documentation/technical/api-sha1-array.txt +++ b/Documentation/technical/api-sha1-array.txt @@ -38,16 +38,20 @@ Functions `sha1_array_for_each_unique`:: Efficiently iterate over each unique element of the list, executing the callback function for each one. If the array is - not sorted, this function has the side effect of sorting it. + not sorted, this function has the side effect of sorting it. If + the callback returns a non-zero value, the iteration ends + immediately and the callback's return is propagated; otherwise, + 0 is returned. Examples -------- ----------------------------------------- -void print_callback(const unsigned char sha1[20], +int print_callback(const unsigned char sha1[20], void *data) { printf("%s\n", sha1_to_hex(sha1)); + return 0; /* always continue */ } void some_func(void) diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 8b36343802..736f3894a8 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -307,7 +307,7 @@ In multi_ack mode: ready to make a packfile, it will blindly ACK all 'have' obj-ids back to the client. - * the server will then send a 'NACK' and then wait for another response + * the server will then send a 'NAK' and then wait for another response from the client - either a 'done' or another list of 'have' lines. In multi_ack_detailed mode: @@ -454,7 +454,8 @@ The reference discovery phase is done nearly the same way as it is in the fetching protocol. Each reference obj-id and name on the server is sent in packet-line format to the client, followed by a flush-pkt. The only real difference is that the capability listing is different - the only -possible values are 'report-status', 'delete-refs' and 'ofs-delta'. +possible values are 'report-status', 'delete-refs', 'ofs-delta' and +'push-options'. Reference Update Request and Packfile Transfer ---------------------------------------------- @@ -465,9 +466,10 @@ that it wants to update, it sends a line listing the obj-id currently on the server, the obj-id the client would like to update it to and the name of the reference. -This list is followed by a flush-pkt and then the packfile that should -contain all the objects that the server will need to complete the new -references. +This list is followed by a flush-pkt. Then the push options are transmitted +one per packet followed by another flush-pkt. After that the packfile that +should contain all the objects that the server will need to complete the new +references will be sent. ---- update-request = *shallow ( command-list | push-cert ) [packfile] diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index eaab6b4ac7..4c28d3a8ae 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -253,6 +253,15 @@ atomic pushes. If the pushing client requests this capability, the server will update the refs in one atomic transaction. Either all refs are updated or none. +push-options +------------ + +If the server sends the 'push-options' capability it is able to accept +push options after the update commands have been sent, but before the +packfile is streamed. If the pushing client requests this capability, +the server will pass the options to the pre- and post- receive hooks +that process this push request. + allow-tip-sha1-in-want ---------------------- diff --git a/Documentation/technical/protocol-common.txt b/Documentation/technical/protocol-common.txt index bf30167ae3..ecedb34bba 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/technical/protocol-common.txt @@ -67,9 +67,9 @@ with non-binary data the same whether or not they contain the trailing LF (stripping the LF if present, and not complaining when it is missing). -The maximum length of a pkt-line's data component is 65520 bytes. -Implementations MUST NOT send pkt-line whose length exceeds 65524 -(65520 bytes of payload + 4 bytes of length data). +The maximum length of a pkt-line's data component is 65516 bytes. +Implementations MUST NOT send pkt-line whose length exceeds 65520 +(65516 bytes of payload + 4 bytes of length data). Implementations SHOULD NOT send an empty pkt-line ("0004"). diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt new file mode 100644 index 0000000000..2c9406a56a --- /dev/null +++ b/Documentation/technical/signature-format.txt @@ -0,0 +1,186 @@ +Git signature format +==================== + +== Overview + +Git uses cryptographic signatures in various places, currently objects (tags, +commits, mergetags) and transactions (pushes). In every case, the command which +is about to create an object or transaction determines a payload from that, +calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and +embeds the signature into the object or transaction. + +Signatures always begin with `-----BEGIN PGP SIGNATURE-----` +and end with `-----END PGP SIGNATURE-----`, unless gpg is told to +produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`. + +The signed payload and the way the signature is embedded depends +on the type of the object resp. transaction. + +== Tag signatures + +- created by: `git tag -s` +- payload: annotated tag object +- embedding: append the signature to the unsigned tag object +- example: tag `signedtag` with subject `signed tag` + +---- +object 04b871796dc0420f8e7561a895b52484b701d51a +type commit +tag signedtag +tagger C O Mitter <committer@example.com> 1465981006 +0000 + +signed tag + +signed tag message body +-----BEGIN PGP SIGNATURE----- +Version: GnuPG v1 + +iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn +rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh +8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods +q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 +rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x +lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= +=jpXa +-----END PGP SIGNATURE----- +---- + +- verify with: `git verify-tag [-v]` or `git tag -v` + +---- +gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia <discord@example.net>" +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +object 04b871796dc0420f8e7561a895b52484b701d51a +type commit +tag signedtag +tagger C O Mitter <committer@example.com> 1465981006 +0000 + +signed tag + +signed tag message body +---- + +== Commit signatures + +- created by: `git commit -S` +- payload: commit object +- embedding: header entry `gpgsig` + (content is preceded by a space) +- example: commit with subject `signed commit` + +---- +tree eebfed94e75e7760540d1485c740902590a00332 +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor <author@example.com> 1465981137 +0000 +committer C O Mitter <committer@example.com> 1465981137 +0000 +gpgsig -----BEGIN PGP SIGNATURE----- + Version: GnuPG v1 + + iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/ + HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7 + DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA + zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4 + HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1 + EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I= + =jKHM + -----END PGP SIGNATURE----- + +signed commit + +signed commit message body +---- + +- verify with: `git verify-commit [-v]` (or `git show --show-signature`) + +---- +gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia <discord@example.net>" +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +tree eebfed94e75e7760540d1485c740902590a00332 +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor <author@example.com> 1465981137 +0000 +committer C O Mitter <committer@example.com> 1465981137 +0000 + +signed commit + +signed commit message body +---- + +== Mergetag signatures + +- created by: `git merge` on signed tag +- payload/embedding: the whole signed tag object is embedded into + the (merge) commit object as header entry `mergetag` +- example: merge of the signed tag `signedtag` as above + +---- +tree c7b1cff039a93f3600a1d18b82d26688668c7dea +parent c33429be94b5f2d3ee9b0adad223f877f174b05d +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor <author@example.com> 1465982009 +0000 +committer C O Mitter <committer@example.com> 1465982009 +0000 +mergetag object 04b871796dc0420f8e7561a895b52484b701d51a + type commit + tag signedtag + tagger C O Mitter <committer@example.com> 1465981006 +0000 + + signed tag + + signed tag message body + -----BEGIN PGP SIGNATURE----- + Version: GnuPG v1 + + iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn + rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh + 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods + q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 + rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x + lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= + =jpXa + -----END PGP SIGNATURE----- + +Merge tag 'signedtag' into downstream + +signed tag + +signed tag message body + +# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 +# gpg: Good signature from "Eris Discordia <discord@example.net>" +# gpg: WARNING: This key is not certified with a trusted signature! +# gpg: There is no indication that the signature belongs to the owner. +# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +---- + +- verify with: verification is embedded in merge commit message by default, + alternatively with `git show --show-signature`: + +---- +commit 9863f0c76ff78712b6800e199a46aa56afbcbd49 +merged tag 'signedtag' +gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia <discord@example.net>" +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +Merge: c33429b 04b8717 +Author: A U Thor <author@example.com> +Date: Wed Jun 15 09:13:29 2016 +0000 + + Merge tag 'signedtag' into downstream + + signed tag + + signed tag message body + + # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 + # gpg: Good signature from "Eris Discordia <discord@example.net>" + # gpg: WARNING: This key is not certified with a trusted signature! + # gpg: There is no indication that the signature belongs to the owner. + # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +---- |