Autogenerated HTML docs for v2.51.0-573-gb660e2

Author: gitster

RelNotes/2.51.1.adoc

@@ -0,0 +1,46 @@
+Git 2.51.1 Release Notes
+========================
+
+There shouldn't be anything exciting to see here. This is primarily
+to flush the "do you still use it?" improvements that has landed on
+the master front, together with a handful of low-hanging low-impact
+fixes that should be safe.
+
+
+Fixes since Git 2.51.0
+----------------------
+
+ * The "do you still use it?" message given by a command that is
+ deeply deprecated and allow us to suggest alternatives has been
+ updated.
+
+ * The compatObjectFormat extension is used to hide an incomplete
+ feature that is not yet usable for any purpose other than
+ developing the feature further. Document it as such to discourage
+ its use by mere mortals.
+
+ * Manual page for "gitk" is updated with the current maintainer's
+ name.
+
+ * Update the instruction to use of GGG in the MyFirstContribution
+ document to say that a GitHub PR could be made against `git/git`
+ instead of `gitgitgadget/git`.
+
+ * Clang-format update to let our control macros formatted the way we
+ had them traditionally, e.g., "for_each_string_list_item()" without
+ space before the parentheses.
+
+ * A few places where an size_t value was cast to curl_off_t without
+ checking has been updated to use the existing helper function.
+
+ * The start_delayed_progress() function in the progress eye-candy API
+ did not clear its internal state, making an initial delay value
+ larger than 1 second ineffective, which has been corrected.
+
+ * Makefile tried to run multiple "cargo build" which would not work
+ very well; serialize their execution to work it around.
+
+ * Adjust to the way newer versions of cURL selectivel enables tracing
+ options, so that our tests can continue to work.
+
+Also contains various documentation updates, code clean-ups and minor fixups.

RelNotes/2.52.0.adoc

@@ -47,6 +47,14 @@ UI, Workflows & Features
  * "git fast-import" learned that "--signed-commits=<how>" option that
  corresponds to that of "git fast-export".
 
+ * Marking a hunk 'selected' in "git add -p" and then splitting made
+ all the split pieces 'selected' this has been changed to make them
+ all 'undecided', which gives better end-user experience.
+
+ * Configuration variables that take a pathname as a value
+ (e.g. blame.ignorerevsfile) can be marked as optional by prefixing
+ ":(optoinal)" before its value.
+
 
 Performance, Internal Implementation, Development Support etc.
 --------------------------------------------------------------
@@ -116,6 +124,9 @@ Performance, Internal Implementation, Development Support etc.
  * Dip our toes a bit to (optionally) use Rust implemented helper
  called from our C code.
 
+ * Documentation for "git log --pretty" options has been updated
+ to make it easier to translate.
+
 
 Fixes since v2.51
 -----------------
@@ -308,6 +319,16 @@ including security updates, are included in this release.
  carefully.
  (merge 466a3a1afd kn/reftable-consistency-checks later to maint).
 
+ * A lot of code clean-up of xdiff.
+ Split out of a larger topic.
+ (merge 8b9c5d2e3a en/xdiff-cleanup later to maint).
+
+ * "git format-patch --range-diff=... --notes=..." did not drive the
+ underlying range-diff with correct --notes parameter, ending up
+ comparing with different set of notes from its main patch output
+ you would get from "git format-patch --notes=..." for a singleton
+ patch.
+
  * Other code cleanup, docfix, build fix, etc.
  (merge 823d537fa7 kh/doc-git-log-markup-fix later to maint).
  (merge cf7efa4f33 rj/t6137-cygwin-fix later to maint).
@@ -337,3 +358,4 @@ including security updates, are included in this release.
  (merge fdd21ba116 mh/doc-credential-url-prefix later to maint).
  (merge 1c573a3451 en/doc-merge-tree-describe-merge-base later to maint).
  (merge 84a6bf7965 ja/doc-markup-attached-paragraph-fix later to maint).
+ (merge 399694384b kh/doc-patch-id-markup-fix later to maint).

config.adoc

@@ -357,7 +357,9 @@ compiled without runtime prefix support, the compiled-in prefix will be
 substituted instead. In the unlikely event that a literal path needs to
 be specified that should _not_ be expanded, it needs to be prefixed by
 `./`, like so: `./%(prefix)/bin`.
