From 979463309733bb608fee0d57c0ba03bdca004d03 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Fri, 4 Nov 2022 21:53:18 -0700 Subject: Autogenerated HTML docs for v2.38.1-385-g3b088 --- RelNotes/2.39.0.txt | 57 ++++ config.txt | 2 + fsck-msgids.txt | 161 ++++++++++ git-config.html | 52 ++++ git-fsck.html | 443 +++++++++++++++++++++++++++- git-fsck.txt | 12 + git-merge-tree.html | 94 +++++- git-merge-tree.txt | 76 ++++- git-patch-id.html | 36 ++- git-patch-id.txt | 24 +- git-rebase.html | 42 +-- git-rebase.txt | 32 +- git-send-email.html | 17 +- git-send-email.txt | 15 +- git-shortlog.html | 19 +- git-shortlog.txt | 8 + howto-index.html | 7 +- howto-index.txt | 5 +- howto/coordinate-embargoed-releases.html | 227 ++++++++++++-- howto/coordinate-embargoed-releases.txt | 165 +++++++++-- howto/keep-canonical-history-correct.html | 2 +- howto/maintain-git.html | 2 +- howto/new-command.html | 2 +- howto/rebase-from-internal-branch.html | 2 +- howto/rebuild-from-update-hook.html | 2 +- howto/recover-corrupted-blob-object.html | 2 +- howto/recover-corrupted-object-harder.html | 2 +- howto/revert-a-faulty-merge.html | 2 +- howto/revert-branch-rebase.html | 2 +- howto/separating-topic-branches.html | 2 +- howto/setup-git-server-over-http.html | 2 +- howto/update-hook-example.html | 2 +- howto/use-git-daemon.html | 2 +- howto/using-merge-subtree.html | 2 +- howto/using-signed-tag-in-pull-request.html | 2 +- technical/api-trace2.html | 213 +++++++++---- technical/api-trace2.txt | 190 ++++++++---- 37 files changed, 1661 insertions(+), 266 deletions(-) create mode 100644 fsck-msgids.txt diff --git a/RelNotes/2.39.0.txt b/RelNotes/2.39.0.txt index f87c4c442..7096f0768 100644 --- a/RelNotes/2.39.0.txt +++ b/RelNotes/2.39.0.txt @@ -20,6 +20,14 @@ UI, Workflows & Features description of the branch you were on before switching to the current branch. + * "git merge-tree --stdin" is a new way to request a series of merges + and report the merge results. + + * "git shortlog" learned to group by the "format" string. + + * A new "--include-whitespace" option is added to "git patch-id", and + existing bugs in the internal patch-id logic that did not match + what "git patch-id" produces have been corrected. Performance, Internal Implementation, Development Support etc. -------------------------------------------------------------- @@ -55,6 +63,26 @@ Performance, Internal Implementation, Development Support etc. compiler. (merge 4b992f0a24 jk/unused-anno-more later to maint). + * Rewrite a deep recursion in the skipping negotiator to use a loop + with on-heap prio queue to avoid stack wastage. + + * Add documentation for message IDs in fsck error messages. + + * Define the logical elements of a "bundle list", data structure to + store them in-core, format to transfer them, and code to parse + them. + + * The role the security mailing list plays in an embargoed release + has been documented. + + * Two new facilities, "timer" and "counter", are introduced to the + trace2 API. + + * Code simplification by using strvec_pushf() instead of building an + argument in a separate strbuf. + + * Make sure generated dependency file is stably sorted to help + developers debugging their build issues. Fixes since v2.38 ----------------- @@ -162,6 +190,35 @@ Fixes since v2.38 adjust them to compute the display width assuming UTF-8 pathnames. (merge ce8529b2bb tb/diffstat-with-utf8-strwidth later to maint). + * "git branch --edit-description" can exit with status -1 which is + not a good practice; it learned to use 1 as everybody else instead. + + * "git apply" limits its input to a bit less than 1 GiB. + + * Merging a branch with directory renames into a branch that changes + the directory to a symlink was mishandled by the ort merge + strategy, which has been corrected. + + * A bugfix to "git subtree" in its split and merge features. + + * Fix some bugs in the reflog messages when rebasing and changes the + reflog messages of "rebase --apply" to match "rebase --merge" with + the aim of making the reflog easier to parse. + + * "git rebase --keep-base" used to discard the commits that are + already cherry-picked to the upstream, even when "keep-base" meant + that the base, on top of which the history is being rebuilt, does + not yet include these cherry-picked commits. The --keep-base + option now implies --reapply-cherry-picks and --no-fork-point + options. + + * The way "git repack" creared temporary files when it received a + signal was prone to deadlocking, which has been corrected. + + * Various tests exercising the transfer.credentialsInUrl + configuration are taught to avoid making requests which require + resolving localhost to reduce CI-flakiness. + * Other code cleanup, docfix, build fix, etc. (merge 413bc6d20a ds/cmd-main-reorder later to maint). (merge 8d2863e4ed nw/t1002-cleanup later to maint). diff --git a/config.txt b/config.txt index 1e2058316..0e93aef86 100644 --- a/config.txt +++ b/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/fsck-msgids.txt b/fsck-msgids.txt new file mode 100644 index 000000000..7af76ff99 --- /dev/null +++ b/fsck-msgids.txt @@ -0,0 +1,161 @@ +`badDate`:: + (ERROR) Invalid date format in an author/committer line. + +`badDateOverflow`:: + (ERROR) Invalid date value in an author/committer line. + +`badEmail`:: + (ERROR) Invalid email format in an author/committer line. + +`badFilemode`:: + (INFO) A tree contains a bad filemode entry. + +`badName`:: + (ERROR) An author/committer name is empty. + +`badObjectSha1`:: + (ERROR) An object has a bad sha1. + +`badParentSha1`:: + (ERROR) A commit object has a bad parent sha1. + +`badTagName`:: + (INFO) A tag has an invalid format. + +`badTimezone`:: + (ERROR) Found an invalid time zone in an author/committer line. + +`badTree`:: + (ERROR) A tree cannot be parsed. + +`badTreeSha1`:: + (ERROR) A tree has an invalid format. + +`badType`:: + (ERROR) Found an invalid object type. + +`duplicateEntries`:: + (ERROR) A tree contains duplicate file entries. + +`emptyName`:: + (WARN) A path contains an empty name. + +`extraHeaderEntry`:: + (IGNORE) Extra headers found after `tagger`. + +`fullPathname`:: + (WARN) A path contains the full path starting with "/". + +`gitattributesSymlink`:: + (INFO) `.gitattributes` is a symlink. + +`gitignoreSymlink`:: + (INFO) `.gitignore` is a symlink. + +`gitmodulesBlob`:: + (ERROR) A non-blob found at `.gitmodules`. + +`gitmodulesLarge`:: + (ERROR) The `.gitmodules` file is too large to parse. + +`gitmodulesMissing`:: + (ERROR) Unable to read `.gitmodules` blob. + +`gitmodulesName`:: + (ERROR) A submodule name is invalid. + +`gitmodulesParse`:: + (INFO) Could not parse `.gitmodules` blob. + +`gitmodulesLarge`; + (ERROR) `.gitmodules` blob is too large to parse. + +`gitmodulesPath`:: + (ERROR) `.gitmodules` path is invalid. + +`gitmodulesSymlink`:: + (ERROR) `.gitmodules` is a symlink. + +`gitmodulesUpdate`:: + (ERROR) Found an invalid submodule update setting. + +`gitmodulesUrl`:: + (ERROR) Found an invalid submodule url. + +`hasDot`:: + (WARN) A tree contains an entry named `.`. + +`hasDotdot`:: + (WARN) A tree contains an entry named `..`. + +`hasDotgit`:: + (WARN) A tree contains an entry named `.git`. + +`mailmapSymlink`:: + (INFO) `.mailmap` is a symlink. + +`missingAuthor`:: + (ERROR) Author is missing. + +`missingCommitter`:: + (ERROR) Committer is missing. + +`missingEmail`:: + (ERROR) Email is missing in an author/committer line. + +`missingNameBeforeEmail`:: + (ERROR) Missing name before an email in an author/committer line. + +`missingObject`:: + (ERROR) Missing `object` line in tag object. + +`missingSpaceBeforeDate`:: + (ERROR) Missing space before date in an author/committer line. + +`missingSpaceBeforeEmail`:: + (ERROR) Missing space before the email in author/committer line. + +`missingTag`:: + (ERROR) Unexpected end after `type` line in a tag object. + +`missingTagEntry`:: + (ERROR) Missing `tag` line in a tag object. + +`missingTaggerEntry`:: + (INFO) Missing `tagger` line in a tag object. + +`missingTree`:: + (ERROR) Missing `tree` line in a commit object. + +`missingType`:: + (ERROR) Invalid type value on the `type` line in a tag object. + +`missingTypeEntry`:: + (ERROR) Missing `type` line in a tag object. + +`multipleAuthors`:: + (ERROR) Multiple author lines found in a commit. + +`nulInCommit`:: + (WARN) Found a NUL byte in the commit object body. + +`nulInHeader`:: + (FATAL) NUL byte exists in the object header. + +`nullSha1`:: + (WARN) Tree contains entries pointing to a null sha1. + +`treeNotSorted`:: + (ERROR) A tree is not properly sorted. + +`unknownType`:: + (ERROR) Found an unknown object type. + +`unterminatedHeader`:: + (FATAL) Missing end-of-line in the object header. + +`zeroPaddedDate`:: + (ERROR) Found a zero padded date in an author/commiter line. + +`zeroPaddedFilemode`:: + (WARN) Found a zero padded filemode in a tree. diff --git a/git-config.html b/git-config.html index a56d461d4..85a5bb365 100644 --- a/git-config.html +++ b/git-config.html @@ -3770,6 +3770,56 @@ browser.<tool>.path

