diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.30.7.txt | 86 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.31.6.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.32.5.txt | 8 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.33.6.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.34.6.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.35.6.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.36.4.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.37.5.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.38.3.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.39.1.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.40.0.txt | 67 | ||||
| -rw-r--r-- | Documentation/config/feature.txt | 5 | ||||
| -rw-r--r-- | Documentation/config/format.txt | 4 | ||||
| -rw-r--r-- | Documentation/config/index.txt | 11 | ||||
| -rw-r--r-- | Documentation/config/transfer.txt | 6 | ||||
| -rw-r--r-- | Documentation/fsck-msgids.txt | 12 | ||||
| -rw-r--r-- | Documentation/git-am.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-branch.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-cat-file.txt | 53 | ||||
| -rw-r--r-- | Documentation/git.txt | 8 | ||||
| -rw-r--r-- | Documentation/gitattributes.txt | 2 | ||||
| -rw-r--r-- | Documentation/gitprotocol-v2.txt | 201 |
22 files changed, 489 insertions, 24 deletions
diff --git a/Documentation/RelNotes/2.30.7.txt b/Documentation/RelNotes/2.30.7.txt new file mode 100644 index 0000000000..285beed232 --- /dev/null +++ b/Documentation/RelNotes/2.30.7.txt @@ -0,0 +1,86 @@ +Git v2.30.7 Release Notes +========================= + +This release addresses the security issues CVE-2022-41903 and +CVE-2022-23521. + + +Fixes since v2.30.6 +------------------- + + * CVE-2022-41903: + + git log has the ability to display commits using an arbitrary + format with its --format specifiers. This functionality is also + exposed to git archive via the export-subst gitattribute. + + When processing the padding operators (e.g., %<(, %<|(, %>(, + %>>(, or %><( ), an integer overflow can occur in + pretty.c::format_and_pad_commit() where a size_t is improperly + stored as an int, and then added as an offset to a subsequent + memcpy() call. + + This overflow can be triggered directly by a user running a + command which invokes the commit formatting machinery (e.g., git + log --format=...). It may also be triggered indirectly through + git archive via the export-subst mechanism, which expands format + specifiers inside of files within the repository during a git + archive. + + This integer overflow can result in arbitrary heap writes, which + may result in remote code execution. + +* CVE-2022-23521: + + gitattributes are a mechanism to allow defining attributes for + paths. These attributes can be defined by adding a `.gitattributes` + file to the repository, which contains a set of file patterns and + the attributes that should be set for paths matching this pattern. + + When parsing gitattributes, multiple integer overflows can occur + when there is a huge number of path patterns, a huge number of + attributes for a single pattern, or when the declared attribute + names are huge. + + These overflows can be triggered via a crafted `.gitattributes` file + that may be part of the commit history. Git silently splits lines + longer than 2KB when parsing gitattributes from a file, but not when + parsing them from the index. Consequentially, the failure mode + depends on whether the file exists in the working tree, the index or + both. + + This integer overflow can result in arbitrary heap reads and writes, + which may result in remote code execution. + +Credit for finding CVE-2022-41903 goes to Joern Schneeweisz of GitLab. +An initial fix was authored by Markus Vervier of X41 D-Sec. Credit for +finding CVE-2022-23521 goes to Markus Vervier and Eric Sesterhenn of X41 +D-Sec. This work was sponsored by OSTIF. + +The proposed fixes have been polished and extended to cover additional +findings by Patrick Steinhardt of GitLab, with help from others on the +Git security mailing list. + +Patrick Steinhardt (21): + attr: fix overflow when upserting attribute with overly long name + attr: fix out-of-bounds read with huge attribute names + attr: fix integer overflow when parsing huge attribute names + attr: fix out-of-bounds write when parsing huge number of attributes + attr: fix out-of-bounds read with unreasonable amount of patterns + attr: fix integer overflow with more than INT_MAX macros + attr: harden allocation against integer overflows + attr: fix silently splitting up lines longer than 2048 bytes + attr: ignore attribute lines exceeding 2048 bytes + attr: ignore overly large gitattributes files + pretty: fix out-of-bounds write caused by integer overflow + pretty: fix out-of-bounds read when left-flushing with stealing + pretty: fix out-of-bounds read when parsing invalid padding format + pretty: fix adding linefeed when placeholder is not expanded + pretty: fix integer overflow in wrapping format + utf8: fix truncated string lengths in `utf8_strnwidth()` + utf8: fix returning negative string width + utf8: fix overflow when returning string width + utf8: fix checking for glyph width in `strbuf_utf8_replace()` + utf8: refactor `strbuf_utf8_replace` to not rely on preallocated buffer + pretty: restrict input lengths for padding and wrapping formats + diff --git a/Documentation/RelNotes/2.31.6.txt b/Documentation/RelNotes/2.31.6.txt new file mode 100644 index 0000000000..425a51875a --- /dev/null +++ b/Documentation/RelNotes/2.31.6.txt @@ -0,0 +1,5 @@ +Git v2.31.6 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.32.5.txt b/Documentation/RelNotes/2.32.5.txt new file mode 100644 index 0000000000..a8cad1a05b --- /dev/null +++ b/Documentation/RelNotes/2.32.5.txt @@ -0,0 +1,8 @@ +Git v2.32.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. + +In addition, included are additional code for "git fsck" to check +for questionable .gitattributes files. diff --git a/Documentation/RelNotes/2.33.6.txt b/Documentation/RelNotes/2.33.6.txt new file mode 100644 index 0000000000..b63e4e6256 --- /dev/null +++ b/Documentation/RelNotes/2.33.6.txt @@ -0,0 +1,5 @@ +Git v2.33.6 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.34.6.txt b/Documentation/RelNotes/2.34.6.txt new file mode 100644 index 0000000000..b32080dba8 --- /dev/null +++ b/Documentation/RelNotes/2.34.6.txt @@ -0,0 +1,5 @@ +Git v2.34.6 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.35.6.txt b/Documentation/RelNotes/2.35.6.txt new file mode 100644 index 0000000000..e7ca57bb41 --- /dev/null +++ b/Documentation/RelNotes/2.35.6.txt @@ -0,0 +1,5 @@ +Git v2.35.6 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.36.4.txt b/Documentation/RelNotes/2.36.4.txt new file mode 100644 index 0000000000..58fb93a35f --- /dev/null +++ b/Documentation/RelNotes/2.36.4.txt @@ -0,0 +1,5 @@ +Git v2.36.4 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.37.5.txt b/Documentation/RelNotes/2.37.5.txt new file mode 100644 index 0000000000..faa1447292 --- /dev/null +++ b/Documentation/RelNotes/2.37.5.txt @@ -0,0 +1,5 @@ +Git v2.37.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.38.3.txt b/Documentation/RelNotes/2.38.3.txt new file mode 100644 index 0000000000..4a46bb4300 --- /dev/null +++ b/Documentation/RelNotes/2.38.3.txt @@ -0,0 +1,5 @@ +Git v2.38.3 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.39.1.txt b/Documentation/RelNotes/2.39.1.txt new file mode 100644 index 0000000000..60c86f4122 --- /dev/null +++ b/Documentation/RelNotes/2.39.1.txt @@ -0,0 +1,5 @@ +Git v2.39.1 Release Notes +========================= + +This release merges the security fix that appears in v2.30.7; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.40.0.txt b/Documentation/RelNotes/2.40.0.txt index 634f0ae33a..07ae9f20c3 100644 --- a/Documentation/RelNotes/2.40.0.txt +++ b/Documentation/RelNotes/2.40.0.txt @@ -23,6 +23,18 @@ UI, Workflows & Features choose which editor gets used behind it, "git var" now give support to GIT_SEQUENCE_EDITOR. + * "git format-patch" learned to honor format.mboxrd even when sending + patches to the standard output stream, + + * 'cat-file' gains mailmap support for its '--batch-check' and '-s' + options. + + * Conditionally skip the pre-applypatch and applypatch-msg hooks when + applying patches with 'git am'. + + * Introduce an optional configuration to allow the trailing hash that + protects the index file from bit flipping. + Performance, Internal Implementation, Development Support etc. @@ -34,6 +46,32 @@ Performance, Internal Implementation, Development Support etc. * Use the SHA1DC implementation on macOS, just like other platforms, by default. + * Even in a repository with promisor remote, it is useless to + attempt to lazily attempt fetching an object that is expected to be + commit, because no "filter" mode omits commit objects. Take + advantage of this assumption to fail fast on errors. + + * Stop using "git --super-prefix" and narrow the scope of its use to + the submodule--helper. + + * Stop running win+VS build by default. + (merge a0da6deeec js/ci-disable-cmake-by-default later to maint). + + * CI updates. We probably want a clean-up to move the long shell + script embedded in yaml file into a separate file, but that can + come later. + (merge 4542582e59 cw/ci-whitespace later to maint). + + * Use `git diff --no-index` as a test_cmp on Windows. + + We'd probably need to revisit "do we really want to, and have to, + lose CRLF vs LF?" later, at which time we may be able to further + clean this up by replacing "git diff --no-index" with "diff -u". + + * Avoid unnecessary builds in CI, with settings configured in + ci-config. + (merge eb5b03a9c0 tb/ci-concurrency later to maint). + Fixes since v2.39 ----------------- @@ -82,6 +120,30 @@ Fixes since v2.39 request and barfed, which has been corrected. (merge 6f65f84766 ss/pull-v-recurse-fix later to maint). + * When given a pattern that matches an empty string at the end of a + line, the code to parse the "git diff" line-ranges fell into an + infinite loop, which has been corrected. + (merge 4e57c88e02 lk/line-range-parsing-fix later to maint). + + * Fix the sequence to fsync $GIT_DIR/packed-refs file that forgot to + flush its output to the disk.. + (merge ce54672f9b ps/fsync-refs-fix later to maint). + + * Fix to a small regression in 2.38 days. + (merge 6d5e9e53aa ab/bundle-wo-args later to maint). + + * "git diff --relative" did not mix well with "git diff --ext-diff", + which has been corrected. + (merge f034bb1cad jk/ext-diff-with-relative later to maint). + + * The logic to see if we are using the "cone" mode by checking the + sparsity patterns has been tightened to avoid mistaking a pattern + that names a single file as specifying a cone. + (merge 5842710dc2 ws/single-file-cone later to maint). + + * Deal with a few deprecation warning from cURL library. + (merge 6c065f72b8 jk/curl-avoid-deprecated-api later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 77e04b2ed4 rs/t4205-do-not-exit-in-test-script later to maint). (merge faebba436e rs/plug-pattern-list-leak-in-lof later to maint). @@ -98,3 +160,8 @@ Fixes since v2.39 (merge b07a819c05 rs/reflog-expiry-cleanup later to maint). (merge d422d06167 rs/clarify-error-in-write-loose-object later to maint). (merge 92cb135855 sk/remove-duplicate-includes later to maint). + (merge 4eb1ccecd4 dh/mingw-ownership-check-typofix later to maint). + (merge f95526419b ar/typofix-gitattributes-doc later to maint). + (merge 27875aeec9 km/doc-branch-start-point later to maint). + (merge 35c194dc57 es/t1509-root-fixes later to maint). + (merge 7b341645e3 pw/ci-print-failure-name-fix later to maint). diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index 95975e5091..e52bc6b858 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -23,6 +23,11 @@ feature.manyFiles:: working directory. With many files, commands such as `git status` and `git checkout` may be slow and these new defaults improve performance: + +* `index.skipHash=true` speeds up index writes by not computing a trailing + checksum. Note that this will cause Git versions earlier than 2.13.0 to + refuse to parse the index and Git versions earlier than 2.40.0 will report + a corrupted index during `git fsck`. ++ * `index.version=4` enables path-prefix compression in the index. + * `core.untrackedCache=true` enables the untracked cache. This setting assumes diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt index c7303d8d9f..3bd78269e2 100644 --- a/Documentation/config/format.txt +++ b/Documentation/config/format.txt @@ -139,3 +139,7 @@ For example, ------------ + will only show notes from `refs/notes/bar`. + +format.mboxrd:: + A boolean value which enables the robust "mboxrd" format when + `--stdout` is in use to escape "^>+From " lines. diff --git a/Documentation/config/index.txt b/Documentation/config/index.txt index 75f3a2d105..23c7985eb4 100644 --- a/Documentation/config/index.txt +++ b/Documentation/config/index.txt @@ -30,3 +30,14 @@ index.version:: Specify the version with which new index files should be initialized. This does not affect existing repositories. If `feature.manyFiles` is enabled, then the default is 4. + +index.skipHash:: + When enabled, do not compute the trailing hash for the index file. + This accelerates Git commands that manipulate the index, such as + `git add`, `git commit`, or `git status`. Instead of storing the + checksum, write a trailing set of bytes with value zero, indicating + that the computation was skipped. ++ +If you enable `index.skipHash`, then Git clients older than 2.13.0 will +refuse to parse the index and Git clients older than 2.40.0 will report an +error during `git fsck`. diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt index 264812cca4..c3ac767d1e 100644 --- a/Documentation/config/transfer.txt +++ b/Documentation/config/transfer.txt @@ -115,3 +115,9 @@ transfer.unpackLimit:: transfer.advertiseSID:: Boolean. When true, client and server processes will advertise their unique session IDs to their remote counterpart. Defaults to false. + +transfer.bundleURI:: + When `true`, local `git clone` commands will request bundle + information from the remote server (if advertised) and download + bundles before continuing the clone through the Git protocol. + Defaults to `false`. diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.txt index 7af76ff99a..12eae8a222 100644 --- a/Documentation/fsck-msgids.txt +++ b/Documentation/fsck-msgids.txt @@ -46,6 +46,18 @@ `fullPathname`:: (WARN) A path contains the full path starting with "/". +`gitattributesBlob`:: + (ERROR) A non-blob found at `.gitattributes`. + +`gitattributesLarge`:: + (ERROR) The `.gitattributes` blob is too large. + +`gitattributesLineLength`:: + (ERROR) The `.gitattributes` blob contains too long lines. + +`gitattributesMissing`:: + (ERROR) Unable to read `.gitattributes` blob. + `gitattributesSymlink`:: (INFO) `.gitattributes` is a symlink. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 326276e51c..0c1dfb3c98 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,7 +9,7 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] +'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--no-verify] [--[no-]3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] @@ -138,6 +138,12 @@ include::rerere-options.txt[] --interactive:: Run interactively. +-n:: +--no-verify:: + By default, the pre-applypatch and applypatch-msg hooks are run. + When any of `--no-verify` or `-n` is given, these are bypassed. + See also linkgit:githooks[5]. + --committer-date-is-author-date:: By default the command records the date from the e-mail message as the commit author date, and uses the time of diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 12c5f84e3b..aa2f78c4c2 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -116,7 +116,7 @@ OPTIONS -f:: --force:: - Reset <branchname> to <startpoint>, even if <branchname> exists + Reset <branchname> to <start-point>, even if <branchname> exists already. Without `-f`, 'git branch' refuses to change an existing branch. In combination with `-d` (or `--delete`), allow deleting the branch irrespective of its merged status, or whether it even diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index ec30b5c574..830f0a2eff 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -45,7 +45,9 @@ OPTIONS -s:: Instead of the content, show the object size identified by - `<object>`. + `<object>`. If used with `--use-mailmap` option, will show + the size of updated object after replacing idents using the + mailmap mechanism. -e:: Exit with zero status if `<object>` exists and is a valid @@ -89,26 +91,49 @@ OPTIONS --batch:: --batch=<format>:: Print object information and contents for each object provided - on stdin. May not be combined with any other options or arguments - except `--textconv` or `--filters`, in which case the input lines - also need to specify the path, separated by whitespace. See the - section `BATCH OUTPUT` below for details. + on stdin. May not be combined with any other options or arguments + except `--textconv`, `--filters`, or `--use-mailmap`. + + + * When used with `--textconv` or `--filters`, the input lines + must specify the path, separated by whitespace. See the section + `BATCH OUTPUT` below for details. + + + * When used with `--use-mailmap`, for commit and tag objects, the + contents part of the output shows the identities replaced using the + mailmap mechanism, while the information part of the output shows + the size of the object as if it actually recorded the replacement + identities. --batch-check:: --batch-check=<format>:: - Print object information for each object provided on stdin. May - not be combined with any other options or arguments except - `--textconv` or `--filters`, in which case the input lines also - need to specify the path, separated by whitespace. See the - section `BATCH OUTPUT` below for details. + Print object information for each object provided on stdin. May not be + combined with any other options or arguments except `--textconv`, `--filters` + or `--use-mailmap`. + + + * When used with `--textconv` or `--filters`, the input lines must + specify the path, separated by whitespace. See the section + `BATCH OUTPUT` below for details. + + + * When used with `--use-mailmap`, for commit and tag objects, the + printed object information shows the size of the object as if the + identities recorded in it were replaced by the mailmap mechanism. --batch-command:: --batch-command=<format>:: Enter a command mode that reads commands and arguments from stdin. May - only be combined with `--buffer`, `--textconv` or `--filters`. In the - case of `--textconv` or `--filters`, the input lines also need to specify - the path, separated by whitespace. See the section `BATCH OUTPUT` below - for details. + only be combined with `--buffer`, `--textconv`, `--use-mailmap` or + `--filters`. + + + * When used with `--textconv` or `--filters`, the input lines must + specify the path, separated by whitespace. See the section + `BATCH OUTPUT` below for details. + + + * When used with `--use-mailmap`, for commit and tag objects, the + `contents` command shows the identities replaced using the + mailmap mechanism, while the `info` command shows the size + of the object as if it actually recorded the replacement + identities. + + `--batch-command` recognizes the following commands: + diff --git a/Documentation/git.txt b/Documentation/git.txt index 1d33e083ab..f9a7a4554c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -13,8 +13,7 @@ SYNOPSIS [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare] [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] - [--super-prefix=<path>] [--config-env=<name>=<envvar>] - <command> [<args>] + [--config-env=<name>=<envvar>] <command> [<args>] DESCRIPTION ----------- @@ -169,11 +168,6 @@ If you just want to run git as if it was started in `<path>` then use details. Equivalent to setting the `GIT_NAMESPACE` environment variable. ---super-prefix=<path>:: - Currently for internal use only. Set a prefix which gives a path from - above a repository down to its root. One use is to give submodules - context about the superproject that invoked it. - --bare:: Treat the repository as a bare repository. If GIT_DIR environment is not set, it is set to the current working diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 4b36d51beb..c19e64ea0e 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -1155,7 +1155,7 @@ Unspecified:: String:: - Specify a comma separate list of common whitespace problems to + Specify a comma separated list of common whitespace problems to notice in the same format as the `core.whitespace` configuration variable. diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt index 59bf41cefb..acb97ad0c2 100644 --- a/Documentation/gitprotocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -578,6 +578,207 @@ and associated requested information, each separated by a single space. obj-info = obj-id SP obj-size +bundle-uri +~~~~~~~~~~ + +If the 'bundle-uri' capability is advertised, the server supports the +`bundle-uri' command. + +The capability is currently advertised with no value (i.e. not +"bundle-uri=somevalue"), a value may be added in the future for +supporting command-wide extensions. Clients MUST ignore any unknown +capability values and proceed with the 'bundle-uri` dialog they +support. + +The 'bundle-uri' command is intended to be issued before `fetch` to +get URIs to bundle files (see linkgit:git-bundle[1]) to "seed" and +inform the subsequent `fetch` command. + +The client CAN issue `bundle-uri` before or after any other valid +command. To be useful to clients it's expected that it'll be issued +after an `ls-refs` and before `fetch`, but CAN be issued at any time +in the dialog. + +DISCUSSION of bundle-uri +^^^^^^^^^^^^^^^^^^^^^^^^ + +The intent of the feature is optimize for server resource consumption +in the common case by changing the common case of fetching a very +large PACK during linkgit:git-clone[1] into a smaller incremental +fetch. + +It also allows servers to achieve better caching in combination with +an `uploadpack.packObjectsHook` (see linkgit:git-config[1]). + +By having new clones or fetches be a more predictable and common +negotiation against the tips of recently produces *.bundle file(s). +Servers might even pre-generate the results of such negotiations for +the `uploadpack.packObjectsHook` as new pushes come in. + +One way that servers could take advantage of these bundles is that the +server would anticipate that fresh clones will download a known bundle, +followed by catching up to the current state of the repository using ref +tips found in that bundle (or bundles). + +PROTOCOL for bundle-uri +^^^^^^^^^^^^^^^^^^^^^^^ + +A `bundle-uri` request takes no arguments, and as noted above does not +currently advertise a capability value. Both may be added in the +future. + +When the client issues a `command=bundle-uri` request, the response is a +list of key-value pairs provided as packet lines with value +`<key>=<value>`. Each `<key>` should be interpreted as a config key from +the `bundle.*` namespace to construct a list of bundles. These keys are +grouped by a `bundle.<id>.` subsection, where each key corresponding to a +given `<id>` contributes attributes to the bundle defined by that `<id>`. +See linkgit:git-config[1] for the specific details of these keys and how +the Git client will interpret their values. + +Clients MUST parse the line according to the above format, lines that do +not conform to the format SHOULD be discarded. The user MAY be warned in +such a case. + +bundle-uri CLIENT AND SERVER EXPECTATIONS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +URI CONTENTS:: +The content at the advertised URIs MUST be one of two types. ++ +The advertised URI may contain a bundle file that `git bundle verify` +would accept. I.e. they MUST contain one or more reference tips for +use by the client, MUST indicate prerequisites (in any) with standard +"-" prefixes, and MUST indicate their "object-format", if +applicable. ++ +The advertised URI may alternatively contain a plaintext file that `git +config --list` would accept (with the `--file` option). The key-value +pairs in this list are in the `bundle.*` namespace (see +linkgit:git-config[1]). + +bundle-uri CLIENT ERROR RECOVERY:: +A client MUST above all gracefully degrade on errors, whether that +error is because of bad missing/data in the bundle URI(s), because +that client is too dumb to e.g. understand and fully parse out bundle +headers and their prerequisite relationships, or something else. ++ +Server operators should feel confident in turning on "bundle-uri" and +not worry if e.g. their CDN goes down that clones or fetches will run +into hard failures. Even if the server bundle(s) are +incomplete, or bad in some way the client should still end up with a +functioning repository, just as if it had chosen not to use this +protocol extension. ++ +All subsequent discussion on client and server interaction MUST keep +this in mind. + +bundle-uri SERVER TO CLIENT:: +The ordering of the returned bundle uris is not significant. Clients +MUST parse their headers to discover their contained OIDS and +prerequisites. A client MUST consider the content of the bundle(s) +themselves and their header as the ultimate source of truth. ++ +A server MAY even return bundle(s) that don't have any direct +relationship to the repository being cloned (either through accident, +or intentional "clever" configuration), and expect a client to sort +out what data they'd like from the bundle(s), if any. + +bundle-uri CLIENT TO SERVER:: +The client SHOULD provide reference tips found in the bundle header(s) +as 'have' lines in any subsequent `fetch` request. A client MAY also +ignore the bundle(s) entirely if doing so is deemed worse for some +reason, e.g. if the bundles can't be downloaded, it doesn't like the +tips it finds etc. + +WHEN ADVERTISED BUNDLE(S) REQUIRE NO FURTHER NEGOTIATION:: +If after issuing `bundle-uri` and `ls-refs`, and getting the header(s) +of the bundle(s) the client finds that the ref tips it wants can be +retrieved entirely from advertised bundle(s), the client MAY disconnect +from the Git server. The results of such a 'clone' or 'fetch' should be +indistinguishable from the state attained without using bundle-uri. + +EARLY CLIENT DISCONNECTIONS AND ERROR RECOVERY:: +A client MAY perform an early disconnect while still downloading the +bundle(s) (having streamed and parsed their headers). In such a case +the client MUST gracefully recover from any errors related to +finishing the download and validation of the bundle(s). ++ +I.e. a client might need to re-connect and issue a 'fetch' command, +and possibly fall back to not making use of 'bundle-uri' at all. ++ +This "MAY" behavior is specified as such (and not a "SHOULD") on the +assumption that a server advertising bundle uris is more likely than +not to be serving up a relatively large repository, and to be pointing +to URIs that have a good chance of being in working order. A client +MAY e.g. look at the payload size of the bundles as a heuristic to see +if an early disconnect is worth it, should falling back on a full +"fetch" dialog be necessary. + +WHEN ADVERTISED BUNDLE(S) REQUIRE FURTHER NEGOTIATION:: +A client SHOULD commence a negotiation of a PACK from the server via +the "fetch" command using the OID tips found in advertised bundles, +even if's still in the process of downloading those bundle(s). ++ +This allows for aggressive early disconnects from any interactive +server dialog. The client blindly trusts that the advertised OID tips +are relevant, and issues them as 'have' lines, it then requests any +tips it would like (usually from the "ls-refs" advertisement) via +'want' lines. The server will then compute a (hopefully small) PACK +with the expected difference between the tips from the bundle(s) and +the data requested. ++ +The only connection the client then needs to keep active is to the +concurrently downloading static bundle(s), when those and the +incremental PACK are retrieved they should be inflated and +validated. Any errors at this point should be gracefully recovered +from, see above. + +bundle-uri PROTOCOL FEATURES +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The client constructs a bundle list from the `<key>=<value>` pairs +provided by the server. These pairs are part of the `bundle.*` namespace +as documented in linkgit:git-config[1]. In this section, we discuss some +of these keys and describe the actions the client will do in response to +this information. + +In particular, the `bundle.version` key specifies an integer value. The +only accepted value at the moment is `1`, but if the client sees an +unexpected value here then the client MUST ignore the bundle list. + +As long as `bundle.version` is understood, all other unknown keys MAY be +ignored by the client. The server will guarantee compatibility with older +clients, though newer clients may be better able to use the extra keys to +minimize downloads. + +Any backwards-incompatible addition of pre-URI key-value will be +guarded by a new `bundle.version` value or values in 'bundle-uri' +capability advertisement itself, and/or by new future `bundle-uri` +request arguments. + +Some example key-value pairs that are not currently implemented but could +be implemented in the future include: + + * Add a "hash=<val>" or "size=<bytes>" advertise the expected hash or + size of the bundle file. + + * Advertise that one or more bundle files are the same (to e.g. have + clients round-robin or otherwise choose one of N possible files). + + * A "oid=<OID>" shortcut and "prerequisite=<OID>" shortcut. For + expressing the common case of a bundle with one tip and no + prerequisites, or one tip and one prerequisite. ++ +This would allow for optimizing the common case of servers who'd like +to provide one "big bundle" containing only their "main" branch, +and/or incremental updates thereof. ++ +A client receiving such a a response MAY assume that they can skip +retrieving the header from a bundle at the indicated URI, and thus +save themselves and the server(s) the request(s) needed to inspect the +headers of that bundle or bundles. + GIT --- Part of the linkgit:git[1] suite |