-
++
+If prefixed with `:(optional)`, the configuration variable is treated
+as if it does not exist, if the named path does not exist.
 
 Variables
 ~~~~~~~~~

git-config.html

@@ -1701,6 +1701,10 @@ <h3 id="_values">Values</h3>
 be specified that should <em>not</em> be expanded, it needs to be prefixed by
 .<code>/</code>, like so: .<code>/%</code>(<code>prefix</code>)<code>/bin</code>.</p>
 </div>
+<divclass="paragraph">
+<p>If prefixed with <code>:</code>(<code>optional</code>), the configuration variable is treated
+as if it does not exist, if the named path does not exist.</p>
+</div>
 </dd>
 </dl>
 </div>
@@ -8978,29 +8982,32 @@ <h3 id="_variables">Variables</h3>
 change as git gains new features.</p>
 </div>
 </dd>
-<dtclass="hdlist1">stash.index</dt>
+</dl>
+</div>
+<divclass="dlist">
+<dl>
+<dtclass="hdlist1"><code>stash.index</code></dt>
 <dd>
-<p>If this is set to true, <code>git</code><code>stash</code><code>apply</code> and <code>git</code><code>stash</code><code>pop</code> will
-behave as if <code>--index</code> was supplied. Defaults to false. See the
-descriptions in <ahref="git-stash.html">git-stash(1)</a>.</p>
+<p>If this is set to true, <code>git</code><code>stash</code><code>apply</code> and <code>git</code><code>stash</code><code>pop</code> will
+behave as if <code>--index</code> was supplied. Defaults to false.
+See the descriptions in <ahref="git-stash.html">git-stash(1)</a>.</p>
 </dd>
-<dtclass="hdlist1">stash.showIncludeUntracked</dt>
+<dtclass="hdlist1"><code>stash.showIncludeUntracked</code></dt>
 <dd>
 <p>If this is set to true, the <code>git</code><code>stash</code><code>show</code> command will show
-the untracked files of a stash entry. Defaults to false. See
-the description of the <em>show</em> command in <ahref="git-stash.html">git-stash(1)</a>.</p>
+the untracked files of a stash entry. Defaults to false. See the description of the 'show' command in <ahref="git-stash.html">git-stash(1)</a>.</p>
 </dd>
-<dtclass="hdlist1">stash.showPatch</dt>
+<dtclass="hdlist1"><code>stash.showPatch</code></dt>
 <dd>
 <p>If this is set to true, the <code>git</code><code>stash</code><code>show</code> command without an
 option will show the stash entry in patch form. Defaults to false.
-See the description of the <em>show</em> command in <ahref="git-stash.html">git-stash(1)</a>.</p>
+See the description of the 'show' command in <ahref="git-stash.html">git-stash(1)</a>.</p>
 </dd>
-<dtclass="hdlist1">stash.showStat</dt>
+<dtclass="hdlist1"><code>stash.showStat</code></dt>
 <dd>
 <p>If this is set to true, the <code>git</code><code>stash</code><code>show</code> command without an
 option will show a diffstat of the stash entry. Defaults to true.
-See the description of the <em>show</em> command in <ahref="git-stash.html">git-stash(1)</a>.</p>
+See the description of the 'show' command in <ahref="git-stash.html">git-stash(1)</a>.</p>
 </dd>
 <dtclass="hdlist1">status.relativePaths</dt>
 <dd>
@@ -9236,26 +9243,27 @@ <h3 id="_variables">Variables</h3>
 or <code>info</code>, and if there is an error with the computed alternate, the
 clone proceeds as if no alternate was specified.</p>
 </dd>
-<dtclass="hdlist1">tag.forceSignAnnotated</dt>
+<dtclass="hdlist1"><code>tag.forceSignAnnotated</code></dt>
 <dd>
 <p>A boolean to specify whether annotated tags created should be GPG signed.
 If <code>--annotate</code> is specified on the command line, it takes
 precedence over this option.</p>
 </dd>
-<dtclass="hdlist1">tag.sort</dt>
+<dtclass="hdlist1"><code>tag.sort</code></dt>
 <dd>
 <p>This variable controls the sort ordering of tags when displayed by