+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 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. +

+
+
checkout.defaultRemote
@@ -5830,6 +5880,8 @@ allow new instances of the same breakages go unnoticed.

Setting an unknown fsck.<msg-id> value will cause fsck to die, but doing the same for receive.fsck.<msg-id> and fetch.fsck.<msg-id> will only cause git to warn.

+

See Fsck Messages section of git-fsck(1) for supported +values of <msg-id>.

fsck.skipList diff --git a/git-fsck.html b/git-fsck.html index 0a795cace..b6bcbcf57 100644 --- a/git-fsck.html +++ b/git-fsck.html @@ -965,6 +965,8 @@ allow new instances of the same breakages go unnoticed.

Setting an unknown fsck.<msg-id> value will cause fsck to die, but doing the same for receive.fsck.<msg-id> and fetch.fsck.<msg-id> will only cause git to warn.

+

See Fsck Messages section of git-fsck(1) for supported +values of <msg-id>.

fsck.skipList @@ -1065,6 +1067,445 @@ hash mismatch <object>
+

FSCK MESSAGES

+
+

The following lists the types of errors git fsck detects and what +each error means, with their default severity. The severity of the +error, other than those that are marked as "(FATAL)", can be tweaked +by setting the corresponding fsck.<msg-id> configuration variable.

