diff options
Diffstat (limited to 'Documentation')
46 files changed, 629 insertions, 225 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index fc7de00aef..9d5c27807a 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -663,8 +663,8 @@ Writing Documentation: (One or more of <file>.) Optional parts are enclosed in square brackets: - [<extra>] - (Zero or one <extra>.) + [<file>...] + (Zero or more of <file>.) --exec-path[=<path>] (Option with an optional argument. Note that the "=" is inside the @@ -678,6 +678,16 @@ Writing Documentation: [-q | --quiet] [--utf8 | --no-utf8] + Use spacing around "|" token(s), but not immediately after opening or + before closing a [] or () pair: + Do: [-q | --quiet] + Don't: [-q|--quiet] + + Don't use spacing around "|" tokens when they're used to seperate the + alternate arguments of an option: + Do: --track[=(direct|inherit)] + Don't: --track[=(direct | inherit)] + Parentheses are used for grouping: [(<rev> | <range>)...] (Any number of either <rev> or <range>. Parens are needed to make diff --git a/Documentation/RelNotes/2.38.2.txt b/Documentation/RelNotes/2.38.2.txt new file mode 100644 index 0000000000..086b900f6c --- /dev/null +++ b/Documentation/RelNotes/2.38.2.txt @@ -0,0 +1,60 @@ +Git 2.38.2 Release Notes +======================== + +This is to backport various fixes accumulated during the development +towards Git 2.39, the next feature release. + + +Fixes since v2.38.1 +------------------- + + * Update CodingGuidelines to clarify what features to use and avoid + in C99. + + * The codepath that reads from the index v4 had unaligned memory + accesses, which has been corrected. + + * "git remote rename" failed to rename a remote without fetch + refspec, which has been corrected. + + * "git clone" did not like to see the "--bare" and the "--origin" + options used together without a good reason. + + * Fix messages incorrectly marked for translation. + + * "git fsck" failed to release contents of tree objects already used + from the memory, which has been fixed. + + * "git rebase -i" can mistakenly attempt to apply a fixup to a commit + itself, which has been corrected. + + * In read-only repositories, "git merge-tree" tried to come up with a + merge result tree object, which it failed (which is not wrong) and + led to a segfault (which is bad), which has been corrected. + + * Force C locale while running tests around httpd to make sure we can + find expected error messages in the log. + + * Fix a logic in "mailinfo -b" that miscomputed the length of a + substring, which lead to an out-of-bounds access. + + * The codepath to sign learned to report errors when it fails to read + from "ssh-keygen". + + * "GIT_EDITOR=: git branch --edit-description" resulted in failure, + which has been corrected. + + * Documentation on various Boolean GIT_* environment variables have + been clarified. + + * "git multi-pack-index repack/expire" used to repack unreachable + cruft into a new pack, which have been corrected. + + * The code to clean temporary object directories (used for + quarantine) tried to remove them inside its signal handler, which + was a no-no. + + * "git branch --edit-description" on an unborh branch misleadingly + said that no such branch exists, which has been corrected. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.39.0.txt b/Documentation/RelNotes/2.39.0.txt index 8153661826..f87c4c442e 100644 --- a/Documentation/RelNotes/2.39.0.txt +++ b/Documentation/RelNotes/2.39.0.txt @@ -45,89 +45,75 @@ Performance, Internal Implementation, Development Support etc. * Update CodingGuidelines to clarify what features to use and avoid in C99. - (merge 438c2f859b ab/coding-guidelines-c99 later to maint). * Avoid false-positive from LSan whose assumption may be broken with higher optimization levels. + * Enable address and undefined sanitizer tasks at GitHub Actions CI. + + * More UNUSED annotation to help using -Wunused option with the + compiler. + (merge 4b992f0a24 jk/unused-anno-more later to maint). + Fixes since v2.38 ----------------- * The codepath that reads from the index v4 had unaligned memory accesses, which has been corrected. - (merge 4a6ed30f96 vd/fix-unaligned-read-index-v4 later to maint). * Fix messages incorrectly marked for translation. - (merge 02cb8b9ee3 ah/fsmonitor-daemon-usage-non-l10n later to maint). * "git fsck" failed to release contents of tree objects already used from the memory, which has been fixed. - (merge 51b27747e5 jk/fsck-on-diet later to maint). * "git clone" did not like to see the "--bare" and the "--origin" options used together without a good reason. - (merge 3b910d6e29 jk/clone-allow-bare-and-o-together later to maint). * "git remote rename" failed to rename a remote without fetch refspec, which has been corrected. - (merge 5a97b38109 jk/remote-rename-without-fetch-refspec later to maint). * Documentation on various Boolean GIT_* environment variables have been clarified. - (merge 819fb68222 jc/environ-docs later to maint). * "git rebase -i" can mistakenly attempt to apply a fixup to a commit itself, which has been corrected. - (merge 3e367a5f2f ja/rebase-i-avoid-amending-self later to maint). * "git multi-pack-index repack/expire" used to repack unreachable cruft into a new pack, which have been corrected. - (merge b62ad5681f tb/midx-repack-ignore-cruft-packs later to maint). * In read-only repositories, "git merge-tree" tried to come up with a merge result tree object, which it failed (which is not wrong) and led to a segfault (which is bad), which has been corrected. - (merge 92481d1b26 js/merge-ort-in-read-only-repo later to maint). * Force C locale while running tests around httpd to make sure we can find expected error messages in the log. - (merge 7a2d8ea47e rs/test-httpd-in-C-locale later to maint). * Fix a logic in "mailinfo -b" that miscomputed the length of a substring, which lead to an out-of-bounds access. - (merge 3ef1494685 pw/mailinfo-b-fix later to maint). * The codepath to sign learned to report errors when it fails to read from "ssh-keygen". - (merge 36fb0d07d8 pw/ssh-sign-report-errors later to maint). * Code clean-up that results in plugging a leak. - (merge 246526d019 rs/bisect-start-leakfix later to maint). * "GIT_EDITOR=: git branch --edit-description" resulted in failure, which has been corrected. - (merge e288b3de35 jc/branch-description-unset later to maint). * The code to clean temporary object directories (used for quarantine) tried to remove them inside its signal handler, which was a no-no. - (merge 22613b25ec jc/tmp-objdir later to maint). * Update comment in the Makefile about the RUNTIME_PREFIX config knob. - (merge ebb6c16607 dd/document-runtime-prefix-better later to maint). * Clarify that "the sentence after <area>: prefix does not begin with a capital letter" rule applies only to the commit title. - (merge 3991bb73dd jc/use-of-uc-in-log-messages later to maint). * "git branch --edit-description" on an unborh branch misleadingly said that no such branch exists, which has been corrected. - (merge bcfc82bd48 rj/branch-edit-desc-unborn later to maint). * Work around older clang that warns against C99 zero initialization syntax for struct. - (merge 54795d37d9 jh/struct-zero-init-with-older-clang later to maint). * Giving "--invert-grep" and "--all-match" without "--grep" to the "git log" command resulted in an attempt to access grep pattern @@ -135,19 +121,47 @@ Fixes since v2.38 corrected. (merge db84376f98 ab/grep-simplify-extended-expression later to maint). + * "git diff rev^!" did not show combined diff to go to the rev from + its parents. + (merge a79c6b6081 rs/diff-caret-bang-with-parents later to maint). + + * Allow configuration files in "protected" scopes to include other + configuration files. + (merge ecec57b3c9 gc/bare-repo-discovery later to maint). + + * Give a bit more diversity to macOS CI by using sha1dc in one of the + jobs (the other one tests Apple Common Crypto). + (merge 1ad5c3df35 jc/ci-osx-with-sha1dc later to maint). + + * A bugfix with tracing support in midx codepath + (merge e9c3839944 tb/midx-bitmap-selection-fix later to maint). + + * When geometric repacking feature is in use together with the + --pack-kept-objects option, we lost packs marked with .keep files. + (merge 197443e80a tb/save-keep-pack-during-geometric-repack later to maint). + + * Move a global variable added as a hack during regression fixes to + its proper place in the API. + (merge 0b0ab95f17 ab/run-hook-api-cleanup later to maint). + + * Update to build procedure with VS using CMake/CTest. + (merge c858750b41 js/cmake-updates later to maint). + + * The short-help text shown by "git cmd -h" and the synopsis text + shown at the beginning of "git help cmd" have been made more + consistent. + + * When creating a multi-pack bitmap, remove per-pack bitmap files + unconditionally as they will never be consulted. + (merge 55d902cd61 tb/remove-unused-pack-bitmap later to maint). + + * Fix a longstanding syntax error in Git.pm error codepath. + + * "git diff --stat" etc. were invented back when everything was ASCII + and strlen() was a way to measure the display width of a string; + adjust them to compute the display width assuming UTF-8 pathnames. + (merge ce8529b2bb tb/diffstat-with-utf8-strwidth later to maint). + * Other code cleanup, docfix, build fix, etc. - (merge c34a6bd291 so/diff-merges-cleanup later to maint). - (merge 5e7c8b75e7 ab/test-malloc-with-sanitize-leak later to maint). - (merge 2a905f8fa8 ah/branch-autosetupmerge-grammofix later to maint). - (merge abcac2e19f rj/ref-filter-get-head-description-leakfix later to maint). - (merge 71e5473493 hn/parse-worktree-ref later to maint). - (merge 7190b7ebf9 ds/bundle-uri-docfix later to maint). - (merge 45350aeb11 jk/sequencer-missing-author-name-check later to maint). - (merge edbf9a2e20 nb/doc-mergetool-typofix later to maint). - (merge b004c90282 rs/gc-pack-refs-simplify later to maint). - (merge 69c5f17f11 jk/cleanup-callback-parameters later to maint). - (merge 7c07f36ad2 ab/unused-annotation later to maint). - (merge f7669676d0 rs/use-fspathncmp later to maint). - (merge a677d3c416 pw/remove-rebase-p-test later to maint). - (merge e3733b646d rs/archive-dedup-printf later to maint). (merge 413bc6d20a ds/cmd-main-reorder later to maint). + (merge 8d2863e4ed nw/t1002-cleanup later to maint). diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl index ba4205e030..1b3ac8fdd9 100755 --- a/Documentation/build-docdep.perl +++ b/Documentation/build-docdep.perl @@ -38,9 +38,10 @@ while ($changed) { } } -while (my ($text, $included) = each %include) { +foreach my $text (sort keys %include) { + my $included = $include{$text}; if (! exists $included{$text} && (my $base = $text) =~ s/\.txt$//) { - print "$base.html $base.xml : ", join(" ", keys %$included), "\n"; + print "$base.html $base.xml : ", join(" ", sort keys %$included), "\n"; } } diff --git a/Documentation/config.txt b/Documentation/config.txt index 1e20583165..0e93aef862 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -387,6 +387,8 @@ include::config/branch.txt[] include::config/browser.txt[] +include::config/bundle.txt[] + include::config/checkout.txt[] include::config/clean.txt[] diff --git a/Documentation/config/bundle.txt b/Documentation/config/bundle.txt new file mode 100644 index 0000000000..daa21eb674 --- /dev/null +++ b/Documentation/config/bundle.txt @@ -0,0 +1,24 @@ +bundle.*:: + The `bundle.*` keys may appear in a bundle list file found via the + `git clone --bundle-uri` option. These keys currently have no effect + if placed in a repository config file, though this will change in the + future. See link:technical/bundle-uri.html[the bundle URI design + document] for more details. + +bundle.version:: + This integer value advertises the version of the bundle list format + used by the bundle list. Currently, the only accepted value is `1`. + +bundle.mode:: + This string value should be either `all` or `any`. This value describes + whether all of the advertised bundles are required to unbundle a + complete understanding of the bundled information (`all`) or if any one + of the listed bundle URIs is sufficient (`any`). + +bundle.<id>.*:: + The `bundle.<id>.*` keys are used to describe a single item in the + bundle list, grouped under `<id>` for identification purposes. + +bundle.<id>.uri:: + This string value defines the URI by which Git can reach the contents + of this `<id>`. This URI may be a bundle file or another bundle list. diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index e44a831339..5ae8aabe0f 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -8,7 +8,7 @@ git-annotate - Annotate file lines with commit information SYNOPSIS -------- [verse] -'git annotate' [<options>] <file> [<revision>] +'git annotate' [<options>] [<rev-opts>] [<rev>] [--] <file> DESCRIPTION ----------- diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 91742633fa..160d08b86b 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... +'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] [<pathspec>...] DESCRIPTION ----------- @@ -20,16 +20,16 @@ Normally, only files unknown to Git are removed, but if the `-x` option is specified, ignored files are also removed. This can, for example, be useful to remove all build products. -If any optional `<path>...` arguments are given, only those paths -are affected. +If any optional `<pathspec>...` arguments are given, only those paths +that match the pathspec are affected. OPTIONS ------- -d:: - Normally, when no <path> is specified, git clean will not + Normally, when no <pathspec> is specified, git clean will not recurse into untracked directories to avoid removing too much. Specify -d to have it recurse into such directories as well. - If any paths are specified, -d is irrelevant; all untracked + If a <pathspec> is specified, -d is irrelevant; all untracked files matching the specified paths (with exceptions for nested git directories mentioned under `--force`) will be removed. diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index 36fe56c2c7..c8dbceba01 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -10,7 +10,10 @@ SYNOPSIS -------- [verse] 'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress] -'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress] +'git commit-graph write' [--object-dir <dir>] [--append] + [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits] + [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] + <split options> DESCRIPTION diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt index 01e1c214dd..650a15a7ed 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- [verse] -'git credential-cache{litdd}daemon' [--debug] <socket> +'git credential-cache{litdd}daemon' [--debug] <socket-path> DESCRIPTION ----------- @@ -16,7 +16,7 @@ DESCRIPTION NOTE: You probably don't want to invoke this command yourself; it is started automatically when you use linkgit:git-credential-cache[1]. -This command listens on the Unix domain socket specified by `<socket>` +This command listens on the Unix domain socket specified by `<socket-path>` for `git-credential-cache` clients. Clients may store and retrieve credentials. Each credential is held for a timeout specified by the client; once no credentials are held, the daemon exits. diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index bf1febb9ae..591e3801b7 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index SYNOPSIS -------- [verse] -'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...] +'git diff-files' [-q] [-0 | -1 | -2 | -3 | -c | --cc] [<common-diff-options>] [<path>...] DESCRIPTION ----------- diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 85ae6d6d08..52b679256c 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -79,10 +79,10 @@ If --merge-base is given, use the merge base of the two commits for the This form is to view the results of a merge commit. The first listed <commit> must be the merge itself; the remaining two or - more commits should be its parents. A convenient way to produce - the desired set of revisions is to use the `^@` suffix. - For instance, if `master` names a merge commit, `git diff master - master^@` gives the same combined diff as `git show master`. + more commits should be its parents. Convenient ways to produce + the desired set of revisions are to use the suffixes `^@` and + `^!`. If A is a merge commit, then `git diff A A^@`, + `git diff A^!` and `git show A` all give the same combined diff. 'git diff' [<options>] <commit>..<commit> [--] [<path>...]:: diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 1978dbdc6a..4643ddbe68 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -9,7 +9,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- [verse] -'git fast-export [<options>]' | 'git fast-import' +'git fast-export' [<options>] | 'git fast-import' DESCRIPTION ----------- diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index df9e2c58bd..472b5bb995 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -9,7 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file SYNOPSIS -------- [verse] -'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>... +'git hash-object' [-t <type>] [-w] [--path=<file> | --no-filters] + [--stdin [--literally]] [--] <file>... 'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] DESCRIPTION diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 6d6197cd0a..22ff3a603e 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -8,8 +8,9 @@ git-interpret-trailers - Add or parse structured information in commit messages SYNOPSIS -------- [verse] -'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...] -'git interpret-trailers' [<options>] [--parse] [<file>...] +'git interpret-trailers' [--in-place] [--trim-empty] + [(--trailer <token>[(=|:)<value>])...] + [--parse] [<file>...] DESCRIPTION ----------- diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 2d944e0851..b01ba3d356 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -9,8 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- [verse] -'git merge-base' [-a|--all] <commit> <commit>... -'git merge-base' [-a|--all] --octopus <commit>... +'git merge-base' [-a | --all] <commit> <commit>... +'git merge-base' [-a | --all] --octopus <commit>... 'git merge-base' --is-ancestor <commit> <commit> 'git merge-base' --independent <commit>... 'git merge-base' --fork-point <ref> [<commit>] diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index d6c356740e..04bcc416e6 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -81,6 +81,31 @@ Whereas for a conflicted merge, the output is by default of the form: These are discussed individually below. +However, there is an exception. If `--stdin` is passed, then there is +an extra section at the beginning, a NUL character at the end, and then +all the sections repeat for each line of input. Thus, if the first merge +is conflicted and the second is clean, the output would be of the form: + + <Merge status> + <OID of toplevel tree> + <Conflicted file info> + <Informational messages> + NUL + <Merge status> + <OID of toplevel tree> + NUL + +[[MS]] +Merge status +~~~~~~~~~~~~ + +This is an integer status followed by a NUL character. The integer status is: + + 0: merge had conflicts + 1: merge was clean + <0: something prevented the merge from running (e.g. access to repository + objects denied by filesystem) + [[OIDTLT]] OID of toplevel tree ~~~~~~~~~~~~~~~~~~~~ @@ -108,18 +133,50 @@ character instead of a newline character. Informational messages ~~~~~~~~~~~~~~~~~~~~~~ -This always starts with a blank line (or NUL if `-z` is passed) to -separate it from the previous sections, and then has free-form -messages about the merge, such as: +This section provides informational messages, typically about +conflicts. The format of the section varies significantly depending +on whether `-z` is passed. + +If `-z` is passed: + +The output format is zero or more conflict informational records, each +of the form: + + <list-of-paths><conflict-type>NUL<conflict-message>NUL + +where <list-of-paths> is of the form + + <number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL + +and includes paths (or branch names) affected by the conflict or +informational message in <conflict-message>. Also, <conflict-type> is a +stable string explaining the type of conflict, such as + + * "Auto-merging" + * "CONFLICT (rename/delete)" + * "CONFLICT (submodule lacks merge base)" + * "CONFLICT (binary)" + +and <conflict-message> is a more detailed message about the conflict which often +(but not always) embeds the <stable-short-type-description> within it. These +strings may change in future Git versions. Some examples: * "Auto-merging <file>" * "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..." - * "Failed to merge submodule <submodule> (<reason>)" + * "Failed to merge submodule <submodule> (no merge base)" * "Warning: cannot merge binary files: <filename>" -Note that these free-form messages will never have a NUL character -in or between them, even if -z is passed. It is simply a large block -of text taking up the remainder of the output. +If `-z` is NOT passed: + +This section starts with a blank line to separate it from the previous +sections, and then only contains the <conflict-message> information +from the previous section (separated by newlines). These are +non-stable strings that should not be parsed by scripts, and are just +meant for human consumption. Also, note that while <conflict-message> +strings usually do not contain embedded newlines, they sometimes do. +(However, the free-form messages will never have an embedded NUL +character). So, the entire block of information is meant for human +readers as an agglomeration of all conflict messages. EXIT STATUS ----------- @@ -127,7 +184,10 @@ EXIT STATUS For a successful, non-conflicted merge, the exit status is 0. When the merge has conflicts, the exit status is 1. If the merge is not able to complete (or start) due to some kind of error, the exit status is -something other than 0 or 1 (and the output is unspecified). +something other than 0 or 1 (and the output is unspecified). When +--stdin is passed, the return status is 0 for both successful and +conflicted merges, and something other than 0 or 1 if it cannot complete +all the requested merges. USAGE NOTES ----------- diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 79449bf98f..fb0220fd18 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -9,7 +9,7 @@ git-mv - Move or rename a file, a directory, or a symlink SYNOPSIS -------- [verse] -'git mv' <options>... <args>... +'git mv' [<options>] <source>... <destination> DESCRIPTION ----------- @@ -30,7 +30,7 @@ OPTIONS ------- -f:: --force:: - Force renaming or moving of a file even if the target exists + Force renaming or moving of a file even if the <destination> exists. -k:: Skip move or rename actions which would lead to an error condition. An error happens when a source is neither existing nor diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index ee7034b5e5..dda80a740c 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files SYNOPSIS -------- [verse] -'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... ) +'git pack-redundant' [--verbose] [--alt-odb] (--all | <pack-filename>...) DESCRIPTION ----------- diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 442caff8a9..1d15fa45d5 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -8,18 +8,18 @@ git-patch-id - Compute unique ID for a patch SYNOPSIS -------- [verse] -'git patch-id' [--stable | --unstable] +'git patch-id' [--stable | --unstable | --verbatim] DESCRIPTION ----------- Read a patch from the standard input and compute the patch ID for it. A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a -patch, with whitespace and line numbers ignored. As such, it's "reasonably -stable", but at the same time also reasonably unique, i.e., two patches that -have the same "patch ID" are almost guaranteed to be the same thing. +patch, with line numbers ignored. As such, it's "reasonably stable", but at +the same time also reasonably unique, i.e., two patches that have the same +"patch ID" are almost guaranteed to be the same thing. -IOW, you can use this thing to look for likely duplicate commits. +The main usecase for this command is to look for likely duplicate commits. When dealing with 'git diff-tree' output, it takes advantage of the fact that the patch is prefixed with the object name of the @@ -30,6 +30,12 @@ This can be used to make a mapping from patch ID to commit ID. OPTIONS ------- +--verbatim:: + Calculate the patch-id of the input as it is given, do not strip + any whitespace. + + This is the default if patchid.verbatim is true. + --stable:: Use a "stable" sum of hashes as the patch ID. With this option: - Reordering file diffs that make up a patch does not affect the ID. @@ -45,14 +51,16 @@ OPTIONS of "-O<orderfile>", thereby making existing databases storing such "unstable" or historical patch-ids unusable. + - All whitespace within the patch is ignored and does not affect the id. + This is the default if patchid.stable is set to true. --unstable:: Use an "unstable" hash as the patch ID. With this option, the result produced is compatible with the patch-id value produced - by git 1.9 and older. Users with pre-existing databases storing - patch-ids produced by git 1.9 and older (who do not deal with reordered - patches) may want to use this option. + by git 1.9 and older and whitespace is ignored. Users with pre-existing + databases storing patch-ids produced by git 1.9 and older (who do not deal + with reordered patches) may want to use this option. This is the default. diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index 9fed59a317..844d6f808a 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -9,7 +9,7 @@ git-prune-packed - Remove extra objects that are already in pack files SYNOPSIS -------- [verse] -'git prune-packed' [-n|--dry-run] [-q|--quiet] +'git prune-packed' [-n | --dry-run] [-q | --quiet] DESCRIPTION diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index b9bfdc0a31..7567955bad 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -9,7 +9,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- [verse] -'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] +'git read-tree' [(-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>) [-u | -i]] [--index-output=<file>] [--no-sparse-checkout] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]]) diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 9cb8931c7a..f9675bd24e 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -218,12 +218,14 @@ leave out at most one of A and B, in which case it defaults to HEAD. merge base of `<upstream>` and `<branch>`. Running `git rebase --keep-base <upstream> <branch>` is equivalent to running - `git rebase --onto <upstream>...<branch> <upstream> <branch>`. + `git rebase --reapply-cherry-picks --no-fork-point --onto <upstream>...<branch> <upstream> <branch>`. + This option is useful in the case where one is developing a feature on top of an upstream branch. While the feature is being worked on, the upstream branch may advance and it may not be the best idea to keep -rebasing on top of the upstream but to keep the base commit as-is. +rebasing on top of the upstream but to keep the base commit as-is. As +the base commit is unchanged this option implies `--reapply-cherry-picks` +to avoid losing commits. + Although both this option and `--fork-point` find the merge base between `<upstream>` and `<branch>`, this option uses the merge base as the _starting @@ -278,7 +280,8 @@ See also INCOMPATIBLE OPTIONS below. Note that commits which start empty are kept (unless `--no-keep-empty` is specified), and commits which are clean cherry-picks (as determined by `git log --cherry-mark ...`) are detected and dropped as a -preliminary step (unless `--reapply-cherry-picks` is passed). +preliminary step (unless `--reapply-cherry-picks` or `--keep-base` is +passed). + See also INCOMPATIBLE OPTIONS below. @@ -311,13 +314,16 @@ See also INCOMPATIBLE OPTIONS below. upstream changes, the behavior towards them is controlled by the `--empty` flag.) + -By default (or if `--no-reapply-cherry-picks` is given), these commits -will be automatically dropped. Because this necessitates reading all -upstream commits, this can be expensive in repos with a large number -of upstream commits that need to be read. When using the 'merge' -backend, warnings will be issued for each dropped commit (unless -`--quiet` is given). Advice will also be issued unless -`advice.skippedCherryPicks` is set to false (see linkgit:git-config[1]). + +In the absence of `--keep-base` (or if `--no-reapply-cherry-picks` is +given), these commits will be automatically dropped. Because this +necessitates reading all upstream commits, this can be expensive in +repositories with a large number of upstream commits that need to be +read. When using the 'merge' backend, warnings will be issued for each +dropped commit (unless `--quiet` is given). Advice will also be issued +unless `advice.skippedCherryPicks` is set to false (see +linkgit:git-config[1]). + + `--reapply-cherry-picks` allows rebase to forgo reading all upstream commits, potentially improving performance. @@ -443,9 +449,9 @@ When `--fork-point` is active, 'fork_point' will be used instead of <branch>` command (see linkgit:git-merge-base[1]). If 'fork_point' ends up being empty, the `<upstream>` will be used as a fallback. + -If `<upstream>` is given on the command line, then the default is -`--no-fork-point`, otherwise the default is `--fork-point`. See also -`rebase.forkpoint` in linkgit:git-config[1]. +If `<upstream>` or `--keep-base` is given on the command line, then +the default is `--no-fork-point`, otherwise the default is +`--fork-point`. See also `rebase.forkpoint` in linkgit:git-config[1]. + If your branch was based on `<upstream>` but `<upstream>` was rewound and your branch contains commits which were dropped, this option can be used diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 014a78409b..65ff518ccf 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -9,7 +9,7 @@ git-receive-pack - Receive what is pushed into the repository SYNOPSIS -------- [verse] -'git-receive-pack' <directory> +'git receive-pack' <git-dir> DESCRIPTION ----------- @@ -38,7 +38,7 @@ its behavior, see linkgit:git-config[1]. OPTIONS ------- -<directory>:: +<git-dir>:: The repository to sync into. --http-backend-info-refs:: diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index db9d46edfa..ec64cbff4c 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -9,15 +9,7 @@ git-reflog - Manage reflog information SYNOPSIS -------- [verse] -'git reflog' <subcommand> <options> - -DESCRIPTION ------------ -The command takes various subcommands, and different options -depending on the subcommand: - -[verse] -'git reflog' ['show'] [<log-options>] [<ref>] +'git reflog' [show] [<log-options>] [<ref>] 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>] [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] @@ -25,6 +17,10 @@ depending on the subcommand: [--dry-run | -n] [--verbose] <ref>@{<specifier>}... 'git reflog exists' <ref> +DESCRIPTION +----------- +This command manages the information recorded in the reflogs. + Reference logs, or "reflogs", record when the tips of branches and other references were updated in the local repository. Reflogs are useful in various Git commands, to specify the old value of a @@ -33,7 +29,8 @@ moves ago", `master@{one.week.ago}` means "where master used to point to one week ago in this local repository", and so on. See linkgit:gitrevisions[7] for more details. -This command manages the information recorded in the reflogs. +The command takes various subcommands, and different options +depending on the subcommand: The "show" subcommand (which is also the default, in the absence of any subcommands) shows the log of the reference provided in the diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index 4cfc883378..992b469270 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- [verse] -'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc'] +'git rerere' [clear | forget <pathspec>... | diff | status | remaining | gc] DESCRIPTION ----------- diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 20bb8e8217..51029a2271 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -9,7 +9,7 @@ git-rev-list - Lists commit objects in reverse chronological order SYNOPSIS -------- [verse] -'git rev-list' [<options>] <commit>... [[--] <path>...] +'git rev-list' [<options>] <commit>... [--] [<path>...] DESCRIPTION ----------- diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 3290043053..765b2df853 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -178,9 +178,18 @@ Sending for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH. --smtp-encryption=<encryption>:: - Specify the encryption to use, either 'ssl' or 'tls'. Any other - value reverts to plain SMTP. Default is the value of - `sendemail.smtpEncryption`. + Specify in what way encrypting begins for the SMTP connection. + Valid values are 'ssl' and 'tls'. Any other value reverts to plain + (unencrypted) SMTP, which defaults to port 25. + Despite the names, both values will use the same newer version of TLS, + but for historic reasons have these names. 'ssl' refers to "implicit" + encryption (sometimes called SMTPS), that uses port 465 by default. + 'tls' refers to "explicit" encryption (often known as STARTTLS), + that uses port 25 by default. Other ports might be used by the SMTP + server, which are not the default. Commonly found alternative port for + 'tls' and unencrypted is 587. You need to check your provider's + documentation or your server configuration to make sure + for your own case. Default is the value of `sendemail.smtpEncryption`. --smtp-domain=<FQDN>:: Specifies the Fully Qualified Domain Name (FQDN) used in the diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index be41f11974..595b002152 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -9,9 +9,10 @@ git-send-pack - Push objects over Git protocol to another repository SYNOPSIS -------- [verse] -'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>] +'git send-pack' [--mirror] [--dry-run] [--force] + [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [--atomic] - [--[no-]signed|--signed=(true|false|if-asked)] + [--[no-]signed | --signed=(true|false|if-asked)] [<host>:]<directory> (--all | <ref>...) DESCRIPTION diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index f64e77047b..7d0277d033 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -47,6 +47,11 @@ OPTIONS Each pretty-printed commit will be rewrapped before it is shown. +--date=<format>:: + Show dates formatted according to the given date string. (See + the `--date` option in the "Commit Formatting" section of + linkgit:git-log[1]). Useful with `--group=format:<format>`. + --group=<type>:: Group commits based on `<type>`. If no `--group` option is specified, the default is `author`. `<type>` is one of: @@ -59,6 +64,9 @@ OPTIONS example, if your project uses `Reviewed-by` trailers, you might want to see who has been reviewing with `git shortlog -ns --group=trailer:reviewed-by`. + - `format:<format>`, any string accepted by the `--format` option of + 'git log'. (See the "PRETTY FORMATS" section of + linkgit:git-log[1].) + Note that commits that do not include the trailer will not be counted. Likewise, commits with multiple trailers (e.g., multiple signoffs) may diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index e5ec6b467f..71f608b1ff 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -8,12 +8,12 @@ git-show-branch - Show branches and their commits SYNOPSIS -------- [verse] -'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order] +'git show-branch' [-a | --all] [-r | --remotes] [--topo-order | --date-order] [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...] -'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] +'git show-branch' (-g | --reflog)[=<n>[,<base>]] [--list] [<ref>] DESCRIPTION ----------- diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index ab4d271925..d1d56f68b4 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -8,8 +8,8 @@ git-show-ref - List references in a local repository SYNOPSIS -------- [verse] -'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference] - [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] +'git show-ref' [-q | --quiet] [--verify] [--head] [-d | --dereference] + [-s | --hash[=<n>]] [--abbrev[=<n>]] [--tags] [--heads] [--] [<pattern>...] 'git show-ref' --exclude-existing[=<pattern>] diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 3776705bf5..68392d2a56 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files SYNOPSIS -------- [verse] -'git sparse-checkout <subcommand> [<options>]' +'git sparse-checkout' (init | list | set | add | reapply | disable) [<options>] DESCRIPTION diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index c5d7091828..f4bb6114d9 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,17 +9,20 @@ SYNOPSIS -------- [verse] 'git stash' list [<log-options>] -'git stash' show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>] -'git stash' drop [-q|--quiet] [<stash>] -'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] +'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>] +'git stash' drop [-q | --quiet] [<stash>] +'git stash' pop [--index] [-q | --quiet] [<stash>] +'git stash' apply [--index] [-q | --quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-q|--quiet] - [-u|--include-untracked] [-a|--all] [-m|--message <message>] +'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet] + [-u | --include-untracked] [-a | --all] [(-m | --message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]] +'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet] + [-u | --include-untracked] [-a | --all] [<message>] 'git stash' clear 'git stash' create [<message>] -'git stash' store [-m|--message <message>] [-q|--quiet] <commit> +'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit> DESCRIPTION ----------- @@ -47,7 +50,7 @@ stash index (e.g. the integer `n` is equivalent to `stash@{n}`). COMMANDS -------- -push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: +push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]:: Save your local modifications to a new 'stash entry' and roll them back to HEAD (in the working tree and in the index). diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 54a4b29b47..5e438a7fdc 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -9,7 +9,7 @@ git-status - Show the working tree status SYNOPSIS -------- [verse] -'git status' [<options>...] [--] [<pathspec>...] +'git status' [<options>] [--] [<pathspec>...] DESCRIPTION ----------- diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 31a97a1b6c..fdc72b5875 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -9,7 +9,7 @@ git-tag - Create, list, delete or verify a tag object signed with GPG SYNOPSIS -------- [verse] -'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e] +'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>] @@ -26,19 +26,19 @@ to delete, list or verify tags. Unless `-f` is given, the named tag must not yet exist. -If one of `-a`, `-s`, or `-u <keyid>` is passed, the command +If one of `-a`, `-s`, or `-u <key-id>` is passed, the command creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. -If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>` +If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. Otherwise, a tag reference that points directly at the given object (i.e., a lightweight tag) is created. A GnuPG signed tag object will be created when `-s` or `-u -<keyid>` is used. When `-u <keyid>` is not used, the +<key-id>` is used. When `-u <key-id>` is not used, the committer identity for the current user is used to find the GnuPG key for signing. The configuration variable `gpg.program` is used to specify custom GnuPG binary. @@ -72,8 +72,8 @@ OPTIONS Override `tag.gpgSign` configuration variable that is set to force each and every tag to be signed. --u <keyid>:: ---local-user=<keyid>:: +-u <key-id>:: +--local-user=<key-id>:: Make a GPG-signed tag, using the given key. -f:: @@ -164,14 +164,14 @@ This option is only applicable when listing tags without annotation lines. Use the given tag message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. - Implies `-a` if none of `-a`, `-s`, or `-u <keyid>` + Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. -F <file>:: --file=<file>:: Take the tag message from the given file. Use '-' to read the message from the standard input. - Implies `-a` if none of `-a`, `-s`, or `-u <keyid>` + Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. -e:: @@ -220,7 +220,7 @@ it in the repository configuration as follows: ------------------------------------- [user] - signingKey = <gpg-keyid> + signingKey = <gpg-key_id> ------------------------------------- `pager.tag` is only respected when listing tags, i.e., when `-l` is diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 969bb2e15f..17e429dbd0 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -9,7 +9,7 @@ git-update-server-info - Update auxiliary info file to help dumb servers SYNOPSIS -------- [verse] -'git update-server-info' +'git update-server-info' [-f | --force] DESCRIPTION ----------- @@ -19,6 +19,12 @@ $GIT_OBJECT_DIRECTORY/info directories to help clients discover what references and packs the server has. This command generates such auxiliary files. +OPTIONS +------- +-f:: +--force:: + update the info files from scratch. + OUTPUT ------ diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt index fba0f1c1b2..e8eb10baad 100644 --- a/Documentation/git-upload-archive.txt +++ b/Documentation/git-upload-archive.txt @@ -9,7 +9,7 @@ git-upload-archive - Send archive back to git-archive SYNOPSIS -------- [verse] -'git upload-archive' <directory> +'git upload-archive' <repository> DESCRIPTION ----------- @@ -54,7 +54,7 @@ access via non-smart-http. OPTIONS ------- -<directory>:: +<repository>:: The repository to get a tar archive from. GIT diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 387cc1b914..6aa521fab2 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -9,7 +9,7 @@ git-var - Show a Git logical variable SYNOPSIS -------- [verse] -'git var' ( -l | <variable> ) +'git var' (-l | <variable>) DESCRIPTION ----------- diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt index 92097f6673..aee4c40eac 100644 --- a/Documentation/git-verify-commit.txt +++ b/Documentation/git-verify-commit.txt @@ -8,7 +8,7 @@ git-verify-commit - Check the GPG signature of commits SYNOPSIS -------- [verse] -'git verify-commit' <commit>... +'git verify-commit' [-v | --verbose] [--raw] <commit>... DESCRIPTION ----------- diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 61ca6d04c2..b8720dce8a 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -9,7 +9,7 @@ git-verify-pack - Validate packed Git archive files SYNOPSIS -------- [verse] -'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... +'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx... DESCRIPTION diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index 0b8075dad9..81d50ecc4c 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -8,7 +8,7 @@ git-verify-tag - Check the GPG signature of tags SYNOPSIS -------- [verse] -'git verify-tag' [--format=<format>] <tag>... +'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>... DESCRIPTION ----------- diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index ada30c86a7..063d6eeb99 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- [verse] -'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>] +'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] + [-b <new-branch>] <path> [<commit-ish>] 'git worktree list' [-v | --porcelain [-z]] 'git worktree lock' [--reason <string>] <worktree> 'git worktree move' <worktree> <new-path> diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.txt index 601aae88e9..e653775bab 100644 --- a/Documentation/howto/coordinate-embargoed-releases.txt +++ b/Documentation/howto/coordinate-embargoed-releases.txt @@ -1,9 +1,10 @@ Content-type: text/asciidoc -Abstract: When a critical vulnerability is discovered and fixed, we follow this - script to coordinate a public release. +Abstract: When a vulnerability is reported, we follow these guidelines to + assess the vulnerability, create and review a fix, and coordinate embargoed + security releases. How we coordinate embargoed releases -==================================== +------------------------------------ To protect Git users from critical vulnerabilities, we do not just release fixed versions like regular maintenance releases. Instead, we coordinate @@ -11,33 +12,147 @@ releases with packagers, keeping the fixes under an embargo until the release date. That way, users will have a chance to upgrade on that date, no matter what Operating System or distribution they run. -Open a Security Advisory draft ------------------------------- +The `git-security` mailing list +------------------------------- + +Responsible disclosures of vulnerabilities, analysis, proposed fixes as +well as the orchestration of coordinated embargoed releases all happen on the +`git-security` mailing list at <git-security@googlegroups.com>. + +In this context, the term "embargo" refers to the time period that information +about a vulnerability is kept under wraps and only shared on a need-to-know +basis. This is necessary to protect Git's users from bad actors who would +otherwise be made aware of attack vectors that could be exploited. "Lifting the +embargo" refers to publishing the version that fixes the vulnerabilities. + +Audience of the `git-security` mailing list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Anybody may contact the `git-security` mailing list by sending an email +to <git-security@googlegroups.com>, though the archive is closed to the +public and only accessible to subscribed members. + +There are a few dozen subscribed members: core Git developers who are trusted +with addressing vulnerabilities, and stakeholders (i.e. owners of products +affected by security vulnerabilities in Git). + +Most of the discussions revolve around assessing the severity of the reported +issue (including the decision whether the report is security-relevant or can be +redirected to the public mailing list), how to remediate the issue, determining +the timeline of the disclosure as well as aligning priorities and +requirements. -The first step is to https://github.com/git/git/security/advisories/new[open an -advisory]. Technically, it is not necessary, but it is convenient and saves a -bit of hassle. This advisory can also be used to obtain the CVE number and it -will give us a private fork associated with it that can be used to collaborate -on a fix. +Communications +~~~~~~~~~~~~~~ -Release date of the embargoed version -------------------------------------- +If you are a stakeholder, it is a good idea to pay close attention to the +discussions, as pertinent information may be buried in the middle of a lively +conversation that might not look relevant to your interests. For example, the +tentative timeline might be agreed upon in the middle of discussing code +comment formatting in one of the patches and whether or not to combine fixes +for multiple, separate vulnerabilities into the same embargoed release. Most +mail threads are not usually structured specifically to communicate +agreements, assessments or timelines. -If the vulnerability affects Windows users, we want to have our friends over at -Visual Studio on board. This means we need to target a "Patch Tuesday" (i.e. a -second Tuesday of the month), at the minimum three weeks from heads-up to -coordinated release. +Typical timeline +---------------- -If the vulnerability affects the server side, or can benefit from scans on the -server side (i.e. if `git fsck` can detect an attack), it is important to give -all involved Git repository hosting sites enough time to scan all of those -repositories. +- A potential vulnerability is reported to the `git-security` mailing list. + +- The members of the git-security list start a discussion to give an initial + assessment of the severity of the reported potential vulnerability. + We aspire to do so within a few days. + +- After discussion, if consensus is reached that it is not critical enough + to warrant any embargo, the reporter is redirected to the public Git mailing + list. This ends the reporter's interaction with the `git-security` list. + +- If it is deemed critical enough for an embargo, ideas are presented on how to + address the vulnerability. + +- Usually around that time, the Git maintainer or their delegate(s) open a draft + security advisory in the `git/git` repository on GitHub (see below for more + details). + +- Code review can take place in a variety of different locations, + depending on context. These are: patches sent inline on the git-security list, + a private fork on GitHub associated with the draft security advisory, or the + git/cabal repository. + +- Contributors working on a fix should consider beginning by sending + patches to the git-security list (inline with the original thread), since they + are accessible to all subscribers, along with the original reporter. + +- Once the review has settled and everyone involved in the review agrees that + the patches are nearing the finish line, the Git maintainer, and others + determine a release date as well as the release trains that are serviced. The + decision regarding which versions need a backported fix is based on input from + the reporter, the contributor who worked on the patches, and from + stakeholders. Operators of hosting sites who may want to analyze whether the + given issue is exploited via any of the repositories they host, and binary + packagers who want to make sure their product gets patched adequately against + the vulnerability, for example, may want to give their input at this stage. + +- While the Git community does its best to accommodate the specific timeline + requests of the various binary packagers, the nature of the issue may preclude + a prolonged release schedule. For fixes deemed urgent, it may be in the best + interest of the Git users community to shorten the disclosure and release + timeline, and packagers may need to adapt accordingly. + +- Subsequently, branches with the fixes are pushed to the git/cabal repository. + +- The tags are created by the Git maintainer and pushed to the same repository. + +- The Git for Windows, Git for macOS, BSD, Debian, etc. maintainers prepare the + corresponding release artifacts, based on the tags created that have been + prepared by the Git maintainer. + +- The release artifacts prepared by various binary packagers can be + made available to stakeholders under embargo via a mail to the + `git-security` list. + +- Less than a week before the release, a mail with the relevant information is + sent to <distros@vs.openwall.org> (see below), a list used to pre-announce + embargoed releases of open source projects to the stakeholders of all major + distributions of Linux as well as other OSes. + +- Public communication is then prepared in advance of the release date. This + includes blog posts and mails to the Git and Git for Windows mailing lists. + +- On the day of the release, at around 10am Pacific Time, the Git maintainer + pushes the tag and the `master` branch to the public repository, then sends + out an announcement mail. + +- Once the tag is pushed, the Git for Windows maintainer publishes the + corresponding tag and creates a GitHub Release with the associated release + artifacts (Git for Windows installer, Portable Git, MinGit, etc). + +- Git for Windows release is then announced via a mail to the public Git and + Git for Windows mailing lists as well as via a tweet. + +- Ditto for distribution packagers for Linux and other platforms: + their releases are announced via their preferred channels. + +- A mail to <oss-security@lists.openwall.org> (see below for details) is sent + as a follow-up to the <distros@vs.openwall.org> one, describing the + vulnerability in detail, often including a proof of concept of an exploit. + +Note: The Git project makes no guarantees about timelines, but aims to keep +embargoes reasonably short in the interest of keeping Git's users safe. + +Opening a Security Advisory draft +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first step is to https://github.com/git/git/security/advisories/new[open +an advisory]. Technically, this is not necessary. However, it is the most +convenient way to obtain the CVE number and it give us a private repository +associated with it that can be used to collaborate on a fix. Notifying the Linux distributions ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At most two weeks before release date, we need to send a notification to -distros@vs.openwall.org, preferably less than 7 days before the release date. +<distros@vs.openwall.org>, preferably less than 7 days before the release date. This will reach most (all?) Linux distributions. See an example below, and the guidelines for this mailing list at https://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists[here]. @@ -65,7 +180,7 @@ created using a command like this: tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle Example mail to distros@vs.openwall.org ---------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .... To: distros@vs.openwall.org @@ -101,7 +216,7 @@ Thanks, .... Example mail to oss-security@lists.openwall.com ------------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .... To: oss-security@lists.openwall.com @@ -128,4 +243,4 @@ it goes to <developer>. Thanks, <name> -.... +....
\ No newline at end of file diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index e3e350126d..0d2e55d781 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -363,7 +363,7 @@ Revision Range Summary '<rev>{caret}!', e.g. 'HEAD{caret}!':: A suffix '{caret}' followed by an exclamation mark is the same - as giving commit '<rev>' and then all its parents prefixed with + as giving commit '<rev>' and all its parents prefixed with '{caret}' to exclude them (and their ancestors). '<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2':: diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 2afa28bb5a..de5fc25059 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -148,20 +148,18 @@ filename collisions). == Trace2 API -All public Trace2 functions and macros are defined in `trace2.h` and -`trace2.c`. All public symbols are prefixed with `trace2_`. +The Trace2 public API is defined and documented in `trace2.h`; refer to it for +more information. All public functions and macros are prefixed +with `trace2_` and are implemented in `trace2.c`. There are no public Trace2 data structures. The Trace2 code also defines a set of private functions and data types in the `trace2/` directory. These symbols are prefixed with `tr2_` -and should only be used by functions in `trace2.c`. +and should only be used by functions in `trace2.c` (or other private +source files in `trace2/`). -== Conventions for Public Functions and Macros - -The functions defined by the Trace2 API are declared and documented -in `trace2.h`. It defines the API functions and wrapper macros for -Trace2. +=== Conventions for Public Functions and Macros Some functions have a `_fl()` suffix to indicate that they take `file` and `line-number` arguments. @@ -172,52 +170,7 @@ take a `va_list` argument. Some functions have a `_printf_fl()` suffix to indicate that they also take a `printf()` style format with a variable number of arguments. -There are CPP wrapper macros and `#ifdef`s to hide most of these details. -See `trace2.h` for more details. The following discussion will only -describe the simplified forms. - -== Public API - -All Trace2 API functions send a message to all of the active -Trace2 Targets. This section describes the set of available -messages. - -It helps to divide these functions into groups for discussion -purposes. - -=== Basic Command Messages - -These are concerned with the lifetime of the overall git process. -e.g: `void trace2_initialize_clock()`, `void trace2_initialize()`, -`int trace2_is_enabled()`, `void trace2_cmd_start(int argc, const char **argv)`. - -=== Command Detail Messages - -These are concerned with describing the specific Git command -after the command line, config, and environment are inspected. -e.g: `void trace2_cmd_name(const char *name)`, -`void trace2_cmd_mode(const char *mode)`. - -=== Child Process Messages - -These are concerned with the various spawned child processes, -including shell scripts, git commands, editors, pagers, and hooks. - -e.g: `void trace2_child_start(struct child_process *cmd)`. - -=== Git Thread Messages - -These messages are concerned with Git thread usage. - -e.g: `void trace2_thread_start(const char *thread_name)`. - -=== Region and Data Messages - -These are concerned with recording performance data -over regions or spans of code. e.g: -`void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`. - -Refer to trace2.h for details about all trace2 functions. +CPP wrapper macros are defined to hide most of these details. == Trace2 Target Formats @@ -685,8 +638,8 @@ The "exec_id" field is a command-unique id and is only useful if the `"thread_start"`:: This event is generated when a thread is started. It is - generated from *within* the new thread's thread-proc (for TLS - reasons). + generated from *within* the new thread's thread-proc (because + it needs to access data in the thread's thread-local storage). + ------------ { @@ -698,7 +651,7 @@ The "exec_id" field is a command-unique id and is only useful if the `"thread_exit"`:: This event is generated when a thread exits. It is generated - from *within* the thread's thread-proc (for TLS reasons). + from *within* the thread's thread-proc. + ------------ { @@ -816,6 +769,73 @@ The "value" field may be an integer or a string. } ------------ +`"th_timer"`:: + This event logs the amount of time that a stopwatch timer was + running in the thread. This event is generated when a thread + exits for timers that requested per-thread events. ++ +------------ +{ + "event":"th_timer", + ... + "category":"my_category", + "name":"my_timer", + "intervals":5, # number of time it was started/stopped + "t_total":0.052741, # total time in seconds it was running + "t_min":0.010061, # shortest interval + "t_max":0.011648 # longest interval +} +------------ + +`"timer"`:: + This event logs the amount of time that a stopwatch timer was + running aggregated across all threads. This event is generated + when the process exits. ++ +------------ +{ + "event":"timer", + ... + "category":"my_category", + "name":"my_timer", + "intervals":5, # number of time it was started/stopped + "t_total":0.052741, # total time in seconds it was running + "t_min":0.010061, # shortest interval + "t_max":0.011648 # longest interval +} +------------ + +`"th_counter"`:: + This event logs the value of a counter variable in a thread. + This event is generated when a thread exits for counters that + requested per-thread events. ++ +------------ +{ + "event":"th_counter", + ... + "category":"my_category", + "name":"my_counter", + "count":23 +} +------------ + +`"counter"`:: + This event logs the value of a counter variable across all threads. + This event is generated when the process exits. The total value + reported here is the sum across all threads. ++ +------------ +{ + "event":"counter", + ... + "category":"my_category", + "name":"my_counter", + "count":23 +} +------------ + + == Example Trace2 API Usage Here is a hypothetical usage of the Trace2 API showing the intended @@ -1206,7 +1226,7 @@ worked on 508 items at offset 2032. Thread "th04" worked on 508 items at offset 508. + This example also shows that thread names are assigned in a racy manner -as each thread starts and allocates TLS storage. +as each thread starts. Config (def param) Events:: @@ -1247,6 +1267,60 @@ d0 | main | data | r0 | 0.002126 | 0.002126 | fsy d0 | main | exit | | 0.000470 | | | code:0 d0 | main | atexit | | 0.000477 | | | code:0 ---------------- + +Stopwatch Timer Events:: + + Measure the time spent in a function call or span of code + that might be called from many places within the code + throughout the life of the process. ++ +---------------- +static void expensive_function(void) +{ + trace2_timer_start(TRACE2_TIMER_ID_TEST1); + ... + sleep_millisec(1000); // Do something expensive + ... + trace2_timer_stop(TRACE2_TIMER_ID_TEST1); +} + +static int ut_100timer(int argc, const char **argv) +{ + ... + + expensive_function(); + + // Do something else 1... + + expensive_function(); + + // Do something else 2... + + expensive_function(); + + return 0; +} +---------------- ++ +In this example, we measure the total time spent in +`expensive_function()` regardless of when it is called +in the overall flow of the program. ++ +---------------- +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf +$ t/helper/test-tool trace2 100timer 3 1000 +... +$ cat ~/log.perf +d0 | main | version | | | | | ... +d0 | main | start | | 0.001453 | | | t/helper/test-tool trace2 100timer 3 1000 +d0 | main | cmd_name | | | | | trace2 (trace2) +d0 | main | exit | | 3.003667 | | | code:0 +d0 | main | timer | | | | test | name:test1 intervals:3 total:3.001686 min:1.000254 max:1.000929 +d0 | main | atexit | | 3.003796 | | | code:0 +---------------- + + == Future Work === Relationship to the Existing Trace Api (api-trace.txt) |