-<ahref="git-tag.html">git-tag(1)</a>. Without the "--sort=&lt;value&gt;" option provided, the
-value of this variable will be used as the default.</p>
+<ahref="git-tag.html">git-tag(1)</a>.
+Without the <code>--sort=</code><em>&lt;value&gt;</em> option provided, the value of this variable will
+be used as the default.</p>
 </dd>
-<dtclass="hdlist1">tag.gpgSign</dt>
+<dtclass="hdlist1"><code>tag.gpgSign</code></dt>
 <dd>
 <p>A boolean to specify whether all tags should be GPG signed.
 Use of this option when running in an automated script can
 result in a large number of tags being signed. It is therefore
-convenient to use an agent to avoid typing your gpg passphrase
+convenient to use an agent to avoid typing your GPG passphrase
 several times. Note that this option doesn&#8217;t affect tag signing
-behavior enabled by "-u &lt;keyid&gt;" or "--local-user=&lt;keyid&gt;" options.</p>
+behavior enabled by <code>-u</code><em>&lt;keyid&gt;</em> or <code>--local-user=</code><em>&lt;keyid&gt;</em> options.</p>
 </dd>
 <dtclass="hdlist1">tar.umask</dt>
 <dd>
@@ -9949,7 +9957,7 @@ <h3 id="_variables">Variables</h3>
 Currently only <ahref="git-instaweb.html">git-instaweb(1)</a> and <ahref="git-help.html">git-help(1)</a>
 may use it.</p>
 </dd>
-<dtclass="hdlist1">worktree.guessRemote</dt>
+<dtclass="hdlist1"><code>worktree.guessRemote</code></dt>
 <dd>
 <p>If no branch is specified and neither <code>-b</code> nor <code>-B</code> nor
 <code>--detach</code> is used, then <code>git</code><code>worktree</code><code>add</code> defaults to
@@ -9958,16 +9966,16 @@ <h3 id="_variables">Variables</h3>
 branch whose name uniquely matches the new branch name. If
 such a branch exists, it is checked out and set as "upstream"
 for the new branch. If no such match can be found, it falls
-back to creating a new branch from the current HEAD.</p>
+back to creating a new branch from the current <code>HEAD</code>.</p>
 </dd>
-<dtclass="hdlist1">worktree.useRelativePaths</dt>
+<dtclass="hdlist1"><code>worktree.useRelativePaths</code></dt>
 <dd>
-<p>Link worktrees using relative paths (when "true") or absolute
-paths (when "false"). This is particularly useful for setups
+<p>Link worktrees using relative paths (when "<code>true</code>") or absolute
+paths (when "<code>false</code>"). This is particularly useful for setups
 where the repository and worktrees may be moved between
-different locations or environments. Defaults to "false".</p>
+different locations or environments. Defaults to "<code>false</code>".</p>
 <divclass="paragraph">
-<p>Note that setting <code>worktree.useRelativePaths</code> to "true" implies enabling the
+<p>Note that setting <code>worktree.useRelativePaths</code> to "<code>true</code>" implies enabling the
 <code>extensions.relativeWorktrees</code> config (see <ahref="git-config.html">git-config(1)</a>),
 thus making it incompatible with older versions of Git.</p>
 </div>

git-diff-tree.html

@@ -1577,10 +1577,10 @@ <h2 id="_options">OPTIONS</h2>
 </dd>
 <dtclass="hdlist1"><code>--notes</code>[<code>=</code><em>&lt;ref&gt;</em>]</dt>
 <dd>
-<p>Show the notes (see <ahref="git-notes.html">git-notes(1)</a>) that annotate the
-commit, when showing the commit log message. This is the default
-for <code>git</code><code>log</code>, <code>git</code><code>show</code> and <code>git</code><code>whatchanged</code> commands when
-there is no <code>--pretty</code>, <code>--format</code>, or <code>--oneline</code> option given
+<p>Show the notes (see <ahref="git-notes.html">git-notes(1)</a>) that annotate the
+commit, when showing the commit log message.
+This is the default for <code>git</code><code>log</code>, <code>git</code><code>show</code> and <code>git</code><code>whatchanged</code>
+commands when there is no <code>--pretty</code>, <code>--format</code>, or <code>--oneline</code> option given
 on the command line.</p>
 <divclass="paragraph">
 <p>By default, the notes shown are from the notes refs listed in the

git-fetch.html