+
+
+badDate +
+
+

+ (ERROR) Invalid date format in an author/committer line. +

+
+
+badDateOverflow +
+
+

+ (ERROR) Invalid date value in an author/committer line. +

+
+
+badEmail +
+
+

+ (ERROR) Invalid email format in an author/committer line. +

+
+
+badFilemode +
+
+

+ (INFO) A tree contains a bad filemode entry. +

+
+
+badName +
+
+

+ (ERROR) An author/committer name is empty. +

+
+
+badObjectSha1 +
+
+

+ (ERROR) An object has a bad sha1. +

+
+
+badParentSha1 +
+
+

+ (ERROR) A commit object has a bad parent sha1. +

+
+
+badTagName +
+
+

+ (INFO) A tag has an invalid format. +

+
+
+badTimezone +
+
+

+ (ERROR) Found an invalid time zone in an author/committer line. +

+
+
+badTree +
+
+

+ (ERROR) A tree cannot be parsed. +

+
+
+badTreeSha1 +
+
+

+ (ERROR) A tree has an invalid format. +

+
+
+badType +
+
+

+ (ERROR) Found an invalid object type. +

+
+
+duplicateEntries +
+
+

+ (ERROR) A tree contains duplicate file entries. +

+
+
+emptyName +
+
+

+ (WARN) A path contains an empty name. +

+
+
+extraHeaderEntry +
+
+

+ (IGNORE) Extra headers found after tagger. +

+
+
+fullPathname +
+
+

