diff options
Diffstat (limited to 'Documentation')
35 files changed, 714 insertions, 35 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 new file mode 100644 index 0000000000..07ae9f20c3 --- /dev/null +++ b/Documentation/RelNotes/2.40.0.txt @@ -0,0 +1,167 @@ +Git v2.40 Release Notes +======================= + +UI, Workflows & Features + + * "merge-tree" learns a new `--merge-base` option. + + * "git jump" (in contrib/) learned to present the "quickfix list" to + its standard output (instead of letting it consumed by the editor + it invokes), and learned to also drive emacs/emacsclient. + + * "git var UNKNOWN_VARIABLE" and "git var VARIABLE" with the variable + given an empty value used to behave identically. Now the latter + just gives an empty output, while the former still gives an error + message. + + * Introduce a case insensitive mode to the Bash completion helpers. + + * The advice message given by "git status" when it takes long time to + enumerate untracked paths has been updated. + + * Just like "git var GIT_EDITOR" abstracts the complex logic to + 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. + + * `git bisect` becomes a builtin. + + * The pack-bitmap machinery is taught to log the paths of redundant + bitmap(s) to trace2 instead of stderr. + + * 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 +----------------- + + * Various leak fixes. + (merge ac95f5d36a ab/various-leak-fixes later to maint). + + * Fix a bug where `pack-objects` would not respect multiple `--filter` + arguments when invoked directly. + (merge d4f7036887 rs/multi-filter-args later to maint). + + * Make fsmonitor more robust to avoid the flakiness seen in t7527. + (merge 6692d45477 jh/t7527-unflake-by-forcing-cookie later to maint). + + * Stop using deprecated macOS API in fsmonitor. + (merge b0226007f0 jh/fsmonitor-darwin-modernize later to maint). + + * Redefining system functions for a few functions did not follow our + usual "implement git_foo() and #define foo(args) git_foo(args)" + pattern, which has broken build for some folks. + (merge e1a95b78d8 jk/avoid-redef-system-functions-2.30 later to maint). + (merge 395bec6b39 jk/avoid-redef-system-functions later to maint). + + * The way the diff machinery prepares the options array for the + parse_options API has been refactored to avoid resource leaks. + (merge 189e97bc4b rs/diff-parseopts later to maint). + + * Correct pthread API usage. + (merge 786e67611d sx/pthread-error-check-fix later to maint). + + * The code to auto-correct a misspelt subcommand unnecessarily called + into git_default_config() from the early config codepath, which was + a no-no. This has bee corrected. + (merge 0918d08887 sg/help-autocorrect-config-fix later to maint). + + * "git http-fetch" (which is rarely used) forgot to identify itself + in the trace2 output. + (merge 7abb43cbc8 jt/http-fetch-trace2-report-name later to maint). + + * The output from "git diff --stat" on an unmerged path lost the + terminating LF in Git 2.39, which has been corrected. + (merge 209d9cb011 pg/diff-stat-unmerged-regression-fix later to maint). + + * "git pull -v --recurse-submodules" attempted to pass "-v" down to + underlying "git submodule update", which did not understand the + 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). + (merge 243caa8982 ab/t5314-avoid-losing-exit-status later to maint). + (merge 4d81ce1b99 ab/t7600-avoid-losing-exit-status-of-git later to maint). + (merge 5f3bfdc4f3 ab/t4023-avoid-losing-exit-status-of-diff later to maint). + (merge 500317ae03 js/t3920-shell-and-or-fix later to maint). + (merge 86325d36e6 rs/t3920-crlf-eating-grep-fix later to maint). + (merge cfbd173ccb rj/branch-copy-and-rename later to maint). + (merge c25d9e529d jk/unused-post-2.39 later to maint). + (merge a31cfe3283 jk/server-supports-v2-cleanup later to maint). + (merge a658e881c1 rs/am-parse-options-cleanup later to maint). + (merge 4cb39fcf19 rs/clear-commit-marks-cleanup later to maint). + (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/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index c78063d4f7..546adf79e5 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -1,3 +1,4 @@ +[[generate_patch_text_with_p]] Generating patch text with -p ----------------------------- diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 3674ac48e9..7d73e976d9 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -22,7 +22,13 @@ ifndef::git-format-patch[] -p:: -u:: --patch:: - Generate patch (see section on generating patches). + Generate patch (see section titled +ifdef::git-log[] +<<generate_patch_text_with_p, "Generating patch text with -p">>). +endif::git-log[] +ifndef::git-log[] +"Generating patch text with -p"). +endif::git-log[] ifdef::git-diff[] This is the default. endif::git-diff[] 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-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index f3d9566c89..0bc165788e 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -1347,8 +1347,8 @@ author to given a talk and for publishing this paper. References ---------- -- [[[1]]] https://www.nist.gov/sites/default/files/documents/director/planning/report02-3.pdf['The Economic Impacts of Inadequate Infratructure for Software Testing'. Nist Planning Report 02-3], see Executive Summary and Chapter 8. -- [[[2]]] http://www.oracle.com/technetwork/java/codeconvtoc-136057.html['Code Conventions for the Java Programming Language'. Sun Microsystems.] +- [[[1]]] https://web.archive.org/web/20091206032101/http://www.nist.gov/public_affairs/releases/n02-10.htm['Software Errors Cost U.S. Economy $59.5 Billion Annually'. Nist News Release.] See also https://www.nist.gov/system/files/documents/director/planning/report02-3.pdf['The Economic Impacts of Inadequate Infratructure for Software Testing'. Nist Planning Report 02-3], Executive Summary and Chapter 8. +- [[[2]]] https://www.oracle.com/java/technologies/javase/codeconventions-introduction.html['Code Conventions for the Java Programming Language: 1. Introduction'. Sun Microsystems.] - [[[3]]] https://en.wikipedia.org/wiki/Software_maintenance['Software maintenance'. Wikipedia.] - [[[4]]] https://lore.kernel.org/git/7vps5xsbwp.fsf_-_@assigned-by-dhcp.cox.net/[Junio C Hamano. 'Automated bisect success story'.] - [[[5]]] https://lwn.net/Articles/317154/[Christian Couder. 'Fully automated bisecting with "git bisect run"'. LWN.net.] 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-checkout.txt b/Documentation/git-checkout.txt index 4cb9d555b4..9f116acdbd 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -477,9 +477,9 @@ before that happens. If we have not yet moved away from commit `f`, any of these will create a reference to it: ------------ -$ git checkout -b foo <1> -$ git branch foo <2> -$ git tag foo <3> +$ git checkout -b foo # or "git switch -c foo" <1> +$ git branch foo <2> +$ git tag foo <3> ------------ <1> creates a new branch `foo`, which refers to commit `f`, and then diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 1e8ac9df60..fdcad3d200 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -219,7 +219,7 @@ again, this time exercising more care about matching up context lines. ------------ $ git cherry-pick topic^ <1> $ git diff <2> -$ git reset --merge ORIG_HEAD <3> +$ git cherry-pick --abort <3> $ git cherry-pick -Xpatience topic^ <4> ------------ <1> apply the change that would be shown by `git show topic^`. diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index 04bcc416e6..88ee942101 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -64,6 +64,11 @@ OPTIONS share no common history. This flag can be given to override that check and make the merge proceed anyway. +--merge-base=<commit>:: + Instead of finding the merge-bases for <branch1> and <branch2>, + specify a merge-base for the merge, and specifying multiple bases is + currently not supported. This option is incompatible with `--stdin`. + [[OUTPUT]] OUTPUT ------ @@ -216,6 +221,17 @@ with linkgit:git-merge[1]: * any messages that would have been printed to stdout (the <<IM,Informational messages>>) +INPUT FORMAT +------------ +'git merge-tree --stdin' input format is fully text based. Each line +has this format: + + [<base-commit> -- ]<branch1> <branch2> + +If one line is separated by `--`, the string before the separator is +used for specifying a merge-base for the merge and the string after +the separator describes the branches to be merged. + MISTAKES TO AVOID ----------------- diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 2d6a1391c8..0aeff572a5 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -37,7 +37,8 @@ Then "`git merge topic`" will replay the changes made on the `topic` branch since it diverged from `master` (i.e., `E`) until its current commit (`C`) on top of `master`, and record the result in a new commit along with the names of the two parent commits and -a log message from the user describing the changes. +a log message from the user describing the changes. Before the operation, +`ORIG_HEAD` is set to the tip of the current branch (`C`). ------------ A---B---C topic diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index f9675bd24e..d811c1cf44 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -38,6 +38,13 @@ The current branch is reset to `<upstream>` or `<newbase>` if the `git reset --hard <upstream>` (or `<newbase>`). `ORIG_HEAD` is set to point at the tip of the branch before the reset. +[NOTE] +`ORIG_HEAD` is not guaranteed to still point to the previous branch tip +at the end of the rebase if other commands that write that pseudo-ref +(e.g. `git reset`) are used during the rebase. The previous branch tip, +however, is accessible using the reflog of the current branch +(i.e. `@{1}`, see linkgit:gitrevisions[7]). + The commits that were previously saved into the temporary area are then reapplied to the current branch, one by one, in order. Note that any commits in `HEAD` which introduce the same textual changes as a commit diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 01cb4c9b9c..79ad5643ee 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -49,7 +49,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 'git reset' [<mode>] [<commit>]:: This form resets the current branch head to `<commit>` and possibly updates the index (resetting it to the tree of `<commit>`) and - the working tree depending on `<mode>`. If `<mode>` is omitted, + the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD` + is set to the tip of the current branch. If `<mode>` is omitted, defaults to `--mixed`. The `<mode>` must be one of the following: + -- diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 5e438a7fdc..a051b1e8f3 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -457,6 +457,66 @@ during the write may conflict with other simultaneous processes, causing them to fail. Scripts running `status` in the background should consider using `git --no-optional-locks status` (see linkgit:git[1] for details). +UNTRACKED FILES AND PERFORMANCE +------------------------------- + +`git status` can be very slow in large worktrees if/when it +needs to search for untracked files and directories. There are +many configuration options available to speed this up by either +avoiding the work or making use of cached results from previous +Git commands. There is no single optimum set of settings right +for everyone. We'll list a summary of the relevant options to help +you, but before going into the list, you may want to run `git status` +again, because your configuration may already be caching `git status` +results, so it could be faster on subsequent runs. + +* The `--untracked-files=no` flag or the + `status.showUntrackedfiles=false` config (see above for both): + indicate that `git status` should not report untracked + files. This is the fastest option. `git status` will not list + the untracked files, so you need to be careful to remember if + you create any new files and manually `git add` them. + +* `advice.statusUoption=false` (see linkgit:git-config[1]): + setting this variable to `false` disables the warning message + given when enumerating untracked files takes more than 2 + seconds. In a large project, it may take longer and the user + may have already accepted the trade off (e.g. using "-uno" may + not be an acceptable option for the user), in which case, there + is no point issuing the warning message, and in such a case, + disabling the warning may be the best. + +* `core.untrackedCache=true` (see linkgit:git-update-index[1]): + enable the untracked cache feature and only search directories + that have been modified since the previous `git status` command. + Git remembers the set of untracked files within each directory + and assumes that if a directory has not been modified, then + the set of untracked files within has not changed. This is much + faster than enumerating the contents of every directory, but still + not without cost, because Git still has to search for the set of + modified directories. The untracked cache is stored in the + `.git/index` file. The reduced cost of searching for untracked + files is offset slightly by the increased size of the index and + the cost of keeping it up-to-date. That reduced search time is + usually worth the additional size. + +* `core.untrackedCache=true` and `core.fsmonitor=true` or + `core.fsmonitor=<hook_command_pathname>` (see + linkgit:git-update-index[1]): enable both the untracked cache + and FSMonitor features and only search directories that have + been modified since the previous `git status` command. This + is faster than using just the untracked cache alone because + Git can also avoid searching for modified directories. Git + only has to enumerate the exact set of directories that have + changed recently. While the FSMonitor feature can be enabled + without the untracked cache, the benefits are greatly reduced + in that case. + +Note that after you turn on the untracked cache and/or FSMonitor +features it may take a few `git status` commands for the various +caches to warm up before you see improved command times. This is +normal. + SEE ALSO -------- linkgit:gitignore[5] diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 6aa521fab2..f40202b8e3 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -13,7 +13,8 @@ SYNOPSIS DESCRIPTION ----------- -Prints a Git logical variable. +Prints a Git logical variable. Exits with code 1 if the variable has +no value. OPTIONS ------- @@ -49,6 +50,14 @@ ifdef::git-default-editor[] The build you are using chose '{git-default-editor}' as the default. endif::git-default-editor[] +GIT_SEQUENCE_EDITOR:: + Text editor used to edit the 'todo' file while running `git rebase + -i`. Like `GIT_EDITOR`, the value is meant to be interpreted by + the shell when it is used. The order of preference is the + `$GIT_SEQUENCE_EDITOR` environment variable, then + `sequence.editor` configuration, and then the value of `git var + GIT_EDITOR`. + GIT_PAGER:: Text viewer for use by Git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference 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/githooks.txt b/Documentation/githooks.txt index a16e62bc8c..62908602e7 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -27,6 +27,18 @@ repository. An exception are hooks triggered during a push ('pre-receive', 'update', 'post-receive', 'post-update', 'push-to-checkout') which are always executed in $GIT_DIR. +Environment variables, such as `GIT_DIR`, `GIT_WORK_TREE`, etc., are exported +so that Git commands run by the hook can correctly locate the repository. If +your hook needs to invoke Git commands in a foreign repository or in a +different working tree of the same repository, then it should clear these +environment variables so they do not interfere with Git operations at the +foreign location. For example: + +------------ +local_desc=$(git describe) +foreign_desc=$(unset $(git rev-parse --local-env-vars); git -C ../foreign-repo describe) +------------ + Hooks can get their arguments via the environment, command-line arguments, and stdin. See the documentation for each hook below for details. 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 diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 0d2e55d781..9aa58052bc 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -49,7 +49,8 @@ characters and to avoid word splitting. `FETCH_HEAD` records the branch which you fetched from a remote repository with your last `git fetch` invocation. `ORIG_HEAD` is created by commands that move your `HEAD` in a drastic -way, to record the position of the `HEAD` before their operation, so that +way (`git am`, `git merge`, `git rebase`, `git reset`), +to record the position of the `HEAD` before their operation, so that you can easily change the tip of the branch back to the state before you ran them. `MERGE_HEAD` records the commit(s) which you are merging into your branch |