@@ -1264,6 +1264,83 @@ <h3 id="_named_file_in_git_dirbranches">Named file in <code>$GIT_DIR/branches</c
 </div>
 </div>
 <divclass="sect1">
+<h2id="UPSTREAM-BRANCHES">UPSTREAM BRANCHES</h2>
+<divclass="sectionbody">
+<divclass="paragraph">
+<p>Branches in Git can optionally have an upstream remote branch.
+Git defaults to using the upstream branch for remote operations, for example:</p>
+</div>
+<divclass="ulist">
+<ul>
+<li>
+<p>It&#8217;s the default for <code>git</code><code>pull</code> or <code>git</code><code>fetch</code> with no arguments.</p>
+</li>
+<li>
+<p>It&#8217;s the default for <code>git</code><code>push</code> with no arguments, with some exceptions.
+For example, you can use the <code>branch.</code><em>&lt;name&gt;</em><code>.pushRemote</code> option to push
+to a different remote than you pull from, and by default with
+<code>push.default=simple</code> the upstream branch you configure must have
+the same name.</p>
+</li>
+<li>
+<p>Various commands, including <code>git</code><code>checkout</code> and <code>git</code><code>status</code>, will
+show you how many commits have been added to your current branch and
+the upstream since you forked from it, for example "Your branch and
+<em>origin/main</em> have diverged, and have 2 and 3 different commits each
+respectively".</p>
+</li>
+</ul>
+</div>
+<divclass="paragraph">
+<p>The upstream is stored in .<code>git/config</code>, in the "remote" and "merge"
+fields. For example, if <code>main</code>'s upstream is <code>origin/main</code>:</p>
+</div>
+<divclass="listingblock">
+<divclass="content">
+<pre>[branch "main"]
+ remote = origin
+ merge = refs/heads/main</pre>
+</div>
+</div>
+<divclass="paragraph">
+<p>You can set an upstream branch explicitly with
+<code>git</code><code>push</code><code>--set-upstream</code><em>&lt;remote&gt;</em><em>&lt;branch&gt;</em>
+but Git will often automatically set the upstream for you, for example:</p>
+</div>
+<divclass="ulist">
+<ul>
+<li>
+<p>When you clone a repository, Git will automatically set the upstream
+for the default branch.</p>
+</li>
+<li>
+<p>If you have the <code>push.autoSetupRemote</code> configuration option set,
+<code>git</code><code>push</code> will automatically set the upstream the first time you push
+a branch.</p>
+</li>
+<li>
+<p>Checking out a remote-tracking branch with <code>git</code><code>checkout</code><em>&lt;branch&gt;</em>
+will automatically create a local branch with that name and set
+the upstream to the remote branch.</p>
+</li>
+</ul>
+</div>
+<divclass="admonitionblock note">
+<table>
+<tr>
+<tdclass="icon">
+<divclass="title">Note</div>
+</td>
+<tdclass="content">
+Upstream branches are sometimes referred to as "tracking information",
+as in "set the branch&#8217;s tracking information".
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<divclass="sect1">
 <h2id="_configured_remote_tracking_branches">CONFIGURED REMOTE-TRACKING BRANCHES<aid="CRTB"></a></h2>
 <divclass="sectionbody">
 <divclass="paragraph">

git-log.html

@@ -1788,10 +1788,10 @@ <h3 id="_commit_formatting">Commit Formatting</h3>
 </dd>
 <dtclass="hdlist1"><code>--notes</code>[<code>=</code><em>&lt;ref&gt;</em>]</dt>
 <dd>
-<p>Show the notes (see <ahref="git-notes.html">git-notes(1)</a>) that annotate the
-commit, when showing the commit log message. This is the default
-for <code>git</code><code>log</code>, <code>git</code><code>show</code> and <code>git</code><code>whatchanged</code> commands when
-there is no <code>--pretty</code>, <code>--format</code>, or <code>--oneline</code> option given
+<p>Show the notes (see <ahref="git-notes.html">git-notes(1)</a>) that annotate the
+commit, when showing the commit log message.
+This is the default for <code>git</code><code>log</code>, <code>git</code><code>show</code> and <code>git</code><code>whatchanged</code>
+commands when there is no <code>--pretty</code>, <code>--format</code>, or <code>--oneline</code> option given
 on the command line.</p>
 <divclass="paragraph">
 <p>By default, the notes shown are from the notes refs listed in the