+ (WARN) A path contains the full path starting with "/". +

+
+
+gitattributesSymlink +
+
+

+ (INFO) .gitattributes is a symlink. +

+
+
+gitignoreSymlink +
+
+

+ (INFO) .gitignore is a symlink. +

+
+
+gitmodulesBlob +
+
+

+ (ERROR) A non-blob found at .gitmodules. +

+
+
+gitmodulesLarge +
+
+

+ (ERROR) The .gitmodules file is too large to parse. +

+
+
+gitmodulesMissing +
+
+

+ (ERROR) Unable to read .gitmodules blob. +

+
+
+gitmodulesName +
+
+

+ (ERROR) A submodule name is invalid. +

+
+
+gitmodulesParse +
+
+

+ (INFO) Could not parse .gitmodules blob. +

+
+
+

gitmodulesLarge; + (ERROR) .gitmodules blob is too large to parse.

+
+
+gitmodulesPath +
+
+

+ (ERROR) .gitmodules path is invalid. +

+
+
+gitmodulesSymlink +
+
+

+ (ERROR) .gitmodules is a symlink. +

+
+
+gitmodulesUpdate +
+
+

+ (ERROR) Found an invalid submodule update setting. +

+
+
+gitmodulesUrl +
+
+

+ (ERROR) Found an invalid submodule url. +

+
+
+hasDot +
+
+

+ (WARN) A tree contains an entry named .. +

+
+
+hasDotdot +
+
+

+ (WARN) A tree contains an entry named ... +

+
+
+hasDotgit +
+
+

+ (WARN) A tree contains an entry named .git. +

+
+
+mailmapSymlink +
+
+

+ (INFO) .mailmap is a symlink. +

+
+
+missingAuthor +
+
+

+ (ERROR) Author is missing. +

+
+
+missingCommitter +
+
+

+ (ERROR) Committer is missing. +

+
+
+missingEmail +
+
+

+ (ERROR) Email is missing in an author/committer line. +

+
+
+missingNameBeforeEmail +
+
+

+ (ERROR) Missing name before an email in an author/committer line. +

+
+
+missingObject +
+
+

+ (ERROR) Missing object line in tag object. +

+
+
+missingSpaceBeforeDate +
+
+

+ (ERROR) Missing space before date in an author/committer line. +

+
+
+missingSpaceBeforeEmail +
+
+

+ (ERROR) Missing space before the email in author/committer line. +

+
+
+missingTag +
+
+

+ (ERROR) Unexpected end after type line in a tag object. +

+
+
+missingTagEntry +
+
+

+ (ERROR) Missing tag line in a tag object. +

+
+
+missingTaggerEntry +
+
+

+ (INFO) Missing tagger line in a tag object. +

+
+
+missingTree +
+
+

+ (ERROR) Missing tree line in a commit object. +

+
+
+missingType +
+
+

+ (ERROR) Invalid type value on the type line in a tag object. +

+
+
+missingTypeEntry +
+
+

+ (ERROR) Missing type line in a tag object. +

+
+
+multipleAuthors +
+
+

+ (ERROR) Multiple author lines found in a commit. +

+
+
+nulInCommit +
+
+

+ (WARN) Found a NUL byte in the commit object body. +

+
+
+nulInHeader +
+
+

+ (FATAL) NUL byte exists in the object header. +

+
+
+nullSha1 +
+
+

+ (WARN) Tree contains entries pointing to a null sha1. +

+
+
+treeNotSorted +
+
+

+ (ERROR) A tree is not properly sorted. +

+
+
+unknownType +
+
+

+ (ERROR) Found an unknown object type. +

+
+
+unterminatedHeader +
+
+

+ (FATAL) Missing end-of-line in the object header. +

+
+
+zeroPaddedDate +
+
+

+ (ERROR) Found a zero padded date in an author/commiter line. +

+
+
+zeroPaddedFilemode +
+
+

+ (WARN) Found a zero padded filemode in a tree. +

+
+
+
+
+

Environment Variables

