diff options
| author | Junio C Hamano <gitster@pobox.com> | 2022-11-04 21:53:18 -0700 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2022-11-04 21:53:18 -0700 |
| commit | 979463309733bb608fee0d57c0ba03bdca004d03 (patch) | |
| tree | 07abf7919d03cba543b6df3fbd451ea7e62bb91f | |
| parent | cf9c77377796343e741a25077f837f607513c7bb (diff) | |
| download | git-htmldocs-979463309733bb608fee0d57c0ba03bdca004d03.tar.gz | |
Autogenerated HTML docs for v2.38.1-385-g3b088
37 files changed, 1661 insertions, 266 deletions
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 </p>
</dd>
<dt class="hdlist1">
+bundle.*
+</dt>
+<dd>
+<p>
+ The <code>bundle.*</code> keys may appear in a bundle list file found via the
+ <code>git clone --bundle-uri</code> option. These keys currently have no effect
+ if placed in a repository config file, though this will change in the
+ future. See <a href="technical/bundle-uri.html">the bundle URI design
+ document</a> for more details.
+</p>
+</dd>
+<dt class="hdlist1">
+bundle.version
+</dt>
+<dd>
+<p>
+ This integer value advertises the version of the bundle list format
+ used by the bundle list. Currently, the only accepted value is <code>1</code>.
+</p>
+</dd>
+<dt class="hdlist1">
+bundle.mode
+</dt>
+<dd>
+<p>
+ This string value should be either <code>all</code> or <code>any</code>. This value describes
+ whether all of the advertised bundles are required to unbundle a
+ complete understanding of the bundled information (<code>all</code>) or if any one
+ of the listed bundle URIs is sufficient (<code>any</code>).
+</p>
+</dd>
+<dt class="hdlist1">
+bundle.<id>.*
+</dt>
+<dd>
+<p>
+ The <code>bundle.<id>.*</code> keys are used to describe a single item in the
+ bundle list, grouped under <code><id></code> for identification purposes.
+</p>
+</dd>
+<dt class="hdlist1">
+bundle.<id>.uri
+</dt>
+<dd>
+<p>
+ This string value defines the URI by which Git can reach the contents
+ of this <code><id></code>. This URI may be a bundle file or another bundle list.
+</p>
+</dd>
+<dt class="hdlist1">
checkout.defaultRemote
</dt>
<dd>
@@ -5830,6 +5880,8 @@ allow new instances of the same breakages go unnoticed.</p></div> <div class="paragraph"><p>Setting an unknown <code>fsck.<msg-id></code> value will cause fsck to die, but
doing the same for <code>receive.fsck.<msg-id></code> and <code>fetch.fsck.<msg-id></code>
will only cause git to warn.</p></div>
+<div class="paragraph"><p>See <code>Fsck Messages</code> section of <a href="git-fsck.html">git-fsck(1)</a> for supported
+values of <code><msg-id></code>.</p></div>
</dd>
<dt class="hdlist1">
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.</p></div> <div class="paragraph"><p>Setting an unknown <code>fsck.<msg-id></code> value will cause fsck to die, but
doing the same for <code>receive.fsck.<msg-id></code> and <code>fetch.fsck.<msg-id></code>
will only cause git to warn.</p></div>
+<div class="paragraph"><p>See <code>Fsck Messages</code> section of <a href="git-fsck.html">git-fsck(1)</a> for supported
+values of <code><msg-id></code>.</p></div>
</dd>
<dt class="hdlist1">
fsck.skipList
@@ -1065,6 +1067,445 @@ hash mismatch <object> </div>
</div>
<div class="sect1">
+<h2 id="_fsck_messages">FSCK MESSAGES</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The following lists the types of errors <code>git fsck</code> 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 <code>fsck.<msg-id></code> configuration variable.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>badDate</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Invalid date format in an author/committer line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badDateOverflow</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Invalid date value in an author/committer line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badEmail</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Invalid email format in an author/committer line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badFilemode</code>
+</dt>
+<dd>
+<p>
+ (INFO) A tree contains a bad filemode entry.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badName</code>
+</dt>
+<dd>
+<p>
+ (ERROR) An author/committer name is empty.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badObjectSha1</code>
+</dt>
+<dd>
+<p>
+ (ERROR) An object has a bad sha1.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badParentSha1</code>
+</dt>
+<dd>
+<p>
+ (ERROR) A commit object has a bad parent sha1.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badTagName</code>
+</dt>
+<dd>
+<p>
+ (INFO) A tag has an invalid format.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badTimezone</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Found an invalid time zone in an author/committer line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badTree</code>
+</dt>
+<dd>
+<p>
+ (ERROR) A tree cannot be parsed.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badTreeSha1</code>
+</dt>
+<dd>
+<p>
+ (ERROR) A tree has an invalid format.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>badType</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Found an invalid object type.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>duplicateEntries</code>
+</dt>
+<dd>
+<p>
+ (ERROR) A tree contains duplicate file entries.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>emptyName</code>
+</dt>
+<dd>
+<p>
+ (WARN) A path contains an empty name.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>extraHeaderEntry</code>
+</dt>
+<dd>
+<p>
+ (IGNORE) Extra headers found after <code>tagger</code>.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>fullPathname</code>
+</dt>
+<dd>
+<p>
+ (WARN) A path contains the full path starting with "/".
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitattributesSymlink</code>
+</dt>
+<dd>
+<p>
+ (INFO) <code>.gitattributes</code> is a symlink.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitignoreSymlink</code>
+</dt>
+<dd>
+<p>
+ (INFO) <code>.gitignore</code> is a symlink.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitmodulesBlob</code>
+</dt>
+<dd>
+<p>
+ (ERROR) A non-blob found at <code>.gitmodules</code>.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitmodulesLarge</code>
+</dt>
+<dd>
+<p>
+ (ERROR) The <code>.gitmodules</code> file is too large to parse.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitmodulesMissing</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Unable to read <code>.gitmodules</code> blob.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitmodulesName</code>
+</dt>
+<dd>
+<p>
+ (ERROR) A submodule name is invalid.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitmodulesParse</code>
+</dt>
+<dd>
+<p>
+ (INFO) Could not parse <code>.gitmodules</code> blob.
+</p>
+</dd>
+</dl></div>
+<div class="paragraph"><p><code>gitmodulesLarge</code>;
+ (ERROR) <code>.gitmodules</code> blob is too large to parse.</p></div>
+<div class="dlist"><dl>
+<dt class="hdlist1">
+<code>gitmodulesPath</code>
+</dt>
+<dd>
+<p>
+ (ERROR) <code>.gitmodules</code> path is invalid.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitmodulesSymlink</code>
+</dt>
+<dd>
+<p>
+ (ERROR) <code>.gitmodules</code> is a symlink.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitmodulesUpdate</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Found an invalid submodule update setting.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>gitmodulesUrl</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Found an invalid submodule url.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>hasDot</code>
+</dt>
+<dd>
+<p>
+ (WARN) A tree contains an entry named <code>.</code>.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>hasDotdot</code>
+</dt>
+<dd>
+<p>
+ (WARN) A tree contains an entry named <code>..</code>.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>hasDotgit</code>
+</dt>
+<dd>
+<p>
+ (WARN) A tree contains an entry named <code>.git</code>.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>mailmapSymlink</code>
+</dt>
+<dd>
+<p>
+ (INFO) <code>.mailmap</code> is a symlink.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingAuthor</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Author is missing.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingCommitter</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Committer is missing.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingEmail</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Email is missing in an author/committer line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingNameBeforeEmail</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Missing name before an email in an author/committer line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingObject</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Missing <code>object</code> line in tag object.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingSpaceBeforeDate</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Missing space before date in an author/committer line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingSpaceBeforeEmail</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Missing space before the email in author/committer line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingTag</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Unexpected end after <code>type</code> line in a tag object.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingTagEntry</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Missing <code>tag</code> line in a tag object.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingTaggerEntry</code>
+</dt>
+<dd>
+<p>
+ (INFO) Missing <code>tagger</code> line in a tag object.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingTree</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Missing <code>tree</code> line in a commit object.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingType</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Invalid type value on the <code>type</code> line in a tag object.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>missingTypeEntry</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Missing <code>type</code> line in a tag object.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>multipleAuthors</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Multiple author lines found in a commit.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>nulInCommit</code>
+</dt>
+<dd>
+<p>
+ (WARN) Found a NUL byte in the commit object body.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>nulInHeader</code>
+</dt>
+<dd>
+<p>
+ (FATAL) NUL byte exists in the object header.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>nullSha1</code>
+</dt>
+<dd>
+<p>
+ (WARN) Tree contains entries pointing to a null sha1.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>treeNotSorted</code>
+</dt>
+<dd>
+<p>
+ (ERROR) A tree is not properly sorted.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>unknownType</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Found an unknown object type.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>unterminatedHeader</code>
+</dt>
+<dd>
+<p>
+ (FATAL) Missing end-of-line in the object header.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>zeroPaddedDate</code>
+</dt>
+<dd>
+<p>
+ (ERROR) Found a zero padded date in an author/commiter line.
+</p>
+</dd>
+<dt class="hdlist1">
+<code>zeroPaddedFilemode</code>
+</dt>
+<dd>
+<p>
+ (WARN) Found a zero padded filemode in a tree.
+</p>
+</dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
<h2 id="_environment_variables">Environment Variables</h2>
<div class="sectionbody">
<div class="dlist"><dl>
@@ -1106,7 +1547,7 @@ GIT_ALTERNATE_OBJECT_DIRECTORIES <div id="footer">
<div id="footer-text">
Last updated
- 2022-09-14 13:23:11 PDT
+ 2022-11-04 21:49:36 PDT
</div>
</div>
</body>
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>:: 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.<msg-id>` 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:</p></div> <Informational messages></code></pre>
</div></div>
<div class="paragraph"><p>These are discussed individually below.</p></div>
+<div class="paragraph"><p>However, there is an exception. If <code>--stdin</code> 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:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><code><Merge status>
+<OID of toplevel tree>
+<Conflicted file info>
+<Informational messages>
+NUL
+<Merge status>
+<OID of toplevel tree>
+NUL</code></pre>
+</div></div>
+<div class="sect2">
+<h3 id="MS">Merge status</h3>
+<div class="paragraph"><p>This is an integer status followed by a NUL character. The integer status is:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><code>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)</code></pre>
+</div></div>
+</div>
<div class="sect2">
<h3 id="OIDTLT">OID of toplevel tree</h3>
<div class="paragraph"><p>This is a tree object that represents what would be checked out in the
@@ -888,9 +914,49 @@ character instead of a newline character.</p></div> </div>
<div class="sect2">
<h3 id="IM">Informational messages</h3>
-<div class="paragraph"><p>This always starts with a blank line (or NUL if <code>-z</code> is passed) to
-separate it from the previous sections, and then has free-form
-messages about the merge, such as:</p></div>
+<div class="paragraph"><p>This section provides informational messages, typically about
+conflicts. The format of the section varies significantly depending
+on whether <code>-z</code> is passed.</p></div>
+<div class="paragraph"><p>If <code>-z</code> is passed:</p></div>
+<div class="paragraph"><p>The output format is zero or more conflict informational records, each
+of the form:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><code><list-of-paths><conflict-type>NUL<conflict-message>NUL</code></pre>
+</div></div>
+<div class="paragraph"><p>where <list-of-paths> is of the form</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><code><number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL</code></pre>
+</div></div>
+<div class="paragraph"><p>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</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+"Auto-merging"
+</p>
+</li>
+<li>
+<p>
+"CONFLICT (rename/delete)"
+</p>
+</li>
+<li>
+<p>
+"CONFLICT (submodule lacks merge base)"
+</p>
+</li>
+<li>
+<p>
+"CONFLICT (binary)"
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>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:</p></div>
<div class="ulist"><ul>
<li>
<p>
@@ -904,7 +970,7 @@ messages about the merge, such as:</p></div> </li>
<li>
<p>
-"Failed to merge submodule <submodule> (<reason>)"
+"Failed to merge submodule <submodule> (no merge base)"
</p>
</li>
<li>
@@ -913,9 +979,16 @@ messages about the merge, such as:</p></div> </p>
</li>
</ul></div>
-<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>If <code>-z</code> is NOT passed:</p></div>
+<div class="paragraph"><p>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.</p></div>
</div>
</div>
</div>
@@ -925,7 +998,10 @@ of text taking up the remainder of the output.</p></div> <div class="paragraph"><p>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).</p></div>
+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.</p></div>
</div>
</div>
<div class="sect1">
@@ -1052,7 +1128,7 @@ large repositories).</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-07-18 13:37:02 PDT
+ 2022-11-04 21:49:36 PDT
</div>
</div>
</body>
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: + + <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/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 <h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="verseblock">
-<pre class="content"><em>git patch-id</em> [--stable | --unstable]</pre>
+<pre class="content"><em>git patch-id</em> [--stable | --unstable | --verbatim]</pre>
<div class="attribution">
</div></div>
</div>
@@ -759,10 +759,10 @@ git-patch-id(1) Manual Page <div class="sectionbody">
<div class="paragraph"><p>Read a patch from the standard input and compute the patch ID for it.</p></div>
<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>IOW, you can use this thing to look for likely duplicate commits.</p></div>
+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.</p></div>
+<div class="paragraph"><p>The main usecase for this command is to look for likely duplicate commits.</p></div>
<div class="paragraph"><p>When dealing with <em>git diff-tree</em> 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.</p></div> <div class="sectionbody">
<div class="dlist"><dl>
<dt class="hdlist1">
+--verbatim
+</dt>
+<dd>
+<p>
+ Calculate the patch-id of the input as it is given, do not strip
+ any whitespace.
+</p>
+<div class="literalblock">
+<div class="content">
+<pre><code>This is the default if patchid.verbatim is true.</code></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
--stable
</dt>
<dd>
@@ -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.
</p>
+</li>
+<li>
+<p>
+All whitespace within the patch is ignored and does not affect the id.
+</p>
<div class="literalblock">
<div class="content">
<pre><code>This is the default if patchid.stable is set to true.</code></pre>
@@ -814,9 +832,9 @@ Result is different from the value produced by git 1.9 and older <p>
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.
</p>
<div class="literalblock">
<div class="content">
@@ -837,7 +855,7 @@ Result is different from the value produced by git 1.9 and older <div id="footer">
<div id="footer-text">
Last updated
- 2020-03-10 15:02:33 PDT
+ 2022-11-04 21:49:36 PDT
</div>
</div>
</body>
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<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/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.</p></div> merge base of <code><upstream></code> and <code><branch></code>. Running
<code>git rebase --keep-base <upstream> <branch></code> is equivalent to
running
- <code>git rebase --onto <upstream>...<branch> <upstream> <branch></code>.
+ <code>git rebase --reapply-cherry-picks --no-fork-point --onto <upstream>...<branch> <upstream> <branch></code>.
</p>
<div class="paragraph"><p>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.</p></div>
+rebasing on top of the upstream but to keep the base commit as-is. As
+the base commit is unchanged this option implies <code>--reapply-cherry-picks</code>
+to avoid losing commits.</p></div>
<div class="paragraph"><p>Although both this option and <code>--fork-point</code> find the merge base between
<code><upstream></code> and <code><branch></code>, this option uses the merge base as the <em>starting
point</em> on which new commits will be created, whereas <code>--fork-point</code> uses
@@ -1046,7 +1048,8 @@ the merge base to determine the <em>set of commits</em> which will be rebased.</ <div class="paragraph"><p>Note that commits which start empty are kept (unless <code>--no-keep-empty</code>
is specified), and commits which are clean cherry-picks (as determined
by <code>git log --cherry-mark ...</code>) are detected and dropped as a
-preliminary step (unless <code>--reapply-cherry-picks</code> is passed).</p></div>
+preliminary step (unless <code>--reapply-cherry-picks</code> or <code>--keep-base</code> is
+passed).</p></div>
<div class="paragraph"><p>See also INCOMPATIBLE OPTIONS below.</p></div>
</dd>
<dt class="hdlist1">
@@ -1088,17 +1091,22 @@ see the <code>--empty</code> flag.</p></div> upstream changes, the behavior towards them is controlled by
the <code>--empty</code> flag.)
</p>
-<div class="paragraph"><p>By default (or if <code>--no-reapply-cherry-picks</code> 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 <em>merge</em>
-backend, warnings will be issued for each dropped commit (unless
-<code>--quiet</code> is given). Advice will also be issued unless
-<code>advice.skippedCherryPicks</code> is set to false (see <a href="git-config.html">git-config(1)</a>).</p></div>
-<div class="paragraph"><p><code>--reapply-cherry-picks</code> allows rebase to forgo reading all upstream
-commits, potentially improving performance.</p></div>
-<div class="paragraph"><p>See also INCOMPATIBLE OPTIONS below.</p></div>
+<div class="paragraph"><p>In the absence of <code>--keep-base</code> (or if <code>--no-reapply-cherry-picks</code> 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 <em>merge</em> backend, warnings will be issued for each
+dropped commit (unless <code>--quiet</code> is given). Advice will also be issued
+unless <code>advice.skippedCherryPicks</code> is set to false (see
+<a href="git-config.html">git-config(1)</a>).</p></div>
</dd>
+</dl></div>
+<div class="paragraph"><p>+
+<code>--reapply-cherry-picks</code> allows rebase to forgo reading all upstream
+commits, potentially improving performance.</p></div>
+<div class="paragraph"><p>+
+See also INCOMPATIBLE OPTIONS below.</p></div>
+<div class="dlist"><dl>
<dt class="hdlist1">
--allow-empty-message
</dt>
@@ -1330,9 +1338,9 @@ details).</p></div> <em>fork_point</em> is the result of <code>git merge-base --fork-point <upstream>
<branch></code> command (see <a href="git-merge-base.html">git-merge-base(1)</a>). If <em>fork_point</em>
ends up being empty, the <code><upstream></code> will be used as a fallback.</p></div>
-<div class="paragraph"><p>If <code><upstream></code> is given on the command line, then the default is
-<code>--no-fork-point</code>, otherwise the default is <code>--fork-point</code>. See also
-<code>rebase.forkpoint</code> in <a href="git-config.html">git-config(1)</a>.</p></div>
+<div class="paragraph"><p>If <code><upstream></code> or <code>--keep-base</code> is given on the command line, then
+the default is <code>--no-fork-point</code>, otherwise the default is
+<code>--fork-point</code>. See also <code>rebase.forkpoint</code> in <a href="git-config.html">git-config(1)</a>.</p></div>
<div class="paragraph"><p>If your branch was based on <code><upstream></code> but <code><upstream></code> was rewound and
your branch contains commits which were dropped, this option can be used
with <code>--keep-base</code> in order to drop those commits from your branch.</p></div>
@@ -2757,7 +2765,7 @@ sequence.editor <div id="footer">
<div id="footer-text">
Last updated
- 2022-09-14 13:23:11 PDT
+ 2022-11-04 21:49:36 PDT
</div>
</div>
</body>
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 `<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/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 <code>auto</code>.</p></div> </dt>
<dd>
<p>
- Specify the encryption to use, either <em>ssl</em> or <em>tls</em>. Any other
- value reverts to plain SMTP. Default is the value of
- <code>sendemail.smtpEncryption</code>.
+ Specify in what way encrypting begins for the SMTP connection.
+ Valid values are <em>ssl</em> and <em>tls</em>. 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. <em>ssl</em> refers to "implicit"
+ encryption (sometimes called SMTPS), that uses port 465 by default.
+ <em>tls</em> 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
+ <em>tls</em> 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 <code>sendemail.smtpEncryption</code>.
</p>
</dd>
<dt class="hdlist1">
@@ -1803,7 +1812,7 @@ Authen::SASL and Mail::Address.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-09-14 13:23:11 PDT
+ 2022-11-04 21:49:36 PDT
</div>
</div>
</body>
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=<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/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.</p></div> </div></div>
</dd>
<dt class="hdlist1">
+--date=<format>
+</dt>
+<dd>
+<p>
+ Show dates formatted according to the given date string. (See
+ the <code>--date</code> option in the "Commit Formatting" section of
+ <a href="git-log.html">git-log(1)</a>). Useful with <code>--group=format:<format></code>.
+</p>
+</dd>
+<dt class="hdlist1">
--group=<type>
</dt>
<dd>
@@ -849,6 +859,13 @@ reference to the current repository.</p></div> to see who has been reviewing with
<code>git shortlog -ns --group=trailer:reviewed-by</code>.
</p>
+</li>
+<li>
+<p>
+<code>format:<format></code>, any string accepted by the <code>--format</code> option of
+ <em>git log</em>. (See the "PRETTY FORMATS" section of
+ <a href="git-log.html">git-log(1)</a>.)
+</p>
<div class="paragraph"><p>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.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2021-12-10 14:52:02 PST
+ 2022-11-04 21:49:36 PDT
</div>
</div>
</body>
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=<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/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.</p></div> </p>
</li>
</ul></div>
-<div class="paragraph"><p>When a critical vulnerability is discovered and fixed, we follow this
-script to coordinate a public release.</p></div>
+<div class="paragraph"><p>When a vulnerability is reported, we follow these guidelines to
+assess the vulnerability, create and review a fix, and coordinate embargoed
+security releases.</p></div>
<div class="ulist"><ul>
<li>
<p>
@@ -894,7 +895,7 @@ later validate it.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-03 09:55:14 PDT
+ 2022-11-04 21:49:37 PDT
</div>
</div>
</body>
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 <gitster@pobox.com> 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 @@ <head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 10.2.0" />
-<title>How we coordinate embargoed releases</title>
+<title></title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
@@ -734,10 +734,10 @@ asciidoc.install(); </head>
<body class="article">
<div id="header">
-<h1>How we coordinate embargoed releases</h1>
</div>
<div id="content">
-<div id="preamble">
+<div class="sect1">
+<h2 id="_how_we_coordinate_embargoed_releases">How we coordinate embargoed releases</h2>
<div class="sectionbody">
<div class="paragraph"><p>To protect Git users from critical vulnerabilities, we do not just release
fixed versions like regular maintenance releases. Instead, we coordinate
@@ -747,33 +747,201 @@ what Operating System or distribution they run.</p></div> </div>
</div>
<div class="sect1">
-<h2 id="_open_a_security_advisory_draft">Open a Security Advisory draft</h2>
+<h2 id="_the_code_git_security_code_mailing_list">The <code>git-security</code> mailing list</h2>
<div class="sectionbody">
-<div class="paragraph"><p>The first step is to <a href="https://github.com/git/git/security/advisories/new">open an
-advisory</a>. 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.</p></div>
+<div class="paragraph"><p>Responsible disclosures of vulnerabilities, analysis, proposed fixes as
+well as the orchestration of coordinated embargoed releases all happen on the
+<code>git-security</code> mailing list at <<a href="mailto:git-security@googlegroups.com">git-security@googlegroups.com</a>>.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="sect2">
+<h3 id="_audience_of_the_code_git_security_code_mailing_list">Audience of the <code>git-security</code> mailing list</h3>
+<div class="paragraph"><p>Anybody may contact the <code>git-security</code> mailing list by sending an email
+to <<a href="mailto:git-security@googlegroups.com">git-security@googlegroups.com</a>>, though the archive is closed to the
+public and only accessible to subscribed members.</p></div>
+<div class="paragraph"><p>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).</p></div>
+<div class="paragraph"><p>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.</p></div>
</div>
+<div class="sect2">
+<h3 id="_communications">Communications</h3>
+<div class="paragraph"><p>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.</p></div>
</div>
-<div class="sect1">
-<h2 id="_release_date_of_the_embargoed_version">Release date of the embargoed version</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>If the vulnerability affects the server side, or can benefit from scans on the
-server side (i.e. if <code>git fsck</code> can detect an attack), it is important to give
-all involved Git repository hosting sites enough time to scan all of those
-repositories.</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_notifying_the_linux_distributions">Notifying the Linux distributions</h2>
+<h2 id="_typical_timeline">Typical timeline</h2>
<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
+<p>
+A potential vulnerability is reported to the <code>git-security</code> mailing list.
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+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 <code>git-security</code> list.
+</p>
+</li>
+<li>
+<p>
+If it is deemed critical enough for an embargo, ideas are presented on how to
+ address the vulnerability.
+</p>
+</li>
+<li>
+<p>
+Usually around that time, the Git maintainer or their delegate(s) open a draft
+ security advisory in the <code>git/git</code> repository on GitHub (see below for more
+ details).
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+Subsequently, branches with the fixes are pushed to the git/cabal repository.
+</p>
+</li>
+<li>
+<p>
+The tags are created by the Git maintainer and pushed to the same repository.
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+The release artifacts prepared by various binary packagers can be
+ made available to stakeholders under embargo via a mail to the
+ <code>git-security</code> list.
+</p>
+</li>
+<li>
+<p>
+Less than a week before the release, a mail with the relevant information is
+ sent to <<a href="mailto:distros@vs.openwall.org">distros@vs.openwall.org</a>> (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.
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+On the day of the release, at around 10am Pacific Time, the Git maintainer
+ pushes the tag and the <code>master</code> branch to the public repository, then sends
+ out an announcement mail.
+</p>
+</li>
+<li>
+<p>
+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).
+</p>
+</li>
+<li>
+<p>
+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.
+</p>
+</li>
+<li>
+<p>
+Ditto for distribution packagers for Linux and other platforms:
+ their releases are announced via their preferred channels.
+</p>
+</li>
+<li>
+<p>
+A mail to <<a href="mailto:oss-security@lists.openwall.org">oss-security@lists.openwall.org</a>> (see below for details) is sent
+ as a follow-up to the <<a href="mailto:distros@vs.openwall.org">distros@vs.openwall.org</a>> one, describing the
+ vulnerability in detail, often including a proof of concept of an exploit.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="sect2">
+<h3 id="_opening_a_security_advisory_draft">Opening a Security Advisory draft</h3>
+<div class="paragraph"><p>The first step is to <a href="https://github.com/git/git/security/advisories/new">open
+an advisory</a>. 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.</p></div>
+</div>
+<div class="sect2">
+<h3 id="_notifying_the_linux_distributions">Notifying the Linux distributions</h3>
<div class="paragraph"><p>At most two weeks before release date, we need to send a notification to
-<a href="mailto:distros@vs.openwall.org">distros@vs.openwall.org</a>, preferably less than 7 days before the release date.
+<<a href="mailto:distros@vs.openwall.org">distros@vs.openwall.org</a>>, 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
<a href="https://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists">here</a>.</p></div>
@@ -798,10 +966,8 @@ created using a command like this:</p></div> tar cJvf cve-xxx.bundle.tar.xz cve-xxx.bundle</code></pre>
</div></div>
</div>
-</div>
-<div class="sect1">
-<h2 id="_example_mail_to_a_href_mailto_distros_vs_openwall_org_distros_vs_openwall_org_a">Example mail to <a href="mailto:distros@vs.openwall.org">distros@vs.openwall.org</a></h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_example_mail_to_a_href_mailto_distros_vs_openwall_org_distros_vs_openwall_org_a">Example mail to <a href="mailto:distros@vs.openwall.org">distros@vs.openwall.org</a></h3>
<div class="literalblock">
<div class="content">
<pre><code>To: distros@vs.openwall.org
@@ -835,10 +1001,8 @@ Thanks, <name></code></pre>
</div></div>
</div>
-</div>
-<div class="sect1">
-<h2 id="_example_mail_to_a_href_mailto_oss_security_lists_openwall_com_oss_security_lists_openwall_com_a">Example mail to <a href="mailto:oss-security@lists.openwall.com">oss-security@lists.openwall.com</a></h2>
-<div class="sectionbody">
+<div class="sect2">
+<h3 id="_example_mail_to_a_href_mailto_oss_security_lists_openwall_com_oss_security_lists_openwall_com_a">Example mail to <a href="mailto:oss-security@lists.openwall.com">oss-security@lists.openwall.com</a></h3>
<div class="literalblock">
<div class="content">
<pre><code>To: oss-security@lists.openwall.com
@@ -869,11 +1033,12 @@ Thanks, </div>
</div>
</div>
+</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:30 PDT
+ 2022-11-04 21:50:28 PDT
</div>
</div>
</body>
diff --git a/howto/coordinate-embargoed-releases.txt b/howto/coordinate-embargoed-releases.txt index 601aae88e..e653775ba 100644 --- a/howto/coordinate-embargoed-releases.txt +++ b/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/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html index 6fb739a93..019afbc06 100644 --- a/howto/keep-canonical-history-correct.html +++ b/howto/keep-canonical-history-correct.html @@ -938,7 +938,7 @@ tip of your <em>master</em> again and redo the two merges:</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:29 PDT
+ 2022-11-04 21:50:28 PDT
</div>
</div>
</body>
diff --git a/howto/maintain-git.html b/howto/maintain-git.html index b011ca141..767862584 100644 --- a/howto/maintain-git.html +++ b/howto/maintain-git.html @@ -1469,7 +1469,7 @@ $ git update-ref -d $mf/ai/topic</code></pre> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:30 PDT
+ 2022-11-04 21:50:28 PDT
</div>
</div>
</body>
diff --git a/howto/new-command.html b/howto/new-command.html index 5cdbdcfa9..251a7b5ac 100644 --- a/howto/new-command.html +++ b/howto/new-command.html @@ -863,7 +863,7 @@ letter [PATCH 0/n]. <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:27 PDT
+ 2022-11-04 21:50:25 PDT
</div>
</div>
</body>
diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html index 8fbf3940c..5270b7200 100644 --- a/howto/rebase-from-internal-branch.html +++ b/howto/rebase-from-internal-branch.html @@ -895,7 +895,7 @@ the #1' commit.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:29 PDT
+ 2022-11-04 21:50:28 PDT
</div>
</div>
</body>
diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html index 1f1a4abc2..76726d633 100644 --- a/howto/rebuild-from-update-hook.html +++ b/howto/rebuild-from-update-hook.html @@ -847,7 +847,7 @@ This is still crude and does not protect against simultaneous <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:29 PDT
+ 2022-11-04 21:50:28 PDT
</div>
</div>
</body>
diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html index fc7c46824..052527675 100644 --- a/howto/recover-corrupted-blob-object.html +++ b/howto/recover-corrupted-blob-object.html @@ -880,7 +880,7 @@ thing.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:29 PDT
+ 2022-11-04 21:50:27 PDT
</div>
</div>
</body>
diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html index ffec0c27b..911c5138c 100644 --- a/howto/recover-corrupted-object-harder.html +++ b/howto/recover-corrupted-object-harder.html @@ -1189,7 +1189,7 @@ int main(int argc, char **argv) <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:29 PDT
+ 2022-11-04 21:50:28 PDT
</div>
</div>
</body>
diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html index 241bde349..8208e1047 100644 --- a/howto/revert-a-faulty-merge.html +++ b/howto/revert-a-faulty-merge.html @@ -1025,7 +1025,7 @@ P---o---o---M---x---x---W---x---M2 <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:29 PDT
+ 2022-11-04 21:50:27 PDT
</div>
</div>
</body>
diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html index 3d2f84c92..339ea0217 100644 --- a/howto/revert-branch-rebase.html +++ b/howto/revert-branch-rebase.html @@ -907,7 +907,7 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:28 PDT
+ 2022-11-04 21:50:25 PDT
</div>
</div>
</body>
diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html index eb804a6e4..ed4baa4e3 100644 --- a/howto/separating-topic-branches.html +++ b/howto/separating-topic-branches.html @@ -841,7 +841,7 @@ o---o"master"</code></pre> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:29 PDT
+ 2022-11-04 21:50:27 PDT
</div>
</div>
</body>
diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index 89c719b09..51b0cbb45 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html @@ -1071,7 +1071,7 @@ help diagnosing the problem, but removes security checks.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:28 PDT
+ 2022-11-04 21:50:27 PDT
</div>
</div>
</body>
diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html index f9432a11e..874750282 100644 --- a/howto/update-hook-example.html +++ b/howto/update-hook-example.html @@ -930,7 +930,7 @@ that JC can make non-fast-forward pushes on it.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:28 PDT
+ 2022-11-04 21:50:26 PDT
</div>
</div>
</body>
diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html index 0c116af3c..d06b19cf4 100644 --- a/howto/use-git-daemon.html +++ b/howto/use-git-daemon.html @@ -791,7 +791,7 @@ a good practice to put the paths after a "--" separator.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:28 PDT
+ 2022-11-04 21:50:26 PDT
</div>
</div>
</body>
diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html index 1a3acb05f..cead6e188 100644 --- a/howto/using-merge-subtree.html +++ b/howto/using-merge-subtree.html @@ -848,7 +848,7 @@ Please note that if the other project merges from you, then it will <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:28 PDT
+ 2022-11-04 21:50:25 PDT
</div>
</div>
</body>
diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html index 9d0791156..c3a6e94de 100644 --- a/howto/using-signed-tag-in-pull-request.html +++ b/howto/using-signed-tag-in-pull-request.html @@ -952,7 +952,7 @@ as part of the merge commit.</p></div> <div id="footer">
<div id="footer-text">
Last updated
- 2022-10-28 11:54:28 PDT
+ 2022-11-04 21:50:26 PDT
</div>
</div>
</body>
diff --git a/technical/api-trace2.html b/technical/api-trace2.html index b04dcc5eb..e0ceee971 100644 --- a/technical/api-trace2.html +++ b/technical/api-trace2.html @@ -909,69 +909,23 @@ filename collisions).</p></div> <div class="sect1">
<h2 id="_trace2_api">Trace2 API</h2>
<div class="sectionbody">
-<div class="paragraph"><p>All public Trace2 functions and macros are defined in <code>trace2.h</code> and
-<code>trace2.c</code>. All public symbols are prefixed with <code>trace2_</code>.</p></div>
+<div class="paragraph"><p>The Trace2 public API is defined and documented in <code>trace2.h</code>; refer to it for
+more information. All public functions and macros are prefixed
+with <code>trace2_</code> and are implemented in <code>trace2.c</code>.</p></div>
<div class="paragraph"><p>There are no public Trace2 data structures.</p></div>
<div class="paragraph"><p>The Trace2 code also defines a set of private functions and data types
in the <code>trace2/</code> directory. These symbols are prefixed with <code>tr2_</code>
-and should only be used by functions in <code>trace2.c</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_conventions_for_public_functions_and_macros">Conventions for Public Functions and Macros</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The functions defined by the Trace2 API are declared and documented
-in <code>trace2.h</code>. It defines the API functions and wrapper macros for
-Trace2.</p></div>
+and should only be used by functions in <code>trace2.c</code> (or other private
+source files in <code>trace2/</code>).</p></div>
+<div class="sect2">
+<h3 id="_conventions_for_public_functions_and_macros">Conventions for Public Functions and Macros</h3>
<div class="paragraph"><p>Some functions have a <code>_fl()</code> suffix to indicate that they take <code>file</code>
and <code>line-number</code> arguments.</p></div>
<div class="paragraph"><p>Some functions have a <code>_va_fl()</code> suffix to indicate that they also
take a <code>va_list</code> argument.</p></div>
<div class="paragraph"><p>Some functions have a <code>_printf_fl()</code> suffix to indicate that they also
take a <code>printf()</code> style format with a variable number of arguments.</p></div>
-<div class="paragraph"><p>There are CPP wrapper macros and <code>#ifdef`s to hide most of these details.
-See `trace2.h</code> for more details. The following discussion will only
-describe the simplified forms.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_public_api">Public API</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All Trace2 API functions send a message to all of the active
-Trace2 Targets. This section describes the set of available
-messages.</p></div>
-<div class="paragraph"><p>It helps to divide these functions into groups for discussion
-purposes.</p></div>
-<div class="sect2">
-<h3 id="_basic_command_messages">Basic Command Messages</h3>
-<div class="paragraph"><p>These are concerned with the lifetime of the overall git process.
-e.g: <code>void trace2_initialize_clock()</code>, <code>void trace2_initialize()</code>,
-<code>int trace2_is_enabled()</code>, <code>void trace2_cmd_start(int argc, const char **argv)</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_command_detail_messages">Command Detail Messages</h3>
-<div class="paragraph"><p>These are concerned with describing the specific Git command
-after the command line, config, and environment are inspected.
-e.g: <code>void trace2_cmd_name(const char *name)</code>,
-<code>void trace2_cmd_mode(const char *mode)</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_child_process_messages">Child Process Messages</h3>
-<div class="paragraph"><p>These are concerned with the various spawned child processes,
-including shell scripts, git commands, editors, pagers, and hooks.</p></div>
-<div class="paragraph"><p>e.g: <code>void trace2_child_start(struct child_process *cmd)</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_git_thread_messages">Git Thread Messages</h3>
-<div class="paragraph"><p>These messages are concerned with Git thread usage.</p></div>
-<div class="paragraph"><p>e.g: <code>void trace2_thread_start(const char *thread_name)</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_region_and_data_messages">Region and Data Messages</h3>
-<div class="paragraph"><p>These are concerned with recording performance data
-over regions or spans of code. e.g:
-<code>void trace2_region_enter(const char *category, const char *label, const struct repository *repo)</code>.</p></div>
-<div class="paragraph"><p>Refer to trace2.h for details about all trace2 functions.</p></div>
+<div class="paragraph"><p>CPP wrapper macros are defined to hide most of these details.</p></div>
</div>
</div>
</div>
@@ -1600,8 +1554,8 @@ not be compared to the child’s atexit times.</p></div> <dd>
<p>
This event is generated when a thread is started. It is
- generated from <strong>within</strong> the new thread’s thread-proc (for TLS
- reasons).
+ generated from <strong>within</strong> the new thread’s thread-proc (because
+ it needs to access data in the thread’s thread-local storage).
</p>
<div class="listingblock">
<div class="content">
@@ -1618,7 +1572,7 @@ not be compared to the child’s atexit times.</p></div> <dd>
<p>
This event is generated when a thread exits. It is generated
- from <strong>within</strong> the thread’s thread-proc (for TLS reasons).
+ from <strong>within</strong> the thread’s thread-proc.
</p>
<div class="listingblock">
<div class="content">
@@ -1763,6 +1717,92 @@ filter deeply nested regions and data events. It defaults to "2".</p></div> }</code></pre>
</div></div>
</dd>
+<dt class="hdlist1">
+<code>"th_timer"</code>
+</dt>
+<dd>
+<p>
+ 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.
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>{
+ "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
+}</code></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
+<code>"timer"</code>
+</dt>
+<dd>
+<p>
+ 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.
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>{
+ "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
+}</code></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
+<code>"th_counter"</code>
+</dt>
+<dd>
+<p>
+ 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.
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>{
+ "event":"th_counter",
+ ...
+ "category":"my_category",
+ "name":"my_counter",
+ "count":23
+}</code></pre>
+</div></div>
+</dd>
+<dt class="hdlist1">
+<code>"counter"</code>
+</dt>
+<dd>
+<p>
+ 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.
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>{
+ "event":"counter",
+ ...
+ "category":"my_category",
+ "name":"my_counter",
+ "count":23
+}</code></pre>
+</div></div>
+</dd>
</dl></div>
</div>
</div>
@@ -2171,7 +2211,7 @@ the index. Thread "th01" worked on 508 items at offset 0. Thread "th02" worked on 508 items at offset 2032. Thread "th04" worked on 508 items
at offset 508.</p></div>
<div class="paragraph"><p>This example also shows that thread names are assigned in a racy manner
-as each thread starts and allocates TLS storage.</p></div>
+as each thread starts.</p></div>
</dd>
<dt class="hdlist1">
Config (def param) Events
@@ -2215,6 +2255,61 @@ d0 | main | exit | | 0.000470 | | d0 | main | atexit | | 0.000477 | | | code:0</code></pre>
</div></div>
</dd>
+<dt class="hdlist1">
+Stopwatch Timer Events
+</dt>
+<dd>
+<p>
+ 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.
+</p>
+<div class="listingblock">
+<div class="content">
+<pre><code>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;
+}</code></pre>
+</div></div>
+<div class="paragraph"><p>In this example, we measure the total time spent in
+<code>expensive_function()</code> regardless of when it is called
+in the overall flow of the program.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><code>$ 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</code></pre>
+</div></div>
+</dd>
</dl></div>
</div>
</div>
@@ -2259,7 +2354,7 @@ Trace2 targets (and convert <key> to a "category"). <div id="footer">
<div id="footer-text">
Last updated
- 2022-08-30 10:56:31 PDT
+ 2022-11-04 21:49:36 PDT
</div>
</div>
</body>
diff --git a/technical/api-trace2.txt b/technical/api-trace2.txt index 2afa28bb5..de5fc2505 100644 --- a/technical/api-trace2.txt +++ b/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) |