@@ -1106,7 +1547,7 @@ GIT_ALTERNATE_OBJECT_DIRECTORIES diff --git a/git-fsck.txt b/git-fsck.txt index 29318ea95..b6a0f8a08 100644 --- a/git-fsck.txt +++ b/git-fsck.txt @@ -152,6 +152,18 @@ hash mismatch :: object database value. This indicates a serious data integrity problem. + +FSCK MESSAGES +------------- + +The following lists the types of errors `git fsck` detects and what +each error means, with their default severity. The severity of the +error, other than those that are marked as "(FATAL)", can be tweaked +by setting the corresponding `fsck.` configuration variable. + +include::fsck-msgids.txt[] + + Environment Variables --------------------- diff --git a/git-merge-tree.html b/git-merge-tree.html index 8878de112..b3ce21244 100644 --- a/git-merge-tree.html +++ b/git-merge-tree.html @@ -866,6 +866,32 @@ line:

<Informational messages>

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
+
+
+

Merge status

+

This is an integer status followed by a NUL character. The integer status is:

+
+
+
0: merge had conflicts
+1: merge was clean
+&lt;0: something prevented the merge from running (e.g. access to repository
+    objects denied by filesystem)
+
+

OID of toplevel tree

This is a tree object that represents what would be checked out in the @@ -888,9 +914,49 @@ 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:

  • @@ -904,7 +970,7 @@ messages about the merge, such as:

  • -"Failed to merge submodule <submodule> (<reason>)" +"Failed to merge submodule <submodule> (no merge base)"

  • @@ -913,9 +979,16 @@ messages about the merge, such as:

    • -

    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.

    @@ -925,7 +998,10 @@ of text taking up the remainder of the output.

    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.

    @@ -1052,7 +1128,7 @@ large repositories).

    diff --git a/git-merge-tree.txt b/git-merge-tree.txt index d6c356740..04bcc416e 100644 --- a/git-merge-tree.txt +++ b/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: + + + + + + NUL + + + 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: + + NULNUL + +where is of the form + + NULNULNUL...NUL + +and includes paths (or branch names) affected by the conflict or +informational message in . Also, is a +stable string explaining the type of conflict, such as + + * "Auto-merging" + * "CONFLICT (rename/delete)" + * "CONFLICT (submodule lacks merge base)" + * "CONFLICT (binary)" + +and is a more detailed message about the conflict which often +(but not always) embeds the within it. These +strings may change in future Git versions. Some examples: * "Auto-merging " * "CONFLICT (rename/delete): renamed...but deleted in..." - * "Failed to merge submodule ()" + * "Failed to merge submodule (no merge base)" * "Warning: cannot merge binary files: " -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 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 +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/git-patch-id.html b/git-patch-id.html index bede81485..2ce031a5b 100644 --- a/git-patch-id.html +++ b/git-patch-id.html @@ -749,7 +749,7 @@ git-patch-id(1) Manual Page

    SYNOPSIS

    -
    git patch-id [--stable | --unstable]
    +
    git patch-id [--stable | --unstable | --verbatim]
    @@ -759,10 +759,10 @@ git-patch-id(1) Manual Page

    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.

    -

    IOW, you can use this thing to look for likely duplicate commits.

    +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.

    +

    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 commit, and outputs two 40-byte hexadecimal strings. The first @@ -775,6 +775,19 @@ This can be used to make a mapping from patch ID to commit ID.

    +--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
    @@ -800,6 +813,11 @@ Result is different from the value produced by git 1.9 and older 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.
    @@ -814,9 +832,9 @@ Result is different from the value produced by git 1.9 and older

    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.

    @@ -837,7 +855,7 @@ Result is different from the value produced by git 1.9 and older diff --git a/git-patch-id.txt b/git-patch-id.txt index 442caff8a..1d15fa45d 100644 --- a/git-patch-id.txt +++ b/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", 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/git-rebase.html b/git-rebase.html index 6b97948bf..ef0720da0 100644 --- a/git-rebase.html +++ b/git-rebase.html @@ -955,12 +955,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 point on which new commits will be created, whereas --fork-point uses @@ -1046,7 +1048,8 @@ the merge base to determine the set of commits which will be rebased.

    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.

    • @@ -1088,17 +1091,22 @@ see the --empty flag.

    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 git-config(1)).

    -

    --reapply-cherry-picks allows rebase to forgo reading all upstream -commits, potentially improving performance.

    -

    See also INCOMPATIBLE OPTIONS below.

    +

    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 +git-config(1)).

    +
    +

    + +--reapply-cherry-picks allows rebase to forgo reading all upstream +commits, potentially improving performance.

    +

    + +See also INCOMPATIBLE OPTIONS below.

    +
    --allow-empty-message
    @@ -1330,9 +1338,9 @@ details).

    fork_point is the result of git merge-base --fork-point <upstream> <branch> command (see 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 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 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 with --keep-base in order to drop those commits from your branch.

    @@ -2757,7 +2765,7 @@ sequence.editor diff --git a/git-rebase.txt b/git-rebase.txt index 9cb8931c7..f9675bd24 100644 --- a/git-rebase.txt +++ b/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 `` and ``. Running `git rebase --keep-base ` is equivalent to running - `git rebase --onto ... `. + `git rebase --reapply-cherry-picks --no-fork-point --onto ... `. + 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 `` and ``, 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 ` command (see linkgit:git-merge-base[1]). If 'fork_point' ends up being empty, the `` will be used as a fallback. + -If `` 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 `` 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 `` but `` was rewound and your branch contains commits which were dropped, this option can be used diff --git a/git-send-email.html b/git-send-email.html index 730286199..cf0b8868b 100644 --- a/git-send-email.html +++ b/git-send-email.html @@ -1000,9 +1000,18 @@ value; if that is unspecified, default to auto.

    - 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.

    @@ -1803,7 +1812,7 @@ Authen::SASL and Mail::Address.

    diff --git a/git-send-email.txt b/git-send-email.txt index 329004305..765b2df85 100644 --- a/git-send-email.txt +++ b/git-send-email.txt @@ -178,9 +178,18 @@ Sending for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH. --smtp-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=:: Specifies the Fully Qualified Domain Name (FQDN) used in the diff --git a/git-shortlog.html b/git-shortlog.html index bb7d55410..28d23dc08 100644 --- a/git-shortlog.html +++ b/git-shortlog.html @@ -821,6 +821,16 @@ reference to the current repository.

    +--date=<format> +
    +
    +

    + Show dates formatted according to the given date string. (See + the --date option in the "Commit Formatting" section of + git-log(1)). Useful with --group=format:<format>. +

    +
    +
    --group=<type>
    @@ -849,6 +859,13 @@ reference to the current repository.

    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 + 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 be counted more than once (but only once per unique trailer value in @@ -2000,7 +2017,7 @@ the current directory.

    diff --git a/git-shortlog.txt b/git-shortlog.txt index f64e77047..7d0277d03 100644 --- a/git-shortlog.txt +++ b/git-shortlog.txt @@ -47,6 +47,11 @@ OPTIONS Each pretty-printed commit will be rewrapped before it is shown. +--date=:: + 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:`. + --group=:: Group commits based on ``. If no `--group` option is specified, the default is `author`. `` 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:`, 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/howto-index.html b/howto-index.html index 0dabcf1be..c5b645ef6 100644 --- a/howto-index.html +++ b/howto-index.html @@ -748,8 +748,9 @@ people describing how they use Git in their workflow.

    • -

    When a critical vulnerability is discovered and fixed, we follow this -script to coordinate a public release.

    +

    When a vulnerability is reported, we follow these guidelines to +assess the vulnerability, create and review a fix, and coordinate embargoed +security releases.

    • @@ -894,7 +895,7 @@ later validate it.

    diff --git a/howto-index.txt b/howto-index.txt index 2aca29db3..9c57cd80c 100644 --- a/howto-index.txt +++ b/howto-index.txt @@ -6,8 +6,9 @@ people describing how they use Git in their workflow. * link:howto/coordinate-embargoed-releases.html[coordinate-embargoed-releases] -When a critical vulnerability is discovered and fixed, we follow this -script to coordinate a public release. +When a vulnerability is reported, we follow these guidelines to +assess the vulnerability, create and review a fix, and coordinate embargoed +security releases. * link:howto/keep-canonical-history-correct.html[keep-canonical-history-correct] by Junio C Hamano diff --git a/howto/coordinate-embargoed-releases.html b/howto/coordinate-embargoed-releases.html index de337a88e..9b449a171 100644 --- a/howto/coordinate-embargoed-releases.html +++ b/howto/coordinate-embargoed-releases.html @@ -5,7 +5,7 @@ -How we coordinate embargoed releases +