963 files changed, 10482 insertions, 5492 deletions

diff --git a/Documentation/.gitattributes b/Documentation/.gitattributes
deleted file mode 100644
index ddb030137d..0000000000
--- a/Documentation/.gitattributes
+++ /dev/null
@@ -1 +0,0 @@
-*.txt whitespace
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 9f4bb3c4bf..dd54cc768a 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -6,11 +6,11 @@
 *.pdf
 git.info
 gitman.info
-howto-index.txt
+howto-index.adoc
 doc.dep
-cmds-*.txt
-mergetools-*.txt
-SubmittingPatches.txt
+cmds-*.adoc
+mergetools-*.adoc
+SubmittingPatches.adoc
 tmp-doc-diff/
 tmp-meson-diff/
 GIT-ASCIIDOCFLAGS
diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
new file mode 100644
index 0000000000..f814450d2f
--- /dev/null
+++ b/Documentation/BreakingChanges.adoc
@@ -0,0 +1,335 @@
+= Upcoming breaking changes
+
+The Git project aims to ensure backwards compatibility to the best extent
+possible. Minor releases will not break backwards compatibility unless there is
+a very strong reason to do so, like for example a security vulnerability.
+
+Regardless of that, due to the age of the Git project, it is only natural to
+accumulate a backlog of backwards-incompatible changes that will eventually be
+required to keep the project aligned with a changing world. These changes fall
+into several categories:
+
+* Changes to long established defaults.
+* Concepts that have been replaced with a superior design.
+* Concepts, commands, configuration or options that have been lacking in major
+  ways and that cannot be fixed and which will thus be removed without any
+  replacement.
+
+Explicitly not included in this list are fixes to minor bugs that may cause a
+change in user-visible behavior.
+
+The Git project irregularly releases breaking versions that deliberately break
+backwards compatibility with older versions. This is done to ensure that Git
+remains relevant, safe and maintainable going forward. The release cadence of
+breaking versions is typically measured in multiple years. We had the following
+major breaking releases in the past:
+
+* Git 1.6.0, released in August 2008.
+* Git 2.0, released in May 2014.
+
+We use <major>.<minor> release numbers these days, starting from Git 2.0. For
+future releases, our plan is to increment <major> in the release number when we
+make the next breaking release. Before Git 2.0, the release numbers were
+1.<major>.<minor> with the intention to increment <major> for "usual" breaking
+releases, reserving the jump to Git 2.0 for really large backward-compatibility
+breaking changes.
+
+The intent of this document is to track upcoming deprecations for future
+breaking releases. Furthermore, this document also tracks what will _not_ be
+deprecated. This is done such that the outcome of discussions document both
+when the discussion favors deprecation, but also when it rejects a deprecation.
+
+Items should have a clear summary of the reasons why we do or do not want to
+make the described change that can be easily understood without having to read
+the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
+where the deprecation was discussed. These references use message-IDs, which
+can visited via
+
+  https://lore.kernel.org/git/$message_id/
+
+to see the message and its surrounding discussion. Such a reference is there to
+make it easier for you to find how the project reached consensus on the
+described item back then.
+
+This is a living document as the environment surrounding the project changes
+over time. If circumstances change, an earlier decision to deprecate or change
+something may need to be revisited from time to time. So do not take items on
+this list to mean "it is settled, do not waste our time bringing it up again".
+
+== Procedure
+
+Discussing the desire to make breaking changes, declaring that breaking
+changes are made at a certain version boundary, and recording these
+decisions in this document, are necessary but not sufficient.
+Because such changes are expected to be numerous, and the design and
+implementation of them are expected to span over time, they have to
+be deployable trivially at such a version boundary, prepared over long
+time.
+
+The breaking changes MUST be guarded with the a compile-time switch,
+WITH_BREAKING_CHANGES, to help this process.  When built with it,
+the resulting Git binary together with its documentation would
+behave as if these breaking changes slated for the next big version
+boundary are already in effect.  We also have a CI job to exercise
+the work-in-progress version of Git with these breaking changes.
+
+
+== Git 3.0
+
+The following subsections document upcoming breaking changes for Git 3.0. There
+is no planned release date for this breaking version yet.
+
+Proposed changes and removals only include items which are "ready" to be done.
+In other words, this is not supposed to be a wishlist of features that should
+be changed to or replaced in case the alternative was implemented already.
+
+=== Changes
+
+* The default hash function for new repositories will be changed from "sha1"
+  to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
+  recommended against in FIPS 140-2 and similar certifications. Furthermore,
+  there are practical attacks on SHA-1 that weaken its cryptographic properties:
++
+  ** The SHAppening (2015). The first demonstration of a practical attack
+     against SHA-1 with 2^57 operations.
+  ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
+  ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
+     attacks with 2^68 operations.
+  ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
+     operations.
++
+While we have protections in place against known attacks, it is expected
+that more attacks against SHA-1 will be found by future research. Paired
+with the ever-growing capability of hardware, it is only a matter of time
+before SHA-1 will be considered broken completely. We want to be prepared
+and will thus change the default hash algorithm to "sha256" for newly
+initialized repositories.
++
+An important requirement for this change is that the ecosystem is ready to
+support the "sha256" object format. This includes popular Git libraries,
+applications and forges.
++
+There is no plan to deprecate the "sha1" object format at this point in time.
++
+Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
+<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
+<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+
+* The default storage format for references in newly created repositories will
+  be changed from "files" to "reftable". The "reftable" format provides
+  multiple advantages over the "files" format:
++
+  ** It is impossible to store two references that only differ in casing on
+     case-insensitive filesystems with the "files" format. This issue is common
+     on Windows and macOS platforms. As the "reftable" backend does not use
+     filesystem paths to encode reference names this problem goes away.
+  ** Similarly, macOS normalizes path names that contain unicode characters,
+     which has the consequence that you cannot store two names with unicode
+     characters that are encoded differently with the "files" backend. Again,
+     this is not an issue with the "reftable" backend.
+  ** Deleting references with the "files" backend requires Git to rewrite the
+     complete "packed-refs" file. In large repositories with many references
+     this file can easily be dozens of megabytes in size, in extreme cases it
+     may be gigabytes. The "reftable" backend uses tombstone markers for
+     deleted references and thus does not have to rewrite all of its data.
+  ** Repository housekeeping with the "files" backend typically performs
+     all-into-one repacks of references. This can be quite expensive, and
+     consequently housekeeping is a tradeoff between the number of loose
+     references that accumulate and slow down operations that read references,
+     and compressing those loose references into the "packed-refs" file. The
+     "reftable" backend uses geometric compaction after every write, which
+     amortizes costs and ensures that the backend is always in a
+     well-maintained state.
+  ** Operations that write multiple references at once are not atomic with the
+     "files" backend. Consequently, Git may see in-between states when it reads
+     references while a reference transaction is in the process of being
+     committed to disk.
+  ** Writing many references at once is slow with the "files" backend because
+     every reference is created as a separate file. The "reftable" backend
+     significantly outperforms the "files" backend by multiple orders of
+     magnitude.
+  ** The reftable backend uses a binary format with prefix compression for
+     reference names. As a result, the format uses less space compared to the
+     "packed-refs" file.
++
+Users that get immediate benefit from the "reftable" backend could continue to
+opt-in to the "reftable" format manually by setting the "init.defaultRefFormat"
+config. But defaults matter, and we think that overall users will have a better
+experience with less platform-specific quirks when they use the new backend by
+default.
++
+A prerequisite for this change is that the ecosystem is ready to support the
+"reftable" format. Most importantly, alternative implementations of Git like
+JGit, libgit2 and Gitoxide need to support it.
+
+* In new repositories, the default branch name will be `main`. We have been
+  warning that the default name will change since 675704c74dd (init:
+  provide useful advice about init.defaultBranch, 2020-12-11).  The new name
+  matches the default branch name used in new repositories by many of the
+  big Git forges.
+
+* Git will require Rust as a mandatory part of the build process. While Git
+  already started to adopt Rust in Git 2.49, all parts written in Rust are
+  optional for the time being. This includes:
++
+  ** The Rust wrapper around libgit.a that is part of "contrib/" and which has
+     been introduced in Git 2.49.
+  ** Subsystems that have an alternative implementation in Rust to test
+     interoperability between our C and Rust codebase.
+  ** Newly written features that are not mission critical for a fully functional
+     Git client.
++
+These changes are meant as test balloons to allow distributors of Git to prepare
+for Rust becoming a mandatory part of the build process. There will be multiple
+milestones for the introduction of Rust:
++
+--
+1. Initially, with Git 2.52, support for Rust will be auto-detected by Meson and
+   disabled in our Makefile so that the project can sort out the initial
+   infrastructure.
+2. In Git 2.53, both build systems will default-enable support for Rust.
+   Consequently, builds will break by default if Rust is not available on the
+   build host. The use of Rust can still be explicitly disabled via build
+   flags.
+3. In Git 3.0, the build options will be removed and support for Rust is
+   mandatory.
+--
++
+You can explicitly ask both Meson and our Makefile-based system to enable Rust
+by saying `meson configure -Drust=enabled` and `make WITH_RUST=YesPlease`,
+respectively.
++
+The Git project will declare the last version before Git 3.0 to be a long-term
+support release. This long-term release will receive important bug fixes for at
+least four release cycles and security fixes for six release cycles. The Git
+project will hand over maintainership of the long-term release to distributors
+in case they need to extend the life of that long-term release even further.
+Details of how this long-term release will be handed over to the community will
+be discussed once the Git project decides to stop officially supporting it.
++
+We will evaluate the impact on downstream distributions before making Rust
+mandatory in Git 3.0. If we see that the impact on downstream distributions
+would be significant, we may decide to defer this change to a subsequent minor
+release. This evaluation will also take into account our own experience with
+how painful it is to keep Rust an optional component.
+
+=== Removals
+
+* Support for grafting commits has long been superseded by git-replace(1).
+  Grafts are inferior to replacement refs:
++
+  ** Grafts are a local-only mechanism and cannot be shared across
+     repositories.
+  ** Grafts can lead to hard-to-diagnose problems when transferring objects
+     between repositories.
++
+The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
+info/grafts as outdated, 2014-03-05) and will be removed.
++
+Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
+
+* The git-pack-redundant(1) command can be used to remove redundant pack files.
+  The subcommand is unusably slow and the reason why nobody reports it as a
+  performance bug is suspected to be the absence of users. We have nominated
+  the command for removal and have started to emit a user-visible warning in
+  c3b58472be (pack-redundant: gauge the usage before proposing its removal,
+  2020-08-25) whenever the command is executed.
++
+So far there was a single complaint about somebody still using the command, but
+that complaint did not cause us to reverse course. On the contrary, we have
+doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
+escalate deprecation warning to an error, 2023-03-23), the command dies unless
+the user passes the `--i-still-use-this` option.
++
+There have not been any subsequent complaints, so this command will finally be
+removed.
++
+Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
+    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
+    <20230323204047.GA9290@coredump.intra.peff.net>,
+
+* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
+  and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
+  the repository configuration.
++
+The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull:
+short-hand notation for remote repositories., 2005-07-16) and was superseded by
+6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin.,
+2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That
+commit already mentions an upcoming deprecation of the ".git/branches/"
+directory, and starting with a1d4aa7424 (Add repository-layout document.,
+2005-09-01) we have also marked this layout as deprecated. Eventually we also
+started to migrate away from ".git/remotes/" in favor of config-based remotes,
+and we have marked the directory as legacy in 3d3d282146 (Documentation:
+Grammar correction, wording fixes and cleanup, 2011-08-23)
++
+As our documentation mentions, these directories are unlikely to be used in
+modern repositories and most users aren't even aware of these mechanisms. They
+have been deprecated for almost 20 years and 14 years respectively, and we are
+not aware of any active users that have complained about this deprecation.
+Furthermore, the ".git/branches/" directory is nowadays misleadingly named and
+may cause confusion as "branches" are almost exclusively used in the context of
+references.
++
+These features will be removed.
+
+* Support for "--stdin" option in the "name-rev" command was
+  deprecated (and hidden from the documentation) in the Git 2.40
+  timeframe, in preference to its synonym "--annotate-stdin".  Git 3.0
+  removes the support for "--stdin" altogether.
+
+* The git-whatchanged(1) command has outlived its usefulness more than
+  10 years ago, and takes more keystrokes to type than its rough
+  equivalent `git log --raw`.  We have nominated the command for
+  removal, have changed the command to refuse to work unless the
+  `--i-still-use-this` option is given, and asked the users to report
+  when they do so.
++
+The command will be removed.
+
+* Support for `core.commentString=auto` has been deprecated and will
+  be removed in Git 3.0.
++
+cf. <xmqqa59i45wc.fsf@gitster.g>
+
+* Support for `core.preferSymlinkRefs=true` has been deprecated and will be
+  removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
+  out in favor of using plain files using the textual representation of
+  symbolic refs.
++
+Symbolic references were initially always stored as a symbolic link. This was
+changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a
+textfile., 2005-09-25), where a new textual symref format was introduced to
+store those symbolic refs in a plain file. In 9f0bb90d16
+(core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02), the Git
+project switched the default to use the textual symrefs in favor of symbolic
+links.
++
+The migration away from symbolic links has happened almost 20 years ago by now,
+and there is no known reason why one should prefer them nowadays. Furthermore,
+symbolic links are not supported on some platforms.
++
+Note that only the writing side for such symbolic links is deprecated. Reading
+such symbolic links is still supported for now.
+
+== Superseded features that will not be deprecated
+
+Some features have gained newer replacements that aim to improve the design in
+certain ways. The fact that there is a replacement does not automatically mean
+that the old way of doing things will eventually be removed. This section tracks
+those features with newer alternatives.
+
+* The features git-checkout(1) offers are covered by the pair of commands
+  git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
+  widespread, and it is not expected that this will change anytime soon, all
+  three commands will stay.
++
+This decision may get revisited in case we ever figure out that there are
+almost no users of any of the commands anymore.
++
+Cf. <xmqqttjazwwa.fsf@gitster.g>,
+<xmqqleeubork.fsf@gitster.g>,
+<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
deleted file mode 100644
index 27acff86db..0000000000
--- a/Documentation/BreakingChanges.txt
+++ /dev/null
@@ -1,174 +0,0 @@
-= Upcoming breaking changes
-
-The Git project aims to ensure backwards compatibility to the best extent
-possible. Minor releases will not break backwards compatibility unless there is
-a very strong reason to do so, like for example a security vulnerability.
-
-Regardless of that, due to the age of the Git project, it is only natural to
-accumulate a backlog of backwards-incompatible changes that will eventually be
-required to keep the project aligned with a changing world. These changes fall
-into several categories:
-
-* Changes to long established defaults.
-* Concepts that have been replaced with a superior design.
-* Concepts, commands, configuration or options that have been lacking in major
-  ways and that cannot be fixed and which will thus be removed without any
-  replacement.
-
-Explicitly not included in this list are fixes to minor bugs that may cause a
-change in user-visible behavior.
-
-The Git project irregularly releases breaking versions that deliberately break
-backwards compatibility with older versions. This is done to ensure that Git
-remains relevant, safe and maintainable going forward. The release cadence of
-breaking versions is typically measured in multiple years. We had the following
-major breaking releases in the past:
-
-* Git 1.6.0, released in August 2008.
-* Git 2.0, released in May 2014.
-
-We use <major>.<minor> release numbers these days, starting from Git 2.0. For
-future releases, our plan is to increment <major> in the release number when we
-make the next breaking release. Before Git 2.0, the release numbers were
-1.<major>.<minor> with the intention to increment <major> for "usual" breaking
-releases, reserving the jump to Git 2.0 for really large backward-compatibility
-breaking changes.
-
-The intent of this document is to track upcoming deprecations for future
-breaking releases. Furthermore, this document also tracks what will _not_ be
-deprecated. This is done such that the outcome of discussions document both
-when the discussion favors deprecation, but also when it rejects a deprecation.
-
-Items should have a clear summary of the reasons why we do or do not want to
-make the described change that can be easily understood without having to read
-the mailing list discussions. If there are alternatives to the changed feature,
-those alternatives should be pointed out to our users.
-
-All items should be accompanied by references to relevant mailing list threads
-where the deprecation was discussed. These references use message-IDs, which
-can visited via
-
-  https://lore.kernel.org/git/$message_id/
-
-to see the message and its surrounding discussion. Such a reference is there to
-make it easier for you to find how the project reached consensus on the
-described item back then.
-
-This is a living document as the environment surrounding the project changes
-over time. If circumstances change, an earlier decision to deprecate or change
-something may need to be revisited from time to time. So do not take items on
-this list to mean "it is settled, do not waste our time bringing it up again".
-
-== Procedure
-
-Discussing the desire to make breaking changes, declaring that breaking
-changes are made at a certain version boundary, and recording these
-decisions in this document, are necessary but not sufficient.
-Because such changes are expected to be numerous, and the design and
-implementation of them are expected to span over time, they have to
-be deployable trivially at such a version boundary.
-
-The breaking changes MUST be guarded with the a compile-time switch,
-WITH_BREAKING_CHANGES, to help this process.  When built with it,
-the resulting Git binary together with its documentation would
-behave as if these breaking changes slated for the next big version
-boundary are already in effect.  We may also want to have a CI job
-or two to exercise the work-in-progress version of Git with these
-breaking changes.
-
-
-== Git 3.0
-
-The following subsections document upcoming breaking changes for Git 3.0. There
-is no planned release date for this breaking version yet.  The early
-adopter configuration used for changes for this release is `feature.git3`.
-
-Proposed changes and removals only include items which are "ready" to be done.
-In other words, this is not supposed to be a wishlist of features that should
-be changed to or replaced in case the alternative was implemented already.
-
-=== Changes
-
-* The default hash function for new repositories will be changed from "sha1"
-  to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
-  recommended against in FIPS 140-2 and similar certifications. Furthermore,
-  there are practical attacks on SHA-1 that weaken its cryptographic properties:
-+
-  ** The SHAppening (2015). The first demonstration of a practical attack
-     against SHA-1 with 2^57 operations.
-  ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
-  ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
-     attacks with 2^68 operations.
-  ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
-     operations.
-+
-While we have protections in place against known attacks, it is expected
-that more attacks against SHA-1 will be found by future research. Paired
-with the ever-growing capability of hardware, it is only a matter of time
-before SHA-1 will be considered broken completely. We want to be prepared
-and will thus change the default hash algorithm to "sha256" for newly
-initialized repositories.
-+
-An important requirement for this change is that the ecosystem is ready to
-support the "sha256" object format. This includes popular Git libraries,
-applications and forges.
-+
-There is no plan to deprecate the "sha1" object format at this point in time.
-+
-Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
-<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
-<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
-
-=== Removals
-
-* Support for grafting commits has long been superseded by git-replace(1).
-  Grafts are inferior to replacement refs:
-+
-  ** Grafts are a local-only mechanism and cannot be shared across
-     repositories.
-  ** Grafts can lead to hard-to-diagnose problems when transferring objects
-     between repositories.
-+
-The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
-info/grafts as outdated, 2014-03-05) and will be removed.
-+
-Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
-
-* The git-pack-redundant(1) command can be used to remove redundant pack files.
-  The subcommand is unusably slow and the reason why nobody reports it as a
-  performance bug is suspected to be the absence of users. We have nominated
-  the command for removal and have started to emit a user-visible warning in
-  c3b58472be (pack-redundant: gauge the usage before proposing its removal,
-  2020-08-25) whenever the command is executed.
-+
-So far there was a single complaint about somebody still using the command, but
-that complaint did not cause us to reverse course. On the contrary, we have
-doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
-escalate deprecation warning to an error, 2023-03-23), the command dies unless
-the user passes the `--i-still-use-this` option.
-+
-There have not been any subsequent complaints, so this command will finally be
-removed.
-+
-Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
-    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
-    <20230323204047.GA9290@coredump.intra.peff.net>,
-
-== Superseded features that will not be deprecated
-
-Some features have gained newer replacements that aim to improve the design in
-certain ways. The fact that there is a replacement does not automatically mean
-that the old way of doing things will eventually be removed. This section tracks
-those features with newer alternatives.
-
-* The features git-checkout(1) offers are covered by the pair of commands
-  git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
-  widespread, and it is not expected that this will change anytime soon, all
-  three commands will stay.
-+
-This decision may get revisited in case we ever figure out that there are
-almost no users of any of the commands anymore.
-+
-Cf. <xmqqttjazwwa.fsf@gitster.g>,
-<xmqqleeubork.fsf@gitster.g>,
-<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index ba047ed224..df72fe0177 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -44,7 +44,7 @@ code are expected to match the style the surrounding code already
 uses (even if it doesn't match the overall style of existing code).
 
 But if you must have a list of rules, here are some language
-specific ones. Note that Documentation/ToolsForGit.txt document
+specific ones. Note that Documentation/ToolsForGit.adoc document
 has a collection of tips to help you use some external tools
 to conform to these guidelines.
 
@@ -298,6 +298,17 @@ For C programs:
    . since late 2021 with 44ba10d6, we have had variables declared in
      the for loop "for (int i = 0; i < 10; i++)".
 
+   . since late 2023 with 8277dbe987 we have been using the bool type
+     from <stdbool.h>.
+
+   C99 features we have test balloons for:
+
+   . since late 2024 with v2.48.0-rc0~20, we have test balloons for
+     compound literal syntax, e.g., (struct foo){ .member = value };
+     our hope is that no platforms we care about have trouble using
+     them, and officially adopt its wider use in mid 2026.  Do not add
+     more use of the syntax until that happens.
+
    New C99 features that we cannot use yet:
 
    . %z and %zu as a printf() argument for a size_t (the %z being for
@@ -315,6 +326,9 @@ For C programs:
    encouraged to have a blank line between the end of the declarations
    and the first statement in the block.
 
+ - Do not explicitly initialize global variables to 0 or NULL;
+   instead, let BSS take care of the zero initialization.
+
  - NULL pointers shall be written as NULL, not as 0.
 
  - When declaring pointers, the star sides with the variable
@@ -610,8 +624,9 @@ For C programs:
     - `S_init()` initializes a structure without allocating the
       structure itself.
 
-    - `S_release()` releases a structure's contents without freeing the
-      structure.
+    - `S_release()` releases a structure's contents without reinitializing
+      the structure for immediate reuse, and without freeing the structure
+      itself.
 
     - `S_clear()` is equivalent to `S_release()` followed by `S_init()`
       such that the structure is directly usable after clearing it. When
@@ -635,6 +650,12 @@ For C programs:
    cases. However, it is recommended to find a more descriptive name wherever
    possible to improve the readability and maintainability of the code.
 
+ - Bit fields should be defined without a space around the colon. E.g.
+
+   unsigned my_field:1;
+   unsigned other_field:1;
+   unsigned field_with_longer_name:1;
+
 For Perl programs:
 
  - Most of the C guidelines above apply.
@@ -755,7 +776,7 @@ Externally Visible Names
 Writing Documentation:
 
  Most (if not all) of the documentation pages are written in the
- AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and
+ AsciiDoc format in *.adoc files (e.g. Documentation/git.adoc), and
  processed into HTML and manpages (e.g. git.html and git.1 in the
  same directory).
 
@@ -861,6 +882,9 @@ Markup:
    _<git-dir>_
    _<key-id>_
 
+Characters are also surrounded by underscores:
+   _LF_, _CR_, _CR_/_LF_, _NUL_, _EOF_
+
  Git's Asciidoc processor has been tailored to treat backticked text
  as complex synopsis. When literal and placeholders are mixed, you can
  use the backtick notation which will take care of correctly typesetting
@@ -874,6 +898,17 @@ Markup:
 As a side effect, backquoted placeholders are correctly typeset, but
 this style is not recommended.
 
+ When documenting multiple related `git config` variables, place them on
+ a separate line instead of separating them by commas.  For example, do
+ not write this:
+   `core.var1`, `core.var2`::
+	Description common to `core.var1` and `core.var2`.
+
+Instead write this:
+   `core.var1`::
+   `core.var2`::
+	Description common to `core.var1` and `core.var2`.
+
 Synopsis Syntax
 
  The synopsis (a paragraph with [synopsis] attribute) is automatically
diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.adoc
index b43c472ae5..b43c472ae5 100644
--- a/Documentation/DecisionMaking.txt
+++ b/Documentation/DecisionMaking.adoc
diff --git a/Documentation/Makefile b/Documentation/Makefile
index aedfe99d1d..04e9e10b27 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,3 +1,6 @@
+# The default target of this Makefile is...
+all::
+
 # Import tree-wide shared Makefile behavior and libraries
 include ../shared.mak
 
@@ -17,56 +20,57 @@ OBSOLETE_HTML =
 -include GIT-EXCLUDED-PROGRAMS
 
 MAN1_TXT += $(filter-out \
-		$(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \
-		$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
-		$(wildcard git-*.txt))
-MAN1_TXT += git.txt
-MAN1_TXT += gitk.txt
-MAN1_TXT += gitweb.txt
-MAN1_TXT += scalar.txt
+		$(patsubst %,%.adoc,$(EXCLUDED_PROGRAMS)) \
+		$(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \
+		$(wildcard git-*.adoc))
+MAN1_TXT += git.adoc
+MAN1_TXT += gitk.adoc
+MAN1_TXT += gitweb.adoc
+MAN1_TXT += scalar.adoc
 
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
-MAN5_TXT += gitattributes.txt
-MAN5_TXT += gitformat-bundle.txt
-MAN5_TXT += gitformat-chunk.txt
-MAN5_TXT += gitformat-commit-graph.txt
-MAN5_TXT += gitformat-index.txt
-MAN5_TXT += gitformat-pack.txt
-MAN5_TXT += gitformat-signature.txt
-MAN5_TXT += githooks.txt
-MAN5_TXT += gitignore.txt
-MAN5_TXT += gitmailmap.txt
-MAN5_TXT += gitmodules.txt
-MAN5_TXT += gitprotocol-capabilities.txt
-MAN5_TXT += gitprotocol-common.txt
-MAN5_TXT += gitprotocol-http.txt
-MAN5_TXT += gitprotocol-pack.txt
-MAN5_TXT += gitprotocol-v2.txt
-MAN5_TXT += gitrepository-layout.txt
-MAN5_TXT += gitweb.conf.txt
-
-MAN7_TXT += gitcli.txt
-MAN7_TXT += gitcore-tutorial.txt
-MAN7_TXT += gitcredentials.txt
-MAN7_TXT += gitcvs-migration.txt
-MAN7_TXT += gitdiffcore.txt
-MAN7_TXT += giteveryday.txt
-MAN7_TXT += gitfaq.txt
-MAN7_TXT += gitglossary.txt
-MAN7_TXT += gitpacking.txt
-MAN7_TXT += gitnamespaces.txt
-MAN7_TXT += gitremote-helpers.txt
-MAN7_TXT += gitrevisions.txt
-MAN7_TXT += gitsubmodules.txt
-MAN7_TXT += gittutorial-2.txt
-MAN7_TXT += gittutorial.txt
-MAN7_TXT += gitworkflows.txt
-
-HOWTO_TXT += $(wildcard howto/*.txt)
-
-DOC_DEP_TXT += $(wildcard *.txt)
-DOC_DEP_TXT += $(wildcard config/*.txt)
-DOC_DEP_TXT += $(wildcard includes/*.txt)
+MAN5_TXT += gitattributes.adoc
+MAN5_TXT += gitformat-bundle.adoc
+MAN5_TXT += gitformat-chunk.adoc
+MAN5_TXT += gitformat-commit-graph.adoc
+MAN5_TXT += gitformat-index.adoc
+MAN5_TXT += gitformat-loose.adoc
+MAN5_TXT += gitformat-pack.adoc
+MAN5_TXT += gitformat-signature.adoc
+MAN5_TXT += githooks.adoc
+MAN5_TXT += gitignore.adoc
+MAN5_TXT += gitmailmap.adoc
+MAN5_TXT += gitmodules.adoc
+MAN5_TXT += gitprotocol-capabilities.adoc
+MAN5_TXT += gitprotocol-common.adoc
+MAN5_TXT += gitprotocol-http.adoc
+MAN5_TXT += gitprotocol-pack.adoc
+MAN5_TXT += gitprotocol-v2.adoc
+MAN5_TXT += gitrepository-layout.adoc
+MAN5_TXT += gitweb.conf.adoc
+
+MAN7_TXT += gitcli.adoc
+MAN7_TXT += gitcore-tutorial.adoc
+MAN7_TXT += gitcredentials.adoc
+MAN7_TXT += gitcvs-migration.adoc
+MAN7_TXT += gitdiffcore.adoc
+MAN7_TXT += giteveryday.adoc
+MAN7_TXT += gitfaq.adoc
+MAN7_TXT += gitglossary.adoc
+MAN7_TXT += gitpacking.adoc
+MAN7_TXT += gitnamespaces.adoc
+MAN7_TXT += gitremote-helpers.adoc
+MAN7_TXT += gitrevisions.adoc
+MAN7_TXT += gitsubmodules.adoc
+MAN7_TXT += gittutorial-2.adoc
+MAN7_TXT += gittutorial.adoc
+MAN7_TXT += gitworkflows.adoc
+
+HOWTO_TXT += $(wildcard howto/*.adoc)
+
+DOC_DEP_TXT += $(wildcard *.adoc)
+DOC_DEP_TXT += $(wildcard config/*.adoc)
+DOC_DEP_TXT += $(wildcard includes/*.adoc)
 
 ifdef MAN_FILTER
 MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
@@ -75,8 +79,8 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
 MAN_FILTER = $(MAN_TXT)
 endif
 
-MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
-MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
+MAN_XML = $(patsubst %.adoc,%.xml,$(MAN_TXT))
+MAN_HTML = $(patsubst %.adoc,%.html,$(MAN_TXT))
 GIT_MAN_REF = master
 
 OBSOLETE_HTML += everyday.html
@@ -103,9 +107,10 @@ SP_ARTICLES += howto/rebase-from-internal-branch
 SP_ARTICLES += howto/keep-canonical-history-correct
 SP_ARTICLES += howto/maintain-git
 SP_ARTICLES += howto/coordinate-embargoed-releases
-API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
+API_DOCS = $(patsubst %.adoc,%,$(filter-out technical/api-index-skel.adoc technical/api-index.adoc, $(wildcard technical/api-*.adoc)))
 SP_ARTICLES += $(API_DOCS)
 
+TECH_DOCS += BreakingChanges
 TECH_DOCS += DecisionMaking
 TECH_DOCS += ReviewingGuidelines
 TECH_DOCS += MyFirstContribution
@@ -115,18 +120,27 @@ TECH_DOCS += ToolsForGit
 TECH_DOCS += technical/bitmap-format
 TECH_DOCS += technical/build-systems
 TECH_DOCS += technical/bundle-uri
+TECH_DOCS += technical/commit-graph
+TECH_DOCS += technical/directory-rename-detection
 TECH_DOCS += technical/hash-function-transition
+TECH_DOCS += technical/large-object-promisors
 TECH_DOCS += technical/long-running-process-protocol
 TECH_DOCS += technical/multi-pack-index
+TECH_DOCS += technical/packfile-uri
 TECH_DOCS += technical/pack-heuristics
 TECH_DOCS += technical/parallel-checkout
 TECH_DOCS += technical/partial-clone
 TECH_DOCS += technical/platform-support
 TECH_DOCS += technical/racy-git
 TECH_DOCS += technical/reftable
+TECH_DOCS += technical/remembering-renames
+TECH_DOCS += technical/repository-version
+TECH_DOCS += technical/rerere
 TECH_DOCS += technical/scalar
 TECH_DOCS += technical/send-pack-pipeline
 TECH_DOCS += technical/shallow
+TECH_DOCS += technical/sparse-checkout
+TECH_DOCS += technical/sparse-index
 TECH_DOCS += technical/trivial-merge
 TECH_DOCS += technical/unit-tests
 SP_ARTICLES += $(TECH_DOCS)
@@ -136,9 +150,9 @@ ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
 HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML)
 DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML))
 
-DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
-DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
-DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
+DOC_MAN1 = $(patsubst %.adoc,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
+DOC_MAN5 = $(patsubst %.adoc,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
+DOC_MAN7 = $(patsubst %.adoc,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
 
 prefix ?= $(HOME)
 bindir ?= $(prefix)/bin
@@ -221,6 +235,10 @@ asciidoc.conf: asciidoc.conf.in FORCE
 	$(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@)
 endif
 
+ifdef WITH_BREAKING_CHANGES
+ASCIIDOC_EXTRA += -awith-breaking-changes
+endif
+
 ASCIIDOC_DEPS += docinfo.html
 
 SHELL_PATH ?= $(SHELL)
@@ -238,7 +256,7 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR))
 ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'
 endif
 
-all: html man
+all:: html man
 
 html: $(DOC_HTML)
 
@@ -278,7 +296,7 @@ install-pdf: pdf
 install-html: html
 	'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
 
-mergetools_txt = mergetools-diff.txt mergetools-merge.txt
+mergetools_txt = mergetools-diff.adoc mergetools-merge.adoc
 
 #
 # Determine "include::" file references in asciidoc files.
@@ -294,29 +312,29 @@ ifneq ($(MAKECMDGOALS),clean)
 -include doc.dep
 endif
 
-cmds_txt = cmds-ancillaryinterrogators.txt \
-	cmds-ancillarymanipulators.txt \
-	cmds-mainporcelain.txt \
-	cmds-plumbinginterrogators.txt \
-	cmds-plumbingmanipulators.txt \
-	cmds-synchingrepositories.txt \
-	cmds-synchelpers.txt \
-	cmds-guide.txt \
-	cmds-developerinterfaces.txt \
-	cmds-userinterfaces.txt \
-	cmds-purehelpers.txt \
-	cmds-foreignscminterface.txt
+cmds_txt = cmds-ancillaryinterrogators.adoc \
+	cmds-ancillarymanipulators.adoc \
+	cmds-mainporcelain.adoc \
+	cmds-plumbinginterrogators.adoc \
+	cmds-plumbingmanipulators.adoc \
+	cmds-synchingrepositories.adoc \
+	cmds-synchelpers.adoc \
+	cmds-guide.adoc \
+	cmds-developerinterfaces.adoc \
+	cmds-userinterfaces.adoc \
+	cmds-purehelpers.adoc \
+	cmds-foreignscminterface.adoc
 
 $(cmds_txt): cmd-list.made
 
-cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
-	$(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl .. . $(cmds_txt) && \
+cmd-list.made: cmd-list.sh ../command-list.txt $(MAN1_TXT)
+	$(QUIET_GEN)$(SHELL_PATH) ./cmd-list.sh .. . $(cmds_txt) && \
 	date >$@
 
-mergetools-%.txt: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
-mergetools-diff.txt:
+mergetools-%.adoc: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
+mergetools-diff.adoc:
 	$(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. diff $@
-mergetools-merge.txt:
+mergetools-merge.adoc:
 	$(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. merge $@
 
 TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
@@ -333,9 +351,9 @@ clean:
 	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
 	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
 	$(RM) *.pdf
-	$(RM) howto-index.txt howto/*.html doc.dep
-	$(RM) technical/*.html technical/api-index.txt
-	$(RM) SubmittingPatches.txt
+	$(RM) howto-index.adoc howto/*.html doc.dep
+	$(RM) technical/*.html technical/api-index.adoc
+	$(RM) SubmittingPatches.adoc
 	$(RM) $(cmds_txt) $(mergetools_txt) *.made
 	$(RM) GIT-ASCIIDOCFLAGS
 	$(RM) asciidoc.conf asciidoctor-extensions.rb
@@ -344,10 +362,10 @@ clean:
 docinfo.html: docinfo-html.in
 	$(QUIET_GEN)$(RM) $@ && cat $< >$@
 
-$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
+$(MAN_HTML): %.html : %.adoc $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<
 
-$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
+$(OBSOLETE_HTML): %.html : %.adoco $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
 manpage-prereqs := $(wildcard manpage*.xsl)
@@ -360,22 +378,22 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 %.7 : %.xml $(manpage-prereqs)
 	$(manpage-cmd)
 
-%.xml : %.txt $(ASCIIDOC_DEPS)
+%.xml : %.adoc $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
 
-user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS)
+user-manual.xml: user-manual.adoc $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<
 
-technical/api-index.txt: technical/api-index-skel.txt \
-	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
-	$(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt
+technical/api-index.adoc: technical/api-index-skel.adoc \
+	technical/api-index.sh $(patsubst %,%.adoc,$(API_DOCS))
+	$(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.adoc
 
 technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
-$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
+$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.adoc \
 	$(ASCIIDOC_DEPS)
-	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
+	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.adoc
 
-SubmittingPatches.txt: SubmittingPatches
+SubmittingPatches.adoc: SubmittingPatches
 	$(QUIET_GEN) cp $< $@
 
 XSLT = docbook.xsl
@@ -390,9 +408,9 @@ user-manual.html: user-manual.xml $(XSLT)
 git.info: user-manual.texi
 	$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi
 
-user-manual.texi: user-manual.xml
+user-manual.texi: user-manual.xml fix-texi.sh
 	$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \
-	$(PERL_PATH) fix-texi.perl <$@+ >$@ && \
+	$(SHELL_PATH) fix-texi.sh <$@+ >$@ && \
 	$(RM) $@+
 
 user-manual.pdf: user-manual.xml
@@ -409,19 +427,19 @@ gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
 gitman.info: gitman.texi
 	$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $<
 
-$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
+$(patsubst %.adoc,%.texi,$(MAN_TXT)): %.texi : %.xml
 	$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@
 
-howto-index.txt: howto/howto-index.sh $(HOWTO_TXT)
+howto-index.adoc: howto/howto-index.sh $(HOWTO_TXT)
 	$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@
 
-$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS)
-	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
+$(patsubst %,%.html,$(ARTICLES)) : %.html : %.adoc $(ASCIIDOC_DEPS)
+	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.adoc
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
 howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
-$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt $(ASCIIDOC_DEPS)
+$(patsubst %.adoc,%.html,$(HOWTO_TXT)): %.html : %.adoc $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC) \
 	sed -e '1,/^$$/d' $< | \
 	$(TXT_TO_HTML) - >$@
@@ -452,9 +470,9 @@ print-man1:
 	@for i in $(MAN1_TXT); do echo $$i; done
 
 ## Lint: gitlink
-LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
+LINT_DOCS_GITLINK = $(patsubst %.adoc,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
 $(LINT_DOCS_GITLINK): lint-gitlink.perl
-$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
+$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.adoc
 	$(call mkdir_p_parent_template)
 	$(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \
 		$< \
@@ -466,17 +484,17 @@ $(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
 lint-docs-gitlink: $(LINT_DOCS_GITLINK)
 
 ## Lint: man-end-blurb
-LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
+LINT_DOCS_MAN_END_BLURB = $(patsubst %.adoc,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
 $(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl
-$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt
+$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.adoc
 	$(call mkdir_p_parent_template)
 	$(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@
 .PHONY: lint-docs-man-end-blurb
 
 ## Lint: man-section-order
-LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
+LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.adoc,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
 $(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl
-$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt
+$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.adoc
 	$(call mkdir_p_parent_template)
 	$(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@
 .PHONY: lint-docs-man-section-order
@@ -485,13 +503,30 @@ lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER)
 .PHONY: lint-docs-fsck-msgids
 LINT_DOCS_FSCK_MSGIDS = .build/lint-docs/fsck-msgids.ok
 $(LINT_DOCS_FSCK_MSGIDS): lint-fsck-msgids.perl
-$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt
+$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc
 	$(call mkdir_p_parent_template)
 	$(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \
-		../fsck.h fsck-msgids.txt $@
-
+		../fsck.h fsck-msgids.adoc $@
 lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
 
+## Lint: delimited sections
+LINT_DOCS_DELIMITED_SECTIONS = $(patsubst %.adoc,.build/lint-docs/delimited-sections/%.ok,$(MAN_TXT))
+$(LINT_DOCS_DELIMITED_SECTIONS): lint-delimited-sections.perl
+$(LINT_DOCS_DELIMITED_SECTIONS): .build/lint-docs/delimited-sections/%.ok: %.adoc
+	$(call mkdir_p_parent_template)
+	$(QUIET_LINT_DELIMSEC)$(PERL_PATH) lint-delimited-sections.perl $< >$@
+.PHONY: lint-docs-delimited-sections
+lint-docs-delimited-sections: $(LINT_DOCS_DELIMITED_SECTIONS)
+
+## Lint: Documentation style
+LINT_DOCS_DOC_STYLE = $(patsubst %.adoc,.build/lint-docs/doc-style/%.ok,$(DOC_DEP_TXT))
+$(LINT_DOCS_DOC_STYLE): lint-documentation-style.perl
+$(LINT_DOCS_DOC_STYLE): .build/lint-docs/doc-style/%.ok: %.adoc
+	$(call mkdir_p_parent_template)
+	$(QUIET_LINT_DOCSTYLE)$(PERL_PATH) lint-documentation-style.perl $< >$@
+.PHONY: lint-docs-doc-style
+lint-docs-doc-style: $(LINT_DOCS_DOC_STYLE)
+
 lint-docs-manpages:
 	$(QUIET_GEN)./lint-manpages.sh
 
@@ -501,11 +536,16 @@ lint-docs-meson:
 	@mkdir -p tmp-meson-diff && \
 	awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^  \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \
 		grep -v -e '#' -e '^$$' | \
-		sort >tmp-meson-diff/meson.txt && \
-	ls git*.txt scalar.txt | grep -v -e git-bisect-lk2009.txt -e git-tools.txt >tmp-meson-diff/actual.txt && \
-	if ! cmp tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; then \
+		sort >tmp-meson-diff/meson.adoc && \
+	ls git*.adoc scalar.adoc | \
+		grep -v -e git-bisect-lk2009.adoc \
+			-e git-pack-redundant.adoc \
+			-e git-tools.adoc \
+			-e git-whatchanged.adoc \
+			>tmp-meson-diff/actual.adoc && \
+	if ! cmp tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; then \
 		echo "Meson man pages differ from actual man pages:"; \
-		diff -u tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; \
+		diff -u tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; \
 		exit 1; \
 	fi
 
@@ -515,6 +555,8 @@ lint-docs: lint-docs-fsck-msgids
 lint-docs: lint-docs-gitlink
 lint-docs: lint-docs-man-end-blurb
 lint-docs: lint-docs-man-section-order
+lint-docs: lint-docs-delimited-sections
+lint-docs: lint-docs-doc-style
 lint-docs: lint-docs-manpages
 lint-docs: lint-docs-meson
 
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.adoc
index e41654c00a..f186dfbc89 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.adoc
@@ -21,7 +21,7 @@ This tutorial aims to summarize the following documents, but the reader may find
 useful additional context:
 
 - `Documentation/SubmittingPatches`
-- `Documentation/howto/new-command.txt`
+- `Documentation/howto/new-command.adoc`
 
 [[getting-help]]
 === Getting Help
@@ -40,14 +40,6 @@ the list by sending an email to <git+subscribe@vger.kernel.org>
 The https://lore.kernel.org/git[archive] of this mailing list is
 available to view in a browser.
 
-==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com]
-
-This mailing list is targeted to new contributors and was created as a place to
-post questions and receive answers outside of the public eye of the main list.
-Veteran contributors who are especially interested in helping mentor newcomers
-are present on the list. In order to avoid search indexers, group membership is
-required to view messages; anyone can join and no approval is required.
-
 ==== https://web.libera.chat/#git-devel[#git-devel] on Libera Chat
 
 This IRC channel is for conversations between Git contributors. If someone is
@@ -60,6 +52,15 @@ respond to you. It's better to ask your questions in the channel so that you
 can be answered if you disconnect and so that others can learn from the
 conversation.
 
+==== https://discord.gg/GRFVkzgxRd[#discord] on Discord
+This is an unofficial Git Discord server for everyone, from people just
+starting out with Git to those who develop it. It's a great place to ask
+questions, share tips, and connect with the broader Git community in real time.
+
+The server has channels for general discussions and specific channels for those
+who use Git and those who develop it. The server's search functionality also
+allows you to find previous conversations and answers to common questions.
+
 [[getting-started]]
 == Getting Started
 
@@ -150,15 +151,31 @@ command in `builtin/psuh.c`. Create that file, and within it, write the entry
 point for your command in a function matching the style and signature:
 
 ----
-int cmd_psuh(int argc, const char **argv, const char *prefix)
+int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
+	     const char *prefix UNUSED, struct repository *repo UNUSED)
 ----
 
+A few things to note:
+
+* A subcommand implementation takes its command line arguments
+  in `int argc` + `const char **argv`, like `main()` would.
+
+* It also takes two extra parameters, `prefix` and `repo`. What
+  they mean will not be discussed until much later.
+
+* Because this first example will not use any of the parameters,
+  your compiler will give warnings on unused parameters. As the
+  list of these four parameters is mandated by the API to add
+  new built-in commands, you cannot omit them. Instead, you add
+  `UNUSED` to each of them to tell the compiler that you *know*
+  you are not (yet) using it.
+
 We'll also need to add the declaration of psuh; open up `builtin.h`, find the
 declaration for `cmd_pull`, and add a new line for `psuh` immediately before it,
 in order to keep the declarations alphabetically sorted:
 
 ----
-int cmd_psuh(int argc, const char **argv, const char *prefix);
+int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo);
 ----
 
 Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to
@@ -174,7 +191,8 @@ Throughout the tutorial, we will mark strings for translation as necessary; you
 should also do so when writing your user-facing commands in the future.
 
 ----
-int cmd_psuh(int argc, const char **argv, const char *prefix)
+int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
+	     const char *prefix UNUSED, struct repository *repo UNUSED)
 {
 	printf(_("Pony saying hello goes here.\n"));
 	return 0;
@@ -287,8 +305,9 @@ on the reference implementation linked at the top of this document.
 It's probably useful to do at least something besides printing out a string.
 Let's start by having a look at everything we get.
 
-Modify your `cmd_psuh` implementation to dump the args you're passed, keeping
-existing `printf()` calls in place:
+Modify your `cmd_psuh` implementation to dump the args you're passed,
+keeping existing `printf()` calls in place; because the args are now
+used, remove the `UNUSED` macro from them:
 
 ----
 	int i;
@@ -312,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty
 for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so
 helpful. So what other context can we get?
 
-Add a line to `#include "config.h"`. Then, add the following bits to the
+Add a line to `#include "config.h"` and `#include "repository.h"`.
+Then, add the following bits to the function body:
 function body:
 
 ----
@@ -320,18 +340,18 @@ function body:
 
 ...
 
-	git_config(git_default_config, NULL);
-	if (git_config_get_string_tmp("user.name", &cfg_name) > 0)
+	repo_config(repo, git_default_config, NULL);
+	if (repo_config_get_string_tmp(repo, "user.name", &cfg_name))
 		printf(_("No name is found in config\n"));
 	else
 		printf(_("Your name: %s\n"), cfg_name);
 ----
 
-`git_config()` will grab the configuration from config files known to Git and
-apply standard precedence rules. `git_config_get_string_tmp()` will look up
+`repo_config()` will grab the configuration from config files known to Git and
+apply standard precedence rules. `repo_config_get_string_tmp()` will look up
 a specific key ("user.name") and give you the value. There are a number of
 single-key lookup functions like this one; you can see them all (and more info
-about how to use `git_config()`) in `Documentation/technical/api-config.txt`.
+about how to use `repo_config()`) in `Documentation/technical/api-config.adoc`.
 
 You should see that the name printed matches the one you see when you run:
 
@@ -364,9 +384,10 @@ status_init_config(&s, git_status_config);
 ----
 
 But as we drill down, we can find that `status_init_config()` wraps a call
-to `git_config()`. Let's modify the code we wrote in the previous commit.
+to `repo_config()`. Let's modify the code we wrote in the previous commit.
 
 Be sure to include the header to allow you to use `struct wt_status`:
+
 ----
 #include "wt-status.h"
 ----
@@ -379,8 +400,8 @@ prepare it, and print its contents:
 
 ...
 
-	wt_status_prepare(the_repository, &status);
-	git_config(git_default_config, &status);
+	wt_status_prepare(repo, &status);
+	repo_config(repo, git_default_config, &status);
 
 ...
 
@@ -461,10 +482,10 @@ $ ./bin-wrappers/git help psuh
 
 Your new command is undocumented! Let's fix that.
 
-Take a look at `Documentation/git-*.txt`. These are the manpages for the
+Take a look at `Documentation/git-*.adoc`. These are the manpages for the
 subcommands that Git knows about. You can open these up and take a look to get
 acquainted with the format, but then go ahead and make a new file
-`Documentation/git-psuh.txt`. Like with most of the documentation in the Git
+`Documentation/git-psuh.adoc`. Like with most of the documentation in the Git
 project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing
 Documentation" section). Use the following template to fill out your own
 manpage:
@@ -543,7 +564,7 @@ Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
 That's because `-h` is a special case which your command should handle by
 printing usage.
 
-Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy
+Take a look at `Documentation/technical/api-parse-options.adoc`. This is a handy
 tool for pulling out options you need to be able to handle, and it takes a
 usage string.
 
@@ -896,10 +917,13 @@ Now you should be able to go and check out your newly created branch on GitHub.
 === Sending a PR to GitGitGadget
 
 In order to have your code tested and formatted for review, you need to start by
-opening a Pull Request against `gitgitgadget/git`. Head to
-https://github.com/gitgitgadget/git and open a PR either with the "New pull
-request" button or the convenient "Compare & pull request" button that may
-appear with the name of your newly pushed branch.
+opening a Pull Request against either `gitgitgadget/git` or `git/git`. Head to
+https://github.com/gitgitgadget/git or https://github.com/git/git and open a PR
+either with the "New pull request" button or the convenient "Compare & pull
+request" button that may appear with the name of your newly pushed branch.
+
+The differences between using `gitgitgadget/git` and `git/git` as your base can
+be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)
 
 Review the PR's title and description, as they're used by GitGitGadget
 respectively as the subject and body of the cover letter for your change. Refer
@@ -1088,14 +1112,14 @@ This gives reviewers a summary of what they're in for when reviewing your topic.
 The one generated for `psuh` from the sample implementation looks like this:
 
 ----
- Documentation/git-psuh.txt | 40 +++++++++++++++++++++
- Makefile                   |  1 +
- builtin.h                  |  1 +
- builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
- git.c                      |  1 +
- t/t9999-psuh-tutorial.sh   | 12 +++++++
+ Documentation/git-psuh.adoc | 40 +++++++++++++++++++++
+ Makefile                    |  1 +
+ builtin.h                   |  1 +
+ builtin/psuh.c              | 73 ++++++++++++++++++++++++++++++++++++++
+ git.c                       |  1 +
+ t/t9999-psuh-tutorial.sh    | 12 +++++++
  6 files changed, 128 insertions(+)
- create mode 100644 Documentation/git-psuh.txt
+ create mode 100644 Documentation/git-psuh.adoc
  create mode 100644 builtin/psuh.c
  create mode 100755 t/t9999-psuh-tutorial.sh
 ----
@@ -1129,6 +1153,11 @@ NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but
 please don't send your patchset from the tutorial to the real mailing list! For
 now, you can send it to yourself, to make sure you understand how it will look.
 
+NOTE: After sending your patches, you can confirm that they reached the mailing
+list by visiting https://lore.kernel.org/git/. Use the search bar to find your
+name or the subject of your patch. If it appears, your email was successfully
+delivered.
+
 After you run the command above, you will be presented with an interactive
 prompt for each patch that's about to go out. This gives you one last chance to
 edit or quit sending something (but again, don't edit code this way). Once you
diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.adoc
index dec8afe5b1..413a9fdb05 100644
--- a/Documentation/MyFirstObjectWalk.txt
+++ b/Documentation/MyFirstObjectWalk.adoc
@@ -15,7 +15,7 @@ revision walk is used for operations like `git log`.
 
 === Related Reading
 
-- `Documentation/user-manual.txt` under "Hacking Git" contains some coverage of
+- `Documentation/user-manual.adoc` under "Hacking Git" contains some coverage of
   the revision walker in its various incarnations.
 - `revision.h`
 - https://eagain.net/articles/git-for-computer-scientists/[Git for Computer Scientists]
@@ -43,7 +43,7 @@ Open up a new file `builtin/walken.c` and set up the command handler:
 #include "builtin.h"
 #include "trace.h"
 
-int cmd_walken(int argc, const char **argv, const char *prefix)
+int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo)
 {
 	trace_printf(_("cmd_walken incoming...\n"));
 	return 0;
@@ -83,23 +83,36 @@ int cmd_walken(int argc, const char **argv, const char *prefix)
 }
 ----
 
-Also add the relevant line in `builtin.h` near `cmd_whatchanged()`:
+Also add the relevant line in `builtin.h` near `cmd_version()`:
 
 ----
-int cmd_walken(int argc, const char **argv, const char *prefix);
+int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo);
 ----
 
-Include the command in `git.c` in `commands[]` near the entry for `whatchanged`,
+Include the command in `git.c` in `commands[]` near the entry for `version`,
 maintaining alphabetical ordering:
 
 ----
 { "walken", cmd_walken, RUN_SETUP },
 ----
 
-Add it to the `Makefile` near the line for `builtin/worktree.o`:
+Add an entry for the new command in the both the Make and Meson build system,
+before the entry for `worktree`:
 
+- In the `Makefile`:
 ----
+...
 BUILTIN_OBJS += builtin/walken.o
+...
+----
+
+- In the `meson.build` file:
+----
+builtin_sources = [
+   ...
+  'builtin/walken.c',
+   ...
+]
 ----
 
 Build and test out your command, without forgetting to ensure the `DEVELOPER`
@@ -112,7 +125,7 @@ $ GIT_TRACE=1 ./bin-wrappers/git walken
 ----
 
 NOTE: For a more exhaustive overview of the new command process, take a look at
-`Documentation/MyFirstContribution.txt`.
+`Documentation/MyFirstContribution.adoc`.
 
 NOTE: A reference implementation can be found at
 https://github.com/nasamuffin/git/tree/revwalk.
@@ -132,7 +145,7 @@ used to track the allocated size of the list.
 Per entry, we find:
 
 `item` is the object provided upon which to base the object walk. Items in Git
-can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.txt`.)
+can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.adoc`.)
 
 `name` is the object ID (OID) of the object - a hex string you may be familiar
 with from using Git to organize your source in the past. Check the tutorial
@@ -141,7 +154,7 @@ from.
 
 `whence` indicates some information about what to do with the parents of the
 specified object. We'll explore this flag more later on; take a look at
-`Documentation/revisions.txt` to get an idea of what could set the `whence`
+`Documentation/revisions.adoc` to get an idea of what could set the `whence`
 value.
 
 `flags` are used to hint the beginning of the revision walk and are the first
@@ -153,7 +166,7 @@ can be used during the walk, as well.
 
 This one is quite a bit longer, and many fields are only used during the walk
 by `revision.c` - not configuration options. Most of the configurable flags in
-`struct rev_info` have a mirror in `Documentation/rev-list-options.txt`. It's a
+`struct rev_info` have a mirror in `Documentation/rev-list-options.adoc`. It's a
 good idea to take some time and read through that document.
 
 == Basic Commit Walk
@@ -193,7 +206,7 @@ initialization functions.
 
 Next, we should have a look at any relevant configuration settings (i.e.,
 settings readable and settable from `git config`). This is done by providing a
-callback to `git_config()`; within that callback, you can also invoke methods
+callback to `repo_config()`; within that callback, you can also invoke methods
 from other components you may need that need to intercept these options. Your
 callback will be invoked once per each configuration value which Git knows about
 (global, local, worktree, etc.).
@@ -221,14 +234,14 @@ static int git_walken_config(const char *var, const char *value,
 }
 ----
 
-Make sure to invoke `git_config()` with it in your `cmd_walken()`:
+Make sure to invoke `repo_config()` with it in your `cmd_walken()`:
 
 ----
-int cmd_walken(int argc, const char **argv, const char *prefix)
+int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo)
 {
 	...
 
-	git_config(git_walken_config, NULL);
+	repo_config(repo, git_walken_config, NULL);
 
 	...
 }
@@ -250,14 +263,14 @@ We'll also need to include the `revision.h` header:
 
 ...
 
-int cmd_walken(int argc, const char **argv, const char *prefix)
+int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo)
 {
 	/* This can go wherever you like in your declarations.*/
 	struct rev_info rev;
 	...
 
-	/* This should go after the git_config() call. */
-	repo_init_revisions(the_repository, &rev, prefix);
+	/* This should go after the repo_config() call. */
+	repo_init_revisions(repo, &rev, prefix);
 
 	...
 }
@@ -287,6 +300,7 @@ static void final_rev_info_setup(struct rev_info *rev)
 ====
 Instead of using the shorthand `add_head_to_pending()`, you could do
 something like this:
+
 ----
 	struct setup_revision_opt opt;
 
@@ -295,6 +309,7 @@ something like this:
 	opt.revarg_opt = REVARG_COMMITTISH;
 	setup_revisions(argc, argv, rev, &opt);
 ----
+
 Using a `setup_revision_opt` gives you finer control over your walk's starting
 point.
 ====
@@ -303,7 +318,7 @@ Then let's invoke `final_rev_info_setup()` after the call to
 `repo_init_revisions()`:
 
 ----
-int cmd_walken(int argc, const char **argv, const char *prefix)
+int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo)
 {
 	...
 
@@ -710,7 +725,7 @@ objects grows along with the Git project.
 === Adding a Filter
 
 There are a handful of filters that we can apply to the object walk laid out in
-`Documentation/rev-list-options.txt`. These filters are typically useful for
+`Documentation/rev-list-options.adoc`. These filters are typically useful for
 operations such as creating packfiles or performing a partial clone. They are
 defined in `list-objects-filter-options.h`. For the purposes of this tutorial we
 will use the "tree:1" filter, which causes the walk to omit all trees and blobs
diff --git a/Documentation/RelNotes/1.5.0.1.txt b/Documentation/RelNotes/1.5.0.1.adoc
index fea3f9935b..fea3f9935b 100644
--- a/Documentation/RelNotes/1.5.0.1.txt
+++ b/Documentation/RelNotes/1.5.0.1.adoc
diff --git a/Documentation/RelNotes/1.5.0.2.txt b/Documentation/RelNotes/1.5.0.2.adoc
index b061e50ff0..b061e50ff0 100644
--- a/Documentation/RelNotes/1.5.0.2.txt
+++ b/Documentation/RelNotes/1.5.0.2.adoc
diff --git a/Documentation/RelNotes/1.5.0.3.txt b/Documentation/RelNotes/1.5.0.3.adoc
index cd500f96bf..cd500f96bf 100644
--- a/Documentation/RelNotes/1.5.0.3.txt
+++ b/Documentation/RelNotes/1.5.0.3.adoc
diff --git a/Documentation/RelNotes/1.5.0.4.txt b/Documentation/RelNotes/1.5.0.4.adoc
index feefa5dfd4..feefa5dfd4 100644
--- a/Documentation/RelNotes/1.5.0.4.txt
+++ b/Documentation/RelNotes/1.5.0.4.adoc
diff --git a/Documentation/RelNotes/1.5.0.5.txt b/Documentation/RelNotes/1.5.0.5.adoc
index eeec3d73d0..eeec3d73d0 100644
--- a/Documentation/RelNotes/1.5.0.5.txt
+++ b/Documentation/RelNotes/1.5.0.5.adoc
diff --git a/Documentation/RelNotes/1.5.0.6.txt b/Documentation/RelNotes/1.5.0.6.adoc
index c02015ad5f..c02015ad5f 100644
--- a/Documentation/RelNotes/1.5.0.6.txt
+++ b/Documentation/RelNotes/1.5.0.6.adoc
diff --git a/Documentation/RelNotes/1.5.0.7.txt b/Documentation/RelNotes/1.5.0.7.adoc
index 670ad32b85..670ad32b85 100644
--- a/Documentation/RelNotes/1.5.0.7.txt
+++ b/Documentation/RelNotes/1.5.0.7.adoc
diff --git a/Documentation/RelNotes/1.5.0.txt b/Documentation/RelNotes/1.5.0.adoc
index d6d42f3183..d6d42f3183 100644
--- a/Documentation/RelNotes/1.5.0.txt
+++ b/Documentation/RelNotes/1.5.0.adoc
diff --git a/Documentation/RelNotes/1.5.1.1.txt b/Documentation/RelNotes/1.5.1.1.adoc
index 91471213bd..91471213bd 100644
--- a/Documentation/RelNotes/1.5.1.1.txt
+++ b/Documentation/RelNotes/1.5.1.1.adoc
diff --git a/Documentation/RelNotes/1.5.1.2.txt b/Documentation/RelNotes/1.5.1.2.adoc
index d88456306c..d88456306c 100644
--- a/Documentation/RelNotes/1.5.1.2.txt
+++ b/Documentation/RelNotes/1.5.1.2.adoc
diff --git a/Documentation/RelNotes/1.5.1.3.txt b/Documentation/RelNotes/1.5.1.3.adoc
index 876408b65a..876408b65a 100644
--- a/Documentation/RelNotes/1.5.1.3.txt
+++ b/Documentation/RelNotes/1.5.1.3.adoc
diff --git a/Documentation/RelNotes/1.5.1.4.txt b/Documentation/RelNotes/1.5.1.4.adoc
index df2f66ccb5..df2f66ccb5 100644
--- a/Documentation/RelNotes/1.5.1.4.txt
+++ b/Documentation/RelNotes/1.5.1.4.adoc
diff --git a/Documentation/RelNotes/1.5.1.5.txt b/Documentation/RelNotes/1.5.1.5.adoc
index b0ab8eb371..b0ab8eb371 100644
--- a/Documentation/RelNotes/1.5.1.5.txt
+++ b/Documentation/RelNotes/1.5.1.5.adoc
diff --git a/Documentation/RelNotes/1.5.1.6.txt b/Documentation/RelNotes/1.5.1.6.adoc
index 55f3ac13e3..55f3ac13e3 100644
--- a/Documentation/RelNotes/1.5.1.6.txt
+++ b/Documentation/RelNotes/1.5.1.6.adoc
diff --git a/Documentation/RelNotes/1.5.1.txt b/Documentation/RelNotes/1.5.1.adoc
index daed367270..daed367270 100644
--- a/Documentation/RelNotes/1.5.1.txt
+++ b/Documentation/RelNotes/1.5.1.adoc
diff --git a/Documentation/RelNotes/1.5.2.1.txt b/Documentation/RelNotes/1.5.2.1.adoc
index d41984df0b..d41984df0b 100644
--- a/Documentation/RelNotes/1.5.2.1.txt
+++ b/Documentation/RelNotes/1.5.2.1.adoc
diff --git a/Documentation/RelNotes/1.5.2.2.txt b/Documentation/RelNotes/1.5.2.2.adoc
index 7bfa341750..7bfa341750 100644
--- a/Documentation/RelNotes/1.5.2.2.txt
+++ b/Documentation/RelNotes/1.5.2.2.adoc
diff --git a/Documentation/RelNotes/1.5.2.3.txt b/Documentation/RelNotes/1.5.2.3.adoc
index addb22955b..addb22955b 100644
--- a/Documentation/RelNotes/1.5.2.3.txt
+++ b/Documentation/RelNotes/1.5.2.3.adoc
diff --git a/Documentation/RelNotes/1.5.2.4.txt b/Documentation/RelNotes/1.5.2.4.adoc
index 75cff475f6..75cff475f6 100644
--- a/Documentation/RelNotes/1.5.2.4.txt
+++ b/Documentation/RelNotes/1.5.2.4.adoc
diff --git a/Documentation/RelNotes/1.5.2.5.txt b/Documentation/RelNotes/1.5.2.5.adoc
index e8281c72a0..e8281c72a0 100644
--- a/Documentation/RelNotes/1.5.2.5.txt
+++ b/Documentation/RelNotes/1.5.2.5.adoc
diff --git a/Documentation/RelNotes/1.5.2.txt b/Documentation/RelNotes/1.5.2.adoc
index e8328d090a..e8328d090a 100644
--- a/Documentation/RelNotes/1.5.2.txt
+++ b/Documentation/RelNotes/1.5.2.adoc
diff --git a/Documentation/RelNotes/1.5.3.1.txt b/Documentation/RelNotes/1.5.3.1.adoc
index 7ff546c743..7ff546c743 100644
--- a/Documentation/RelNotes/1.5.3.1.txt
+++ b/Documentation/RelNotes/1.5.3.1.adoc
diff --git a/Documentation/RelNotes/1.5.3.2.txt b/Documentation/RelNotes/1.5.3.2.adoc
index 4bbde3cab4..4bbde3cab4 100644
--- a/Documentation/RelNotes/1.5.3.2.txt
+++ b/Documentation/RelNotes/1.5.3.2.adoc
diff --git a/Documentation/RelNotes/1.5.3.3.txt b/Documentation/RelNotes/1.5.3.3.adoc
index d213846951..d213846951 100644
--- a/Documentation/RelNotes/1.5.3.3.txt
+++ b/Documentation/RelNotes/1.5.3.3.adoc
diff --git a/Documentation/RelNotes/1.5.3.4.txt b/Documentation/RelNotes/1.5.3.4.adoc
index b04b3a45a5..b04b3a45a5 100644
--- a/Documentation/RelNotes/1.5.3.4.txt
+++ b/Documentation/RelNotes/1.5.3.4.adoc
diff --git a/Documentation/RelNotes/1.5.3.5.txt b/Documentation/RelNotes/1.5.3.5.adoc
index 7ff1d5d0d1..7ff1d5d0d1 100644
--- a/Documentation/RelNotes/1.5.3.5.txt
+++ b/Documentation/RelNotes/1.5.3.5.adoc
diff --git a/Documentation/RelNotes/1.5.3.6.txt b/Documentation/RelNotes/1.5.3.6.adoc
index 069a2b2cf9..069a2b2cf9 100644
--- a/Documentation/RelNotes/1.5.3.6.txt
+++ b/Documentation/RelNotes/1.5.3.6.adoc
diff --git a/Documentation/RelNotes/1.5.3.7.txt b/Documentation/RelNotes/1.5.3.7.adoc
index 2f690616c8..2f690616c8 100644
--- a/Documentation/RelNotes/1.5.3.7.txt
+++ b/Documentation/RelNotes/1.5.3.7.adoc
diff --git a/Documentation/RelNotes/1.5.3.8.txt b/Documentation/RelNotes/1.5.3.8.adoc
index 0e3ff58a46..0e3ff58a46 100644
--- a/Documentation/RelNotes/1.5.3.8.txt
+++ b/Documentation/RelNotes/1.5.3.8.adoc
diff --git a/Documentation/RelNotes/1.5.3.txt b/Documentation/RelNotes/1.5.3.adoc
index 0668d3c0ca..0668d3c0ca 100644
--- a/Documentation/RelNotes/1.5.3.txt
+++ b/Documentation/RelNotes/1.5.3.adoc
diff --git a/Documentation/RelNotes/1.5.4.1.txt b/Documentation/RelNotes/1.5.4.1.adoc
index d4e44b8b09..d4e44b8b09 100644
--- a/Documentation/RelNotes/1.5.4.1.txt
+++ b/Documentation/RelNotes/1.5.4.1.adoc
diff --git a/Documentation/RelNotes/1.5.4.2.txt b/Documentation/RelNotes/1.5.4.2.adoc
index 21d0df59fb..21d0df59fb 100644
--- a/Documentation/RelNotes/1.5.4.2.txt
+++ b/Documentation/RelNotes/1.5.4.2.adoc
diff --git a/Documentation/RelNotes/1.5.4.3.txt b/Documentation/RelNotes/1.5.4.3.adoc
index b0fc67fb2a..b0fc67fb2a 100644
--- a/Documentation/RelNotes/1.5.4.3.txt
+++ b/Documentation/RelNotes/1.5.4.3.adoc
diff --git a/Documentation/RelNotes/1.5.4.4.txt b/Documentation/RelNotes/1.5.4.4.adoc
index 323c1a88c7..323c1a88c7 100644
--- a/Documentation/RelNotes/1.5.4.4.txt
+++ b/Documentation/RelNotes/1.5.4.4.adoc
diff --git a/Documentation/RelNotes/1.5.4.5.txt b/Documentation/RelNotes/1.5.4.5.adoc
index bbd130e36d..bbd130e36d 100644
--- a/Documentation/RelNotes/1.5.4.5.txt
+++ b/Documentation/RelNotes/1.5.4.5.adoc
diff --git a/Documentation/RelNotes/1.5.4.6.txt b/Documentation/RelNotes/1.5.4.6.adoc
index 3e3c3e55a3..3e3c3e55a3 100644
--- a/Documentation/RelNotes/1.5.4.6.txt
+++ b/Documentation/RelNotes/1.5.4.6.adoc
diff --git a/Documentation/RelNotes/1.5.4.7.txt b/Documentation/RelNotes/1.5.4.7.adoc
index 9065a0e273..9065a0e273 100644
--- a/Documentation/RelNotes/1.5.4.7.txt
+++ b/Documentation/RelNotes/1.5.4.7.adoc
diff --git a/Documentation/RelNotes/1.5.4.txt b/Documentation/RelNotes/1.5.4.adoc
index f1323b6174..f1323b6174 100644
--- a/Documentation/RelNotes/1.5.4.txt
+++ b/Documentation/RelNotes/1.5.4.adoc
diff --git a/Documentation/RelNotes/1.5.5.1.txt b/Documentation/RelNotes/1.5.5.1.adoc
index 7de419708f..7de419708f 100644
--- a/Documentation/RelNotes/1.5.5.1.txt
+++ b/Documentation/RelNotes/1.5.5.1.adoc
diff --git a/Documentation/RelNotes/1.5.5.2.txt b/Documentation/RelNotes/1.5.5.2.adoc
index 391a7b02ea..391a7b02ea 100644
--- a/Documentation/RelNotes/1.5.5.2.txt
+++ b/Documentation/RelNotes/1.5.5.2.adoc
diff --git a/Documentation/RelNotes/1.5.5.3.txt b/Documentation/RelNotes/1.5.5.3.adoc
index f22f98b734..f22f98b734 100644
--- a/Documentation/RelNotes/1.5.5.3.txt
+++ b/Documentation/RelNotes/1.5.5.3.adoc
diff --git a/Documentation/RelNotes/1.5.5.4.txt b/Documentation/RelNotes/1.5.5.4.adoc
index 2d0279ecce..2d0279ecce 100644
--- a/Documentation/RelNotes/1.5.5.4.txt
+++ b/Documentation/RelNotes/1.5.5.4.adoc
diff --git a/Documentation/RelNotes/1.5.5.5.txt b/Documentation/RelNotes/1.5.5.5.adoc
index 30fa3615c7..30fa3615c7 100644
--- a/Documentation/RelNotes/1.5.5.5.txt
+++ b/Documentation/RelNotes/1.5.5.5.adoc
diff --git a/Documentation/RelNotes/1.5.5.6.txt b/Documentation/RelNotes/1.5.5.6.adoc
index d5e85cb70e..d5e85cb70e 100644
--- a/Documentation/RelNotes/1.5.5.6.txt
+++ b/Documentation/RelNotes/1.5.5.6.adoc
diff --git a/Documentation/RelNotes/1.5.5.txt b/Documentation/RelNotes/1.5.5.adoc
index 2932212488..2932212488 100644
--- a/Documentation/RelNotes/1.5.5.txt
+++ b/Documentation/RelNotes/1.5.5.adoc
diff --git a/Documentation/RelNotes/1.5.6.1.txt b/Documentation/RelNotes/1.5.6.1.adoc
index 4864b16445..4864b16445 100644
--- a/Documentation/RelNotes/1.5.6.1.txt
+++ b/Documentation/RelNotes/1.5.6.1.adoc
diff --git a/Documentation/RelNotes/1.5.6.2.txt b/Documentation/RelNotes/1.5.6.2.adoc
index 5902a85a78..5902a85a78 100644
--- a/Documentation/RelNotes/1.5.6.2.txt
+++ b/Documentation/RelNotes/1.5.6.2.adoc
diff --git a/Documentation/RelNotes/1.5.6.3.txt b/Documentation/RelNotes/1.5.6.3.adoc
index f61dd3504a..f61dd3504a 100644
--- a/Documentation/RelNotes/1.5.6.3.txt
+++ b/Documentation/RelNotes/1.5.6.3.adoc
diff --git a/Documentation/RelNotes/1.5.6.4.txt b/Documentation/RelNotes/1.5.6.4.adoc
index d8968f1ecb..d8968f1ecb 100644
--- a/Documentation/RelNotes/1.5.6.4.txt
+++ b/Documentation/RelNotes/1.5.6.4.adoc
diff --git a/Documentation/RelNotes/1.5.6.5.txt b/Documentation/RelNotes/1.5.6.5.adoc
index 47ca172462..47ca172462 100644
--- a/Documentation/RelNotes/1.5.6.5.txt
+++ b/Documentation/RelNotes/1.5.6.5.adoc
diff --git a/Documentation/RelNotes/1.5.6.6.txt b/Documentation/RelNotes/1.5.6.6.adoc
index 79da23db5a..79da23db5a 100644
--- a/Documentation/RelNotes/1.5.6.6.txt
+++ b/Documentation/RelNotes/1.5.6.6.adoc
diff --git a/Documentation/RelNotes/1.5.6.txt b/Documentation/RelNotes/1.5.6.adoc
index e143d8d61b..e143d8d61b 100644
--- a/Documentation/RelNotes/1.5.6.txt
+++ b/Documentation/RelNotes/1.5.6.adoc
diff --git a/Documentation/RelNotes/1.6.0.1.txt b/Documentation/RelNotes/1.6.0.1.adoc
index 49d7a1cafa..49d7a1cafa 100644
--- a/Documentation/RelNotes/1.6.0.1.txt
+++ b/Documentation/RelNotes/1.6.0.1.adoc
diff --git a/Documentation/RelNotes/1.6.0.2.txt b/Documentation/RelNotes/1.6.0.2.adoc
index 7d8fb85e1b..7d8fb85e1b 100644
--- a/Documentation/RelNotes/1.6.0.2.txt
+++ b/Documentation/RelNotes/1.6.0.2.adoc
diff --git a/Documentation/RelNotes/1.6.0.3.txt b/Documentation/RelNotes/1.6.0.3.adoc
index ad36c0f0b7..ad36c0f0b7 100644
--- a/Documentation/RelNotes/1.6.0.3.txt
+++ b/Documentation/RelNotes/1.6.0.3.adoc
diff --git a/Documentation/RelNotes/1.6.0.4.txt b/Documentation/RelNotes/1.6.0.4.adoc
index d522661d31..d522661d31 100644
--- a/Documentation/RelNotes/1.6.0.4.txt
+++ b/Documentation/RelNotes/1.6.0.4.adoc
diff --git a/Documentation/RelNotes/1.6.0.5.txt b/Documentation/RelNotes/1.6.0.5.adoc
index a08bb96738..a08bb96738 100644
--- a/Documentation/RelNotes/1.6.0.5.txt
+++ b/Documentation/RelNotes/1.6.0.5.adoc
diff --git a/Documentation/RelNotes/1.6.0.6.txt b/Documentation/RelNotes/1.6.0.6.adoc
index 64ece1ffd5..64ece1ffd5 100644
--- a/Documentation/RelNotes/1.6.0.6.txt
+++ b/Documentation/RelNotes/1.6.0.6.adoc
diff --git a/Documentation/RelNotes/1.6.0.txt b/Documentation/RelNotes/1.6.0.adoc
index de7ef166b6..de7ef166b6 100644
--- a/Documentation/RelNotes/1.6.0.txt
+++ b/Documentation/RelNotes/1.6.0.adoc
diff --git a/Documentation/RelNotes/1.6.1.1.txt b/Documentation/RelNotes/1.6.1.1.adoc
index 8c594ba02f..8c594ba02f 100644
--- a/Documentation/RelNotes/1.6.1.1.txt
+++ b/Documentation/RelNotes/1.6.1.1.adoc
diff --git a/Documentation/RelNotes/1.6.1.2.txt b/Documentation/RelNotes/1.6.1.2.adoc
index be37cbb858..be37cbb858 100644
--- a/Documentation/RelNotes/1.6.1.2.txt
+++ b/Documentation/RelNotes/1.6.1.2.adoc
diff --git a/Documentation/RelNotes/1.6.1.3.txt b/Documentation/RelNotes/1.6.1.3.adoc
index cd08d8174e..cd08d8174e 100644
--- a/Documentation/RelNotes/1.6.1.3.txt
+++ b/Documentation/RelNotes/1.6.1.3.adoc
diff --git a/Documentation/RelNotes/1.6.1.4.txt b/Documentation/RelNotes/1.6.1.4.adoc
index ccbad794c0..ccbad794c0 100644
--- a/Documentation/RelNotes/1.6.1.4.txt
+++ b/Documentation/RelNotes/1.6.1.4.adoc
diff --git a/Documentation/RelNotes/1.6.1.txt b/Documentation/RelNotes/1.6.1.adoc
index 7b152a6fdc..7b152a6fdc 100644
--- a/Documentation/RelNotes/1.6.1.txt
+++ b/Documentation/RelNotes/1.6.1.adoc
diff --git a/Documentation/RelNotes/1.6.2.1.txt b/Documentation/RelNotes/1.6.2.1.adoc
index dfa36416af..dfa36416af 100644
--- a/Documentation/RelNotes/1.6.2.1.txt
+++ b/Documentation/RelNotes/1.6.2.1.adoc
diff --git a/Documentation/RelNotes/1.6.2.2.txt b/Documentation/RelNotes/1.6.2.2.adoc
index fafa9986b0..fafa9986b0 100644
--- a/Documentation/RelNotes/1.6.2.2.txt
+++ b/Documentation/RelNotes/1.6.2.2.adoc
diff --git a/Documentation/RelNotes/1.6.2.3.txt b/Documentation/RelNotes/1.6.2.3.adoc
index 4d3c1ac91c..4d3c1ac91c 100644
--- a/Documentation/RelNotes/1.6.2.3.txt
+++ b/Documentation/RelNotes/1.6.2.3.adoc
diff --git a/Documentation/RelNotes/1.6.2.4.txt b/Documentation/RelNotes/1.6.2.4.adoc
index f4bf1d0986..053dbb604d 100644
--- a/Documentation/RelNotes/1.6.2.4.txt
+++ b/Documentation/RelNotes/1.6.2.4.adoc
@@ -37,3 +37,4 @@ exec >/var/tmp/1
 echo O=$(git describe maint)
 O=v1.6.2.3-38-g318b847
 git shortlog --no-merges $O..maint
+---
diff --git a/Documentation/RelNotes/1.6.2.5.txt b/Documentation/RelNotes/1.6.2.5.adoc
index b23f9e95d1..b23f9e95d1 100644
--- a/Documentation/RelNotes/1.6.2.5.txt
+++ b/Documentation/RelNotes/1.6.2.5.adoc
diff --git a/Documentation/RelNotes/1.6.2.txt b/Documentation/RelNotes/1.6.2.adoc
index 166d73c60f..166d73c60f 100644
--- a/Documentation/RelNotes/1.6.2.txt
+++ b/Documentation/RelNotes/1.6.2.adoc
diff --git a/Documentation/RelNotes/1.6.3.1.txt b/Documentation/RelNotes/1.6.3.1.adoc
index 2400b72ef7..2400b72ef7 100644
--- a/Documentation/RelNotes/1.6.3.1.txt
+++ b/Documentation/RelNotes/1.6.3.1.adoc
diff --git a/Documentation/RelNotes/1.6.3.2.txt b/Documentation/RelNotes/1.6.3.2.adoc
index b2f3f0293c..b2f3f0293c 100644
--- a/Documentation/RelNotes/1.6.3.2.txt
+++ b/Documentation/RelNotes/1.6.3.2.adoc
diff --git a/Documentation/RelNotes/1.6.3.3.txt b/Documentation/RelNotes/1.6.3.3.adoc
index 1c28398bb6..1c28398bb6 100644
--- a/Documentation/RelNotes/1.6.3.3.txt
+++ b/Documentation/RelNotes/1.6.3.3.adoc
diff --git a/Documentation/RelNotes/1.6.3.4.txt b/Documentation/RelNotes/1.6.3.4.adoc
index cad461bc76..cad461bc76 100644
--- a/Documentation/RelNotes/1.6.3.4.txt
+++ b/Documentation/RelNotes/1.6.3.4.adoc
diff --git a/Documentation/RelNotes/1.6.3.txt b/Documentation/RelNotes/1.6.3.adoc
index bbf177fc3c..bbf177fc3c 100644
--- a/Documentation/RelNotes/1.6.3.txt
+++ b/Documentation/RelNotes/1.6.3.adoc
diff --git a/Documentation/RelNotes/1.6.4.1.txt b/Documentation/RelNotes/1.6.4.1.adoc
index e439e45b96..e439e45b96 100644
--- a/Documentation/RelNotes/1.6.4.1.txt
+++ b/Documentation/RelNotes/1.6.4.1.adoc
diff --git a/Documentation/RelNotes/1.6.4.2.txt b/Documentation/RelNotes/1.6.4.2.adoc
index c11ec0115c..c11ec0115c 100644
--- a/Documentation/RelNotes/1.6.4.2.txt
+++ b/Documentation/RelNotes/1.6.4.2.adoc
diff --git a/Documentation/RelNotes/1.6.4.3.txt b/Documentation/RelNotes/1.6.4.3.adoc
index 5643e6537d..5643e6537d 100644
--- a/Documentation/RelNotes/1.6.4.3.txt
+++ b/Documentation/RelNotes/1.6.4.3.adoc
diff --git a/Documentation/RelNotes/1.6.4.4.txt b/Documentation/RelNotes/1.6.4.4.adoc
index 0ead45fc72..0ead45fc72 100644
--- a/Documentation/RelNotes/1.6.4.4.txt
+++ b/Documentation/RelNotes/1.6.4.4.adoc
diff --git a/Documentation/RelNotes/1.6.4.5.txt b/Documentation/RelNotes/1.6.4.5.adoc
index eb6307dcbb..eb6307dcbb 100644
--- a/Documentation/RelNotes/1.6.4.5.txt
+++ b/Documentation/RelNotes/1.6.4.5.adoc
diff --git a/Documentation/RelNotes/1.6.4.txt b/Documentation/RelNotes/1.6.4.adoc
index 0fccfb0bf0..0fccfb0bf0 100644
--- a/Documentation/RelNotes/1.6.4.txt
+++ b/Documentation/RelNotes/1.6.4.adoc
diff --git a/Documentation/RelNotes/1.6.5.1.txt b/Documentation/RelNotes/1.6.5.1.adoc
index 309ba181b2..309ba181b2 100644
--- a/Documentation/RelNotes/1.6.5.1.txt
+++ b/Documentation/RelNotes/1.6.5.1.adoc
diff --git a/Documentation/RelNotes/1.6.5.2.txt b/Documentation/RelNotes/1.6.5.2.adoc
index aa7ccce3a2..aa7ccce3a2 100644
--- a/Documentation/RelNotes/1.6.5.2.txt
+++ b/Documentation/RelNotes/1.6.5.2.adoc
diff --git a/Documentation/RelNotes/1.6.5.3.txt b/Documentation/RelNotes/1.6.5.3.adoc
index b2fad1b22e..b2fad1b22e 100644
--- a/Documentation/RelNotes/1.6.5.3.txt
+++ b/Documentation/RelNotes/1.6.5.3.adoc
diff --git a/Documentation/RelNotes/1.6.5.4.txt b/Documentation/RelNotes/1.6.5.4.adoc
index 344333de66..344333de66 100644
--- a/Documentation/RelNotes/1.6.5.4.txt
+++ b/Documentation/RelNotes/1.6.5.4.adoc
diff --git a/Documentation/RelNotes/1.6.5.5.txt b/Documentation/RelNotes/1.6.5.5.adoc
index ecfc57d875..ecfc57d875 100644
--- a/Documentation/RelNotes/1.6.5.5.txt
+++ b/Documentation/RelNotes/1.6.5.5.adoc
diff --git a/Documentation/RelNotes/1.6.5.6.txt b/Documentation/RelNotes/1.6.5.6.adoc
index a9eaf76f62..a9eaf76f62 100644
--- a/Documentation/RelNotes/1.6.5.6.txt
+++ b/Documentation/RelNotes/1.6.5.6.adoc
diff --git a/Documentation/RelNotes/1.6.5.7.txt b/Documentation/RelNotes/1.6.5.7.adoc
index dc5302c21c..dc5302c21c 100644
--- a/Documentation/RelNotes/1.6.5.7.txt
+++ b/Documentation/RelNotes/1.6.5.7.adoc
diff --git a/Documentation/RelNotes/1.6.5.8.txt b/Documentation/RelNotes/1.6.5.8.adoc
index 8b24bebb96..8b24bebb96 100644
--- a/Documentation/RelNotes/1.6.5.8.txt
+++ b/Documentation/RelNotes/1.6.5.8.adoc
diff --git a/Documentation/RelNotes/1.6.5.9.txt b/Documentation/RelNotes/1.6.5.9.adoc
index bb469dd71e..bb469dd71e 100644
--- a/Documentation/RelNotes/1.6.5.9.txt
+++ b/Documentation/RelNotes/1.6.5.9.adoc
diff --git a/Documentation/RelNotes/1.6.5.txt b/Documentation/RelNotes/1.6.5.adoc
index 79cb1b2b6d..79cb1b2b6d 100644
--- a/Documentation/RelNotes/1.6.5.txt
+++ b/Documentation/RelNotes/1.6.5.adoc
diff --git a/Documentation/RelNotes/1.6.6.1.txt b/Documentation/RelNotes/1.6.6.1.adoc
index f1d0a4ae2d..f1d0a4ae2d 100644
--- a/Documentation/RelNotes/1.6.6.1.txt
+++ b/Documentation/RelNotes/1.6.6.1.adoc
diff --git a/Documentation/RelNotes/1.6.6.2.txt b/Documentation/RelNotes/1.6.6.2.adoc
index 4eaddc0106..4eaddc0106 100644
--- a/Documentation/RelNotes/1.6.6.2.txt
+++ b/Documentation/RelNotes/1.6.6.2.adoc
diff --git a/Documentation/RelNotes/1.6.6.3.txt b/Documentation/RelNotes/1.6.6.3.adoc
index 11483acaec..11483acaec 100644
--- a/Documentation/RelNotes/1.6.6.3.txt
+++ b/Documentation/RelNotes/1.6.6.3.adoc
diff --git a/Documentation/RelNotes/1.6.6.txt b/Documentation/RelNotes/1.6.6.adoc
index 88b86a827e..88b86a827e 100644
--- a/Documentation/RelNotes/1.6.6.txt
+++ b/Documentation/RelNotes/1.6.6.adoc
diff --git a/Documentation/RelNotes/1.7.0.1.txt b/Documentation/RelNotes/1.7.0.1.adoc
index 8ff5bcada8..8ff5bcada8 100644
--- a/Documentation/RelNotes/1.7.0.1.txt
+++ b/Documentation/RelNotes/1.7.0.1.adoc
diff --git a/Documentation/RelNotes/1.7.0.2.txt b/Documentation/RelNotes/1.7.0.2.adoc
index 73ed2b5278..73ed2b5278 100644
--- a/Documentation/RelNotes/1.7.0.2.txt
+++ b/Documentation/RelNotes/1.7.0.2.adoc
diff --git a/Documentation/RelNotes/1.7.0.3.txt b/Documentation/RelNotes/1.7.0.3.adoc
index 3b355737c0..3b355737c0 100644
--- a/Documentation/RelNotes/1.7.0.3.txt
+++ b/Documentation/RelNotes/1.7.0.3.adoc
diff --git a/Documentation/RelNotes/1.7.0.4.txt b/Documentation/RelNotes/1.7.0.4.adoc
index cf7f60e60d..cf7f60e60d 100644
--- a/Documentation/RelNotes/1.7.0.4.txt
+++ b/Documentation/RelNotes/1.7.0.4.adoc
diff --git a/Documentation/RelNotes/1.7.0.5.txt b/Documentation/RelNotes/1.7.0.5.adoc
index 3149c91b7b..3149c91b7b 100644
--- a/Documentation/RelNotes/1.7.0.5.txt
+++ b/Documentation/RelNotes/1.7.0.5.adoc
diff --git a/Documentation/RelNotes/1.7.0.6.txt b/Documentation/RelNotes/1.7.0.6.adoc
index b2852b67d0..b2852b67d0 100644
--- a/Documentation/RelNotes/1.7.0.6.txt
+++ b/Documentation/RelNotes/1.7.0.6.adoc
diff --git a/Documentation/RelNotes/1.7.0.7.txt b/Documentation/RelNotes/1.7.0.7.adoc
index d0cb7ca7e2..d0cb7ca7e2 100644
--- a/Documentation/RelNotes/1.7.0.7.txt
+++ b/Documentation/RelNotes/1.7.0.7.adoc
diff --git a/Documentation/RelNotes/1.7.0.8.txt b/Documentation/RelNotes/1.7.0.8.adoc
index 7f05b48e17..7f05b48e17 100644
--- a/Documentation/RelNotes/1.7.0.8.txt
+++ b/Documentation/RelNotes/1.7.0.8.adoc
diff --git a/Documentation/RelNotes/1.7.0.9.txt b/Documentation/RelNotes/1.7.0.9.adoc
index bfb3166387..bfb3166387 100644
--- a/Documentation/RelNotes/1.7.0.9.txt
+++ b/Documentation/RelNotes/1.7.0.9.adoc
diff --git a/Documentation/RelNotes/1.7.0.txt b/Documentation/RelNotes/1.7.0.adoc
index 0bb8c0b2a2..0bb8c0b2a2 100644
--- a/Documentation/RelNotes/1.7.0.txt
+++ b/Documentation/RelNotes/1.7.0.adoc
diff --git a/Documentation/RelNotes/1.7.1.1.txt b/Documentation/RelNotes/1.7.1.1.adoc
index 3f6b3148a3..3f6b3148a3 100644
--- a/Documentation/RelNotes/1.7.1.1.txt
+++ b/Documentation/RelNotes/1.7.1.1.adoc
diff --git a/Documentation/RelNotes/1.7.1.2.txt b/Documentation/RelNotes/1.7.1.2.adoc
index 61ba14e262..61ba14e262 100644
--- a/Documentation/RelNotes/1.7.1.2.txt
+++ b/Documentation/RelNotes/1.7.1.2.adoc
diff --git a/Documentation/RelNotes/1.7.1.3.txt b/Documentation/RelNotes/1.7.1.3.adoc
index 5b18518449..5b18518449 100644
--- a/Documentation/RelNotes/1.7.1.3.txt
+++ b/Documentation/RelNotes/1.7.1.3.adoc
diff --git a/Documentation/RelNotes/1.7.1.4.txt b/Documentation/RelNotes/1.7.1.4.adoc
index 7c734b4f7b..7c734b4f7b 100644
--- a/Documentation/RelNotes/1.7.1.4.txt
+++ b/Documentation/RelNotes/1.7.1.4.adoc
diff --git a/Documentation/RelNotes/1.7.1.txt b/Documentation/RelNotes/1.7.1.adoc
index 9d89fedb36..9d89fedb36 100644
--- a/Documentation/RelNotes/1.7.1.txt
+++ b/Documentation/RelNotes/1.7.1.adoc
diff --git a/Documentation/RelNotes/1.7.10.1.txt b/Documentation/RelNotes/1.7.10.1.adoc
index 71a86cb7c6..71a86cb7c6 100644
--- a/Documentation/RelNotes/1.7.10.1.txt
+++ b/Documentation/RelNotes/1.7.10.1.adoc
diff --git a/Documentation/RelNotes/1.7.10.2.txt b/Documentation/RelNotes/1.7.10.2.adoc
index 7a7e9d6fd1..7a7e9d6fd1 100644
--- a/Documentation/RelNotes/1.7.10.2.txt
+++ b/Documentation/RelNotes/1.7.10.2.adoc
diff --git a/Documentation/RelNotes/1.7.10.3.txt b/Documentation/RelNotes/1.7.10.3.adoc
index 703fbf1d60..703fbf1d60 100644
--- a/Documentation/RelNotes/1.7.10.3.txt
+++ b/Documentation/RelNotes/1.7.10.3.adoc
diff --git a/Documentation/RelNotes/1.7.10.4.txt b/Documentation/RelNotes/1.7.10.4.adoc
index 57597f2bf3..57597f2bf3 100644
--- a/Documentation/RelNotes/1.7.10.4.txt
+++ b/Documentation/RelNotes/1.7.10.4.adoc
diff --git a/Documentation/RelNotes/1.7.10.5.txt b/Documentation/RelNotes/1.7.10.5.adoc
index 4db1770e38..4db1770e38 100644
--- a/Documentation/RelNotes/1.7.10.5.txt
+++ b/Documentation/RelNotes/1.7.10.5.adoc
diff --git a/Documentation/RelNotes/1.7.10.txt b/Documentation/RelNotes/1.7.10.adoc
index 58100bf04e..58100bf04e 100644
--- a/Documentation/RelNotes/1.7.10.txt
+++ b/Documentation/RelNotes/1.7.10.adoc
diff --git a/Documentation/RelNotes/1.7.11.1.txt b/Documentation/RelNotes/1.7.11.1.adoc
index 577eccaacd..577eccaacd 100644
--- a/Documentation/RelNotes/1.7.11.1.txt
+++ b/Documentation/RelNotes/1.7.11.1.adoc
diff --git a/Documentation/RelNotes/1.7.11.2.txt b/Documentation/RelNotes/1.7.11.2.adoc
index f0cfd02d6f..f0cfd02d6f 100644
--- a/Documentation/RelNotes/1.7.11.2.txt
+++ b/Documentation/RelNotes/1.7.11.2.adoc
diff --git a/Documentation/RelNotes/1.7.11.3.txt b/Documentation/RelNotes/1.7.11.3.adoc
index 64494f89d9..64494f89d9 100644
--- a/Documentation/RelNotes/1.7.11.3.txt
+++ b/Documentation/RelNotes/1.7.11.3.adoc
diff --git a/Documentation/RelNotes/1.7.11.4.txt b/Documentation/RelNotes/1.7.11.4.adoc
index 3a640c2d4d..3a640c2d4d 100644
--- a/Documentation/RelNotes/1.7.11.4.txt
+++ b/Documentation/RelNotes/1.7.11.4.adoc
diff --git a/Documentation/RelNotes/1.7.11.5.txt b/Documentation/RelNotes/1.7.11.5.adoc
index 0a2ed855c5..0a2ed855c5 100644
--- a/Documentation/RelNotes/1.7.11.5.txt
+++ b/Documentation/RelNotes/1.7.11.5.adoc
diff --git a/Documentation/RelNotes/1.7.11.6.txt b/Documentation/RelNotes/1.7.11.6.adoc
index ba7d3c3966..ba7d3c3966 100644
--- a/Documentation/RelNotes/1.7.11.6.txt
+++ b/Documentation/RelNotes/1.7.11.6.adoc
diff --git a/Documentation/RelNotes/1.7.11.7.txt b/Documentation/RelNotes/1.7.11.7.adoc
index e743a2a8e4..e743a2a8e4 100644
--- a/Documentation/RelNotes/1.7.11.7.txt
+++ b/Documentation/RelNotes/1.7.11.7.adoc
diff --git a/Documentation/RelNotes/1.7.11.txt b/Documentation/RelNotes/1.7.11.adoc
index 15b954ca4b..15b954ca4b 100644
--- a/Documentation/RelNotes/1.7.11.txt
+++ b/Documentation/RelNotes/1.7.11.adoc
diff --git a/Documentation/RelNotes/1.7.12.1.txt b/Documentation/RelNotes/1.7.12.1.adoc
index b8f04af19f..b8f04af19f 100644
--- a/Documentation/RelNotes/1.7.12.1.txt
+++ b/Documentation/RelNotes/1.7.12.1.adoc
diff --git a/Documentation/RelNotes/1.7.12.2.txt b/Documentation/RelNotes/1.7.12.2.adoc
index 69255745e6..69255745e6 100644
--- a/Documentation/RelNotes/1.7.12.2.txt
+++ b/Documentation/RelNotes/1.7.12.2.adoc
diff --git a/Documentation/RelNotes/1.7.12.3.txt b/Documentation/RelNotes/1.7.12.3.adoc
index 4b822976b8..4b822976b8 100644
--- a/Documentation/RelNotes/1.7.12.3.txt
+++ b/Documentation/RelNotes/1.7.12.3.adoc
diff --git a/Documentation/RelNotes/1.7.12.4.txt b/Documentation/RelNotes/1.7.12.4.adoc
index c6da3cc939..c6da3cc939 100644
--- a/Documentation/RelNotes/1.7.12.4.txt
+++ b/Documentation/RelNotes/1.7.12.4.adoc
diff --git a/Documentation/RelNotes/1.7.12.txt b/Documentation/RelNotes/1.7.12.adoc
index 010d8c7de4..010d8c7de4 100644
--- a/Documentation/RelNotes/1.7.12.txt
+++ b/Documentation/RelNotes/1.7.12.adoc
diff --git a/Documentation/RelNotes/1.7.2.1.txt b/Documentation/RelNotes/1.7.2.1.adoc
index 1103c47a4f..1103c47a4f 100644
--- a/Documentation/RelNotes/1.7.2.1.txt
+++ b/Documentation/RelNotes/1.7.2.1.adoc
diff --git a/Documentation/RelNotes/1.7.2.2.txt b/Documentation/RelNotes/1.7.2.2.adoc
index 71eb6a8b0a..71eb6a8b0a 100644
--- a/Documentation/RelNotes/1.7.2.2.txt
+++ b/Documentation/RelNotes/1.7.2.2.adoc
diff --git a/Documentation/RelNotes/1.7.2.3.txt b/Documentation/RelNotes/1.7.2.3.adoc
index 610960cfe1..610960cfe1 100644
--- a/Documentation/RelNotes/1.7.2.3.txt
+++ b/Documentation/RelNotes/1.7.2.3.adoc
diff --git a/Documentation/RelNotes/1.7.2.4.txt b/Documentation/RelNotes/1.7.2.4.adoc
index f7950a4c04..f7950a4c04 100644
--- a/Documentation/RelNotes/1.7.2.4.txt
+++ b/Documentation/RelNotes/1.7.2.4.adoc
diff --git a/Documentation/RelNotes/1.7.2.5.txt b/Documentation/RelNotes/1.7.2.5.adoc
index bf976c40db..bf976c40db 100644
--- a/Documentation/RelNotes/1.7.2.5.txt
+++ b/Documentation/RelNotes/1.7.2.5.adoc
diff --git a/Documentation/RelNotes/1.7.2.txt b/Documentation/RelNotes/1.7.2.adoc
index 15cf01178c..15cf01178c 100644
--- a/Documentation/RelNotes/1.7.2.txt
+++ b/Documentation/RelNotes/1.7.2.adoc
diff --git a/Documentation/RelNotes/1.7.3.1.txt b/Documentation/RelNotes/1.7.3.1.adoc
index 002c93b961..002c93b961 100644
--- a/Documentation/RelNotes/1.7.3.1.txt
+++ b/Documentation/RelNotes/1.7.3.1.adoc
diff --git a/Documentation/RelNotes/1.7.3.2.txt b/Documentation/RelNotes/1.7.3.2.adoc
index 5c93b85af4..5c93b85af4 100644
--- a/Documentation/RelNotes/1.7.3.2.txt
+++ b/Documentation/RelNotes/1.7.3.2.adoc
diff --git a/Documentation/RelNotes/1.7.3.3.txt b/Documentation/RelNotes/1.7.3.3.adoc
index 9b2b2448df..9b2b2448df 100644
--- a/Documentation/RelNotes/1.7.3.3.txt
+++ b/Documentation/RelNotes/1.7.3.3.adoc
diff --git a/Documentation/RelNotes/1.7.3.4.txt b/Documentation/RelNotes/1.7.3.4.adoc
index e57f7c176d..e57f7c176d 100644
--- a/Documentation/RelNotes/1.7.3.4.txt
+++ b/Documentation/RelNotes/1.7.3.4.adoc
diff --git a/Documentation/RelNotes/1.7.3.5.txt b/Documentation/RelNotes/1.7.3.5.adoc
index 40f3ba5795..40f3ba5795 100644
--- a/Documentation/RelNotes/1.7.3.5.txt
+++ b/Documentation/RelNotes/1.7.3.5.adoc
diff --git a/Documentation/RelNotes/1.7.3.txt b/Documentation/RelNotes/1.7.3.adoc
index 309c33181f..309c33181f 100644
--- a/Documentation/RelNotes/1.7.3.txt
+++ b/Documentation/RelNotes/1.7.3.adoc
diff --git a/Documentation/RelNotes/1.7.4.1.txt b/Documentation/RelNotes/1.7.4.1.adoc
index 79923a6d2f..79923a6d2f 100644
--- a/Documentation/RelNotes/1.7.4.1.txt
+++ b/Documentation/RelNotes/1.7.4.1.adoc
diff --git a/Documentation/RelNotes/1.7.4.2.txt b/Documentation/RelNotes/1.7.4.2.adoc
index ef4ce1fcd3..ef4ce1fcd3 100644
--- a/Documentation/RelNotes/1.7.4.2.txt
+++ b/Documentation/RelNotes/1.7.4.2.adoc
diff --git a/Documentation/RelNotes/1.7.4.3.txt b/Documentation/RelNotes/1.7.4.3.adoc
index 02a3d5bdf6..02a3d5bdf6 100644
--- a/Documentation/RelNotes/1.7.4.3.txt
+++ b/Documentation/RelNotes/1.7.4.3.adoc
diff --git a/Documentation/RelNotes/1.7.4.4.txt b/Documentation/RelNotes/1.7.4.4.adoc
index ff06e04a58..ff06e04a58 100644
--- a/Documentation/RelNotes/1.7.4.4.txt
+++ b/Documentation/RelNotes/1.7.4.4.adoc
diff --git a/Documentation/RelNotes/1.7.4.5.txt b/Documentation/RelNotes/1.7.4.5.adoc
index b7a0eeb22f..b7a0eeb22f 100644
--- a/Documentation/RelNotes/1.7.4.5.txt
+++ b/Documentation/RelNotes/1.7.4.5.adoc
diff --git a/Documentation/RelNotes/1.7.4.txt b/Documentation/RelNotes/1.7.4.adoc
index d5bca731b5..d5bca731b5 100644
--- a/Documentation/RelNotes/1.7.4.txt
+++ b/Documentation/RelNotes/1.7.4.adoc
diff --git a/Documentation/RelNotes/1.7.5.1.txt b/Documentation/RelNotes/1.7.5.1.adoc
index c6ebd76d19..c6ebd76d19 100644
--- a/Documentation/RelNotes/1.7.5.1.txt
+++ b/Documentation/RelNotes/1.7.5.1.adoc
diff --git a/Documentation/RelNotes/1.7.5.2.txt b/Documentation/RelNotes/1.7.5.2.adoc
index 951eb7cb08..951eb7cb08 100644
--- a/Documentation/RelNotes/1.7.5.2.txt
+++ b/Documentation/RelNotes/1.7.5.2.adoc
diff --git a/Documentation/RelNotes/1.7.5.3.txt b/Documentation/RelNotes/1.7.5.3.adoc
index 1d24edcf2f..1d24edcf2f 100644
--- a/Documentation/RelNotes/1.7.5.3.txt
+++ b/Documentation/RelNotes/1.7.5.3.adoc
diff --git a/Documentation/RelNotes/1.7.5.4.txt b/Documentation/RelNotes/1.7.5.4.adoc
index 7796df3fe4..7796df3fe4 100644
--- a/Documentation/RelNotes/1.7.5.4.txt
+++ b/Documentation/RelNotes/1.7.5.4.adoc
diff --git a/Documentation/RelNotes/1.7.5.txt b/Documentation/RelNotes/1.7.5.adoc
index 987919c321..987919c321 100644
--- a/Documentation/RelNotes/1.7.5.txt
+++ b/Documentation/RelNotes/1.7.5.adoc
diff --git a/Documentation/RelNotes/1.7.6.1.txt b/Documentation/RelNotes/1.7.6.1.adoc
index 42e46ab17f..42e46ab17f 100644
--- a/Documentation/RelNotes/1.7.6.1.txt
+++ b/Documentation/RelNotes/1.7.6.1.adoc
diff --git a/Documentation/RelNotes/1.7.6.2.txt b/Documentation/RelNotes/1.7.6.2.adoc
index 67ae414965..67ae414965 100644
--- a/Documentation/RelNotes/1.7.6.2.txt
+++ b/Documentation/RelNotes/1.7.6.2.adoc
diff --git a/Documentation/RelNotes/1.7.6.3.txt b/Documentation/RelNotes/1.7.6.3.adoc
index 95971831b9..95971831b9 100644
--- a/Documentation/RelNotes/1.7.6.3.txt
+++ b/Documentation/RelNotes/1.7.6.3.adoc
diff --git a/Documentation/RelNotes/1.7.6.4.txt b/Documentation/RelNotes/1.7.6.4.adoc
index e19acac2da..e19acac2da 100644
--- a/Documentation/RelNotes/1.7.6.4.txt
+++ b/Documentation/RelNotes/1.7.6.4.adoc
diff --git a/Documentation/RelNotes/1.7.6.5.txt b/Documentation/RelNotes/1.7.6.5.adoc
index 6713132a9e..6713132a9e 100644
--- a/Documentation/RelNotes/1.7.6.5.txt
+++ b/Documentation/RelNotes/1.7.6.5.adoc
diff --git a/Documentation/RelNotes/1.7.6.6.txt b/Documentation/RelNotes/1.7.6.6.adoc
index 5343e00400..5343e00400 100644
--- a/Documentation/RelNotes/1.7.6.6.txt
+++ b/Documentation/RelNotes/1.7.6.6.adoc
diff --git a/Documentation/RelNotes/1.7.6.txt b/Documentation/RelNotes/1.7.6.adoc
index 9ec498ea39..9ec498ea39 100644
--- a/Documentation/RelNotes/1.7.6.txt
+++ b/Documentation/RelNotes/1.7.6.adoc
diff --git a/Documentation/RelNotes/1.7.7.1.txt b/Documentation/RelNotes/1.7.7.1.adoc
index ac9b838e25..ac9b838e25 100644
--- a/Documentation/RelNotes/1.7.7.1.txt
+++ b/Documentation/RelNotes/1.7.7.1.adoc
diff --git a/Documentation/RelNotes/1.7.7.2.txt b/Documentation/RelNotes/1.7.7.2.adoc
index e6bbef2f01..e6bbef2f01 100644
--- a/Documentation/RelNotes/1.7.7.2.txt
+++ b/Documentation/RelNotes/1.7.7.2.adoc
diff --git a/Documentation/RelNotes/1.7.7.3.txt b/Documentation/RelNotes/1.7.7.3.adoc
index 09301f0957..09301f0957 100644
--- a/Documentation/RelNotes/1.7.7.3.txt
+++ b/Documentation/RelNotes/1.7.7.3.adoc
diff --git a/Documentation/RelNotes/1.7.7.4.txt b/Documentation/RelNotes/1.7.7.4.adoc
index e5234485e7..e5234485e7 100644
--- a/Documentation/RelNotes/1.7.7.4.txt
+++ b/Documentation/RelNotes/1.7.7.4.adoc
diff --git a/Documentation/RelNotes/1.7.7.5.txt b/Documentation/RelNotes/1.7.7.5.adoc
index 7b0931987b..7b0931987b 100644
--- a/Documentation/RelNotes/1.7.7.5.txt
+++ b/Documentation/RelNotes/1.7.7.5.adoc
diff --git a/Documentation/RelNotes/1.7.7.6.txt b/Documentation/RelNotes/1.7.7.6.adoc
index 8df606d452..8df606d452 100644
--- a/Documentation/RelNotes/1.7.7.6.txt
+++ b/Documentation/RelNotes/1.7.7.6.adoc
diff --git a/Documentation/RelNotes/1.7.7.7.txt b/Documentation/RelNotes/1.7.7.7.adoc
index e79118d063..e79118d063 100644
--- a/Documentation/RelNotes/1.7.7.7.txt
+++ b/Documentation/RelNotes/1.7.7.7.adoc
diff --git a/Documentation/RelNotes/1.7.7.txt b/Documentation/RelNotes/1.7.7.adoc
index 6eff128c80..6eff128c80 100644
--- a/Documentation/RelNotes/1.7.7.txt
+++ b/Documentation/RelNotes/1.7.7.adoc
diff --git a/Documentation/RelNotes/1.7.8.1.txt b/Documentation/RelNotes/1.7.8.1.adoc
index 33dc948b94..33dc948b94 100644
--- a/Documentation/RelNotes/1.7.8.1.txt
+++ b/Documentation/RelNotes/1.7.8.1.adoc
diff --git a/Documentation/RelNotes/1.7.8.2.txt b/Documentation/RelNotes/1.7.8.2.adoc
index b9c66aa1b7..b9c66aa1b7 100644
--- a/Documentation/RelNotes/1.7.8.2.txt
+++ b/Documentation/RelNotes/1.7.8.2.adoc
diff --git a/Documentation/RelNotes/1.7.8.3.txt b/Documentation/RelNotes/1.7.8.3.adoc
index a92714c14b..a92714c14b 100644
--- a/Documentation/RelNotes/1.7.8.3.txt
+++ b/Documentation/RelNotes/1.7.8.3.adoc
diff --git a/Documentation/RelNotes/1.7.8.4.txt b/Documentation/RelNotes/1.7.8.4.adoc
index 9bebdbf13d..9bebdbf13d 100644
--- a/Documentation/RelNotes/1.7.8.4.txt
+++ b/Documentation/RelNotes/1.7.8.4.adoc
diff --git a/Documentation/RelNotes/1.7.8.5.txt b/Documentation/RelNotes/1.7.8.5.adoc
index 011fd2a428..011fd2a428 100644
--- a/Documentation/RelNotes/1.7.8.5.txt
+++ b/Documentation/RelNotes/1.7.8.5.adoc
diff --git a/Documentation/RelNotes/1.7.8.6.txt b/Documentation/RelNotes/1.7.8.6.adoc
index d9bf2b741a..d9bf2b741a 100644
--- a/Documentation/RelNotes/1.7.8.6.txt
+++ b/Documentation/RelNotes/1.7.8.6.adoc
diff --git a/Documentation/RelNotes/1.7.8.txt b/Documentation/RelNotes/1.7.8.adoc
index 249311361e..249311361e 100644
--- a/Documentation/RelNotes/1.7.8.txt
+++ b/Documentation/RelNotes/1.7.8.adoc
diff --git a/Documentation/RelNotes/1.7.9.1.txt b/Documentation/RelNotes/1.7.9.1.adoc
index 6957183dbb..6957183dbb 100644
--- a/Documentation/RelNotes/1.7.9.1.txt
+++ b/Documentation/RelNotes/1.7.9.1.adoc
diff --git a/Documentation/RelNotes/1.7.9.2.txt b/Documentation/RelNotes/1.7.9.2.adoc
index e500da75dd..e500da75dd 100644
--- a/Documentation/RelNotes/1.7.9.2.txt
+++ b/Documentation/RelNotes/1.7.9.2.adoc
diff --git a/Documentation/RelNotes/1.7.9.3.txt b/Documentation/RelNotes/1.7.9.3.adoc
index 91c65012f9..91c65012f9 100644
--- a/Documentation/RelNotes/1.7.9.3.txt
+++ b/Documentation/RelNotes/1.7.9.3.adoc
diff --git a/Documentation/RelNotes/1.7.9.4.txt b/Documentation/RelNotes/1.7.9.4.adoc
index e5217a1889..e5217a1889 100644
--- a/Documentation/RelNotes/1.7.9.4.txt
+++ b/Documentation/RelNotes/1.7.9.4.adoc
diff --git a/Documentation/RelNotes/1.7.9.5.txt b/Documentation/RelNotes/1.7.9.5.adoc
index 95cc2bbf2c..95cc2bbf2c 100644
--- a/Documentation/RelNotes/1.7.9.5.txt
+++ b/Documentation/RelNotes/1.7.9.5.adoc
diff --git a/Documentation/RelNotes/1.7.9.6.txt b/Documentation/RelNotes/1.7.9.6.adoc
index 74bf8825e2..74bf8825e2 100644
--- a/Documentation/RelNotes/1.7.9.6.txt
+++ b/Documentation/RelNotes/1.7.9.6.adoc
diff --git a/Documentation/RelNotes/1.7.9.7.txt b/Documentation/RelNotes/1.7.9.7.adoc
index 59667d0f2a..59667d0f2a 100644
--- a/Documentation/RelNotes/1.7.9.7.txt
+++ b/Documentation/RelNotes/1.7.9.7.adoc
diff --git a/Documentation/RelNotes/1.7.9.txt b/Documentation/RelNotes/1.7.9.adoc
index 95320aad5d..95320aad5d 100644
--- a/Documentation/RelNotes/1.7.9.txt
+++ b/Documentation/RelNotes/1.7.9.adoc
diff --git a/Documentation/RelNotes/1.8.0.1.txt b/Documentation/RelNotes/1.8.0.1.adoc
index 1f372fa0b5..1f372fa0b5 100644
--- a/Documentation/RelNotes/1.8.0.1.txt
+++ b/Documentation/RelNotes/1.8.0.1.adoc
diff --git a/Documentation/RelNotes/1.8.0.2.txt b/Documentation/RelNotes/1.8.0.2.adoc
index 8497e051de..8497e051de 100644
--- a/Documentation/RelNotes/1.8.0.2.txt
+++ b/Documentation/RelNotes/1.8.0.2.adoc
diff --git a/Documentation/RelNotes/1.8.0.3.txt b/Documentation/RelNotes/1.8.0.3.adoc
index 92b1e4b363..92b1e4b363 100644
--- a/Documentation/RelNotes/1.8.0.3.txt
+++ b/Documentation/RelNotes/1.8.0.3.adoc
diff --git a/Documentation/RelNotes/1.8.0.txt b/Documentation/RelNotes/1.8.0.adoc
index 63d6e4afa4..63d6e4afa4 100644
--- a/Documentation/RelNotes/1.8.0.txt
+++ b/Documentation/RelNotes/1.8.0.adoc
diff --git a/Documentation/RelNotes/1.8.1.1.txt b/Documentation/RelNotes/1.8.1.1.adoc
index 6cde07ba29..6cde07ba29 100644
--- a/Documentation/RelNotes/1.8.1.1.txt
+++ b/Documentation/RelNotes/1.8.1.1.adoc
diff --git a/Documentation/RelNotes/1.8.1.2.txt b/Documentation/RelNotes/1.8.1.2.adoc
index 5ab7b18906..5ab7b18906 100644
--- a/Documentation/RelNotes/1.8.1.2.txt
+++ b/Documentation/RelNotes/1.8.1.2.adoc
diff --git a/Documentation/RelNotes/1.8.1.3.txt b/Documentation/RelNotes/1.8.1.3.adoc
index 681cb35c0a..681cb35c0a 100644
--- a/Documentation/RelNotes/1.8.1.3.txt
+++ b/Documentation/RelNotes/1.8.1.3.adoc
diff --git a/Documentation/RelNotes/1.8.1.4.txt b/Documentation/RelNotes/1.8.1.4.adoc
index 22af1d1643..22af1d1643 100644
--- a/Documentation/RelNotes/1.8.1.4.txt
+++ b/Documentation/RelNotes/1.8.1.4.adoc
diff --git a/Documentation/RelNotes/1.8.1.5.txt b/Documentation/RelNotes/1.8.1.5.adoc
index efa68aef22..efa68aef22 100644
--- a/Documentation/RelNotes/1.8.1.5.txt
+++ b/Documentation/RelNotes/1.8.1.5.adoc
diff --git a/Documentation/RelNotes/1.8.1.6.txt b/Documentation/RelNotes/1.8.1.6.adoc
index c15cf2e805..c15cf2e805 100644
--- a/Documentation/RelNotes/1.8.1.6.txt
+++ b/Documentation/RelNotes/1.8.1.6.adoc
diff --git a/Documentation/RelNotes/1.8.1.txt b/Documentation/RelNotes/1.8.1.adoc
index d6f9555923..d6f9555923 100644
--- a/Documentation/RelNotes/1.8.1.txt
+++ b/Documentation/RelNotes/1.8.1.adoc
diff --git a/Documentation/RelNotes/1.8.2.1.txt b/Documentation/RelNotes/1.8.2.1.adoc
index 769a6fc06c..769a6fc06c 100644
--- a/Documentation/RelNotes/1.8.2.1.txt
+++ b/Documentation/RelNotes/1.8.2.1.adoc
diff --git a/Documentation/RelNotes/1.8.2.2.txt b/Documentation/RelNotes/1.8.2.2.adoc
index 708df1ae19..708df1ae19 100644
--- a/Documentation/RelNotes/1.8.2.2.txt
+++ b/Documentation/RelNotes/1.8.2.2.adoc
diff --git a/Documentation/RelNotes/1.8.2.3.txt b/Documentation/RelNotes/1.8.2.3.adoc
index 613948251a..613948251a 100644
--- a/Documentation/RelNotes/1.8.2.3.txt
+++ b/Documentation/RelNotes/1.8.2.3.adoc
diff --git a/Documentation/RelNotes/1.8.2.txt b/Documentation/RelNotes/1.8.2.adoc
index fc606ae116..fc606ae116 100644
--- a/Documentation/RelNotes/1.8.2.txt
+++ b/Documentation/RelNotes/1.8.2.adoc
diff --git a/Documentation/RelNotes/1.8.3.1.txt b/Documentation/RelNotes/1.8.3.1.adoc
index 986637b755..986637b755 100644
--- a/Documentation/RelNotes/1.8.3.1.txt
+++ b/Documentation/RelNotes/1.8.3.1.adoc
diff --git a/Documentation/RelNotes/1.8.3.2.txt b/Documentation/RelNotes/1.8.3.2.adoc
index 26ae142c3d..26ae142c3d 100644
--- a/Documentation/RelNotes/1.8.3.2.txt
+++ b/Documentation/RelNotes/1.8.3.2.adoc
diff --git a/Documentation/RelNotes/1.8.3.3.txt b/Documentation/RelNotes/1.8.3.3.adoc
index 9ba4f4da0f..9ba4f4da0f 100644
--- a/Documentation/RelNotes/1.8.3.3.txt
+++ b/Documentation/RelNotes/1.8.3.3.adoc
diff --git a/Documentation/RelNotes/1.8.3.4.txt b/Documentation/RelNotes/1.8.3.4.adoc
index 56f106e262..56f106e262 100644
--- a/Documentation/RelNotes/1.8.3.4.txt
+++ b/Documentation/RelNotes/1.8.3.4.adoc
diff --git a/Documentation/RelNotes/1.8.3.txt b/Documentation/RelNotes/1.8.3.adoc
index ead568e7f1..ead568e7f1 100644
--- a/Documentation/RelNotes/1.8.3.txt
+++ b/Documentation/RelNotes/1.8.3.adoc
diff --git a/Documentation/RelNotes/1.8.4.1.txt b/Documentation/RelNotes/1.8.4.1.adoc
index c257beb114..c257beb114 100644
--- a/Documentation/RelNotes/1.8.4.1.txt
+++ b/Documentation/RelNotes/1.8.4.1.adoc
diff --git a/Documentation/RelNotes/1.8.4.2.txt b/Documentation/RelNotes/1.8.4.2.adoc
index bf6fb1a023..bf6fb1a023 100644
--- a/Documentation/RelNotes/1.8.4.2.txt
+++ b/Documentation/RelNotes/1.8.4.2.adoc
diff --git a/Documentation/RelNotes/1.8.4.3.txt b/Documentation/RelNotes/1.8.4.3.adoc
index 267a1b34b4..267a1b34b4 100644
--- a/Documentation/RelNotes/1.8.4.3.txt
+++ b/Documentation/RelNotes/1.8.4.3.adoc
diff --git a/Documentation/RelNotes/1.8.4.4.txt b/Documentation/RelNotes/1.8.4.4.adoc
index a7c1ce15c0..a7c1ce15c0 100644
--- a/Documentation/RelNotes/1.8.4.4.txt
+++ b/Documentation/RelNotes/1.8.4.4.adoc
diff --git a/Documentation/RelNotes/1.8.4.5.txt b/Documentation/RelNotes/1.8.4.5.adoc
index 215bd1a7a2..215bd1a7a2 100644
--- a/Documentation/RelNotes/1.8.4.5.txt
+++ b/Documentation/RelNotes/1.8.4.5.adoc
diff --git a/Documentation/RelNotes/1.8.4.txt b/Documentation/RelNotes/1.8.4.adoc
index 2e7529928b..2e7529928b 100644
--- a/Documentation/RelNotes/1.8.4.txt
+++ b/Documentation/RelNotes/1.8.4.adoc
diff --git a/Documentation/RelNotes/1.8.5.1.txt b/Documentation/RelNotes/1.8.5.1.adoc
index 7236aaf232..7236aaf232 100644
--- a/Documentation/RelNotes/1.8.5.1.txt
+++ b/Documentation/RelNotes/1.8.5.1.adoc
diff --git a/Documentation/RelNotes/1.8.5.2.txt b/Documentation/RelNotes/1.8.5.2.adoc
index 3ac4984f10..3ac4984f10 100644
--- a/Documentation/RelNotes/1.8.5.2.txt
+++ b/Documentation/RelNotes/1.8.5.2.adoc
diff --git a/Documentation/RelNotes/1.8.5.3.txt b/Documentation/RelNotes/1.8.5.3.adoc
index 3de2dd0f19..3de2dd0f19 100644
--- a/Documentation/RelNotes/1.8.5.3.txt
+++ b/Documentation/RelNotes/1.8.5.3.adoc
diff --git a/Documentation/RelNotes/1.8.5.4.txt b/Documentation/RelNotes/1.8.5.4.adoc
index d18c40389e..d18c40389e 100644
--- a/Documentation/RelNotes/1.8.5.4.txt
+++ b/Documentation/RelNotes/1.8.5.4.adoc
diff --git a/Documentation/RelNotes/1.8.5.5.txt b/Documentation/RelNotes/1.8.5.5.adoc
index 9191ce948f..9191ce948f 100644
--- a/Documentation/RelNotes/1.8.5.5.txt
+++ b/Documentation/RelNotes/1.8.5.5.adoc
diff --git a/Documentation/RelNotes/1.8.5.6.txt b/Documentation/RelNotes/1.8.5.6.adoc
index 92ff92b1e6..92ff92b1e6 100644
--- a/Documentation/RelNotes/1.8.5.6.txt
+++ b/Documentation/RelNotes/1.8.5.6.adoc
diff --git a/Documentation/RelNotes/1.8.5.txt b/Documentation/RelNotes/1.8.5.adoc
index 602df0cac2..602df0cac2 100644
--- a/Documentation/RelNotes/1.8.5.txt
+++ b/Documentation/RelNotes/1.8.5.adoc
diff --git a/Documentation/RelNotes/1.9.0.txt b/Documentation/RelNotes/1.9.0.adoc
index 4e4b88aa5c..4e4b88aa5c 100644
--- a/Documentation/RelNotes/1.9.0.txt
+++ b/Documentation/RelNotes/1.9.0.adoc
diff --git a/Documentation/RelNotes/1.9.1.txt b/Documentation/RelNotes/1.9.1.adoc
index 5b0602053c..5b0602053c 100644
--- a/Documentation/RelNotes/1.9.1.txt
+++ b/Documentation/RelNotes/1.9.1.adoc
diff --git a/Documentation/RelNotes/1.9.2.txt b/Documentation/RelNotes/1.9.2.adoc
index 47a34ca964..47a34ca964 100644
--- a/Documentation/RelNotes/1.9.2.txt
+++ b/Documentation/RelNotes/1.9.2.adoc
diff --git a/Documentation/RelNotes/1.9.3.txt b/Documentation/RelNotes/1.9.3.adoc
index 17b05ca7b5..17b05ca7b5 100644
--- a/Documentation/RelNotes/1.9.3.txt
+++ b/Documentation/RelNotes/1.9.3.adoc
diff --git a/Documentation/RelNotes/1.9.4.txt b/Documentation/RelNotes/1.9.4.adoc
index e1d1835436..e1d1835436 100644
--- a/Documentation/RelNotes/1.9.4.txt
+++ b/Documentation/RelNotes/1.9.4.adoc
diff --git a/Documentation/RelNotes/1.9.5.txt b/Documentation/RelNotes/1.9.5.adoc
index 8d6ac0cf53..8d6ac0cf53 100644
--- a/Documentation/RelNotes/1.9.5.txt
+++ b/Documentation/RelNotes/1.9.5.adoc
diff --git a/Documentation/RelNotes/2.0.0.txt b/Documentation/RelNotes/2.0.0.adoc
index 2617372a0c..2617372a0c 100644
--- a/Documentation/RelNotes/2.0.0.txt
+++ b/Documentation/RelNotes/2.0.0.adoc
diff --git a/Documentation/RelNotes/2.0.1.txt b/Documentation/RelNotes/2.0.1.adoc
index ce5579db3e..ce5579db3e 100644
--- a/Documentation/RelNotes/2.0.1.txt
+++ b/Documentation/RelNotes/2.0.1.adoc
diff --git a/Documentation/RelNotes/2.0.2.txt b/Documentation/RelNotes/2.0.2.adoc
index 8e8321b2ef..8e8321b2ef 100644
--- a/Documentation/RelNotes/2.0.2.txt
+++ b/Documentation/RelNotes/2.0.2.adoc
diff --git a/Documentation/RelNotes/2.0.3.txt b/Documentation/RelNotes/2.0.3.adoc
index 4047b46bbe..4047b46bbe 100644
--- a/Documentation/RelNotes/2.0.3.txt
+++ b/Documentation/RelNotes/2.0.3.adoc
diff --git a/Documentation/RelNotes/2.0.4.txt b/Documentation/RelNotes/2.0.4.adoc
index 7e340921a2..7e340921a2 100644
--- a/Documentation/RelNotes/2.0.4.txt
+++ b/Documentation/RelNotes/2.0.4.adoc
diff --git a/Documentation/RelNotes/2.0.5.txt b/Documentation/RelNotes/2.0.5.adoc
index 3a16f697e8..3a16f697e8 100644
--- a/Documentation/RelNotes/2.0.5.txt
+++ b/Documentation/RelNotes/2.0.5.adoc
diff --git a/Documentation/RelNotes/2.1.0.txt b/Documentation/RelNotes/2.1.0.adoc
index ae4753728e..ae4753728e 100644
--- a/Documentation/RelNotes/2.1.0.txt
+++ b/Documentation/RelNotes/2.1.0.adoc
diff --git a/Documentation/RelNotes/2.1.1.txt b/Documentation/RelNotes/2.1.1.adoc
index 830fc3cc6d..830fc3cc6d 100644
--- a/Documentation/RelNotes/2.1.1.txt
+++ b/Documentation/RelNotes/2.1.1.adoc
diff --git a/Documentation/RelNotes/2.1.2.txt b/Documentation/RelNotes/2.1.2.adoc
index abc3b8928a..abc3b8928a 100644
--- a/Documentation/RelNotes/2.1.2.txt
+++ b/Documentation/RelNotes/2.1.2.adoc
diff --git a/Documentation/RelNotes/2.1.3.txt b/Documentation/RelNotes/2.1.3.adoc
index 0dfb17c4fc..0dfb17c4fc 100644
--- a/Documentation/RelNotes/2.1.3.txt
+++ b/Documentation/RelNotes/2.1.3.adoc
diff --git a/Documentation/RelNotes/2.1.4.txt b/Documentation/RelNotes/2.1.4.adoc
index d16e5f041f..d16e5f041f 100644
--- a/Documentation/RelNotes/2.1.4.txt
+++ b/Documentation/RelNotes/2.1.4.adoc
diff --git a/Documentation/RelNotes/2.10.0.txt b/Documentation/RelNotes/2.10.0.adoc
index 3792b7d03d..3792b7d03d 100644
--- a/Documentation/RelNotes/2.10.0.txt
+++ b/Documentation/RelNotes/2.10.0.adoc
diff --git a/Documentation/RelNotes/2.10.1.txt b/Documentation/RelNotes/2.10.1.adoc
index 70462f7f7e..70462f7f7e 100644
--- a/Documentation/RelNotes/2.10.1.txt
+++ b/Documentation/RelNotes/2.10.1.adoc
diff --git a/Documentation/RelNotes/2.10.2.txt b/Documentation/RelNotes/2.10.2.adoc
index abbd331508..abbd331508 100644
--- a/Documentation/RelNotes/2.10.2.txt
+++ b/Documentation/RelNotes/2.10.2.adoc
diff --git a/Documentation/RelNotes/2.10.3.txt b/Documentation/RelNotes/2.10.3.adoc
index ad6a01bf83..ad6a01bf83 100644
--- a/Documentation/RelNotes/2.10.3.txt
+++ b/Documentation/RelNotes/2.10.3.adoc
diff --git a/Documentation/RelNotes/2.10.4.txt b/Documentation/RelNotes/2.10.4.adoc
index ee8142ad24..ee8142ad24 100644
--- a/Documentation/RelNotes/2.10.4.txt
+++ b/Documentation/RelNotes/2.10.4.adoc
diff --git a/Documentation/RelNotes/2.10.5.txt b/Documentation/RelNotes/2.10.5.adoc
index a498fd6fdc..a498fd6fdc 100644
--- a/Documentation/RelNotes/2.10.5.txt
+++ b/Documentation/RelNotes/2.10.5.adoc
diff --git a/Documentation/RelNotes/2.11.0.txt b/Documentation/RelNotes/2.11.0.adoc
index b7b7dd361e..b7b7dd361e 100644
--- a/Documentation/RelNotes/2.11.0.txt
+++ b/Documentation/RelNotes/2.11.0.adoc
diff --git a/Documentation/RelNotes/2.11.1.txt b/Documentation/RelNotes/2.11.1.adoc
index 7d35cf186d..7d35cf186d 100644
--- a/Documentation/RelNotes/2.11.1.txt
+++ b/Documentation/RelNotes/2.11.1.adoc
diff --git a/Documentation/RelNotes/2.11.2.txt b/Documentation/RelNotes/2.11.2.adoc
index 7428851168..7428851168 100644
--- a/Documentation/RelNotes/2.11.2.txt
+++ b/Documentation/RelNotes/2.11.2.adoc
diff --git a/Documentation/RelNotes/2.11.3.txt b/Documentation/RelNotes/2.11.3.adoc
index 4e3b78d0e8..4e3b78d0e8 100644
--- a/Documentation/RelNotes/2.11.3.txt
+++ b/Documentation/RelNotes/2.11.3.adoc
diff --git a/Documentation/RelNotes/2.11.4.txt b/Documentation/RelNotes/2.11.4.adoc
index ad4da8eb09..ad4da8eb09 100644
--- a/Documentation/RelNotes/2.11.4.txt
+++ b/Documentation/RelNotes/2.11.4.adoc
diff --git a/Documentation/RelNotes/2.12.0.txt b/Documentation/RelNotes/2.12.0.adoc
index d2f6a83614..d2f6a83614 100644
--- a/Documentation/RelNotes/2.12.0.txt
+++ b/Documentation/RelNotes/2.12.0.adoc
diff --git a/Documentation/RelNotes/2.12.1.txt b/Documentation/RelNotes/2.12.1.adoc
index a74f7db747..a74f7db747 100644
--- a/Documentation/RelNotes/2.12.1.txt
+++ b/Documentation/RelNotes/2.12.1.adoc
diff --git a/Documentation/RelNotes/2.12.2.txt b/Documentation/RelNotes/2.12.2.adoc
index 441939709c..441939709c 100644
--- a/Documentation/RelNotes/2.12.2.txt
+++ b/Documentation/RelNotes/2.12.2.adoc
diff --git a/Documentation/RelNotes/2.12.3.txt b/Documentation/RelNotes/2.12.3.adoc
index ebca846d5d..ebca846d5d 100644
--- a/Documentation/RelNotes/2.12.3.txt
+++ b/Documentation/RelNotes/2.12.3.adoc
diff --git a/Documentation/RelNotes/2.12.4.txt b/Documentation/RelNotes/2.12.4.adoc
index 3f56938221..3f56938221 100644
--- a/Documentation/RelNotes/2.12.4.txt
+++ b/Documentation/RelNotes/2.12.4.adoc
diff --git a/Documentation/RelNotes/2.12.5.txt b/Documentation/RelNotes/2.12.5.adoc
index 8fa73cfce7..8fa73cfce7 100644
--- a/Documentation/RelNotes/2.12.5.txt
+++ b/Documentation/RelNotes/2.12.5.adoc
diff --git a/Documentation/RelNotes/2.13.0.txt b/Documentation/RelNotes/2.13.0.adoc
index 2a47b4cb0c..2a47b4cb0c 100644
--- a/Documentation/RelNotes/2.13.0.txt
+++ b/Documentation/RelNotes/2.13.0.adoc
diff --git a/Documentation/RelNotes/2.13.1.txt b/Documentation/RelNotes/2.13.1.adoc
index ed7cd976d9..ed7cd976d9 100644
--- a/Documentation/RelNotes/2.13.1.txt
+++ b/Documentation/RelNotes/2.13.1.adoc
diff --git a/Documentation/RelNotes/2.13.2.txt b/Documentation/RelNotes/2.13.2.adoc
index 8c2b20071e..8c2b20071e 100644
--- a/Documentation/RelNotes/2.13.2.txt
+++ b/Documentation/RelNotes/2.13.2.adoc
diff --git a/Documentation/RelNotes/2.13.3.txt b/Documentation/RelNotes/2.13.3.adoc
index 384e4de265..384e4de265 100644
--- a/Documentation/RelNotes/2.13.3.txt
+++ b/Documentation/RelNotes/2.13.3.adoc
diff --git a/Documentation/RelNotes/2.13.4.txt b/Documentation/RelNotes/2.13.4.adoc
index 9a9f8f9599..9a9f8f9599 100644
--- a/Documentation/RelNotes/2.13.4.txt
+++ b/Documentation/RelNotes/2.13.4.adoc
diff --git a/Documentation/RelNotes/2.13.5.txt b/Documentation/RelNotes/2.13.5.adoc
index 6949fcda78..6949fcda78 100644
--- a/Documentation/RelNotes/2.13.5.txt
+++ b/Documentation/RelNotes/2.13.5.adoc
diff --git a/Documentation/RelNotes/2.13.6.txt b/Documentation/RelNotes/2.13.6.adoc
index afcae9c808..afcae9c808 100644
--- a/Documentation/RelNotes/2.13.6.txt
+++ b/Documentation/RelNotes/2.13.6.adoc
diff --git a/Documentation/RelNotes/2.13.7.txt b/Documentation/RelNotes/2.13.7.adoc
index 09fc01406c..09fc01406c 100644
--- a/Documentation/RelNotes/2.13.7.txt
+++ b/Documentation/RelNotes/2.13.7.adoc
diff --git a/Documentation/RelNotes/2.14.0.txt b/Documentation/RelNotes/2.14.0.adoc
index 2711a2529d..2711a2529d 100644
--- a/Documentation/RelNotes/2.14.0.txt
+++ b/Documentation/RelNotes/2.14.0.adoc
diff --git a/Documentation/RelNotes/2.14.1.txt b/Documentation/RelNotes/2.14.1.adoc
index 9403340f7f..9403340f7f 100644
--- a/Documentation/RelNotes/2.14.1.txt
+++ b/Documentation/RelNotes/2.14.1.adoc
diff --git a/Documentation/RelNotes/2.14.2.txt b/Documentation/RelNotes/2.14.2.adoc
index bec9186ade..bec9186ade 100644
--- a/Documentation/RelNotes/2.14.2.txt
+++ b/Documentation/RelNotes/2.14.2.adoc
diff --git a/Documentation/RelNotes/2.14.3.txt b/Documentation/RelNotes/2.14.3.adoc
index 977c9e857c..977c9e857c 100644
--- a/Documentation/RelNotes/2.14.3.txt
+++ b/Documentation/RelNotes/2.14.3.adoc
diff --git a/Documentation/RelNotes/2.14.4.txt b/Documentation/RelNotes/2.14.4.adoc
index 97755a89d9..97755a89d9 100644
--- a/Documentation/RelNotes/2.14.4.txt
+++ b/Documentation/RelNotes/2.14.4.adoc
diff --git a/Documentation/RelNotes/2.14.5.txt b/Documentation/RelNotes/2.14.5.adoc
index 130645fb29..130645fb29 100644
--- a/Documentation/RelNotes/2.14.5.txt
+++ b/Documentation/RelNotes/2.14.5.adoc
diff --git a/Documentation/RelNotes/2.14.6.txt b/Documentation/RelNotes/2.14.6.adoc
index 72b7af6799..72b7af6799 100644
--- a/Documentation/RelNotes/2.14.6.txt
+++ b/Documentation/RelNotes/2.14.6.adoc
diff --git a/Documentation/RelNotes/2.15.0.txt b/Documentation/RelNotes/2.15.0.adoc
index cdd761bcc2..cdd761bcc2 100644
--- a/Documentation/RelNotes/2.15.0.txt
+++ b/Documentation/RelNotes/2.15.0.adoc
diff --git a/Documentation/RelNotes/2.15.1.txt b/Documentation/RelNotes/2.15.1.adoc
index ec06704e63..ec06704e63 100644
--- a/Documentation/RelNotes/2.15.1.txt
+++ b/Documentation/RelNotes/2.15.1.adoc
diff --git a/Documentation/RelNotes/2.15.2.txt b/Documentation/RelNotes/2.15.2.adoc
index b480e56b68..b480e56b68 100644
--- a/Documentation/RelNotes/2.15.2.txt
+++ b/Documentation/RelNotes/2.15.2.adoc
diff --git a/Documentation/RelNotes/2.15.3.txt b/Documentation/RelNotes/2.15.3.adoc
index fd2e6f8df7..fd2e6f8df7 100644
--- a/Documentation/RelNotes/2.15.3.txt
+++ b/Documentation/RelNotes/2.15.3.adoc
diff --git a/Documentation/RelNotes/2.15.4.txt b/Documentation/RelNotes/2.15.4.adoc
index dc241cba34..dc241cba34 100644
--- a/Documentation/RelNotes/2.15.4.txt
+++ b/Documentation/RelNotes/2.15.4.adoc
diff --git a/Documentation/RelNotes/2.16.0.txt b/Documentation/RelNotes/2.16.0.adoc
index b474781ed8..b474781ed8 100644
--- a/Documentation/RelNotes/2.16.0.txt
+++ b/Documentation/RelNotes/2.16.0.adoc
diff --git a/Documentation/RelNotes/2.16.1.txt b/Documentation/RelNotes/2.16.1.adoc
index 66e64361fd..66e64361fd 100644
--- a/Documentation/RelNotes/2.16.1.txt
+++ b/Documentation/RelNotes/2.16.1.adoc
diff --git a/Documentation/RelNotes/2.16.2.txt b/Documentation/RelNotes/2.16.2.adoc
index a216466d3d..a216466d3d 100644
--- a/Documentation/RelNotes/2.16.2.txt
+++ b/Documentation/RelNotes/2.16.2.adoc
diff --git a/Documentation/RelNotes/2.16.3.txt b/Documentation/RelNotes/2.16.3.adoc
index f0121a8f2d..f0121a8f2d 100644
--- a/Documentation/RelNotes/2.16.3.txt
+++ b/Documentation/RelNotes/2.16.3.adoc
diff --git a/Documentation/RelNotes/2.16.4.txt b/Documentation/RelNotes/2.16.4.adoc
index 6be538ba30..6be538ba30 100644
--- a/Documentation/RelNotes/2.16.4.txt
+++ b/Documentation/RelNotes/2.16.4.adoc
diff --git a/Documentation/RelNotes/2.16.5.txt b/Documentation/RelNotes/2.16.5.adoc
index cb8ee02a9a..cb8ee02a9a 100644
--- a/Documentation/RelNotes/2.16.5.txt
+++ b/Documentation/RelNotes/2.16.5.adoc
diff --git a/Documentation/RelNotes/2.16.6.txt b/Documentation/RelNotes/2.16.6.adoc
index 438306e60b..438306e60b 100644
--- a/Documentation/RelNotes/2.16.6.txt
+++ b/Documentation/RelNotes/2.16.6.adoc
diff --git a/Documentation/RelNotes/2.17.0.txt b/Documentation/RelNotes/2.17.0.adoc
index 8b17c26033..8b17c26033 100644
--- a/Documentation/RelNotes/2.17.0.txt
+++ b/Documentation/RelNotes/2.17.0.adoc
diff --git a/Documentation/RelNotes/2.17.1.txt b/Documentation/RelNotes/2.17.1.adoc
index e01384fe8e..e01384fe8e 100644
--- a/Documentation/RelNotes/2.17.1.txt
+++ b/Documentation/RelNotes/2.17.1.adoc
diff --git a/Documentation/RelNotes/2.17.2.txt b/Documentation/RelNotes/2.17.2.adoc
index ef021be870..ef021be870 100644
--- a/Documentation/RelNotes/2.17.2.txt
+++ b/Documentation/RelNotes/2.17.2.adoc
diff --git a/Documentation/RelNotes/2.17.3.txt b/Documentation/RelNotes/2.17.3.adoc
index 5a46c94271..5a46c94271 100644
--- a/Documentation/RelNotes/2.17.3.txt
+++ b/Documentation/RelNotes/2.17.3.adoc
diff --git a/Documentation/RelNotes/2.17.4.txt b/Documentation/RelNotes/2.17.4.adoc
index 7d794ca01a..7d794ca01a 100644
--- a/Documentation/RelNotes/2.17.4.txt
+++ b/Documentation/RelNotes/2.17.4.adoc
diff --git a/Documentation/RelNotes/2.17.5.txt b/Documentation/RelNotes/2.17.5.adoc
index 2abb821a73..2abb821a73 100644
--- a/Documentation/RelNotes/2.17.5.txt
+++ b/Documentation/RelNotes/2.17.5.adoc
diff --git a/Documentation/RelNotes/2.17.6.txt b/Documentation/RelNotes/2.17.6.adoc
index 2f181e8064..2f181e8064 100644
--- a/Documentation/RelNotes/2.17.6.txt
+++ b/Documentation/RelNotes/2.17.6.adoc
diff --git a/Documentation/RelNotes/2.18.0.txt b/Documentation/RelNotes/2.18.0.adoc
index 6c8a0e97c1..6c8a0e97c1 100644
--- a/Documentation/RelNotes/2.18.0.txt
+++ b/Documentation/RelNotes/2.18.0.adoc
diff --git a/Documentation/RelNotes/2.18.1.txt b/Documentation/RelNotes/2.18.1.adoc
index 2098cdd776..2098cdd776 100644
--- a/Documentation/RelNotes/2.18.1.txt
+++ b/Documentation/RelNotes/2.18.1.adoc
diff --git a/Documentation/RelNotes/2.18.2.txt b/Documentation/RelNotes/2.18.2.adoc
index 98b168aade..98b168aade 100644
--- a/Documentation/RelNotes/2.18.2.txt
+++ b/Documentation/RelNotes/2.18.2.adoc
diff --git a/Documentation/RelNotes/2.18.3.txt b/Documentation/RelNotes/2.18.3.adoc
index 25143f0cec..25143f0cec 100644
--- a/Documentation/RelNotes/2.18.3.txt
+++ b/Documentation/RelNotes/2.18.3.adoc
diff --git a/Documentation/RelNotes/2.18.4.txt b/Documentation/RelNotes/2.18.4.adoc
index e8ef858a00..e8ef858a00 100644
--- a/Documentation/RelNotes/2.18.4.txt
+++ b/Documentation/RelNotes/2.18.4.adoc
diff --git a/Documentation/RelNotes/2.18.5.txt b/Documentation/RelNotes/2.18.5.adoc
index dfb1de4ceb..dfb1de4ceb 100644
--- a/Documentation/RelNotes/2.18.5.txt
+++ b/Documentation/RelNotes/2.18.5.adoc
diff --git a/Documentation/RelNotes/2.19.0.txt b/Documentation/RelNotes/2.19.0.adoc
index 891c79b9cb..891c79b9cb 100644
--- a/Documentation/RelNotes/2.19.0.txt
+++ b/Documentation/RelNotes/2.19.0.adoc
diff --git a/Documentation/RelNotes/2.19.1.txt b/Documentation/RelNotes/2.19.1.adoc
index da7672674e..da7672674e 100644
--- a/Documentation/RelNotes/2.19.1.txt
+++ b/Documentation/RelNotes/2.19.1.adoc
diff --git a/Documentation/RelNotes/2.19.2.txt b/Documentation/RelNotes/2.19.2.adoc
index 759e6ca957..759e6ca957 100644
--- a/Documentation/RelNotes/2.19.2.txt
+++ b/Documentation/RelNotes/2.19.2.adoc
diff --git a/Documentation/RelNotes/2.19.3.txt b/Documentation/RelNotes/2.19.3.adoc
index 92d7f89de6..92d7f89de6 100644
--- a/Documentation/RelNotes/2.19.3.txt
+++ b/Documentation/RelNotes/2.19.3.adoc
diff --git a/Documentation/RelNotes/2.19.4.txt b/Documentation/RelNotes/2.19.4.adoc
index 35d0ae561b..35d0ae561b 100644
--- a/Documentation/RelNotes/2.19.4.txt
+++ b/Documentation/RelNotes/2.19.4.adoc
diff --git a/Documentation/RelNotes/2.19.5.txt b/Documentation/RelNotes/2.19.5.adoc
index 18a4dcbfd6..18a4dcbfd6 100644
--- a/Documentation/RelNotes/2.19.5.txt
+++ b/Documentation/RelNotes/2.19.5.adoc
diff --git a/Documentation/RelNotes/2.19.6.txt b/Documentation/RelNotes/2.19.6.adoc
index bcca6cd258..bcca6cd258 100644
--- a/Documentation/RelNotes/2.19.6.txt
+++ b/Documentation/RelNotes/2.19.6.adoc
diff --git a/Documentation/RelNotes/2.2.0.txt b/Documentation/RelNotes/2.2.0.adoc
index e98ecbcff6..e98ecbcff6 100644
--- a/Documentation/RelNotes/2.2.0.txt
+++ b/Documentation/RelNotes/2.2.0.adoc
diff --git a/Documentation/RelNotes/2.2.1.txt b/Documentation/RelNotes/2.2.1.adoc
index d5a3cd9e73..d5a3cd9e73 100644
--- a/Documentation/RelNotes/2.2.1.txt
+++ b/Documentation/RelNotes/2.2.1.adoc
diff --git a/Documentation/RelNotes/2.2.2.txt b/Documentation/RelNotes/2.2.2.adoc
index b19a35d94f..b19a35d94f 100644
--- a/Documentation/RelNotes/2.2.2.txt
+++ b/Documentation/RelNotes/2.2.2.adoc
diff --git a/Documentation/RelNotes/2.2.3.txt b/Documentation/RelNotes/2.2.3.adoc
index 5bfffa4106..5bfffa4106 100644
--- a/Documentation/RelNotes/2.2.3.txt
+++ b/Documentation/RelNotes/2.2.3.adoc
diff --git a/Documentation/RelNotes/2.20.0.txt b/Documentation/RelNotes/2.20.0.adoc
index 3dd7e6e1fc..3dd7e6e1fc 100644
--- a/Documentation/RelNotes/2.20.0.txt
+++ b/Documentation/RelNotes/2.20.0.adoc
diff --git a/Documentation/RelNotes/2.20.1.txt b/Documentation/RelNotes/2.20.1.adoc
index dcba888dba..dcba888dba 100644
--- a/Documentation/RelNotes/2.20.1.txt
+++ b/Documentation/RelNotes/2.20.1.adoc
diff --git a/Documentation/RelNotes/2.20.2.txt b/Documentation/RelNotes/2.20.2.adoc
index 8e680cb9fb..8e680cb9fb 100644
--- a/Documentation/RelNotes/2.20.2.txt
+++ b/Documentation/RelNotes/2.20.2.adoc
diff --git a/Documentation/RelNotes/2.20.3.txt b/Documentation/RelNotes/2.20.3.adoc
index f6eccd103b..f6eccd103b 100644
--- a/Documentation/RelNotes/2.20.3.txt
+++ b/Documentation/RelNotes/2.20.3.adoc
diff --git a/Documentation/RelNotes/2.20.4.txt b/Documentation/RelNotes/2.20.4.adoc
index 5a9e24e470..5a9e24e470 100644
--- a/Documentation/RelNotes/2.20.4.txt
+++ b/Documentation/RelNotes/2.20.4.adoc
diff --git a/Documentation/RelNotes/2.20.5.txt b/Documentation/RelNotes/2.20.5.adoc
index 1dfb784ded..1dfb784ded 100644
--- a/Documentation/RelNotes/2.20.5.txt
+++ b/Documentation/RelNotes/2.20.5.adoc
diff --git a/Documentation/RelNotes/2.21.0.txt b/Documentation/RelNotes/2.21.0.adoc
index 7a49deddf3..7a49deddf3 100644
--- a/Documentation/RelNotes/2.21.0.txt
+++ b/Documentation/RelNotes/2.21.0.adoc
diff --git a/Documentation/RelNotes/2.21.1.txt b/Documentation/RelNotes/2.21.1.adoc
index b7594151e4..b7594151e4 100644
--- a/Documentation/RelNotes/2.21.1.txt
+++ b/Documentation/RelNotes/2.21.1.adoc
diff --git a/Documentation/RelNotes/2.21.2.txt b/Documentation/RelNotes/2.21.2.adoc
index a0fb83bb53..a0fb83bb53 100644
--- a/Documentation/RelNotes/2.21.2.txt
+++ b/Documentation/RelNotes/2.21.2.adoc
diff --git a/Documentation/RelNotes/2.21.3.txt b/Documentation/RelNotes/2.21.3.adoc
index 2ca0aa5c62..2ca0aa5c62 100644
--- a/Documentation/RelNotes/2.21.3.txt
+++ b/Documentation/RelNotes/2.21.3.adoc
diff --git a/Documentation/RelNotes/2.21.4.txt b/Documentation/RelNotes/2.21.4.adoc
index 0089dd6702..0089dd6702 100644
--- a/Documentation/RelNotes/2.21.4.txt
+++ b/Documentation/RelNotes/2.21.4.adoc
diff --git a/Documentation/RelNotes/2.22.0.txt b/Documentation/RelNotes/2.22.0.adoc
index 91e6ae9887..91e6ae9887 100644
--- a/Documentation/RelNotes/2.22.0.txt
+++ b/Documentation/RelNotes/2.22.0.adoc
diff --git a/Documentation/RelNotes/2.22.1.txt b/Documentation/RelNotes/2.22.1.adoc
index 432762f270..432762f270 100644
--- a/Documentation/RelNotes/2.22.1.txt
+++ b/Documentation/RelNotes/2.22.1.adoc
diff --git a/Documentation/RelNotes/2.22.2.txt b/Documentation/RelNotes/2.22.2.adoc
index 940a23f0d9..940a23f0d9 100644
--- a/Documentation/RelNotes/2.22.2.txt
+++ b/Documentation/RelNotes/2.22.2.adoc
diff --git a/Documentation/RelNotes/2.22.3.txt b/Documentation/RelNotes/2.22.3.adoc
index 57296f6d17..57296f6d17 100644
--- a/Documentation/RelNotes/2.22.3.txt
+++ b/Documentation/RelNotes/2.22.3.adoc
diff --git a/Documentation/RelNotes/2.22.4.txt b/Documentation/RelNotes/2.22.4.adoc
index 8b5f3e3f37..8b5f3e3f37 100644
--- a/Documentation/RelNotes/2.22.4.txt
+++ b/Documentation/RelNotes/2.22.4.adoc
diff --git a/Documentation/RelNotes/2.22.5.txt b/Documentation/RelNotes/2.22.5.adoc
index 6b280d9321..6b280d9321 100644
--- a/Documentation/RelNotes/2.22.5.txt
+++ b/Documentation/RelNotes/2.22.5.adoc
diff --git a/Documentation/RelNotes/2.23.0.txt b/Documentation/RelNotes/2.23.0.adoc
index e3c4e78265..e3c4e78265 100644
--- a/Documentation/RelNotes/2.23.0.txt
+++ b/Documentation/RelNotes/2.23.0.adoc
diff --git a/Documentation/RelNotes/2.23.1.txt b/Documentation/RelNotes/2.23.1.adoc
index 2083b492ce..2083b492ce 100644
--- a/Documentation/RelNotes/2.23.1.txt
+++ b/Documentation/RelNotes/2.23.1.adoc
diff --git a/Documentation/RelNotes/2.23.2.txt b/Documentation/RelNotes/2.23.2.adoc
index b697cbe0e3..b697cbe0e3 100644
--- a/Documentation/RelNotes/2.23.2.txt
+++ b/Documentation/RelNotes/2.23.2.adoc
diff --git a/Documentation/RelNotes/2.23.3.txt b/Documentation/RelNotes/2.23.3.adoc
index 2e35490137..2e35490137 100644
--- a/Documentation/RelNotes/2.23.3.txt
+++ b/Documentation/RelNotes/2.23.3.adoc
diff --git a/Documentation/RelNotes/2.23.4.txt b/Documentation/RelNotes/2.23.4.adoc
index 6e5424d0da..6e5424d0da 100644
--- a/Documentation/RelNotes/2.23.4.txt
+++ b/Documentation/RelNotes/2.23.4.adoc
diff --git a/Documentation/RelNotes/2.24.0.txt b/Documentation/RelNotes/2.24.0.adoc
index bde154124c..bde154124c 100644
--- a/Documentation/RelNotes/2.24.0.txt
+++ b/Documentation/RelNotes/2.24.0.adoc
diff --git a/Documentation/RelNotes/2.24.1.txt b/Documentation/RelNotes/2.24.1.adoc
index 18104850fe..18104850fe 100644
--- a/Documentation/RelNotes/2.24.1.txt
+++ b/Documentation/RelNotes/2.24.1.adoc
diff --git a/Documentation/RelNotes/2.24.2.txt b/Documentation/RelNotes/2.24.2.adoc
index 0049f65503..0049f65503 100644
--- a/Documentation/RelNotes/2.24.2.txt
+++ b/Documentation/RelNotes/2.24.2.adoc
diff --git a/Documentation/RelNotes/2.24.3.txt b/Documentation/RelNotes/2.24.3.adoc
index 5302e0f73b..5302e0f73b 100644
--- a/Documentation/RelNotes/2.24.3.txt
+++ b/Documentation/RelNotes/2.24.3.adoc
diff --git a/Documentation/RelNotes/2.24.4.txt b/Documentation/RelNotes/2.24.4.adoc
index 4e216eec2a..4e216eec2a 100644
--- a/Documentation/RelNotes/2.24.4.txt
+++ b/Documentation/RelNotes/2.24.4.adoc
diff --git a/Documentation/RelNotes/2.25.0.txt b/Documentation/RelNotes/2.25.0.adoc
index 91ceb34927..91ceb34927 100644
--- a/Documentation/RelNotes/2.25.0.txt
+++ b/Documentation/RelNotes/2.25.0.adoc
diff --git a/Documentation/RelNotes/2.25.1.txt b/Documentation/RelNotes/2.25.1.adoc
index cd869b02bb..cd869b02bb 100644
--- a/Documentation/RelNotes/2.25.1.txt
+++ b/Documentation/RelNotes/2.25.1.adoc
diff --git a/Documentation/RelNotes/2.25.2.txt b/Documentation/RelNotes/2.25.2.adoc
index 303c53a17f..303c53a17f 100644
--- a/Documentation/RelNotes/2.25.2.txt
+++ b/Documentation/RelNotes/2.25.2.adoc
diff --git a/Documentation/RelNotes/2.25.3.txt b/Documentation/RelNotes/2.25.3.adoc
index 15f7f21f10..15f7f21f10 100644
--- a/Documentation/RelNotes/2.25.3.txt
+++ b/Documentation/RelNotes/2.25.3.adoc
diff --git a/Documentation/RelNotes/2.25.4.txt b/Documentation/RelNotes/2.25.4.adoc
index 0dbb5daeec..0dbb5daeec 100644
--- a/Documentation/RelNotes/2.25.4.txt
+++ b/Documentation/RelNotes/2.25.4.adoc
diff --git a/Documentation/RelNotes/2.25.5.txt b/Documentation/RelNotes/2.25.5.adoc
index fcb9566b15..fcb9566b15 100644
--- a/Documentation/RelNotes/2.25.5.txt
+++ b/Documentation/RelNotes/2.25.5.adoc
diff --git a/Documentation/RelNotes/2.26.0.txt b/Documentation/RelNotes/2.26.0.adoc
index 3a7a734c26..3a7a734c26 100644
--- a/Documentation/RelNotes/2.26.0.txt
+++ b/Documentation/RelNotes/2.26.0.adoc
diff --git a/Documentation/RelNotes/2.26.1.txt b/Documentation/RelNotes/2.26.1.adoc
index 1b4ecb3fdc..1b4ecb3fdc 100644
--- a/Documentation/RelNotes/2.26.1.txt
+++ b/Documentation/RelNotes/2.26.1.adoc
diff --git a/Documentation/RelNotes/2.26.2.txt b/Documentation/RelNotes/2.26.2.adoc
index d434d0c695..d434d0c695 100644
--- a/Documentation/RelNotes/2.26.2.txt
+++ b/Documentation/RelNotes/2.26.2.adoc
diff --git a/Documentation/RelNotes/2.26.3.txt b/Documentation/RelNotes/2.26.3.adoc
index 4111c38f0a..4111c38f0a 100644
--- a/Documentation/RelNotes/2.26.3.txt
+++ b/Documentation/RelNotes/2.26.3.adoc
diff --git a/Documentation/RelNotes/2.27.0.txt b/Documentation/RelNotes/2.27.0.adoc
index 15518d06c1..15518d06c1 100644
--- a/Documentation/RelNotes/2.27.0.txt
+++ b/Documentation/RelNotes/2.27.0.adoc
diff --git a/Documentation/RelNotes/2.27.1.txt b/Documentation/RelNotes/2.27.1.adoc
index a1e08a9f72..a1e08a9f72 100644
--- a/Documentation/RelNotes/2.27.1.txt
+++ b/Documentation/RelNotes/2.27.1.adoc
diff --git a/Documentation/RelNotes/2.28.0.txt b/Documentation/RelNotes/2.28.0.adoc
index 6baf781380..6baf781380 100644
--- a/Documentation/RelNotes/2.28.0.txt
+++ b/Documentation/RelNotes/2.28.0.adoc
diff --git a/Documentation/RelNotes/2.28.1.txt b/Documentation/RelNotes/2.28.1.adoc
index 8484c8297c..8484c8297c 100644
--- a/Documentation/RelNotes/2.28.1.txt
+++ b/Documentation/RelNotes/2.28.1.adoc
diff --git a/Documentation/RelNotes/2.29.0.txt b/Documentation/RelNotes/2.29.0.adoc
index 1f41302ebb..1f41302ebb 100644
--- a/Documentation/RelNotes/2.29.0.txt
+++ b/Documentation/RelNotes/2.29.0.adoc
diff --git a/Documentation/RelNotes/2.29.1.txt b/Documentation/RelNotes/2.29.1.adoc
index 295ee2135f..295ee2135f 100644
--- a/Documentation/RelNotes/2.29.1.txt
+++ b/Documentation/RelNotes/2.29.1.adoc
diff --git a/Documentation/RelNotes/2.29.2.txt b/Documentation/RelNotes/2.29.2.adoc
index 632b5b580a..632b5b580a 100644
--- a/Documentation/RelNotes/2.29.2.txt
+++ b/Documentation/RelNotes/2.29.2.adoc
diff --git a/Documentation/RelNotes/2.29.3.txt b/Documentation/RelNotes/2.29.3.adoc
index e10eedb35a..e10eedb35a 100644
--- a/Documentation/RelNotes/2.29.3.txt
+++ b/Documentation/RelNotes/2.29.3.adoc
diff --git a/Documentation/RelNotes/2.3.0.txt b/Documentation/RelNotes/2.3.0.adoc
index e3c639c840..e3c639c840 100644
--- a/Documentation/RelNotes/2.3.0.txt
+++ b/Documentation/RelNotes/2.3.0.adoc
diff --git a/Documentation/RelNotes/2.3.1.txt b/Documentation/RelNotes/2.3.1.adoc
index cf96186288..cf96186288 100644
--- a/Documentation/RelNotes/2.3.1.txt
+++ b/Documentation/RelNotes/2.3.1.adoc
diff --git a/Documentation/RelNotes/2.3.10.txt b/Documentation/RelNotes/2.3.10.adoc
index 20c2d2cacc..20c2d2cacc 100644
--- a/Documentation/RelNotes/2.3.10.txt
+++ b/Documentation/RelNotes/2.3.10.adoc
diff --git a/Documentation/RelNotes/2.3.2.txt b/Documentation/RelNotes/2.3.2.adoc
index 93462e45c2..93462e45c2 100644
--- a/Documentation/RelNotes/2.3.2.txt
+++ b/Documentation/RelNotes/2.3.2.adoc
diff --git a/Documentation/RelNotes/2.3.3.txt b/Documentation/RelNotes/2.3.3.adoc
index 850dc68ede..850dc68ede 100644
--- a/Documentation/RelNotes/2.3.3.txt
+++ b/Documentation/RelNotes/2.3.3.adoc
diff --git a/Documentation/RelNotes/2.3.4.txt b/Documentation/RelNotes/2.3.4.adoc
index 094c7b853b..094c7b853b 100644
--- a/Documentation/RelNotes/2.3.4.txt
+++ b/Documentation/RelNotes/2.3.4.adoc
diff --git a/Documentation/RelNotes/2.3.5.txt b/Documentation/RelNotes/2.3.5.adoc
index 5b309db689..5b309db689 100644
--- a/Documentation/RelNotes/2.3.5.txt
+++ b/Documentation/RelNotes/2.3.5.adoc
diff --git a/Documentation/RelNotes/2.3.6.txt b/Documentation/RelNotes/2.3.6.adoc
index 432f770ef3..432f770ef3 100644
--- a/Documentation/RelNotes/2.3.6.txt
+++ b/Documentation/RelNotes/2.3.6.adoc
diff --git a/Documentation/RelNotes/2.3.7.txt b/Documentation/RelNotes/2.3.7.adoc
index 5769184081..5769184081 100644
--- a/Documentation/RelNotes/2.3.7.txt
+++ b/Documentation/RelNotes/2.3.7.adoc
diff --git a/Documentation/RelNotes/2.3.8.txt b/Documentation/RelNotes/2.3.8.adoc
index 0b67268a96..0b67268a96 100644
--- a/Documentation/RelNotes/2.3.8.txt
+++ b/Documentation/RelNotes/2.3.8.adoc
diff --git a/Documentation/RelNotes/2.3.9.txt b/Documentation/RelNotes/2.3.9.adoc
index 1a2ad3235a..1a2ad3235a 100644
--- a/Documentation/RelNotes/2.3.9.txt
+++ b/Documentation/RelNotes/2.3.9.adoc
diff --git a/Documentation/RelNotes/2.30.0.txt b/Documentation/RelNotes/2.30.0.adoc
index c2f1dc7b06..c2f1dc7b06 100644
--- a/Documentation/RelNotes/2.30.0.txt
+++ b/Documentation/RelNotes/2.30.0.adoc
diff --git a/Documentation/RelNotes/2.30.1.txt b/Documentation/RelNotes/2.30.1.adoc
index 249ef1492f..249ef1492f 100644
--- a/Documentation/RelNotes/2.30.1.txt
+++ b/Documentation/RelNotes/2.30.1.adoc
diff --git a/Documentation/RelNotes/2.30.2.txt b/Documentation/RelNotes/2.30.2.adoc
index bada398501..bada398501 100644
--- a/Documentation/RelNotes/2.30.2.txt
+++ b/Documentation/RelNotes/2.30.2.adoc
diff --git a/Documentation/RelNotes/2.30.3.txt b/Documentation/RelNotes/2.30.3.adoc
index 31b2a4daa6..31b2a4daa6 100644
--- a/Documentation/RelNotes/2.30.3.txt
+++ b/Documentation/RelNotes/2.30.3.adoc
diff --git a/Documentation/RelNotes/2.30.4.txt b/Documentation/RelNotes/2.30.4.adoc
index 4eedb74b16..4eedb74b16 100644
--- a/Documentation/RelNotes/2.30.4.txt
+++ b/Documentation/RelNotes/2.30.4.adoc
diff --git a/Documentation/RelNotes/2.30.5.txt b/Documentation/RelNotes/2.30.5.adoc
index 5191cab3ae..5191cab3ae 100644
--- a/Documentation/RelNotes/2.30.5.txt
+++ b/Documentation/RelNotes/2.30.5.adoc
diff --git a/Documentation/RelNotes/2.30.6.txt b/Documentation/RelNotes/2.30.6.adoc
index d649071b79..d649071b79 100644
--- a/Documentation/RelNotes/2.30.6.txt
+++ b/Documentation/RelNotes/2.30.6.adoc
diff --git a/Documentation/RelNotes/2.30.7.txt b/Documentation/RelNotes/2.30.7.adoc
index 285beed232..285beed232 100644
--- a/Documentation/RelNotes/2.30.7.txt
+++ b/Documentation/RelNotes/2.30.7.adoc
diff --git a/Documentation/RelNotes/2.30.8.txt b/Documentation/RelNotes/2.30.8.adoc
index 5ed3efbd6a..5ed3efbd6a 100644
--- a/Documentation/RelNotes/2.30.8.txt
+++ b/Documentation/RelNotes/2.30.8.adoc
diff --git a/Documentation/RelNotes/2.30.9.txt b/Documentation/RelNotes/2.30.9.adoc
index 708d626ce6..708d626ce6 100644
--- a/Documentation/RelNotes/2.30.9.txt
+++ b/Documentation/RelNotes/2.30.9.adoc
diff --git a/Documentation/RelNotes/2.31.0.txt b/Documentation/RelNotes/2.31.0.adoc
index cf0c7d8d40..cf0c7d8d40 100644
--- a/Documentation/RelNotes/2.31.0.txt
+++ b/Documentation/RelNotes/2.31.0.adoc
diff --git a/Documentation/RelNotes/2.31.1.txt b/Documentation/RelNotes/2.31.1.adoc
index f9b06b8e1b..f9b06b8e1b 100644
--- a/Documentation/RelNotes/2.31.1.txt
+++ b/Documentation/RelNotes/2.31.1.adoc
diff --git a/Documentation/RelNotes/2.31.2.txt b/Documentation/RelNotes/2.31.2.adoc
index aa13a5b022..aa13a5b022 100644
--- a/Documentation/RelNotes/2.31.2.txt
+++ b/Documentation/RelNotes/2.31.2.adoc
diff --git a/Documentation/RelNotes/2.31.3.txt b/Documentation/RelNotes/2.31.3.adoc
index ca143abad0..ca143abad0 100644
--- a/Documentation/RelNotes/2.31.3.txt
+++ b/Documentation/RelNotes/2.31.3.adoc
diff --git a/Documentation/RelNotes/2.31.4.txt b/Documentation/RelNotes/2.31.4.adoc
index 97a91fd07a..97a91fd07a 100644
--- a/Documentation/RelNotes/2.31.4.txt
+++ b/Documentation/RelNotes/2.31.4.adoc
diff --git a/Documentation/RelNotes/2.31.5.txt b/Documentation/RelNotes/2.31.5.adoc
index 0d87e6e03f..0d87e6e03f 100644
--- a/Documentation/RelNotes/2.31.5.txt
+++ b/Documentation/RelNotes/2.31.5.adoc
diff --git a/Documentation/RelNotes/2.31.6.txt b/Documentation/RelNotes/2.31.6.adoc
index 425a51875a..425a51875a 100644
--- a/Documentation/RelNotes/2.31.6.txt
+++ b/Documentation/RelNotes/2.31.6.adoc
diff --git a/Documentation/RelNotes/2.31.7.txt b/Documentation/RelNotes/2.31.7.adoc
index dd44d5bc62..dd44d5bc62 100644
--- a/Documentation/RelNotes/2.31.7.txt
+++ b/Documentation/RelNotes/2.31.7.adoc
diff --git a/Documentation/RelNotes/2.31.8.txt b/Documentation/RelNotes/2.31.8.adoc
index 0aa3080780..0aa3080780 100644
--- a/Documentation/RelNotes/2.31.8.txt
+++ b/Documentation/RelNotes/2.31.8.adoc
diff --git a/Documentation/RelNotes/2.32.0.txt b/Documentation/RelNotes/2.32.0.adoc
index 87d56fa1aa..87d56fa1aa 100644
--- a/Documentation/RelNotes/2.32.0.txt
+++ b/Documentation/RelNotes/2.32.0.adoc
diff --git a/Documentation/RelNotes/2.32.1.txt b/Documentation/RelNotes/2.32.1.adoc
index 7dcca13b92..7dcca13b92 100644
--- a/Documentation/RelNotes/2.32.1.txt
+++ b/Documentation/RelNotes/2.32.1.adoc
diff --git a/Documentation/RelNotes/2.32.2.txt b/Documentation/RelNotes/2.32.2.adoc
index cf49695f2f..cf49695f2f 100644
--- a/Documentation/RelNotes/2.32.2.txt
+++ b/Documentation/RelNotes/2.32.2.adoc
diff --git a/Documentation/RelNotes/2.32.3.txt b/Documentation/RelNotes/2.32.3.adoc
index 583fabe684..583fabe684 100644
--- a/Documentation/RelNotes/2.32.3.txt
+++ b/Documentation/RelNotes/2.32.3.adoc
diff --git a/Documentation/RelNotes/2.32.4.txt b/Documentation/RelNotes/2.32.4.adoc
index 76c67b209e..76c67b209e 100644
--- a/Documentation/RelNotes/2.32.4.txt
+++ b/Documentation/RelNotes/2.32.4.adoc
diff --git a/Documentation/RelNotes/2.32.5.txt b/Documentation/RelNotes/2.32.5.adoc
index a8cad1a05b..a8cad1a05b 100644
--- a/Documentation/RelNotes/2.32.5.txt
+++ b/Documentation/RelNotes/2.32.5.adoc
diff --git a/Documentation/RelNotes/2.32.6.txt b/Documentation/RelNotes/2.32.6.adoc
index fd659612e3..fd659612e3 100644
--- a/Documentation/RelNotes/2.32.6.txt
+++ b/Documentation/RelNotes/2.32.6.adoc
diff --git a/Documentation/RelNotes/2.32.7.txt b/Documentation/RelNotes/2.32.7.adoc
index 7bb35388b5..7bb35388b5 100644
--- a/Documentation/RelNotes/2.32.7.txt
+++ b/Documentation/RelNotes/2.32.7.adoc
diff --git a/Documentation/RelNotes/2.33.0.txt b/Documentation/RelNotes/2.33.0.adoc
index 893c18bfdd..893c18bfdd 100644
--- a/Documentation/RelNotes/2.33.0.txt
+++ b/Documentation/RelNotes/2.33.0.adoc
diff --git a/Documentation/RelNotes/2.33.1.txt b/Documentation/RelNotes/2.33.1.adoc
index b71738e654..b71738e654 100644
--- a/Documentation/RelNotes/2.33.1.txt
+++ b/Documentation/RelNotes/2.33.1.adoc
diff --git a/Documentation/RelNotes/2.33.2.txt b/Documentation/RelNotes/2.33.2.adoc
index e504489d61..e504489d61 100644
--- a/Documentation/RelNotes/2.33.2.txt
+++ b/Documentation/RelNotes/2.33.2.adoc
diff --git a/Documentation/RelNotes/2.33.3.txt b/Documentation/RelNotes/2.33.3.adoc
index e2bada12a1..e2bada12a1 100644
--- a/Documentation/RelNotes/2.33.3.txt
+++ b/Documentation/RelNotes/2.33.3.adoc
diff --git a/Documentation/RelNotes/2.33.4.txt b/Documentation/RelNotes/2.33.4.adoc
index a145cc25de..a145cc25de 100644
--- a/Documentation/RelNotes/2.33.4.txt
+++ b/Documentation/RelNotes/2.33.4.adoc
diff --git a/Documentation/RelNotes/2.33.5.txt b/Documentation/RelNotes/2.33.5.adoc
index a63652602b..a63652602b 100644
--- a/Documentation/RelNotes/2.33.5.txt
+++ b/Documentation/RelNotes/2.33.5.adoc
diff --git a/Documentation/RelNotes/2.33.6.txt b/Documentation/RelNotes/2.33.6.adoc
index b63e4e6256..b63e4e6256 100644
--- a/Documentation/RelNotes/2.33.6.txt
+++ b/Documentation/RelNotes/2.33.6.adoc
diff --git a/Documentation/RelNotes/2.33.7.txt b/Documentation/RelNotes/2.33.7.adoc
index 078a837cb4..078a837cb4 100644
--- a/Documentation/RelNotes/2.33.7.txt
+++ b/Documentation/RelNotes/2.33.7.adoc
diff --git a/Documentation/RelNotes/2.33.8.txt b/Documentation/RelNotes/2.33.8.adoc
index d8cf4c7f3a..d8cf4c7f3a 100644
--- a/Documentation/RelNotes/2.33.8.txt
+++ b/Documentation/RelNotes/2.33.8.adoc
diff --git a/Documentation/RelNotes/2.34.0.txt b/Documentation/RelNotes/2.34.0.adoc
index 75d4fdfde7..75d4fdfde7 100644
--- a/Documentation/RelNotes/2.34.0.txt
+++ b/Documentation/RelNotes/2.34.0.adoc
diff --git a/Documentation/RelNotes/2.34.1.txt b/Documentation/RelNotes/2.34.1.adoc
index ad404e9aa0..ad404e9aa0 100644
--- a/Documentation/RelNotes/2.34.1.txt
+++ b/Documentation/RelNotes/2.34.1.adoc
diff --git a/Documentation/RelNotes/2.34.2.txt b/Documentation/RelNotes/2.34.2.adoc
index 0c32cd844b..0c32cd844b 100644
--- a/Documentation/RelNotes/2.34.2.txt
+++ b/Documentation/RelNotes/2.34.2.adoc
diff --git a/Documentation/RelNotes/2.34.3.txt b/Documentation/RelNotes/2.34.3.adoc
index 10f6171ace..10f6171ace 100644
--- a/Documentation/RelNotes/2.34.3.txt
+++ b/Documentation/RelNotes/2.34.3.adoc
diff --git a/Documentation/RelNotes/2.34.4.txt b/Documentation/RelNotes/2.34.4.adoc
index 2a6b223403..2a6b223403 100644
--- a/Documentation/RelNotes/2.34.4.txt
+++ b/Documentation/RelNotes/2.34.4.adoc
diff --git a/Documentation/RelNotes/2.34.5.txt b/Documentation/RelNotes/2.34.5.adoc
index 0e8999204d..0e8999204d 100644
--- a/Documentation/RelNotes/2.34.5.txt
+++ b/Documentation/RelNotes/2.34.5.adoc
diff --git a/Documentation/RelNotes/2.34.6.txt b/Documentation/RelNotes/2.34.6.adoc
index b32080dba8..b32080dba8 100644
--- a/Documentation/RelNotes/2.34.6.txt
+++ b/Documentation/RelNotes/2.34.6.adoc
diff --git a/Documentation/RelNotes/2.34.7.txt b/Documentation/RelNotes/2.34.7.adoc
index 88898adacc..88898adacc 100644
--- a/Documentation/RelNotes/2.34.7.txt
+++ b/Documentation/RelNotes/2.34.7.adoc
diff --git a/Documentation/RelNotes/2.34.8.txt b/Documentation/RelNotes/2.34.8.adoc
index 2b5bd7d9a3..2b5bd7d9a3 100644
--- a/Documentation/RelNotes/2.34.8.txt
+++ b/Documentation/RelNotes/2.34.8.adoc
diff --git a/Documentation/RelNotes/2.35.0.txt b/Documentation/RelNotes/2.35.0.adoc
index d69b50d180..d69b50d180 100644
--- a/Documentation/RelNotes/2.35.0.txt
+++ b/Documentation/RelNotes/2.35.0.adoc
diff --git a/Documentation/RelNotes/2.35.1.txt b/Documentation/RelNotes/2.35.1.adoc
index 726ba250ef..726ba250ef 100644
--- a/Documentation/RelNotes/2.35.1.txt
+++ b/Documentation/RelNotes/2.35.1.adoc
diff --git a/Documentation/RelNotes/2.35.2.txt b/Documentation/RelNotes/2.35.2.adoc
index 290bfa9ea4..290bfa9ea4 100644
--- a/Documentation/RelNotes/2.35.2.txt
+++ b/Documentation/RelNotes/2.35.2.adoc
diff --git a/Documentation/RelNotes/2.35.3.txt b/Documentation/RelNotes/2.35.3.adoc
index 5458ba3441..5458ba3441 100644
--- a/Documentation/RelNotes/2.35.3.txt
+++ b/Documentation/RelNotes/2.35.3.adoc
diff --git a/Documentation/RelNotes/2.35.4.txt b/Documentation/RelNotes/2.35.4.adoc
index 47abd5ad45..47abd5ad45 100644
--- a/Documentation/RelNotes/2.35.4.txt
+++ b/Documentation/RelNotes/2.35.4.adoc
diff --git a/Documentation/RelNotes/2.35.5.txt b/Documentation/RelNotes/2.35.5.adoc
index e19cc48b33..e19cc48b33 100644
--- a/Documentation/RelNotes/2.35.5.txt
+++ b/Documentation/RelNotes/2.35.5.adoc
diff --git a/Documentation/RelNotes/2.35.6.txt b/Documentation/RelNotes/2.35.6.adoc
index e7ca57bb41..e7ca57bb41 100644
--- a/Documentation/RelNotes/2.35.6.txt
+++ b/Documentation/RelNotes/2.35.6.adoc
diff --git a/Documentation/RelNotes/2.35.7.txt b/Documentation/RelNotes/2.35.7.adoc
index 42baabfc3b..42baabfc3b 100644
--- a/Documentation/RelNotes/2.35.7.txt
+++ b/Documentation/RelNotes/2.35.7.adoc
diff --git a/Documentation/RelNotes/2.35.8.txt b/Documentation/RelNotes/2.35.8.adoc
index 3c9c094c2b..3c9c094c2b 100644
--- a/Documentation/RelNotes/2.35.8.txt
+++ b/Documentation/RelNotes/2.35.8.adoc
diff --git a/Documentation/RelNotes/2.36.0.txt b/Documentation/RelNotes/2.36.0.adoc
index e477fba12d..e477fba12d 100644
--- a/Documentation/RelNotes/2.36.0.txt
+++ b/Documentation/RelNotes/2.36.0.adoc
diff --git a/Documentation/RelNotes/2.36.1.txt b/Documentation/RelNotes/2.36.1.adoc
index a9617095db..a9617095db 100644
--- a/Documentation/RelNotes/2.36.1.txt
+++ b/Documentation/RelNotes/2.36.1.adoc
diff --git a/Documentation/RelNotes/2.36.2.txt b/Documentation/RelNotes/2.36.2.adoc
index 958f5b4102..958f5b4102 100644
--- a/Documentation/RelNotes/2.36.2.txt
+++ b/Documentation/RelNotes/2.36.2.adoc
diff --git a/Documentation/RelNotes/2.36.3.txt b/Documentation/RelNotes/2.36.3.adoc
index 56db77b5bd..56db77b5bd 100644
--- a/Documentation/RelNotes/2.36.3.txt
+++ b/Documentation/RelNotes/2.36.3.adoc
diff --git a/Documentation/RelNotes/2.36.4.txt b/Documentation/RelNotes/2.36.4.adoc
index 58fb93a35f..58fb93a35f 100644
--- a/Documentation/RelNotes/2.36.4.txt
+++ b/Documentation/RelNotes/2.36.4.adoc
diff --git a/Documentation/RelNotes/2.36.5.txt b/Documentation/RelNotes/2.36.5.adoc
index 8a098c7916..8a098c7916 100644
--- a/Documentation/RelNotes/2.36.5.txt
+++ b/Documentation/RelNotes/2.36.5.adoc
diff --git a/Documentation/RelNotes/2.36.6.txt b/Documentation/RelNotes/2.36.6.adoc
index e1edebcc43..e1edebcc43 100644
--- a/Documentation/RelNotes/2.36.6.txt
+++ b/Documentation/RelNotes/2.36.6.adoc
diff --git a/Documentation/RelNotes/2.37.0.txt b/Documentation/RelNotes/2.37.0.adoc
index 99dc7e32f8..99dc7e32f8 100644
--- a/Documentation/RelNotes/2.37.0.txt
+++ b/Documentation/RelNotes/2.37.0.adoc
diff --git a/Documentation/RelNotes/2.37.1.txt b/Documentation/RelNotes/2.37.1.adoc
index 84609327d1..84609327d1 100644
--- a/Documentation/RelNotes/2.37.1.txt
+++ b/Documentation/RelNotes/2.37.1.adoc
diff --git a/Documentation/RelNotes/2.37.2.txt b/Documentation/RelNotes/2.37.2.adoc
index d82b29e014..d82b29e014 100644
--- a/Documentation/RelNotes/2.37.2.txt
+++ b/Documentation/RelNotes/2.37.2.adoc
diff --git a/Documentation/RelNotes/2.37.3.txt b/Documentation/RelNotes/2.37.3.adoc
index d66689e598..d66689e598 100644
--- a/Documentation/RelNotes/2.37.3.txt
+++ b/Documentation/RelNotes/2.37.3.adoc
diff --git a/Documentation/RelNotes/2.37.4.txt b/Documentation/RelNotes/2.37.4.adoc
index e42a5c1620..e42a5c1620 100644
--- a/Documentation/RelNotes/2.37.4.txt
+++ b/Documentation/RelNotes/2.37.4.adoc
diff --git a/Documentation/RelNotes/2.37.5.txt b/Documentation/RelNotes/2.37.5.adoc
index faa1447292..faa1447292 100644
--- a/Documentation/RelNotes/2.37.5.txt
+++ b/Documentation/RelNotes/2.37.5.adoc
diff --git a/Documentation/RelNotes/2.37.6.txt b/Documentation/RelNotes/2.37.6.adoc
index 51dc149711..51dc149711 100644
--- a/Documentation/RelNotes/2.37.6.txt
+++ b/Documentation/RelNotes/2.37.6.adoc
diff --git a/Documentation/RelNotes/2.37.7.txt b/Documentation/RelNotes/2.37.7.adoc
index 4b8165f4b5..4b8165f4b5 100644
--- a/Documentation/RelNotes/2.37.7.txt
+++ b/Documentation/RelNotes/2.37.7.adoc
diff --git a/Documentation/RelNotes/2.38.0.txt b/Documentation/RelNotes/2.38.0.adoc
index 870581fc57..870581fc57 100644
--- a/Documentation/RelNotes/2.38.0.txt
+++ b/Documentation/RelNotes/2.38.0.adoc
diff --git a/Documentation/RelNotes/2.38.1.txt b/Documentation/RelNotes/2.38.1.adoc
index b2b5854aac..b2b5854aac 100644
--- a/Documentation/RelNotes/2.38.1.txt
+++ b/Documentation/RelNotes/2.38.1.adoc
diff --git a/Documentation/RelNotes/2.38.2.txt b/Documentation/RelNotes/2.38.2.adoc
index 92acb62bbb..92acb62bbb 100644
--- a/Documentation/RelNotes/2.38.2.txt
+++ b/Documentation/RelNotes/2.38.2.adoc
diff --git a/Documentation/RelNotes/2.38.3.txt b/Documentation/RelNotes/2.38.3.adoc
index 4a46bb4300..4a46bb4300 100644
--- a/Documentation/RelNotes/2.38.3.txt
+++ b/Documentation/RelNotes/2.38.3.adoc
diff --git a/Documentation/RelNotes/2.38.4.txt b/Documentation/RelNotes/2.38.4.adoc
index fdfde22022..fdfde22022 100644
--- a/Documentation/RelNotes/2.38.4.txt
+++ b/Documentation/RelNotes/2.38.4.adoc
diff --git a/Documentation/RelNotes/2.38.5.txt b/Documentation/RelNotes/2.38.5.adoc
index 2d1f3b1249..2d1f3b1249 100644
--- a/Documentation/RelNotes/2.38.5.txt
+++ b/Documentation/RelNotes/2.38.5.adoc
diff --git a/Documentation/RelNotes/2.39.0.txt b/Documentation/RelNotes/2.39.0.adoc
index 9bf00ece53..9bf00ece53 100644
--- a/Documentation/RelNotes/2.39.0.txt
+++ b/Documentation/RelNotes/2.39.0.adoc
diff --git a/Documentation/RelNotes/2.39.1.txt b/Documentation/RelNotes/2.39.1.adoc
index 60c86f4122..60c86f4122 100644
--- a/Documentation/RelNotes/2.39.1.txt
+++ b/Documentation/RelNotes/2.39.1.adoc
diff --git a/Documentation/RelNotes/2.39.2.txt b/Documentation/RelNotes/2.39.2.adoc
index ebb9900bc5..ebb9900bc5 100644
--- a/Documentation/RelNotes/2.39.2.txt
+++ b/Documentation/RelNotes/2.39.2.adoc
diff --git a/Documentation/RelNotes/2.39.3.txt b/Documentation/RelNotes/2.39.3.adoc
index 66351b65c2..66351b65c2 100644
--- a/Documentation/RelNotes/2.39.3.txt
+++ b/Documentation/RelNotes/2.39.3.adoc
diff --git a/Documentation/RelNotes/2.39.4.txt b/Documentation/RelNotes/2.39.4.adoc
index 7f54521fea..7f54521fea 100644
--- a/Documentation/RelNotes/2.39.4.txt
+++ b/Documentation/RelNotes/2.39.4.adoc
diff --git a/Documentation/RelNotes/2.39.5.txt b/Documentation/RelNotes/2.39.5.adoc
index 97c0185de4..97c0185de4 100644
--- a/Documentation/RelNotes/2.39.5.txt
+++ b/Documentation/RelNotes/2.39.5.adoc
diff --git a/Documentation/RelNotes/2.4.0.txt b/Documentation/RelNotes/2.4.0.adoc
index cde64be535..cde64be535 100644
--- a/Documentation/RelNotes/2.4.0.txt
+++ b/Documentation/RelNotes/2.4.0.adoc
diff --git a/Documentation/RelNotes/2.4.1.txt b/Documentation/RelNotes/2.4.1.adoc
index a65a6c5829..a65a6c5829 100644
--- a/Documentation/RelNotes/2.4.1.txt
+++ b/Documentation/RelNotes/2.4.1.adoc
diff --git a/Documentation/RelNotes/2.4.10.txt b/Documentation/RelNotes/2.4.10.adoc
index 702d8d4e22..702d8d4e22 100644
--- a/Documentation/RelNotes/2.4.10.txt
+++ b/Documentation/RelNotes/2.4.10.adoc
diff --git a/Documentation/RelNotes/2.4.11.txt b/Documentation/RelNotes/2.4.11.adoc
index 723360295c..723360295c 100644
--- a/Documentation/RelNotes/2.4.11.txt
+++ b/Documentation/RelNotes/2.4.11.adoc
diff --git a/Documentation/RelNotes/2.4.12.txt b/Documentation/RelNotes/2.4.12.adoc
index 7d15f94725..7d15f94725 100644
--- a/Documentation/RelNotes/2.4.12.txt
+++ b/Documentation/RelNotes/2.4.12.adoc
diff --git a/Documentation/RelNotes/2.4.2.txt b/Documentation/RelNotes/2.4.2.adoc
index 250cdc423c..250cdc423c 100644
--- a/Documentation/RelNotes/2.4.2.txt
+++ b/Documentation/RelNotes/2.4.2.adoc
diff --git a/Documentation/RelNotes/2.4.3.txt b/Documentation/RelNotes/2.4.3.adoc
index 422e930aa2..422e930aa2 100644
--- a/Documentation/RelNotes/2.4.3.txt
+++ b/Documentation/RelNotes/2.4.3.adoc
diff --git a/Documentation/RelNotes/2.4.4.txt b/Documentation/RelNotes/2.4.4.adoc
index f1ccd001be..f1ccd001be 100644
--- a/Documentation/RelNotes/2.4.4.txt
+++ b/Documentation/RelNotes/2.4.4.adoc
diff --git a/Documentation/RelNotes/2.4.5.txt b/Documentation/RelNotes/2.4.5.adoc
index 568297ccb7..568297ccb7 100644
--- a/Documentation/RelNotes/2.4.5.txt
+++ b/Documentation/RelNotes/2.4.5.adoc
diff --git a/Documentation/RelNotes/2.4.6.txt b/Documentation/RelNotes/2.4.6.adoc
index b53f353939..b53f353939 100644
--- a/Documentation/RelNotes/2.4.6.txt
+++ b/Documentation/RelNotes/2.4.6.adoc
diff --git a/Documentation/RelNotes/2.4.7.txt b/Documentation/RelNotes/2.4.7.adoc
index b3ac412b82..b3ac412b82 100644
--- a/Documentation/RelNotes/2.4.7.txt
+++ b/Documentation/RelNotes/2.4.7.adoc
diff --git a/Documentation/RelNotes/2.4.8.txt b/Documentation/RelNotes/2.4.8.adoc
index ad946b2673..ad946b2673 100644
--- a/Documentation/RelNotes/2.4.8.txt
+++ b/Documentation/RelNotes/2.4.8.adoc
diff --git a/Documentation/RelNotes/2.4.9.txt b/Documentation/RelNotes/2.4.9.adoc
index 09af9ddbc7..09af9ddbc7 100644
--- a/Documentation/RelNotes/2.4.9.txt
+++ b/Documentation/RelNotes/2.4.9.adoc
diff --git a/Documentation/RelNotes/2.40.0.txt b/Documentation/RelNotes/2.40.0.adoc
index 3ea445bf20..3ea445bf20 100644
--- a/Documentation/RelNotes/2.40.0.txt
+++ b/Documentation/RelNotes/2.40.0.adoc
diff --git a/Documentation/RelNotes/2.40.1.txt b/Documentation/RelNotes/2.40.1.adoc
index e72f6b1b25..e72f6b1b25 100644
--- a/Documentation/RelNotes/2.40.1.txt
+++ b/Documentation/RelNotes/2.40.1.adoc
diff --git a/Documentation/RelNotes/2.40.2.txt b/Documentation/RelNotes/2.40.2.adoc
index 646a2cc3eb..646a2cc3eb 100644
--- a/Documentation/RelNotes/2.40.2.txt
+++ b/Documentation/RelNotes/2.40.2.adoc
diff --git a/Documentation/RelNotes/2.40.3.txt b/Documentation/RelNotes/2.40.3.adoc
index 6ca088ec86..6ca088ec86 100644
--- a/Documentation/RelNotes/2.40.3.txt
+++ b/Documentation/RelNotes/2.40.3.adoc
diff --git a/Documentation/RelNotes/2.40.4.txt b/Documentation/RelNotes/2.40.4.adoc
index 0ff29f3cfc..0ff29f3cfc 100644
--- a/Documentation/RelNotes/2.40.4.txt
+++ b/Documentation/RelNotes/2.40.4.adoc
diff --git a/Documentation/RelNotes/2.41.0.txt b/Documentation/RelNotes/2.41.0.adoc
index 8a9e17016e..8a9e17016e 100644
--- a/Documentation/RelNotes/2.41.0.txt
+++ b/Documentation/RelNotes/2.41.0.adoc
diff --git a/Documentation/RelNotes/2.41.1.txt b/Documentation/RelNotes/2.41.1.adoc
index 9fb4c218b2..9fb4c218b2 100644
--- a/Documentation/RelNotes/2.41.1.txt
+++ b/Documentation/RelNotes/2.41.1.adoc
diff --git a/Documentation/RelNotes/2.41.2.txt b/Documentation/RelNotes/2.41.2.adoc
index f94afde8c2..f94afde8c2 100644
--- a/Documentation/RelNotes/2.41.2.txt
+++ b/Documentation/RelNotes/2.41.2.adoc
diff --git a/Documentation/RelNotes/2.41.3.txt b/Documentation/RelNotes/2.41.3.adoc
index b5aba88790..b5aba88790 100644
--- a/Documentation/RelNotes/2.41.3.txt
+++ b/Documentation/RelNotes/2.41.3.adoc
diff --git a/Documentation/RelNotes/2.42.0.txt b/Documentation/RelNotes/2.42.0.adoc
index 0f1897ad5f..0f1897ad5f 100644
--- a/Documentation/RelNotes/2.42.0.txt
+++ b/Documentation/RelNotes/2.42.0.adoc
diff --git a/Documentation/RelNotes/2.42.1.txt b/Documentation/RelNotes/2.42.1.adoc
index 3d391b7dcd..3d391b7dcd 100644
--- a/Documentation/RelNotes/2.42.1.txt
+++ b/Documentation/RelNotes/2.42.1.adoc
diff --git a/Documentation/RelNotes/2.42.2.txt b/Documentation/RelNotes/2.42.2.adoc
index dbf761a01d..dbf761a01d 100644
--- a/Documentation/RelNotes/2.42.2.txt
+++ b/Documentation/RelNotes/2.42.2.adoc
diff --git a/Documentation/RelNotes/2.42.3.txt b/Documentation/RelNotes/2.42.3.adoc
index bfe3ba5629..bfe3ba5629 100644
--- a/Documentation/RelNotes/2.42.3.txt
+++ b/Documentation/RelNotes/2.42.3.adoc
diff --git a/Documentation/RelNotes/2.42.4.txt b/Documentation/RelNotes/2.42.4.adoc
index 3129d76e75..3129d76e75 100644
--- a/Documentation/RelNotes/2.42.4.txt
+++ b/Documentation/RelNotes/2.42.4.adoc
diff --git a/Documentation/RelNotes/2.43.0.txt b/Documentation/RelNotes/2.43.0.adoc
index e0e5b535bb..e0e5b535bb 100644
--- a/Documentation/RelNotes/2.43.0.txt
+++ b/Documentation/RelNotes/2.43.0.adoc
diff --git a/Documentation/RelNotes/2.43.1.txt b/Documentation/RelNotes/2.43.1.adoc
index 20e96f2dfa..20e96f2dfa 100644
--- a/Documentation/RelNotes/2.43.1.txt
+++ b/Documentation/RelNotes/2.43.1.adoc
diff --git a/Documentation/RelNotes/2.43.2.txt b/Documentation/RelNotes/2.43.2.adoc
index 5895e23a54..5895e23a54 100644
--- a/Documentation/RelNotes/2.43.2.txt
+++ b/Documentation/RelNotes/2.43.2.adoc
diff --git a/Documentation/RelNotes/2.43.3.txt b/Documentation/RelNotes/2.43.3.adoc
index 924f20594f..924f20594f 100644
--- a/Documentation/RelNotes/2.43.3.txt
+++ b/Documentation/RelNotes/2.43.3.adoc
diff --git a/Documentation/RelNotes/2.43.4.txt b/Documentation/RelNotes/2.43.4.adoc
index 0a842515ff..0a842515ff 100644
--- a/Documentation/RelNotes/2.43.4.txt
+++ b/Documentation/RelNotes/2.43.4.adoc
diff --git a/Documentation/RelNotes/2.43.5.txt b/Documentation/RelNotes/2.43.5.adoc
index 236b234b06..236b234b06 100644
--- a/Documentation/RelNotes/2.43.5.txt
+++ b/Documentation/RelNotes/2.43.5.adoc
diff --git a/Documentation/RelNotes/2.43.6.txt b/Documentation/RelNotes/2.43.6.adoc
index 2114b9f78d..2114b9f78d 100644
--- a/Documentation/RelNotes/2.43.6.txt
+++ b/Documentation/RelNotes/2.43.6.adoc
diff --git a/Documentation/RelNotes/2.43.7.txt b/Documentation/RelNotes/2.43.7.adoc
index 95702a036e..95702a036e 100644
--- a/Documentation/RelNotes/2.43.7.txt
+++ b/Documentation/RelNotes/2.43.7.adoc
diff --git a/Documentation/RelNotes/2.44.0.txt b/Documentation/RelNotes/2.44.0.adoc
index 14f9ce8226..14f9ce8226 100644
--- a/Documentation/RelNotes/2.44.0.txt
+++ b/Documentation/RelNotes/2.44.0.adoc
diff --git a/Documentation/RelNotes/2.44.1.txt b/Documentation/RelNotes/2.44.1.adoc
index b5135c3281..b5135c3281 100644
--- a/Documentation/RelNotes/2.44.1.txt
+++ b/Documentation/RelNotes/2.44.1.adoc
diff --git a/Documentation/RelNotes/2.44.2.txt b/Documentation/RelNotes/2.44.2.adoc
index 76700f0b73..76700f0b73 100644
--- a/Documentation/RelNotes/2.44.2.txt
+++ b/Documentation/RelNotes/2.44.2.adoc
diff --git a/Documentation/RelNotes/2.44.3.txt b/Documentation/RelNotes/2.44.3.adoc
index 5862845458..5862845458 100644
--- a/Documentation/RelNotes/2.44.3.txt
+++ b/Documentation/RelNotes/2.44.3.adoc
diff --git a/Documentation/RelNotes/2.44.4.txt b/Documentation/RelNotes/2.44.4.adoc
index 8db4d5b537..8db4d5b537 100644
--- a/Documentation/RelNotes/2.44.4.txt
+++ b/Documentation/RelNotes/2.44.4.adoc
diff --git a/Documentation/RelNotes/2.45.0.txt b/Documentation/RelNotes/2.45.0.adoc
index aa0315259b..aa0315259b 100644
--- a/Documentation/RelNotes/2.45.0.txt
+++ b/Documentation/RelNotes/2.45.0.adoc
diff --git a/Documentation/RelNotes/2.45.1.txt b/Documentation/RelNotes/2.45.1.adoc
index 3b0d60cfa3..3b0d60cfa3 100644
--- a/Documentation/RelNotes/2.45.1.txt
+++ b/Documentation/RelNotes/2.45.1.adoc
diff --git a/Documentation/RelNotes/2.45.2.txt b/Documentation/RelNotes/2.45.2.adoc
index 13429e6491..13429e6491 100644
--- a/Documentation/RelNotes/2.45.2.txt
+++ b/Documentation/RelNotes/2.45.2.adoc
diff --git a/Documentation/RelNotes/2.45.3.txt b/Documentation/RelNotes/2.45.3.adoc
index ddb3cb694b..ddb3cb694b 100644
--- a/Documentation/RelNotes/2.45.3.txt
+++ b/Documentation/RelNotes/2.45.3.adoc
diff --git a/Documentation/RelNotes/2.45.4.txt b/Documentation/RelNotes/2.45.4.adoc
index 5b50d8daf0..5b50d8daf0 100644
--- a/Documentation/RelNotes/2.45.4.txt
+++ b/Documentation/RelNotes/2.45.4.adoc
diff --git a/Documentation/RelNotes/2.46.0.txt b/Documentation/RelNotes/2.46.0.adoc
index c06a04a91b..c06a04a91b 100644
--- a/Documentation/RelNotes/2.46.0.txt
+++ b/Documentation/RelNotes/2.46.0.adoc
diff --git a/Documentation/RelNotes/2.46.1.txt b/Documentation/RelNotes/2.46.1.adoc
index e55c2c4a46..e55c2c4a46 100644
--- a/Documentation/RelNotes/2.46.1.txt
+++ b/Documentation/RelNotes/2.46.1.adoc
diff --git a/Documentation/RelNotes/2.46.2.txt b/Documentation/RelNotes/2.46.2.adoc
index 613386878d..613386878d 100644
--- a/Documentation/RelNotes/2.46.2.txt
+++ b/Documentation/RelNotes/2.46.2.adoc
diff --git a/Documentation/RelNotes/2.46.3.txt b/Documentation/RelNotes/2.46.3.adoc
index 4af032b63c..4af032b63c 100644
--- a/Documentation/RelNotes/2.46.3.txt
+++ b/Documentation/RelNotes/2.46.3.adoc
diff --git a/Documentation/RelNotes/2.46.4.txt b/Documentation/RelNotes/2.46.4.adoc
index 622f4c752f..622f4c752f 100644
--- a/Documentation/RelNotes/2.46.4.txt
+++ b/Documentation/RelNotes/2.46.4.adoc
diff --git a/Documentation/RelNotes/2.47.0.txt b/Documentation/RelNotes/2.47.0.adoc
index b63c3364af..b63c3364af 100644
--- a/Documentation/RelNotes/2.47.0.txt
+++ b/Documentation/RelNotes/2.47.0.adoc
diff --git a/Documentation/RelNotes/2.47.1.txt b/Documentation/RelNotes/2.47.1.adoc
index 39206c09fd..39206c09fd 100644
--- a/Documentation/RelNotes/2.47.1.txt
+++ b/Documentation/RelNotes/2.47.1.adoc
diff --git a/Documentation/RelNotes/2.47.2.txt b/Documentation/RelNotes/2.47.2.adoc
index 7a52ad8cb4..7a52ad8cb4 100644
--- a/Documentation/RelNotes/2.47.2.txt
+++ b/Documentation/RelNotes/2.47.2.adoc
diff --git a/Documentation/RelNotes/2.47.3.txt b/Documentation/RelNotes/2.47.3.adoc
index bc2a2b833b..bc2a2b833b 100644
--- a/Documentation/RelNotes/2.47.3.txt
+++ b/Documentation/RelNotes/2.47.3.adoc
diff --git a/Documentation/RelNotes/2.48.0.txt b/Documentation/RelNotes/2.48.0.adoc
index eff93be37a..eff93be37a 100644
--- a/Documentation/RelNotes/2.48.0.txt
+++ b/Documentation/RelNotes/2.48.0.adoc
diff --git a/Documentation/RelNotes/2.48.1.txt b/Documentation/RelNotes/2.48.1.adoc
index 26c59b6e3b..26c59b6e3b 100644
--- a/Documentation/RelNotes/2.48.1.txt
+++ b/Documentation/RelNotes/2.48.1.adoc
diff --git a/Documentation/RelNotes/2.48.2.txt b/Documentation/RelNotes/2.48.2.adoc
index f3f2f90c2b..f3f2f90c2b 100644
--- a/Documentation/RelNotes/2.48.2.txt
+++ b/Documentation/RelNotes/2.48.2.adoc
diff --git a/Documentation/RelNotes/2.49.0.adoc b/Documentation/RelNotes/2.49.0.adoc
new file mode 100644
index 0000000000..494c83096f
--- /dev/null
+++ b/Documentation/RelNotes/2.49.0.adoc
@@ -0,0 +1,288 @@
+Git v2.49 Release Notes
+=======================
+
+UI, Workflows & Features
+------------------------
+
+ * Completion script updates for zsh
+
+ * "git pack-objects" and its wrapper "git repack" learned an option
+   to use an alternative path-hash function to improve delta-base
+   selection to produce a packfile with deeper history than window
+   size.
+
+ * "git gc" learned the "--expire-to" option and passes it down to
+   underlying "git repack".
+
+ * "[help] autocorrect = 1" used to be a way to say "please wait for
+   0.1 second after suggesting a typofix of the command name before
+   running that command"; now it means "yes, if there is a plausible
+   typofix for the command name, please run it immediately".
+
+ * "git clone" learned to make a shallow clone for a single commit
+   that is not necessarily be at the tip of any branch.
+
+ * Lazy-loading missing files in a blobless clone on demand is costly
+   as it tends to be one-blob-at-a-time.  "git backfill" is introduced
+   to help bulk-download necessary files beforehand.
+
+ * "git push --atomic --porcelain" used to ignore failures from the
+   other side, losing the error status from the child process, which
+   has been corrected.
+
+ * "git rev-list --missing=" learned to accept "print-info" that gives
+   known details expected of the missing objects, like path and type.
+
+ * Comes with an updated "gitk".
+
+ * The documentation of "git commit" and "git rebase" now refer to
+   commit titles as such, not "subject".
+
+ * The value of "uname -s" is by default sent over the wire as a part
+   of the "version" capability.
+
+ * "git refs migrate" can optionally be told not to migrate the reflog.
+
+ * The netrc support (via the cURL library) for the HTTP transport has
+   been re-enabled.
+
+ * Removal of ".git/branches" and ".git/remotes" support in the
+   BreakingChanges document has been further clarified.
+
+ * What happens to submodules during merge has been documented in a
+   bit more detail.
+
+
+Performance, Internal Implementation, Development Support etc.
+--------------------------------------------------------------
+
+ * More -Wsign-compare fixes.
+
+ * meson-based build now supports the unsafe-sha1 build knob.
+
+ * The meson-based build procedure covers contrib/ and other places as
+   well.
+
+ * The code to check LSan results has been simplified and made more
+   robust.
+   (merge 164a2516eb jk/lsan-race-ignore-false-positive later to maint).
+
+ * More code paths have a repository passed through the callchain,
+   instead of assuming the primary the_repository object.
+
+ * Move a few more unit tests to the clar test framework.
+
+ * Introduce a new API to visit objects in batches based on a common
+   path, or by type.
+
+ * Following the procedure we established to introduce breaking
+   changes for Git 3.0, allow an early opt-in for removing support of
+   $GIT_DIR/branches/ and $GIT_DIR/remotes/ directories to configure
+   remotes.
+
+ * The code paths to interact with zlib has been cleaned up in
+   preparation for building with zlib-ng.
+
+ * Foreign language interface for Rust into our code base has been added.
+
+ * All the documentation .txt files have been renamed to .adoc to help
+   content aware editors.
+
+ * "git difftool" code clean-up.
+
+ * Rename processing in the recursive merge backend has seen a micro
+   optimization.
+
+ * The path.[ch] API takes an explicit repository parameter passed
+   throughout the callchain, instead of relying on the_repository
+   singleton instance.
+
+ * Large-object promisor protocol extension has been introduced.
+
+ * The editorconfig file is updated to tell us that bash scripts are
+   similar to general Bourne shell scripts.
+
+ * Meson-based build procedure forgot to build some docs, which has
+   been corrected.
+
+
+Fixes since v2.48
+-----------------
+
+ * "git submodule" learned various ways to spell the same option,
+   e.g. "--branch=B" can be spelled "--branch B" or "-bB".
+   (merge b86f0f9071 re/submodule-parse-opt later to maint).
+
+ * Tweak the help text used for the option value placeholders by
+   parse-options API so that translations can customize the "<>"
+   placeholder signal (e.g. "--option=<value>").
+   (merge 5b34dd08d0 as/long-option-help-i18n later to maint).
+
+ * CI jobs gave sporadic failures, which turns out that that the
+   object finalization code was giving an error when it did not have
+   to.
+   (merge d7fcbe2c56 ps/object-collision-check later to maint).
+
+ * The code to compute "unique" name used git_rand() which can fail or
+   get stuck; the callsite does not require cryptographic security.
+   Introduce the "insecure" mode and use it appropriately.
+   (merge 0b4f8afef6 ps/reftable-get-random-fix later to maint).
+
+ * A misconfigured "fsck.skiplist" configuration variable was not
+   diagnosed as an error, which has been corrected.
+   (merge ca7158076f jt/fsck-skiplist-parse-fix later to maint).
+
+ * Extended SHA-1 expression parser did not work well when a branch
+   with an unusual name (e.g. "foo{bar") is involved.
+   (merge 191f0c8db2 en/object-name-with-funny-refname-fix later to maint).
+
+ * The meson build procedure looked for the 'version-def.h' file in a
+   wrong directory, which has been corrected.
+   (merge 4771501c0a tc/meson-use-our-version-def-h later to maint).
+
+ * The meson build procedure for Documentation/technical/ hierarchy was
+   missing necessary dependencies, which has been corrected.
+   (merge 1dca492edd sj/meson-doc-technical-dependency-fix later to maint).
+
+ * The "instaweb" bound only to local IP address without "--local" and
+   to all addresses with "--local", which was the other way around, when
+   using Python's http.server class, which has been corrected.
+   (merge 76baf97fa1 ak/instaweb-python-port-binding-fix later to maint).
+
+ * Document that it is insecure to use Personal Access Tokens, which
+   some hosting providers take as username/password, embedded in URLs.
+   (merge a90ff409f0 mh/doc-credential-helpers-with-pat later to maint).
+
+ * The help text from "git $cmd -h" appear on the standard output for
+   some $cmd and the standard error for others.  The built-in commands
+   have been fixed to show them on the standard output consistently.
+   (merge f66d1423f5 jc/show-usage-help later to maint).
+
+ * The meson-driven build is now aware of "git-subtree" housed in
+   contrib/subtree hierarchy.
+   (merge 8454b42f94 ps/build-meson-subtree later to maint).
+
+ * It was possible for "git unpack-objects" and "git index-pack" to
+   make an unaligned access, which has been corrected.
+   (merge 98046591b9 jk/pack-header-parse-alignment-fix later to maint).
+
+ * The "cache" credential back-end did not handle authtype correctly,
+   which has been corrected.
+   (merge 0b43274850 mh/credential-cache-authtype-request-fix later to maint).
+
+ * "git branch --sort=..." and "git for-each-ref --format=... --sort=..."
+   did not work as expected with some atoms, which has been corrected.
+   (merge c5490ce9d1 rs/ref-fitler-used-atoms-value-fix later to maint).
+
+ * reflog entries for symbolic ref updates were broken, which has been
+   corrected.
+   (merge 3519492430 kn/reflog-symref-fix later to maint).
+
+ * The trace2 code was not prepared to show a configuration variable
+   that is set to true using the valueless true syntax, which has been
+   corrected.
+   (merge 2fd367cf63 am/trace2-with-valueless-true later to maint).
+
+ * The "git refs migrate" command did not migrate the reflog for
+   refs/stash, which is the contents of the stashes, which has been
+   corrected.
+   (merge a0bea0978f ps/reflog-migration-with-logall-fix later to maint).
+
+ * Doc and short-help text for "show-index" has been clarified to
+   stress that the command reads its data from the standard input.
+   (merge 49edce4ff9 jc/show-index-h-update later to maint).
+
+ * The API around choosing to use unsafe variant of SHA-1
+   implementation has been updated in an attempt to make it harder to
+   abuse.
+   (merge 04292c3796 tb/unsafe-hash-cleanup later to maint).
+
+ * Fix bugs in an earlier attempt to fix "git refs migration".
+   (merge f11f0a5a2d kn/reflog-migration-fix-fix later to maint).
+
+ * The code path used when "git fetch" fetches from a bundle file
+   closed the same file descriptor twice, which sometimes broke things
+   unexpectedly when the file descriptor was reused, which has been
+   corrected.
+   (merge 9a84794ad8 js/bundle-unbundle-fd-reuse-fix later to maint).
+
+ * "git init" to reinitialize a repository that already exists cannot
+   change the hash function and ref backends; such a request is
+   silently ignored now.
+   (merge 7e88640cd1 ps/setup-reinit-fixes later to maint).
+
+ * "git apply" internally uses unsigned long for line numbers and uses
+   strtoul() to parse numbers on the hunk headers.  It however forgot
+   to check parse errors.
+   (merge a206058fda pw/apply-ulong-overflow-check later to maint).
+
+ * Two CI tasks, whitespace check and style check, work on the
+   difference from the base version and the version being checked, but
+   the base was computed incorrectly in GitLab CI in some cases, which
+   has been corrected.
+   (merge acc4fb302b jt/gitlab-ci-base-fix later to maint).
+
+ * "git repack --keep-unreachable" to send unreachable objects to the
+   main pack "git repack -ad" produces did not work when there is no
+   existing packs, which has been corrected.
+   (merge 414c82300a ps/repack-keep-unreachable-in-unpacked-repo later to maint).
+
+ * Going into a secondary worktree and asking "is the main worktree
+   bare?" did not work correctly when per-worktree configuration
+   option was in use, which has been corrected.
+
+ * Fetching into a bare repository incorrectly assumed it always used
+   a mirror layout when deciding to update remote-tracking HEAD, which
+   has been corrected.
+   (merge 93dc16483a bf/fetch-set-head-fix later to maint).
+
+ * A thunderbird helper script lost its bashism.
+   (merge 59d26bd961 bc/contrib-thunderbird-patch-inline-fix later to maint).
+
+ * The -G/-S options to the "diff" family of commands caused us to hit
+   a BUG() when they get no values; they have been corrected.
+   (merge a620046b29 bc/diff-reject-empty-arg-to-pickaxe later to maint).
+
+ * "git merge-tree --stdin" has been improved (including a workaround
+   for a deadlock).
+   (merge 6a9ae81015 pw/merge-tree-stdin-deadlock-fix later to maint).
+
+ * Correct the default target in Documentation/Makefile, and
+   future-proof all Makefiles from similar breakages by declaring the
+   default target (which happens to be "all") upfront.
+   (merge 5309c1e9fb ad/set-default-target-in-makefiles later to maint).
+
+ * "git check-mailmap" used to segfault when queried without human
+   readable name.
+   (merge bb60c52131 jk/check-mailmap-wo-name-fix later to maint).
+
+ * Support for renaming of symbolic links on Windows has been improved.
+
+ * "git rebase -i" failed to allow rewording an empty commit that has
+   been fast-forwarded.
+   (merge af8fc7be10 pw/rebase-i-ff-empty-commit later to maint).
+
+ * The use of "paste" command for aggregating the test results have
+   been corrected.
+   (merge ce98863204 dk/test-aggregate-results-paste-fix later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+   (merge ddb5287894 jk/t7407-use-test-grep later to maint).
+   (merge 21e1b44865 aj/difftool-config-doc-fix later to maint).
+   (merge 6a63995335 mh/gitattr-doc-markup-fix later to maint).
+   (merge 43850dcf9c sk/unit-test-hash later to maint).
+   (merge 4ad47d2de3 jc/cli-doc-option-and-config later to maint).
+   (merge 2d0ff147e5 jp/t8002-printf-fix later to maint).
+   (merge 69666e6746 ja/doc-restore-markup-update later to maint).
+   (merge d11d003ba5 sk/strlen-returns-size_t later to maint).
+   (merge 77b2d29e91 ja/doc-notes-markup-updates later to maint).
+   (merge 6979bf6f8f jk/combine-diff-cleanup later to maint).
+   (merge 8705c9bd13 kn/pack-write-with-reduced-globals later to maint).
+   (merge 087740d65a ps/leakfixes-0129 later to maint).
+   (merge 6bba6f604b jp/doc-trailer-config later to maint).
+   (merge f1cc562b77 lo/t7603-path-is-file-update later to maint).
+   (merge 45761988ac en/doc-renormalize later to maint).
+   (merge 832f56f06a jc/doc-boolean-synonyms later to maint).
+   (merge 3eeed876a9 ac/doc-http-ssl-type-config later to maint).
+   (merge c268e3285d jc/breaking-changes-early-adopter-option later to maint).
+   (merge 0d03fda6a5 pb/doc-follow-remote-head later to maint).
diff --git a/Documentation/RelNotes/2.49.1.adoc b/Documentation/RelNotes/2.49.1.adoc
new file mode 100644
index 0000000000..c619e8b495
--- /dev/null
+++ b/Documentation/RelNotes/2.49.1.adoc
@@ -0,0 +1,12 @@
+Git v2.49.1 Release Notes
+=========================
+
+This release merges up the fixes that appear in v2.43.7, v2.44.4,
+v2.45.4, v2.46.4, v2.47.3, and v2.48.2 to address the following CVEs:
+CVE-2025-27613, CVE-2025-27614, CVE-2025-46334, CVE-2025-46835,
+CVE-2025-48384, CVE-2025-48385, and CVE-2025-48386. See the release
+notes for v2.43.7 for details.
+
+It also contains some updates to various CI bits to work around
+and/or to adjust to the deprecation of use of Ubuntu 20.04 GitHub
+Actions CI, updates to to Fedora base image.
diff --git a/Documentation/RelNotes/2.5.0.txt b/Documentation/RelNotes/2.5.0.adoc
index 84723f912a..84723f912a 100644
--- a/Documentation/RelNotes/2.5.0.txt
+++ b/Documentation/RelNotes/2.5.0.adoc
diff --git a/Documentation/RelNotes/2.5.1.txt b/Documentation/RelNotes/2.5.1.adoc
index b70553308a..b70553308a 100644
--- a/Documentation/RelNotes/2.5.1.txt
+++ b/Documentation/RelNotes/2.5.1.adoc
diff --git a/Documentation/RelNotes/2.5.2.txt b/Documentation/RelNotes/2.5.2.adoc
index 3f749398bb..3f749398bb 100644
--- a/Documentation/RelNotes/2.5.2.txt
+++ b/Documentation/RelNotes/2.5.2.adoc
diff --git a/Documentation/RelNotes/2.5.3.txt b/Documentation/RelNotes/2.5.3.adoc
index d1436857cb..d1436857cb 100644
--- a/Documentation/RelNotes/2.5.3.txt
+++ b/Documentation/RelNotes/2.5.3.adoc
diff --git a/Documentation/RelNotes/2.5.4.txt b/Documentation/RelNotes/2.5.4.adoc
index b8a2f93ee7..b8a2f93ee7 100644
--- a/Documentation/RelNotes/2.5.4.txt
+++ b/Documentation/RelNotes/2.5.4.adoc
diff --git a/Documentation/RelNotes/2.5.5.txt b/Documentation/RelNotes/2.5.5.adoc
index 37eae9a2d9..37eae9a2d9 100644
--- a/Documentation/RelNotes/2.5.5.txt
+++ b/Documentation/RelNotes/2.5.5.adoc
diff --git a/Documentation/RelNotes/2.5.6.txt b/Documentation/RelNotes/2.5.6.adoc
index 9cd025bb1c..9cd025bb1c 100644
--- a/Documentation/RelNotes/2.5.6.txt
+++ b/Documentation/RelNotes/2.5.6.adoc
diff --git a/Documentation/RelNotes/2.50.0.adoc b/Documentation/RelNotes/2.50.0.adoc
new file mode 100644
index 0000000000..e85747335b
--- /dev/null
+++ b/Documentation/RelNotes/2.50.0.adoc
@@ -0,0 +1,441 @@
+Git v2.50 Release Notes
+=======================
+
+UI, Workflows & Features
+------------------------
+
+ * A post-processing filter for "diff --raw" output has been
+   introduced.
+
+ * "git repack" learned "--combine-cruft-below-size" option that
+   controls how cruft-packs are combined.
+
+ * TCP keepalive behaviour on http transports can now be configured by
+   calling cURL library.
+
+ * Incrementally updating multi-pack index files.
+
+ * "git reflog" learns "drop" subcommand, that discards the entire
+   reflog data for a ref.
+
+ * A new userdiff driver for ".ini" format configuration files has
+   been added.
+
+ * The job to coalesce loose objects into packfiles in "git
+   maintenance" now has configurable batch size.
+
+ * "git clone" still gave the message about the default branch name;
+   this message has been turned into an advice message that can be
+   turned off.
+
+ * "git rev-list" learns machine-parsable output format that delimits
+   each field with NUL.
+
+ * "git maintenance" learns a new task to expire reflog entries.
+
+ * Auth-related (and unrelated) error handling in send-email has been
+   made more robust.
+
+ * Updating multiple references have only been possible in an all-or-nothing
+   fashion with transactions, but it can be more efficient to batch
+   multiple updates even when some of them are allowed to fail in a
+   best-effort manner.  A new "best effort batches of updates" mode
+   has been introduced.
+
+ * "git help --build-options" reports SHA-1 and SHA-256 backends used
+   in the build.
+
+ * "git cat-file --batch" and friends learned to allow "--filter=" to
+   omit certain objects, just like the transport layer does.
+
+ * "git blame --porcelain" mode now talks about unblamable lines and
+   lines that are blamed to an ignored commit.
+
+ * The build procedure installs bash (but not zsh) completion script.
+
+ * send-email has been updated to work better with Outlook's SMTP server.
+
+ * "git diff --minimal" used to give non-minimal output when its
+   optimization kicked in, which has been disabled.
+
+ * "git index-pack --fix-thin" used to abort to prevent a cycle in
+   delta chains from forming in a corner case even when there is no
+   such cycle.
+
+ * Make repository clean-up tasks that "gc" can do available to "git
+   maintenance" front-end.
+
+ * Bundle-URI feature did not use refs recorded in the bundle other
+   than normal branches as anchoring points to optimize the follow-up
+   fetch during "git clone"; now it is told to utilize all.
+
+ * The `send-email` documentation has been updated with OAuth2.0
+   related examples.
+
+ * Two of the "scalar" subcommands that add a repository that hasn't
+   been under "scalar"'s control are taught an option not to enable the
+   scheduled maintenance on it.
+
+ * The userdiff pattern for shell scripts has been updated to cope
+   with more bash-isms.
+
+ * "git merge-tree" learned an option to see if it resolves cleanly
+   without actually creating a result.
+
+ * The commit title in the "rebase -i" todo file are now prefixed with
+   '#', just like a merge commit being replayed.
+
+ * "git receive-pack" optionally learns not to care about connectivity
+   check, which can be useful when the repository arranges to ensure
+   connectivity by some other means.
+
+ * "git notes --help" documentation updates.
+
+
+Performance, Internal Implementation, Development Support etc.
+--------------------------------------------------------------
+
+ * A handful of built-in command implementations have been rewritten
+   to use the repository instance supplied by git.c:run_builtin(), its
+   caller.
+
+ * "git fsck" becomes more careful when checking the refs.
+
+ * "git fast-export | git fast-import" learns to deal with commit and
+   tag objects with embedded signatures a bit better.  This is highly
+   experimental and the format of the data stream may change in the
+   future without compatibility guarantees.
+
+ * The code paths to check whether a refname X is available (by seeing
+   if another ref X/Y exists, etc.) have been optimized.
+
+ * First step of deprecating and removing merge-recursive.
+
+ * In protocol v2 where the refs advertisement is constrained, we try
+   to tell the server side not to limit the advertisement when there
+   is no specific need to, which has been the source of confusion and
+   recent bugs.  Revamp the logic to simplify.
+
+ * Update meson based build procedure for breaking changes support.
+
+ * Enable -Wunreachable-code for developer builds.
+
+ * Ensure what we write in assert() does not have side effects,
+   and introduce ASSERT() macro to mark those that cannot be
+   mechanically checked for lack of side effects.
+
+ * Give more meaningful error return values from block writer layer of
+   the reftable ref-API backend.
+
+ * Make the code in reftable library less reliant on the service
+   routines it used to borrow from Git proper, to make it easier to
+   use by external users of the library.
+
+ * CI update.
+
+ * The object layer has been updated to take an explicit repository
+   instance as a parameter in more code paths.
+
+ * Some warnings from "-Wsign-compare" for builtin/rm.c have been
+   squelched.
+
+ * A few traditional unit tests have been rewritten to use the clar
+   framework.
+
+ * Some warnings from "-Wsign-compare" for pathspec.c have been
+   squelched.
+
+ * "make test" used to have a hard dependency on (basic) Perl; tests
+   have been rewritten help environment with NO_PERL test the build as
+   much as possible.
+
+ * Remove remnants of the recursive merge strategy backend, which was
+   superseded by the ort merge strategy.
+
+ * Optimize the code to dedup references recorded in a bundle file.
+
+ * Update parse-options API to catch mistakes to pass address of an
+   integral variable of a wrong type/size.
+
+ * Since a call to repo_config() can be called with repo set to NULL
+   these days, a command that is marked as RUN_SETUP in the builtin
+   command table does not have to check repo with NULL before making
+   the call.
+
+ * Overhaul of the reftable API.
+
+ * Reduce requirement for Perl in our documentation build and a few
+   scripts.
+
+ * The build procedure based on Meson learned to drive the
+   benchmarking tests.
+
+ * Code clean-up for meson-based build infrastructure.
+
+ * Add an equivalent to "make hdr-check" target to meson based builds.
+
+ * Further code clean-up in the object-store layer.
+
+ * Build performance fix.
+
+ * Teach "git send-email" to also consult `hostname -f` for mail
+   domain to compute the identity given to SMTP servers.
+
+ * The dependency on the_repository variable has been reduced from the
+   code paths in "git replay".
+
+ * Support to create a loose object file with unknown object type has
+   been dropped.
+
+ * The code path to access the "packed-refs" file while "fsck" is
+   taught to mmap the file, instead of reading the whole file into
+   memory.
+
+ * Assorted fixes for issues found with CodeQL.
+
+ * Remove the leftover hints to the test framework to mark tests that
+   do not pass the leak checker tests, as they should no longer be
+   needed.
+
+ * When a stale .midx file refers to .pack files that no longer exist,
+   we ended up checking for these non-existent files repeatedly, which
+   has been optimized by memoizing the non-existence.
+
+ * Build settings have been improved for BSD based systems.
+
+ * Newer version of libcURL detected curl_easy_setopt() calls we made
+   with platform-natural "int" when we should have used "long", which
+   all have been corrected.
+
+ * Tests that compare $HOME and $(pwd), which should be the same
+   directory unless the tests chdir's around, would fail when the user
+   enters the test directory via symbolic links, which has been
+   corrected.
+
+
+Fixes since v2.49
+-----------------
+
+ * The refname exclusion logic in the packed-ref backend has been
+   broken for some time, which confused upload-pack to advertise
+   different set of refs.  This has been corrected.
+   (merge 10e8a9352b tb/refs-exclude-fixes later to maint).
+
+ * The merge-recursive and merge-ort machinery crashed in corner cases
+   when certain renames are involved.
+   (merge 3adba40858 en/merge-process-renames-crash-fix later to maint).
+
+ * Certain "cruft" objects would have never been refreshed when there
+   are multiple cruft packs in the repository, which has been
+   corrected.
+   (merge 08f612ba70 tb/multi-cruft-pack-refresh-fix later to maint).
+
+ * The xdiff code on 32-bit platform misbehaved when an insanely large
+   context size is given, which has been corrected.
+   (merge d39e28e68c rs/xdiff-context-length-fix later to maint).
+
+ * GitHub Actions CI switched on a CI/CD variable that does not exist
+   when choosing what packages to install etc., which has been
+   corrected.
+   (merge ee89f7c79d kn/ci-meson-check-build-docs-fix later to maint).
+
+ * Using "git name-rev --stdin" as an example, improve the framework to
+   prepare tests to pretend to be in the future where the breaking
+   changes have already happened.
+   (merge de3dec1187 jc/name-rev-stdin later to maint).
+
+ * An earlier code refactoring of the hash machinery missed a few
+   required calls to init_fn.
+   (merge d39f04b638 jh/hash-init-fixes later to maint).
+
+ * A documentation page was left out from formatting and installation,
+   which has been corrected.
+   (merge ae85116f18 pw/build-breaking-changes-doc later to maint).
+
+ * The bash command line completion script (in contrib/) has been
+   updated to cope with remote repository nicknames with slashes in
+   them.
+   (merge 778d2f1760 dm/completion-remote-names-fix later to maint).
+
+ * "Dubious ownership" checks on Windows has been tightened up.
+   (merge 5bb88e89ef js/mingw-admins-are-special later to maint).
+
+ * Layout configuration in vimdiff backend didn't work as advertised,
+   which has been corrected.
+   (merge 93bab2d04b fr/vimdiff-layout-fixes later to maint).
+
+ * Fix our use of zlib corner cases.
+   (merge 1cb2f293f5 jk/zlib-inflate-fixes later to maint).
+
+ * Fix lockfile contention in reftable code on Windows.
+   (merge 0a3dceabf1 ps/mingw-creat-excl-fix later to maint).
+
+ * "git-merge-file" documentation source, which has lines that look
+   like conflict markers, lacked custom conflict marker size defined,
+   which has been corrected..
+   (merge d3b5832381 pw/custom-conflict-marker-size-for-merge-related-docs later to maint).
+
+ * Squelch false-positive from sparse.
+   (merge da87b58014 dd/sparse-glibc-workaround later to maint).
+
+ * Adjust to the deprecation of use of Ubuntu 20.04 GitHub Actions CI.
+   (merge 832d9f6d0b js/ci-github-update-ubuntu later to maint).
+
+ * Work around CI breakage due to fedora base image getting updated.
+   (merge 8a471a663b js/ci-fedora-gawk later to maint).
+
+ * A ref transaction corner case fix.
+   (merge b9fadeead7 jt/ref-transaction-abort-fix later to maint).
+
+ * Random build fixes.
+   (merge 85e1d6819f ps/misc-build-fixes later to maint).
+
+ * "git fetch [<remote>]" with only the configured fetch refspec
+   should be the only thing to update refs/remotes/<remote>/HEAD,
+   but the code was overly eager to do so in other cases.
+
+ * Incorrect sorting of refs with bytes with high-bit set on platforms
+   with signed char led to a BUG, which has been corrected.
+
+ * "make perf" fixes.
+   (merge 1665f12fa0 pb/perf-test-fixes later to maint).
+
+ * Doc mark-up updates.
+   (merge 5a5565ec44 ja/doc-reset-mv-rm-markup-updates later to maint).
+
+ * Work around false positive from CodeQL checker.
+   (merge 0f558141ed js/range-check-codeql-workaround later to maint).
+
+ * "git log --{left,right}-only A...B", when A and B does not share
+   any common ancestor, now behaves as expected.
+   (merge e7ef4be7c2 mh/left-right-limited later to maint).
+
+ * Document the convention to disable hooks altogether by setting the
+   hooksPath configuration variable to /dev/null.
+   (merge 1b2eee94f1 ds/doc-disable-hooks later to maint).
+
+ * Make sure outage of third-party sites that supply P4, Git-LFS, and
+   JGit we use for testing would not prevent our CI jobs from running
+   at all.
+
+ * Various build tweaks, including CSPRNG selection on some platforms.
+   (merge cdda67de03 rj/build-tweaks later to maint).
+
+ * Developer support fix..
+   (merge 32b74b9809 js/git-perf-env-override later to maint).
+
+ * Fix for scheduled maintenance tasks on platforms using launchctl.
+   (merge eb2d7beb0e jh/gc-launchctl-schedule-fix later to maint).
+
+ * Update to arm64 Windows port (part of which had been reverted as it
+   broke builds for existing platforms, which may need to be redone in
+   future releases).
+
+ * hashmap API clean-up to ensure hashmap_clear() leaves a cleared map
+   in a reusable state.
+   (merge 9481877de3 en/hashmap-clear-fix later to maint).
+
+ * "git mv a a/b dst" would ask to move the directory 'a' itself, as
+   well as its contents, in a single destination directory, which is
+   a contradicting request that is impossible to satisfy. This case is
+   now detected and the command errors out.
+   (merge 974f0d4664 ps/mv-contradiction-fix later to maint).
+
+ * Further refinement on CI messages when an optional external
+   software is unavailable (e.g. due to third-party service outage).
+   (merge 956acbefbd jc/ci-skip-unavailable-external-software later to maint).
+
+ * Test result aggregation did not work in Meson based CI jobs.
+   (merge bd38ed5be1 ps/ci-test-aggreg-fix-for-meson later to maint).
+
+ * Code clean-up around stale CI elements and building with Visual Studio.
+   (merge a7b060f67f js/ci-buildsystems-cleanup later to maint).
+
+ * "git add 'f?o'" did not add 'foo' if 'f?o', an unusual pathname,
+   also existed on the working tree, which has been corrected.
+   (merge ec727e189c kj/glob-path-with-special-char later to maint).
+
+ * The fallback implementation of open_nofollow() depended on
+   open("symlink", O_NOFOLLOW) to set errno to ELOOP, but a few BSD
+   derived systems use different errno, which has been worked around.
+   (merge f47bcc3413 cf/wrapper-bsd-eloop later to maint).
+
+ * Use-after-free fix in the sequencer.
+   (merge 5dbaec628d pw/sequencer-reflog-use-after-free later to maint).
+
+ * win+Meson CI pipeline, unlike other pipelines for Windows,
+   used to build artifacts in developer mode, which has been changed to
+   build them in release mode for consistency.
+   (merge 184abdcf05 js/ci-build-win-in-release-mode later to maint).
+
+ * CI settings at GitLab has been updated to run MSVC based Meson job
+   automatically (as opposed to be done only upon manual request).
+   (merge 6389579b2f ps/ci-gitlab-enable-msvc-meson-job later to maint).
+
+ * "git apply" and "git add -i/-p" code paths no longer unnecessarily
+   expand sparse-index while working.
+   (merge ecf9ba20e3 ds/sparse-apply-add-p later to maint).
+
+ * Avoid adding directory path to a sparse-index tree entries to the
+   name-hash, since they would bloat the hashtable without anybody
+   querying for them.  This was done already for a single threaded
+   part of the code, but now the multi-threaded code also does the
+   same.
+   (merge 2e60aabc75 am/sparse-index-name-hash-fix later to maint).
+
+ * Recent versions of Perl started warning against "! A =~ /pattern/"
+   which does not negate the result of the matching.  As it turns out
+   that the problematic function is not even called, it was removed.
+   (merge 67cae845d2 op/cvsserver-perl-warning later to maint).
+
+ * "git apply --index/--cached" when applying a deletion patch in
+   reverse failed to give the mode bits of the path "removed" by the
+   patch to the file it creates, which has been corrected.
+
+ * "git verify-refs" errored out in a repository in which
+   linked worktrees were prepared with Git 2.43 or lower.
+   (merge d5b3c38b8a sj/ref-contents-check-fix later to maint).
+
+ * Update total_ram() function on BSD variants.
+
+ * Update online_cpus() function on BSD variants.
+
+ * Revert a botched bswap.h change that broke ntohll() functions on
+   big-endian systems with __builtin_bswap32/64().
+
+ * Fixes for GitHub Actions Coverity job.
+   (merge 3cc4fc1ebd js/github-ci-win-coverity-fix later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+   (merge 227c4f33a0 ja/doc-block-delimiter-markup-fix later to maint).
+   (merge 2bfd3b3685 ab/decorate-code-cleanup later to maint).
+   (merge 5337daddc7 am/dir-dedup-decl-of-repository later to maint).
+   (merge 554051d691 en/diff-rename-follow-fix later to maint).
+   (merge a18c18b470 en/random-cleanups later to maint).
+   (merge 5af21c9acb hj/doc-rev-list-ancestry-fix later to maint).
+   (merge 26d76ca284 aj/doc-restore-p-update later to maint).
+   (merge 2c0dcb9754 cc/lop-remote later to maint).
+   (merge 7b399322a2 ja/doc-branch-markup later to maint).
+   (merge ee434e1807 pw/doc-pack-refs-markup-fix later to maint).
+   (merge c000918eb7 tb/bitamp-typofix later to maint).
+   (merge fa8cd29676 js/imap-send-peer-cert-verify later to maint).
+   (merge 98b423bc1c rs/clear-commit-marks-simplify later to maint).
+   (merge 133d065dd6 ta/bulk-checkin-signed-compare-false-warning-fix later to maint).
+   (merge d2827dc31e es/meson-build-skip-coccinelle later to maint).
+   (merge ee8edb7156 dk/vimdiff-doc-fix later to maint).
+   (merge 107d889303 md/t1403-path-is-file later to maint).
+   (merge abd4192b07 js/comma-semicolon-confusion later to maint).
+   (merge 27b7264206 ab/environment-clean-header later to maint).
+   (merge ff4a749354 as/typofix-in-env-h-header later to maint).
+   (merge 86eef3541e az/tighten-string-array-constness later to maint).
+   (merge 25292c301d lo/remove-log-reencode-from-rev-info later to maint).
+   (merge 1aa50636fd jk/p5332-testfix later to maint).
+   (merge 42cf4ac552 ps/ci-resurrect-p4-on-github later to maint).
+   (merge 104add8368 js/diff-codeql-false-positive-workaround later to maint).
+   (merge f62977b93c en/get-tree-entry-doc later to maint).
+   (merge e5dd0a05ed ly/am-split-stgit-leakfix later to maint).
+   (merge bac220e154 rc/t1001-test-path-is-file later to maint).
+   (merge 91db6c735d ly/reftable-writer-leakfix later to maint).
+   (merge 20e4e9ad0b jc/doc-synopsis-option-markup later to maint).
+   (merge cddcee7f64 es/meson-configure-build-options-fix later to maint).
+   (merge cea9f55f00 wk/sparse-checkout-doc-fix later to maint).
diff --git a/Documentation/RelNotes/2.50.1.adoc b/Documentation/RelNotes/2.50.1.adoc
new file mode 100644
index 0000000000..aa4a71adbc
--- /dev/null
+++ b/Documentation/RelNotes/2.50.1.adoc
@@ -0,0 +1,8 @@
+Git v2.50.1 Release Notes
+=========================
+
+This release merges up the fixes that appear in v2.43.7, v2.44.4,
+v2.45.4, v2.46.4, v2.47.3, v2.48.2, and v2.49.1 to address the
+following CVEs: CVE-2025-27613, CVE-2025-27614, CVE-2025-46334,
+CVE-2025-46835, CVE-2025-48384, CVE-2025-48385, and
+CVE-2025-48386. See the release notes for v2.43.7 for details.
diff --git a/Documentation/RelNotes/2.51.0.adoc b/Documentation/RelNotes/2.51.0.adoc
new file mode 100644
index 0000000000..a73ea3e808
--- /dev/null
+++ b/Documentation/RelNotes/2.51.0.adoc
@@ -0,0 +1,341 @@
+Git v2.51 Release Notes
+=======================
+
+UI, Workflows & Features
+------------------------
+
+ * Userdiff patterns for the R language have been added.
+
+ * Documentation for "git send-email" has been updated with a bit more
+   credential helper and OAuth information.
+
+ * "git cat-file --batch" learns to understand %(objectmode) atom to
+   allow the caller to tell missing objects (due to repository
+   corruption) and submodules (whose commit objects are OK to be
+   missing) apart.
+
+ * "git diff --no-index dirA dirB" can limit the comparison with
+   pathspec at the end of the command line, just like normal "git
+   diff".
+
+ * "git subtree" (in contrib/) learned to grok GPG signing its commits.
+
+ * "git whatchanged" that is longer to type than "git log --raw"
+   which is its modern rough equivalent has outlived its usefulness
+   more than 10 years ago.  Plan to deprecate and remove it.
+
+ * An interchange format for stash entries is defined, and subcommand
+   of "git stash" to import/export has been added.
+
+ * "git merge/pull" has been taught the "--compact-summary" option to
+   use the compact-summary format, intead of diffstat, when showing
+   the summary of the incoming changes.
+
+ * "git imap-send" has been broken for a long time, which has been
+   resurrected and then taught to talk OAuth2.0 etc.
+
+ * Some error messages from "git imap-send" has been updated.
+
+ * When "git daemon" sees a signal while attempting to accept() a new
+   client, instead of retrying, it skipped it by mistake, which has
+   been corrected.
+
+ * The reftable ref backend has matured enough; Git 3.0 will make it
+   the default format in a newly created repositories by default.
+
+ * "netrc" credential helper has been improved to understand textual
+   service names (like smtp) in addition to the numeric port numbers
+   (like 25).
+
+ * Lift the limitation to use changed-path filter in "git log" so that
+   it can be used for a pathspec with multiple literal paths.
+
+ * Clean up the way how signature on commit objects are exported to
+   and imported from fast-import stream.
+
+ * Remove unsupported, unused, and unsupportable old option from "git
+   log".
+
+ * Document recently added "git imap-send --list" with an example.
+
+ * "git pull" learned to pay attention to pull.autostash configuration
+   variable, which overrides rebase/merge.autostash.
+
+ * "git for-each-ref" learns "--start-after" option to help
+   applications that want to page its output.
+
+ * "git switch" and "git restore" are declared to be no longer
+   experimental.
+
+ * "git -c alias.foo=bar foo -h baz" reported "'foo' is aliased to
+   'bar'" and then went on to run "git foo -h baz", which was
+   unexpected.  Tighten the rule so that alias expansion is reported
+   only when "-h" is the sole option.
+
+
+Performance, Internal Implementation, Development Support etc.
+--------------------------------------------------------------
+
+ * "git pack-objects" learned to find delta bases from blobs at the
+   same path, using the --path-walk API.
+
+ * CodingGuidelines update.
+
+ * Add settings for Solaris 10 & 11.
+
+ * Meson-based build/test framework now understands TAP output
+   generated by our tests.
+
+ * "Do not explicitly initialize to zero" rule has been clarified in
+   the CodingGuidelines document.
+
+ * A test helper "test_seq" function learned the "-f <fmt>" option,
+   which allowed us to simplify a lot of test scripts.
+
+ * A lot of stale stuff has been removed from the contrib/ hierarchy.
+
+ * "git push" and "git fetch" are taught to update refs in batches to
+   gain performance.
+
+ * Some code paths in "git prune" used to ignore the passed-in
+   repository object and used the `the_repository` singleton instance
+   instead, which has been corrected.
+
+ * Update ".clang-format" and ".editorconfig" to match our style guide
+   a bit better.
+
+ * "make coccicheck" succeeds even when spatch made suggestions, which
+   has been updated to fail in such a case.
+
+ * Code clean-up around object access API.
+
+ * Define .precision to more canned parse-options type to avoid bugs
+   coming from using a variable with a wrong type to capture the
+   parsed values.
+
+ * Flipping the default hash function to SHA-256 at Git 3.0 boundary
+   is planned.
+
+ * Declare weather-balloon we raised for "bool" type 18 months ago a
+   success and officially allow using the type in our codebase.
+
+ * GIT_TEST_INSTALLED was not honored in the recent topic related to
+   SHA256 hashes, which has been corrected.
+
+ * The pop_most_recent_commit() function can have quite expensive
+   worst case performance characteristics, which has been optimized by
+   using prio-queue data structure.
+
+ * Move structure definition from unrelated header file to where it
+   belongs.
+
+ * To help our developers, document what C99 language features are
+   being considered for adoption, in addition to what past experiments
+   have already decided.
+
+ * The reftable unit tests are now ported to the "clar" unit testing
+   framework.
+
+ * Redefine where the multi-pack-index sits in the object subsystem,
+   which recently was restructured to allow multiple backends that
+   support a single object source that belongs to one repository.  A
+   MIDX does span multiple "object sources".
+
+ * Reduce implicit assumption and dependence on the_repository in the
+   object-file subsystem.
+
+
+Fixes since v2.50
+-----------------
+
+Unless otherwise noted, all the changes in 2.50.X maintenance track,
+including security updates, are included in this release.
+
+ * A memory-leak in an error code path has been plugged.
+   (merge 7082da85cb ly/commit-graph-graph-write-leakfix later to maint).
+
+ * A memory-leak in an error code path has been plugged.
+   (merge aedebdb6b9 ly/fetch-pack-leakfix later to maint).
+
+ * Some leftover references to documentation source files that no
+   longer exist, due to recent ".txt" -> ".adoc" renaming, have been
+   corrected.
+   (merge 3717a5775a jw/doc-txt-to-adoc-refs later to maint).
+
+ * "git stash -p <pathspec>" improvements.
+   (merge 468817bab2 pw/stash-p-pathspec-fixes later to maint).
+
+ * "git send-email" incremented its internal message counter when a
+   message was edited, which made logic that treats the first message
+   specially misbehave, which has been corrected.
+   (merge 2cc27b3501 ag/send-email-edit-threading-fix later to maint).
+
+ * "git stash" recorded a wrong branch name when submodules are
+   present in the current checkout, which has been corrected.
+   (merge ffb36c64f2 kj/stash-onbranch-submodule-fix later to maint).
+
+ * When asking to apply mailmap to both author and committer field
+   while showing a commit object, the field that appears later was not
+   correctly parsed and replaced, which has been corrected.
+   (merge abf94a283f sa/multi-mailmap-fix later to maint).
+
+ * "git maintenance" lacked the care "git gc" had to avoid holding
+   onto the repository lock for too long during packing refs, which
+   has been remedied.
+   (merge 1b5074e614 ps/maintenance-ref-lock later to maint).
+
+ * Avoid regexp_constraint and instead use comparison_constraint when
+   listing functions to exclude from application of coccinelle rules,
+   as spatch can be built with different regexp engine X-<.
+   (merge f2ad545813 jc/cocci-avoid-regexp-constraint later to maint).
+
+ * Updating submodules from the upstream did not work well when
+   submodule's HEAD is detached, which has been improved.
+   (merge ca62f524c1 jk/submodule-remote-lookup-cleanup later to maint).
+
+ * Remove unnecessary check from "git daemon" code.
+   (merge 0c856224d2 cb/daemon-fd-check-fix later to maint).
+
+ * Use of sysctl() system call to learn the total RAM size used on
+   BSDs has been corrected.
+   (merge 781c1cf571 cb/total-ram-bsd-fix later to maint).
+
+ * Drop FreeBSD 4 support and declare that we support only FreeBSD 12
+   or later, which has memmem() supported.
+   (merge 0392f976a7 bs/config-mak-freebsd later to maint).
+
+ * A diff-filter with negative-only specification like "git log
+   --diff-filter=d" did not trigger correctly, which has been fixed.
+   (merge 375ac087c5 jk/all-negative-diff-filter-fix later to maint).
+
+ * A failure to open the index file for writing due to conflicting
+   access did not state what went wrong, which has been corrected.
+   (merge 9455397a5c hy/read-cache-lock-error-fix later to maint).
+
+ * Tempfile removal fix in the codepath to sign commits with SSH keys.
+   (merge 4498127b04 re/ssh-sign-buffer-fix later to maint).
+
+ * Code and test clean-up around string-list API.
+   (merge 6e5b26c3ff sj/string-list later to maint).
+
+ * "git apply -N" should start from the current index and register
+   only new files, but it instead started from an empty index, which
+   has been corrected.
+   (merge 2b49d97fcb rp/apply-intent-to-add-fix later to maint).
+
+ * Leakfix with a new and a bit invasive test on pack-bitmap files.
+   (merge bfd5522e98 ly/load-bitmap-leakfix later to maint).
+
+ * "git fetch --prune" used to be O(n^2) expensive when there are many
+   refs, which has been corrected.
+   (merge 87d8d8c5d0 ph/fetch-prune-optim later to maint).
+
+ * When a ref creation at refs/heads/foo/bar fails, the files backend
+   now removes refs/heads/foo/ if the directory is otherwise not used.
+   (merge a3a7f20516 ps/refs-files-remove-empty-parent later to maint).
+
+ * "pack-objects" has been taught to avoid pointing into objects in
+   cruft packs from midx.
+
+ * "git remote" now detects remote names that overlap with each other
+   (e.g., remote nickname "outer" and "outer/inner" are used at the
+   same time), as it will lead to overlapping remote-tracking
+   branches.
+   (merge a5a727c448 jk/remote-avoid-overlapping-names later to maint).
+
+ * The gpg.program configuration variable, which names a pathname to
+   the (custom) GPG compatible program, can now be spelled with ~tilde
+   expansion.
+   (merge 7d275cd5c0 jb/gpg-program-variable-is-a-pathname later to maint).
+
+ * Our <sane-ctype.h> header file relied on that the system-supplied
+   <ctype.h> header is not later included, which would override our
+   macro definitions, but "amazon linux" broke this assumption.  Fix
+   this by preemptively including <ctype.h> near the beginning of
+   <sane-ctype.h> ourselves.
+   (merge 9d3b33125f ps/sane-ctype-workaround later to maint).
+
+ * Clean-up compat/bswap.h mess.
+   (merge f4ac32c03a ss/compat-bswap-revamp later to maint).
+
+ * Meson-based build did not handle libexecdir setting correctly,
+   which has been corrected.
+   (merge 056dbe8612 rj/meson-libexecdir-fix later to maint).
+
+ * Document that we do not require "real" name when signing your
+   patches off.
+   (merge 1f0fed312a bc/contribution-under-non-real-names later to maint).
+
+ * "git commit" that concludes a conflicted merge failed to notice and remove
+   existing comment added automatically (like "# Conflicts:") when the
+   core.commentstring is set to 'auto'.
+   (merge 92b7c7c9f5 ac/auto-comment-char-fix later to maint).
+
+ * "git rebase -i" with bogus rebase.instructionFormat configuration
+   failed to produce the todo file after recording the state files,
+   leading to confused "git status"; this has been corrected.
+   (merge ade14bffd7 ow/rebase-verify-insn-fmt-before-initializing-state later to maint).
+
+ * A few file descriptors left unclosed upon program completion in a
+   few test helper programs are now closed.
+   (merge 0f1b33815b hl/test-helper-fd-close later to maint).
+
+ * Interactive prompt code did not correctly strip CRLF from the end
+   of line on Windows.
+   (merge 711a20827b js/prompt-crlf-fix later to maint).
+
+ * The config API had a set of convenience wrapper functions that
+   implicitly use the_repository instance; they have been removed and
+   inlined at the calling sites.
+
+ * "git add/etc -p" now honor the diff.context configuration variable,
+   and also they learn to honor the -U<n> command-line option.
+   (merge 2b3ae04011 lm/add-p-context later to maint).
+
+ * The case where a new submodule takes a path where there used to be a
+   completely different subproject is now dealt with a bit better than
+   before.
+   (merge 5ed8c5b465 kj/renamed-submodule later to maint).
+
+ * The deflate codepath in "git archive --format=zip" had a
+   longstanding bug coming from misuse of zlib API, which has been
+   corrected.
+
+ * Other code cleanup, docfix, build fix, etc.
+   (merge b257adb571 lo/my-first-ow-doc-update later to maint).
+   (merge 8b34b6a220 ly/sequencer-update-squash-is-fixup-only later to maint).
+   (merge 5dceb8bd05 ly/do-not-localize-bug-messages later to maint).
+   (merge 61372dd613 ly/commit-buffer-reencode-leakfix later to maint).
+   (merge 81cd1eef7d ly/pack-bitmap-root-leakfix later to maint).
+   (merge bfc9f9cc64 ly/submodule-update-failure-leakfix later to maint).
+   (merge 65dff89c6b ma/doc-diff-cc-headers later to maint).
+   (merge efb61591ee jm/bundle-uri-debug-output-to-fp later to maint).
+   (merge a3d278bb64 ly/prepare-show-merge-leakfix later to maint).
+   (merge 1fde1c5daf ac/preload-index-wo-the-repository later to maint).
+   (merge 855cfc65ae rm/t2400-modernize later to maint).
+   (merge 2939494284 ly/run-builtin-use-passed-in-repo later to maint).
+   (merge ff73f375bb jg/mailinfo-leakfix later to maint).
+   (merge 996f14c02b jj/doc-branch-markup-fix later to maint).
+   (merge 1e77de1864 cb/ci-freebsd-update-to-14.3 later to maint).
+   (merge b0e9d25865 jk/fix-leak-send-pack later to maint).
+   (merge f3a9558c8c bs/remote-helpers-doc-markup-fix later to maint).
+   (merge c4e9775c60 kh/doc-config-subcommands later to maint).
+   (merge de404249ab ps/perlless-test-fixes later to maint).
+   (merge 953049eed8 ts/merge-orig-head-doc-fix later to maint).
+   (merge 0c83bbc704 rj/freebsd-sysinfo-build-fix later to maint).
+   (merge ad7780b38f ps/doc-pack-refs-auto-with-files-backend-fix later to maint).
+   (merge f4fa8a3687 rh/doc-glob-pathspec-fix later to maint).
+   (merge b27be108c8 ja/doc-git-log-markup later to maint).
+   (merge 14d7583beb pw/config-kvi-remove-path later to maint).
+   (merge f31abb421d jc/do-not-scan-argv-without-parsing later to maint).
+   (merge 26552cb62a jk/unleak-reflog-expire-entry later to maint).
+   (merge 339d95fda9 jc/ci-print-test-failures-fix later to maint).
+   (merge 8c3add51a8 cb/meson-avoid-broken-macos-pcre2 later to maint).
+   (merge 5247da07b8 ps/meson-clar-decls-fix later to maint).
+   (merge f3ef347bb2 ch/t7450-recursive-clone-test-fix later to maint).
+   (merge 4ac3302a1a jc/doc-release-vs-clear later to maint).
+   (merge 3bdd897413 ms/meson-with-ancient-git-wo-ls-files-dedup later to maint).
+   (merge cca758d324 kh/doc-fast-import-historical later to maint).
+   (merge 9b0781196a jc/test-hashmap-is-still-here later to maint).
+   (merge 1bad05bacc jk/revert-squelch-compiler-warning later to maint).
+   (merge 3a7e783d9c dl/squelch-maybe-uninitialized later to maint).
diff --git a/Documentation/RelNotes/2.51.1.adoc b/Documentation/RelNotes/2.51.1.adoc
new file mode 100644
index 0000000000..b8bd49c876
--- /dev/null
+++ b/Documentation/RelNotes/2.51.1.adoc
@@ -0,0 +1,99 @@
+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 instructions for using 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 be formatted the way we
+   had them traditionally, e.g., "for_each_string_list_item()" without
+   space before the parentheses.
+
+ * A few places where a 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 around this problem.
+
+ * Adjust to the way newer versions of cURL selectively enable tracing
+   options, so that our tests can continue to work.
+
+ * During interactive rebase, using 'drop' on a merge commit led to
+   an error, which has been corrected.
+
+ * "git refs migrate" to migrate the reflog entries from a refs
+   backend to another had a handful of bugs squashed.
+
+ * "git push" had a code path that led to BUG() but it should have
+   been a die(), as it is a response to a usual but invalid end-user
+   action to attempt pushing an object that does not exist.
+
+ * Various bugs about rename handling in "ort" merge strategy have
+   been fixed.
+
+ * "git diff --no-index" run inside a subdirectory under control of a
+   Git repository operated at the top of the working tree and stripped
+   the prefix from the output, and oddballs like "-" (stdin) did not
+   work correctly because of it.  Correct the set-up by undoing what
+   the set-up sequence did to cwd and prefix.
+
+ * Various options to "git diff" that make comparison ignore certain
+   aspects of the differences (like "space changes are ignored",
+   "differences in lines that match these regular expressions are
+   ignored") did not work well with "--name-only" and friends.
+
+ * Under a race against another process that is repacking the
+   repository, especially a partially cloned one, "git fetch" may
+   mistakenly think some objects we do have are missing, which has
+   been corrected.
+
+ * "git repack --path-walk" lost objects in some corner cases, which
+   has been corrected.
+   cf. <CABPp-BHFxxGrqKc0m==TjQNjDGdO=H5Rf6EFsf2nfE1=TuraOQ@mail.gmail.com>
+
+ * Fixes multiple crashes around midx write-out codepaths.
+
+ * A broken or malicious "git fetch" can say that it has the same
+   object for many many times, and the upload-pack serving it can
+   exhaust memory storing them redundantly, which has been corrected.
+
+ * A corner case bug in "git log -L..." has been corrected.
+
+ * Some among "git add -p" and friends ignored color.diff and/or
+   color.ui configuration variables, which is an old regression, which
+   has been corrected.
+
+ * "git rebase -i" failed to clean-up the commit log message when the
+   command commits the final one in a chain of "fixup" commands, which
+   has been corrected.
+
+ * Deal more gracefully with directory / file conflicts when the files
+   backend is used for ref storage, by failing only the ones that are
+   involved in the conflict while allowing others.
+
+Also contains various documentation updates, code cleanups and minor fixups.
diff --git a/Documentation/RelNotes/2.51.2.adoc b/Documentation/RelNotes/2.51.2.adoc
new file mode 100644
index 0000000000..f0be60333a
--- /dev/null
+++ b/Documentation/RelNotes/2.51.2.adoc
@@ -0,0 +1,45 @@
+Git 2.51.2 Release Notes
+========================
+
+In addition to fixes for an unfortunate regression introduced in Git
+2.51.1 that caused "git diff --quiet -w" to be not so quiet when there
+are additions, deletions and conflicts, this maintenance release merges
+more fixes/improvements that have landed on the master front, primarily
+to make the CI part of the system a bit more robust.
+
+
+Fixes since Git 2.51.1
+----------------------
+
+ * Recently we attempted to improve "git diff -w --quiet" and friends
+   to handle cases where patch output would be suppressed, but it
+   introduced a bug that emits unnecessary output, which has been
+   corrected.
+
+ * The code to squelch output from "git diff -w --name-status"
+   etc. for paths that "git diff -w -p" would have stayed silent
+   leaked output from dry-run patch generation, which has been
+   corrected.
+
+ * Windows "real-time monitoring" interferes with the execution of
+   tests and affects negatively in both correctness and performance,
+   which has been disabled in Gitlab CI.
+
+ * An earlier addition to "git diff --no-index A B" to limit the
+   output with pathspec after the two directories misbehaved when
+   these directories were given with a trailing slash, which has been
+   corrected.
+
+ * The "--short" option of "git status" that meant output for humans
+   and "-z" option to show NUL delimited output format did not mix
+   well, and colored some but not all things.  The command has been
+   updated to color all elements consistently in such a case.
+
+ * Unicode width table update.
+
+ * Recent OpenSSH creates the Unix domain socket to communicate with
+   ssh-agent under $HOME instead of /tmp, which causes our test to
+   fail doe to overly long pathname in our test environment, which has
+   been worked around by using "ssh-agent -T".
+
+Also contains various documentation updates, code cleanups and minor fixups.
diff --git a/Documentation/RelNotes/2.52.0.adoc b/Documentation/RelNotes/2.52.0.adoc
new file mode 100644
index 0000000000..ba213c0d6c
--- /dev/null
+++ b/Documentation/RelNotes/2.52.0.adoc
@@ -0,0 +1,411 @@
+Git v2.52 Release Notes
+=======================
+
+UI, Workflows & Features
+------------------------
+
+ * The "list" subcommand of "git refs" acts as a front-end for
+   "git for-each-ref".
+
+ * "git cmd --help-all" now works outside repositories.
+
+ * "git diff-tree" learned "--max-depth" option.
+
+ * A new subcommand "git repo" gives users a way to grab various
+   repository characteristics.
+
+ * A new command "git last-modified" has been added to show the closest
+   ancestor commit that touched each path.
+
+ * "git refs exists" that works like "git show-ref --exists" has been
+   added.
+
+ * "repo info" learns a short-hand option "-z" that is the same as
+   "--format=nul", and learns to report the objects format used in the
+   repository.
+
+ * "core.commentChar=auto" that attempts to dynamically pick a
+   suitable comment character is non-workable, as it is too much
+   trouble to support for little benefit, and is marked as deprecated.
+
+ * "git send-email" learned to drive "git imap-send" to store already
+   sent e-mails in an IMAP folder.
+
+ * The "promisor-remote" capability mechanism has been updated to
+   allow the "partialCloneFilter" settings and the "token" value to be
+   communicated from the server side.
+
+ * Declare that "git init" that is not otherwise configured uses
+   'main' as the initial branch, not 'master', starting Git 3.0.
+
+ * Keep giving hint about the default initial branch name for users
+   who may be surprised after Git 3.0 switch-over.
+
+ * The stash.index configuration variable can be set to make "git stash
+   pop/apply" pretend that it was invoked with "--index".
+
+ * "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.
+
+ * Show 'P'ipe command in "git add -p".
+
+ * "git sparse-checkout" subcommand learned a new "clean" action to
+   prune otherwise unused working-tree files that are outside the
+   areas of interest.
+
+ * "git fast-import" is taught to handle signed tags, just like it
+   recently learned to handle signed commits, in different ways.
+
+ * A new configuration variable commitGraph.changedPaths allows to
+   turn "--changed-paths" on by default for "git commit-graph".
+
+ * "Symlink symref" has been added to the list of things that will
+   disappear at Git 3.0 boundary.
+
+ * "git maintenance" command learns the "geometric" strategy where it
+   avoids doing maintenance tasks that rebuilds everything from
+   scratch.
+
+
+Performance, Internal Implementation, Development Support etc.
+--------------------------------------------------------------
+
+ * string_list_split*() family of functions have been extended to
+   simplify common use cases.
+
+ * Arrays of strbuf is often a wrong data structure to use, and
+   strbuf_split*() family of functions that create them often have
+   better alternatives.  Update several code paths and replace
+   strbuf_split*().
+
+ * Revision traversal limited with pathspec, like "git log dir/*",
+   used to ignore changed-paths Bloom filter when the pathspec
+   contained wildcards; now they take advantage of the filter when
+   they can.
+
+ * Doc lint updates to encourage the newer and easier-to-use
+   `synopsis` format, with fixes to a handful of existing uses.
+
+ * Remove dependency on the_repository and other globals from the
+   commit-graph code, and other changes unrelated to de-globaling.
+
+ * Discord has been added to the first contribution documentation as
+   another way to ask for help.
+
+ * Inspired by Ezekiel's recent effort to showcase Rust interface, the
+   hash function implementation used to hash lines have been updated
+   to the one used for ELF symbol lookup by Glibc.
+
+ * Instead of scanning for the remaining items to see if there are
+   still commits to be explored in the queue, use khash to remember
+   which items are still on the queue (an unacceptable alternative is
+   to reserve one object flag bits).
+
+ * The bulk-checkin code used to depend on a file-scope static
+   singleton variable, which has been updated to pass an instance
+   throughout the callchain.
+
+ * The work to build on the bulk-checkin infrastructure to create many
+   objects at once in a transaction and to abstract it into the
+   generic object layer continues.
+
+ * CodingGuidelines now spells out how bitfields are to be written.
+
+ * Adjust to the way newer versions of cURL selectively enable tracing
+   options, so that our tests can continue to work.
+
+ * The clear_alloc_state() API function was not fully clearing the
+   structure for reuse, but since nobody reuses it, replace it with a
+   variant that frees the structure as well, making the callers simpler.
+
+ * "git range-diff" learned a way to limit the memory consumed by
+   O(N*N) cost matrix.
+
+ * Some places in the code confused a variable that is *not* a boolean
+   to enable color but is an enum that records what the user requested
+   to do about color.  A couple of bugs of this sort have been fixed,
+   while the code has been cleaned up to prevent similar bugs in the
+   future.
+
+ * The build procedure based on meson learned a target to only build
+   documentation, similar to "make doc".
+   (merge ff4ec8ded0 ps/meson-build-docs later to maint).
+
+ * 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.
+
+ * Instead of three library archives (one for git, one for reftable,
+   and one for xdiff), roll everything into a single libgit.a archive.
+   This would help later effort to FFI into Rust.
+
+ * The beginning of SHA1-SHA256 interoperability work.
+
+ * Build procedure for a few credential helpers (in contrib/) have
+   been updated.
+
+ * CI improvements to handle the recent Rust integration better.
+
+ * The code in "git repack" machinery has been cleaned up to prepare
+   for incremental update of midx files.
+
+ * Two slightly different ways to get at "all the packfiles" in API
+   has been cleaned up.
+
+ * The code to walk revision graph to compute merge base has been
+   optimized.
+
+
+Fixes since v2.51
+-----------------
+
+Unless otherwise noted, all the changes in 2.51.X maintenance track,
+including security updates, are included in this release.
+
+ * During interactive rebase, using 'drop' on a merge commit lead to
+   an error, which was incorrect.
+
+ * "git refs migrate" to migrate the reflog entries from a refs
+   backend to another had a handful of bugs squashed.
+
+ * "git remote rename origin upstream" failed to move origin/HEAD to
+   upstream/HEAD when origin/HEAD is unborn and performed other
+   renames extremely inefficiently, which has been corrected.
+   (merge 16c4fa26b9 ps/remote-rename-fix later to maint).
+
+ * "git describe" has been optimized by using better data structure.
+   (merge 08bb69d70f rs/describe-with-prio-queue later to maint).
+
+ * "git push" had a code path that led to BUG() but it should have
+   been a die(), as it is a response to a usual but invalid end-user
+   action to attempt pushing an object that does not exist.
+
+ * Various bugs about rename handling in "ort" merge strategy have
+   been fixed.
+
+ * "git jump" (in contrib/) fails to parse the diff header correctly
+   when a file has a space in its name, which has been corrected.
+   (merge 621ce9c1c6 gh/git-jump-pathname-with-sp later to maint).
+
+ * "git diff --no-index" run inside a subdirectory under control of a
+   Git repository operated at the top of the working tree and stripped
+   the prefix from the output, and oddballs like "-" (stdin) did not
+   work correctly because of it.  Correct the set-up by undoing what
+   the set-up sequence did to cwd and prefix.
+
+ * Various options to "git diff" that makes comparison ignore certain
+   aspects of the differences (like "space changes are ignored",
+   "differences in lines that match these regular expressions are
+   ignored") did not work well with "--name-only" and friends.
+   (merge b55e6d36eb ly/diff-name-only-with-diff-from-content later to maint).
+
+ * The above caused regressions, which has been corrected.
+
+ * Documentation for "git rebase" has been updated.
+   (merge 3f7f2b0359 je/doc-rebase later to maint).
+
+ * 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.
+
+ * 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.
+
+ * "git log -L..." compared trees of multiple parents with the tree of the
+   merge result in an unnecessarily inefficient way.
+   (merge 0a15bb634c sg/line-log-merge-optim later to maint).
+
+ * Under a race against another process that is repacking the
+   repository, especially a partially cloned one, "git fetch" may
+   mistakenly think some objects we do have are missing, which has
+   been corrected.
+
+ * "git fetch" can clobber a symref that is dangling when the
+   remote-tracking HEAD is set to auto update, which has been
+   corrected.
+
+ * "git describe <blob>" misbehaves and/or crashes in some corner
+   cases, which has been taught to exit with failure gracefully.
+   (merge 7c10e48e81 jk/describe-blob later to maint).
+
+ * Manual page for "gitk" is updated with the current maintainer's
+   name.
+
+ * Update the instructions for using GGG in the MyFirstContribution
+   document to say that a GitHub PR could be made against `git/git`
+   instead of `gitgitgadget/git`.
+
+ * Makefile tried to run multiple "cargo build" which would not work
+   very well; serialize their execution to work around this problem.
+
+ * "git repack --path-walk" lost objects in some corner cases, which
+   has been corrected.
+
+ * "git ls-files <pathspec>..." should not necessarily have to expand
+   the index fully if a sparsified directory is excluded by the
+   pathspec; the code is taught to expand the index on demand to avoid
+   this.
+   (merge 681f26bccc ds/ls-files-lazy-unsparse later to maint).
+
+ * Windows "real-time monitoring" interferes with the execution of
+   tests and affects negatively in both correctness and performance,
+   which has been disabled in Gitlab CI.
+
+ * A broken or malicious "git fetch" can say that it has the same
+   object for many many times, and the upload-pack serving it can
+   exhaust memory storing them redundantly, which has been corrected.
+
+ * A corner case bug in "git log -L..." has been corrected.
+
+ * "git rev-parse --short" and friends failed to disambiguate two
+   objects with object names that share common prefix longer than 32
+   characters, which has been fixed.
+   (merge 8655908b9e jc/longer-disambiguation-fix later to maint).
+
+ * Some among "git add -p" and friends ignored color.diff and/or
+   color.ui configuration variables, which is an old regression, which
+   has been corrected.
+
+ * "git subtree" (in contrib/) did not work correctly when splitting
+   squashed subtrees, which has been improved.
+
+ * Import a newer version of the clar unit testing framework.
+   (merge 93dbb6b3c5 ps/clar-updates later to maint).
+
+ * "git send-email --compose --reply-to=<address>" used to add
+   duplicated Reply-To: header, which made mailservers unhappy.  This
+   has been corrected.
+   (merge f448f65719 nb/send-email-no-dup-reply-to later to maint).
+
+ * "git rebase -i" failed to clean-up the commit log message when the
+   command commits the final one in a chain of "fixup" commands, which
+   has been corrected.
+
+ * There are double frees and leaks around setup_revisions() API used
+   in "git stash show", which has been fixed, and setup_revisions()
+   API gained a wrapper to make it more ergonomic when using it with
+   strvec-manged argc/argv pairs.
+   (merge a04bc71725 jk/setup-revisions-freefix later to maint).
+
+ * Deal more gracefully with directory / file conflicts when the files
+   backend is used for ref storage, by failing only the ones that are
+   involved in the conflict while allowing others.
+
+ * "git last-modified" operating in non-recursive mode used to trigger
+   a BUG(), which has been corrected.
+
+ * The use of "git config get" command to learn how ANSI color
+   sequence is for a particular type, e.g., "git config get
+   --type=color --default=reset no.such.thing", isn't very ergonomic.
+   (merge e4dabf4fd6 ps/config-get-color-fixes later to maint).
+
+ * The "do you still use it?" message given by a command that is
+   deeply deprecated and allow us to suggest alternatives has been
+   updated.
+
+ * Clang-format update to let our control macros be formatted the way we
+   had them traditionally, e.g., "for_each_string_list_item()" without
+   space before the parentheses.
+
+ * A few places where a size_t value was cast to curl_off_t without
+   checking has been updated to use the existing helper function.
+
+ * "git reflog write" did not honor the configured user.name/email
+   which has been corrected.
+
+ * Handling of an empty subdirectory of .git/refs/ in the ref-files
+   backend has been corrected.
+
+ * Our CI script requires "sudo" that can be told to preserve
+   environment, but Ubuntu replaced with "sudo" with an implementation
+   that lacks the feature.  Work this around by reinstalling the
+   original version.
+
+ * The reftable backend learned to sanity check its on-disk data more
+   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.
+
+ * The code in "git add -p" and friends to iterate over hunks was
+   riddled with bugs, which has been corrected.
+
+ * A few more things that patch authors can do to help maintainer to
+   keep track of their topics better.
+   (merge 1a41698841 tb/doc-submitting-patches later to maint).
+
+ * An earlier addition to "git diff --no-index A B" to limit the
+   output with pathspec after the two directories misbehaved when
+   these directories were given with a trailing slash, which has been
+   corrected.
+
+ * The "--short" option of "git status" that meant output for humans
+   and "-z" option to show NUL delimited output format did not mix
+   well, and colored some but not all things.  The command has been
+   updated to color all elements consistently in such a case.
+
+ * Unicode width table update.
+
+ * GPG signing test set-up has been broken for a year, which has been
+   corrected.
+   (merge 516bf45749 jc/t1016-setup-fix later to maint).
+
+ * Recent OpenSSH creates the Unix domain socket to communicate with
+   ssh-agent under $HOME instead of /tmp, which causes our test to
+   fail doe to overly long pathname in our test environment, which has
+   been worked around by using "ssh-agent -T".
+
+ * strbuf_split*() to split a string into multiple strbufs is often a
+   wrong API to use.  A few uses of it have been removed by
+   simplifying the code.
+   (merge 2ab72a16d9 ob/gpg-interface-cleanup later to maint).
+
+ * "git shortlog" knows "--committer" and "--author" options, which
+   the command line completion (in contrib/) did not handle well,
+   which has been corrected.
+   (merge c568fa8e1c kf/log-shortlog-completion-fix later to maint).
+
+ * "git bisect" command did not react correctly to "git bisect help"
+   and "git bisect unknown", which has been corrected.
+   (merge 2bb3a012f3 rz/bisect-help-unknown later to maint).
+
+ * The 'q'(uit) command in "git add -p" has been improved to quit
+   without doing any meaningless work before leaving, and giving EOF
+   (typically control-D) to the prompt is made to behave the same way.
+
+ * The wildmatch code had a corner case bug that mistakenly makes
+   "foo**/bar" match with "foobar", which has been corrected.
+   (merge 1940a02dc1 jk/match-pathname-fix later to maint).
+
+ * Other code cleanup, docfix, build fix, etc.
+   (merge 529a60a885 ua/t1517-short-help-tests later to maint).
+   (merge 22d421fed9 ac/deglobal-fmt-merge-log-config later to maint).
+   (merge a60203a015 dk/t7005-editor-updates later to maint).
+   (merge 16684b6fae ps/reftable-libgit2-cleanup later to maint).
+   (merge e5c27bd3d8 je/doc-add later to maint).
+   (merge 13296ac909 ps/object-store-midx-dedup-info later to maint).
+   (merge f9a6705d9a tc/t0450-harden later to maint).
+   (merge a66fc22bf9 rs/get-oid-with-flags-cleanup later to maint).
+   (merge 15b8abde07 js/mingw-includes-cleanup later to maint).
+   (merge 2cebca0582 tb/cat-file-objectmode-update later to maint).
+   (merge 8f487db07a kh/doc-patch-id-1 later to maint).
diff --git a/Documentation/RelNotes/2.6.0.txt b/Documentation/RelNotes/2.6.0.adoc
index 7288aaf716..7288aaf716 100644
--- a/Documentation/RelNotes/2.6.0.txt
+++ b/Documentation/RelNotes/2.6.0.adoc
diff --git a/Documentation/RelNotes/2.6.1.txt b/Documentation/RelNotes/2.6.1.adoc
index f37ea89cda..f37ea89cda 100644
--- a/Documentation/RelNotes/2.6.1.txt
+++ b/Documentation/RelNotes/2.6.1.adoc
diff --git a/Documentation/RelNotes/2.6.2.txt b/Documentation/RelNotes/2.6.2.adoc
index 5b65e35245..5b65e35245 100644
--- a/Documentation/RelNotes/2.6.2.txt
+++ b/Documentation/RelNotes/2.6.2.adoc
diff --git a/Documentation/RelNotes/2.6.3.txt b/Documentation/RelNotes/2.6.3.adoc
index fc6fe1711f..fc6fe1711f 100644
--- a/Documentation/RelNotes/2.6.3.txt
+++ b/Documentation/RelNotes/2.6.3.adoc
diff --git a/Documentation/RelNotes/2.6.4.txt b/Documentation/RelNotes/2.6.4.adoc
index b0256a2dc9..b0256a2dc9 100644
--- a/Documentation/RelNotes/2.6.4.txt
+++ b/Documentation/RelNotes/2.6.4.adoc
diff --git a/Documentation/RelNotes/2.6.5.txt b/Documentation/RelNotes/2.6.5.adoc
index f0924b62e0..f0924b62e0 100644
--- a/Documentation/RelNotes/2.6.5.txt
+++ b/Documentation/RelNotes/2.6.5.adoc
diff --git a/Documentation/RelNotes/2.6.6.txt b/Documentation/RelNotes/2.6.6.adoc
index 023ad85ec6..023ad85ec6 100644
--- a/Documentation/RelNotes/2.6.6.txt
+++ b/Documentation/RelNotes/2.6.6.adoc
diff --git a/Documentation/RelNotes/2.6.7.txt b/Documentation/RelNotes/2.6.7.adoc
index 1335de49a6..1335de49a6 100644
--- a/Documentation/RelNotes/2.6.7.txt
+++ b/Documentation/RelNotes/2.6.7.adoc
diff --git a/Documentation/RelNotes/2.7.0.txt b/Documentation/RelNotes/2.7.0.adoc
index e3cbf3a73c..e3cbf3a73c 100644
--- a/Documentation/RelNotes/2.7.0.txt
+++ b/Documentation/RelNotes/2.7.0.adoc
diff --git a/Documentation/RelNotes/2.7.1.txt b/Documentation/RelNotes/2.7.1.adoc
index 6323feaf64..6323feaf64 100644
--- a/Documentation/RelNotes/2.7.1.txt
+++ b/Documentation/RelNotes/2.7.1.adoc
diff --git a/Documentation/RelNotes/2.7.2.txt b/Documentation/RelNotes/2.7.2.adoc
index 4feef76704..4feef76704 100644
--- a/Documentation/RelNotes/2.7.2.txt
+++ b/Documentation/RelNotes/2.7.2.adoc
diff --git a/Documentation/RelNotes/2.7.3.txt b/Documentation/RelNotes/2.7.3.adoc
index f618d71efd..f618d71efd 100644
--- a/Documentation/RelNotes/2.7.3.txt
+++ b/Documentation/RelNotes/2.7.3.adoc
diff --git a/Documentation/RelNotes/2.7.4.txt b/Documentation/RelNotes/2.7.4.adoc
index 883ae896fe..883ae896fe 100644
--- a/Documentation/RelNotes/2.7.4.txt
+++ b/Documentation/RelNotes/2.7.4.adoc
diff --git a/Documentation/RelNotes/2.7.5.txt b/Documentation/RelNotes/2.7.5.adoc
index 83559ce3b2..83559ce3b2 100644
--- a/Documentation/RelNotes/2.7.5.txt
+++ b/Documentation/RelNotes/2.7.5.adoc
diff --git a/Documentation/RelNotes/2.7.6.txt b/Documentation/RelNotes/2.7.6.adoc
index 4c6d1dcd4a..4c6d1dcd4a 100644
--- a/Documentation/RelNotes/2.7.6.txt
+++ b/Documentation/RelNotes/2.7.6.adoc
diff --git a/Documentation/RelNotes/2.8.0.txt b/Documentation/RelNotes/2.8.0.adoc
index 38453281b8..38453281b8 100644
--- a/Documentation/RelNotes/2.8.0.txt
+++ b/Documentation/RelNotes/2.8.0.adoc
diff --git a/Documentation/RelNotes/2.8.1.txt b/Documentation/RelNotes/2.8.1.adoc
index ef6d80b008..ef6d80b008 100644
--- a/Documentation/RelNotes/2.8.1.txt
+++ b/Documentation/RelNotes/2.8.1.adoc
diff --git a/Documentation/RelNotes/2.8.2.txt b/Documentation/RelNotes/2.8.2.adoc
index 447b1933a8..447b1933a8 100644
--- a/Documentation/RelNotes/2.8.2.txt
+++ b/Documentation/RelNotes/2.8.2.adoc
diff --git a/Documentation/RelNotes/2.8.3.txt b/Documentation/RelNotes/2.8.3.adoc
index a63825ed87..a63825ed87 100644
--- a/Documentation/RelNotes/2.8.3.txt
+++ b/Documentation/RelNotes/2.8.3.adoc
diff --git a/Documentation/RelNotes/2.8.4.txt b/Documentation/RelNotes/2.8.4.adoc
index f4e2552836..f4e2552836 100644
--- a/Documentation/RelNotes/2.8.4.txt
+++ b/Documentation/RelNotes/2.8.4.adoc
diff --git a/Documentation/RelNotes/2.8.5.txt b/Documentation/RelNotes/2.8.5.adoc
index 7bd179fa12..7bd179fa12 100644
--- a/Documentation/RelNotes/2.8.5.txt
+++ b/Documentation/RelNotes/2.8.5.adoc
diff --git a/Documentation/RelNotes/2.8.6.txt b/Documentation/RelNotes/2.8.6.adoc
index d8db55d920..d8db55d920 100644
--- a/Documentation/RelNotes/2.8.6.txt
+++ b/Documentation/RelNotes/2.8.6.adoc
diff --git a/Documentation/RelNotes/2.9.0.txt b/Documentation/RelNotes/2.9.0.adoc
index 991640119a..991640119a 100644
--- a/Documentation/RelNotes/2.9.0.txt
+++ b/Documentation/RelNotes/2.9.0.adoc
diff --git a/Documentation/RelNotes/2.9.1.txt b/Documentation/RelNotes/2.9.1.adoc
index 338394097e..338394097e 100644
--- a/Documentation/RelNotes/2.9.1.txt
+++ b/Documentation/RelNotes/2.9.1.adoc
diff --git a/Documentation/RelNotes/2.9.2.txt b/Documentation/RelNotes/2.9.2.adoc
index 2620003dcf..2620003dcf 100644
--- a/Documentation/RelNotes/2.9.2.txt
+++ b/Documentation/RelNotes/2.9.2.adoc
diff --git a/Documentation/RelNotes/2.9.3.txt b/Documentation/RelNotes/2.9.3.adoc
index 305e08062b..305e08062b 100644
--- a/Documentation/RelNotes/2.9.3.txt
+++ b/Documentation/RelNotes/2.9.3.adoc
diff --git a/Documentation/RelNotes/2.9.4.txt b/Documentation/RelNotes/2.9.4.adoc
index 9768293831..9768293831 100644
--- a/Documentation/RelNotes/2.9.4.txt
+++ b/Documentation/RelNotes/2.9.4.adoc
diff --git a/Documentation/RelNotes/2.9.5.txt b/Documentation/RelNotes/2.9.5.adoc
index 668313ae55..668313ae55 100644
--- a/Documentation/RelNotes/2.9.5.txt
+++ b/Documentation/RelNotes/2.9.5.adoc
diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.adoc
index 6534643cff..6534643cff 100644
--- a/Documentation/ReviewingGuidelines.txt
+++ b/Documentation/ReviewingGuidelines.adoc
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 958e3cc3d5..e270ccbe85 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -408,8 +408,15 @@ your patch differs from project to project, so it may be different
 from that of the project you are accustomed to.
 
 [[real-name]]
-Also notice that a real name is used in the `Signed-off-by` trailer. Please
-don't hide your real name.
+Please use a known identity in the `Signed-off-by` trailer, since we cannot
+accept anonymous contributions. It is common, but not required, to use some form
+of your real name. We realize that some contributors are not comfortable doing
+so or prefer to contribute under a pseudonym or preferred name and we can accept
+your patch either way, as long as the name and email you use are distinctive,
+identifying, and not misleading.
+
+The goal of this policy is to allow us to have sufficient information to contact
+you if questions arise about your contribution.
 
 [[commit-trailers]]
 If you like, you can put extra trailers at the end:
@@ -439,6 +446,34 @@ highlighted above.
 Only capitalize the very first letter of the trailer, i.e. favor
 "Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
 
+[[ai]]
+=== Use of Artificial Intelligence (AI)
+
+The Developer's Certificate of Origin requires contributors to certify
+that they know the origin of their contributions to the project and
+that they have the right to submit it under the project's license.
+It's not yet clear that this can be legally satisfied when submitting
+significant amount of content that has been generated by AI tools.
+
+Another issue with AI generated content is that AIs still often
+hallucinate or just produce bad code, commit messages, documentation
+or output, even when you point out their mistakes.
+
+To avoid these issues, we will reject anything that looks AI
+generated, that sounds overly formal or bloated, that looks like AI
+slop, that looks good on the surface but makes no sense, or that
+senders don’t understand or cannot explain.
+
+We strongly recommend using AI tools carefully and responsibly.
+
+Contributors would often benefit more from AI by using it to guide and
+help them step by step towards producing a solution by themselves
+rather than by asking for a full solution that they would then mostly
+copy-paste. They can also use AI to help with debugging, or with
+checking for obvious mistakes, things that can be improved, things
+that don’t match our style, guidelines or our feedback, before sending
+it to us.
+
 [[git-tools]]
 === Generate your patch using Git tools out of your commits.
 
@@ -572,14 +607,27 @@ line via `git format-patch --notes`.
 [[the-topic-summary]]
 *This is EXPERIMENTAL*.
 
-When sending a topic, you can propose a one-paragraph summary that
-should appear in the "What's cooking" report when it is picked up to
-explain the topic.  If you choose to do so, please write a 2-5 line
-paragraph that will fit well in our release notes (see many bulleted
-entries in the Documentation/RelNotes/* files for examples), and make
-it the first paragraph of the cover letter.  For a single-patch
-series, use the space between the three-dash line and the diffstat, as
-described earlier.
+When sending a topic, you can optionally propose a topic name and/or a
+one-paragraph summary that should appear in the "What's cooking"
+report when it is picked up to explain the topic.  If you choose to do
+so, please write a 2-5 line paragraph that will fit well in our
+release notes (see many bulleted entries in the
+Documentation/RelNotes/* files for examples), and make it the first
+(or second, if including a suggested topic name) paragraph of the
+cover letter.  If suggesting a topic name, use the format
+"XX/your-topic-name", where "XX" is a stand-in for the primary
+author's initials, and "your-topic-name" is a brief, dash-delimited
+description of what your topic does.  For a single-patch series, use
+the space between the three-dash line and the diffstat, as described
+earlier.
+
+[[multi-series-efforts]]
+If your patch series is part of a larger effort spanning multiple
+patch series, briefly describe the broader goal, and state where the
+current series fits into that goal.  If you are suggesting a topic
+name as in <<the-topic-summary, section above>>, consider
+"XX/the-broader-goal-part-one", "XX/the-broader-goal-part-two", and so
+on.
 
 [[attachment]]
 Do not attach the patch as a MIME attachment, compressed or not.
diff --git a/Documentation/ToolsForGit.txt b/Documentation/ToolsForGit.adoc
index ae7690b45d..a842c13327 100644
--- a/Documentation/ToolsForGit.txt
+++ b/Documentation/ToolsForGit.adoc
@@ -34,6 +34,7 @@ This is adapted from Linux's suggestion in its CodingStyle document:
 
 - To follow the rules in CodingGuidelines, it's useful to put the following in
 GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
+
 ----
 ;; note the first part is useful for C editing, too
 ((nil . ((indent-tabs-mode . t)
diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in
index f2aef6cb79..ff9ea0a294 100644
--- a/Documentation/asciidoc.conf.in
+++ b/Documentation/asciidoc.conf.in
@@ -43,7 +43,7 @@ ifdef::doctype-book[]
 endif::doctype-book[]
 
 [literal-inlinemacro]
-{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$%]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
 
 endif::backend-docbook[]
 
@@ -75,18 +75,18 @@ git-relative-html-prefix=
 <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
 
 [literal-inlinemacro]
-{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\\\*\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
 
 endif::backend-xhtml11[]
 
 ifdef::backend-docbook[]
 ifdef::doctype-manpage[]
 [paradef-default]
-synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
+synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<emphasis>\\0</emphasis>!g'"
 endif::doctype-manpage[]
 endif::backend-docbook[]
 
 ifdef::backend-xhtml11[]
 [paradef-default]
-synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
+synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
 endif::backend-xhtml11[]
diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in
index 2494f17a51..fe64a62d96 100644
--- a/Documentation/asciidoctor-extensions.rb.in
+++ b/Documentation/asciidoctor-extensions.rb.in
@@ -49,8 +49,8 @@ module Git
 
       def process parent, reader, attrs
         outlines = reader.lines.map do |l|
-          l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
-           .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
+          l.gsub(/(\.\.\.?)([^\]$\. ])/, '{empty}`\1`{empty}\2')
+           .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}')
            .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
            .gsub(']', ']{empty}')
         end
@@ -71,8 +71,9 @@ module Git
           # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
           %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
         elsif type == :monospaced
-          node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
-              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
+          node.text.gsub(/(\.\.\.?)([^\]$\.])/, '<literal>\1</literal>\2')
+              .gsub(/^\.\.\.?$/, '<literal>\0</literal>')
+              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*%]+\.{0,2})+|,)}, '\1<literal>\2</literal>')
               .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
         else
           open, close, supports_phrase = QUOTE_TAGS[type]
@@ -100,7 +101,8 @@ module Git
       def convert_inline_quoted node
         if node.type == :monospaced
           node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
-              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
+              .gsub(/^\.\.\.?$/, '<code>\0</code>')
+              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*%]+\.{0,2})+)}, '\1<code>\2</code>')
               .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
 
         else
diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.adoc
index 552dcc60f2..1fb948fc76 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.adoc
@@ -18,7 +18,7 @@
 '<start>' and '<end>' are optional. `-L <start>` or `-L <start>,` spans from
 '<start>' to end of file. `-L ,<end>` spans from start of file to '<end>'.
 +
-include::line-range-format.txt[]
+include::line-range-format.adoc[]
 
 -l::
 	Show long rev (Default: off).
@@ -75,7 +75,8 @@ include::line-range-format.txt[]
 	iso format is used. For supported values, see the discussion
 	of the --date option at linkgit:git-log[1].
 
---[no-]progress::
+--progress::
+--no-progress::
 	Progress status is reported on the standard error stream
 	by default when it is attached to a terminal. This flag
 	enables progress reporting even if not attached to a
@@ -125,7 +126,8 @@ take effect.
 	another commit will be marked with a `?` in the blame output.  If the
 	`blame.markUnblamableLines` config option is set, then those lines touched
 	by an ignored commit that we could not attribute to another revision are
-	marked with a '*'.
+	marked with a '*'. In the porcelain modes, we print 'ignored' and
+	'unblamable' on a newline respectively.
 
 --ignore-revs-file <file>::
 	Ignore revisions listed in `file`, which must be in the same format as an
diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl
index 315efaa2fa..781da12b2e 100755
--- a/Documentation/build-docdep.perl
+++ b/Documentation/build-docdep.perl
@@ -4,15 +4,15 @@ my ($build_dir) = @ARGV;
 my %include = ();
 my %included = ();
 
-for my $text (<*.txt>) {
-    open I, '<', $text || die "cannot read: $text";
+for my $adoc (<*.adoc>) {
+    open I, '<', $adoc || die "cannot read: $adoc";
     while (<I>) {
 	if (/^include::/) {
 	    chomp;
 	    s/^include::\s*//;
 	    s/\[\]//;
 	    s/{build_dir}/${build_dir}/;
-	    $include{$text}{$_} = 1;
+	    $include{$adoc}{$_} = 1;
 	    $included{$_} = 1;
 	}
     }
@@ -23,14 +23,14 @@ for my $text (<*.txt>) {
 my $changed = 1;
 while ($changed) {
     $changed = 0;
-    while (my ($text, $included) = each %include) {
+    while (my ($adoc, $included) = each %include) {
 	for my $i (keys %$included) {
-	    # $text has include::$i; if $i includes $j
-	    # $text indirectly includes $j.
+	    # $adoc has include::$i; if $i includes $j
+	    # $adoc indirectly includes $j.
 	    if (exists $include{$i}) {
 		for my $j (keys %{$include{$i}}) {
-		    if (!exists $include{$text}{$j}) {
-			$include{$text}{$j} = 1;
+		    if (!exists $include{$adoc}{$j}) {
+			$include{$adoc}{$j} = 1;
 			$included{$j} = 1;
 			$changed = 1;
 		    }
@@ -40,10 +40,10 @@ while ($changed) {
     }
 }
 
-foreach my $text (sort keys %include) {
-    my $included = $include{$text};
-    if (! exists $included{$text} &&
-	(my $base = $text) =~ s/\.txt$//) {
+foreach my $adoc (sort keys %include) {
+    my $included = $include{$adoc};
+    if (! exists $included{$adoc} &&
+	(my $base = $adoc) =~ s/\.adoc$//) {
 	print "$base.html $base.xml : ", join(" ", sort keys %$included), "\n";
     }
 }
diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl
deleted file mode 100755
index e260a98977..0000000000
--- a/Documentation/cmd-list.perl
+++ /dev/null
@@ -1,80 +0,0 @@
-#!/usr/bin/perl -w
-
-use File::Compare qw(compare);
-
-sub format_one {
-	my ($source_dir, $out, $nameattr) = @_;
-	my ($name, $attr) = @$nameattr;
-	my ($path) = "$source_dir/Documentation/$name.txt";
-	my ($state, $description);
-	my $mansection;
-	$state = 0;
-	open I, '<', "$path" or die "No such file $path.txt";
-	while (<I>) {
-		if (/^(?:git|scalar)[a-z0-9-]*\(([0-9])\)$/) {
-			$mansection = $1;
-			next;
-		}
-		if (/^NAME$/) {
-			$state = 1;
-			next;
-		}
-		if ($state == 1 && /^----$/) {
-			$state = 2;
-			next;
-		}
-		next if ($state != 2);
-		chomp;
-		$description = $_;
-		last;
-	}
-	close I;
-	if (!defined $description) {
-		die "No description found in $path.txt";
-	}
-	if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) {
-		print $out "linkgit:$name\[$mansection\]::\n\t";
-		if ($attr =~ / deprecated /) {
-			print $out "(deprecated) ";
-		}
-		print $out "$text.\n\n";
-	}
-	else {
-		die "Description does not match $name: $description";
-	}
-}
-
-my ($source_dir, $build_dir, @categories) = @ARGV;
-
-open IN, "<$source_dir/command-list.txt";
-while (<IN>) {
-	last if /^### command list/;
-}
-
-my %cmds = ();
-for (sort <IN>) {
-	next if /^#/;
-
-	chomp;
-	my ($name, $cat, $attr) = /^(\S+)\s+(.*?)(?:\s+(.*))?$/;
-	$attr = '' unless defined $attr;
-	push @{$cmds{$cat}}, [$name, " $attr "];
-}
-close IN;
-
-for my $out (@categories) {
-	my ($cat) = $out =~ /^cmds-(.*)\.txt$/;
-	my ($path) = "$build_dir/$out";
-	open O, '>', "$path+" or die "Cannot open output file $out+";
-	for (@{$cmds{$cat}}) {
-		format_one($source_dir, \*O, $_);
-	}
-	close O;
-
-	if (-f "$path" && compare("$path", "$path+") == 0) {
-		unlink "$path+";
-	}
-	else {
-		rename "$path+", "$path";
-	}
-}
diff --git a/Documentation/cmd-list.sh b/Documentation/cmd-list.sh
new file mode 100755
index 0000000000..077def3b72
--- /dev/null
+++ b/Documentation/cmd-list.sh
@@ -0,0 +1,104 @@
+#!/bin/sh
+
+set -e
+
+format_one () {
+	source_dir="$1"
+	command="$2"
+	attributes="$3"
+
+	path="$source_dir/Documentation/$command.adoc"
+	if ! test -f "$path"
+	then
+		echo >&2 "No such file $path"
+		exit 1
+	fi
+
+	state=0
+	while read line
+	do
+		case "$state" in
+		0)
+			case "$line" in
+			git*\(*\)|scalar*\(*\))
+				mansection="${line##*\(}"
+				mansection="${mansection%\)}"
+				;;
+			NAME)
+				state=1;;
+			esac
+			;;
+		1)
+			if test "$line" = "----"
+			then
+				state=2
+			fi
+			;;
+		2)
+			description="$line"
+			break
+			;;
+		esac
+	done <"$path"
+
+	if test -z "$mansection"
+	then
+		echo "No man section found in $path" >&2
+		exit 1
+	fi
+
+	if test -z "$description"
+	then
+		echo >&2 "No description found in $path"
+		exit 1
+	fi
+
+	case "$description" in
+	"$command - "*)
+		text="${description#$command - }"
+
+		printf "linkgit:%s[%s]::\n\t" "$command" "$mansection"
+		case "$attributes" in
+		*" deprecated "*)
+			printf "(deprecated) "
+			;;
+		esac
+		printf "$text.\n\n"
+		;;
+	*)
+		echo >&2 "Description does not match $command: $description"
+		exit 1
+		;;
+	esac
+}
+
+source_dir="$1"
+build_dir="$2"
+shift 2
+
+for out
+do
+	category="${out#cmds-}"
+	category="${category%.adoc}"
+	path="$build_dir/$out"
+
+	while read command command_category attributes
+	do
+		case "$command" in
+		"#"*)
+			continue;;
+		esac
+
+		case "$command_category" in
+		"$category")
+			format_one "$source_dir" "$command" " $attributes ";;
+		esac
+	done <"$source_dir/command-list.txt" >"$build_dir/$out+"
+
+	if cmp "$build_dir/$out+" "$build_dir/$out" >/dev/null 2>&1
+	then
+		rm "$build_dir/$out+"
+	else
+		mv "$build_dir/$out+" "$build_dir/$out"
+	fi
+done
diff --git a/Documentation/config.txt b/Documentation/config.adoc
index 8c0b3ed807..62eebe7c54 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.adoc
@@ -114,8 +114,7 @@ whose format and meaning depends on the keyword. Supported keywords
 are:
 
 `gitdir`::
-
-	The data that follows the keyword `gitdir:` is used as a glob
+	The data that follows the keyword `gitdir` and a colon is used as a glob
 	pattern. If the location of the .git directory matches the
 	pattern, the include condition is met.
 +
@@ -148,7 +147,7 @@ refer to linkgit:gitignore[5] for details. For convenience:
 	case-insensitively (e.g. on case-insensitive file systems)
 
 `onbranch`::
-	The data that follows the keyword `onbranch:` is taken to be a
+	The data that follows the keyword `onbranch` and a colon is taken to be a
 	pattern with standard globbing wildcards and two additional
 	ones, `**/` and `/**`, that can match multiple path components.
 	If we are in a worktree where the name of the branch that is
@@ -161,8 +160,8 @@ all branches that begin with `foo/`. This is useful if your branches are
 organized hierarchically and you would like to apply a configuration to
 all the branches in that hierarchy.
 
-`hasconfig:remote.*.url:`::
-	The data that follows this keyword is taken to
+`hasconfig:remote.*.url`::
+	The data that follows this keyword and a colon is taken to
 	be a pattern with standard globbing wildcards and two
 	additional ones, `**/` and `/**`, that can match multiple
 	components. The first time this keyword is seen, the rest of
@@ -358,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
 ~~~~~~~~~
@@ -372,186 +373,188 @@ inventing new variables for use in your own tool, make sure their
 names do not conflict with those that are used by Git itself and
 other popular tools, and describe them in your documentation.
 
-include::config/add.txt[]
+include::config/add.adoc[]
+
+include::config/advice.adoc[]
 
-include::config/advice.txt[]
+include::config/alias.adoc[]
 
-include::config/alias.txt[]
+include::config/am.adoc[]
 
-include::config/am.txt[]
+include::config/apply.adoc[]
 
-include::config/apply.txt[]
+include::config/attr.adoc[]
 
-include::config/attr.txt[]
+include::config/bitmap-pseudo-merge.adoc[]
 
-include::config/bitmap-pseudo-merge.txt[]
+include::config/blame.adoc[]
 
-include::config/blame.txt[]
+include::config/branch.adoc[]
 
-include::config/branch.txt[]
+include::config/browser.adoc[]
 
-include::config/browser.txt[]
+include::config/bundle.adoc[]
 
-include::config/bundle.txt[]
+include::config/checkout.adoc[]
 
-include::config/checkout.txt[]
+include::config/clean.adoc[]
 
-include::config/clean.txt[]
+include::config/clone.adoc[]
 
-include::config/clone.txt[]
+include::config/color.adoc[]
 
-include::config/color.txt[]
+include::config/column.adoc[]
 
-include::config/column.txt[]
+include::config/commit.adoc[]
 
-include::config/commit.txt[]
+include::config/commitgraph.adoc[]
 
-include::config/commitgraph.txt[]
+include::config/completion.adoc[]
 
-include::config/completion.txt[]
+include::config/core.adoc[]
 
-include::config/core.txt[]
+include::config/credential.adoc[]
 
-include::config/credential.txt[]
+include::config/diff.adoc[]
 
-include::config/diff.txt[]
+include::config/difftool.adoc[]
 
-include::config/difftool.txt[]
+include::config/extensions.adoc[]
 
-include::config/extensions.txt[]
+include::config/fastimport.adoc[]
 
-include::config/fastimport.txt[]
+include::config/feature.adoc[]
 
-include::config/feature.txt[]
+include::config/fetch.adoc[]
 
-include::config/fetch.txt[]
+include::config/filter.adoc[]
 
-include::config/filter.txt[]
+include::config/format.adoc[]
 
-include::config/format.txt[]
+include::config/fsck.adoc[]
 
-include::config/fsck.txt[]
+include::config/fsmonitor--daemon.adoc[]
 
-include::config/fsmonitor--daemon.txt[]
+include::config/gc.adoc[]
 
-include::config/gc.txt[]
+include::config/gitcvs.adoc[]
 
-include::config/gitcvs.txt[]
+include::config/gitweb.adoc[]
 
-include::config/gitweb.txt[]
+include::config/gpg.adoc[]
 
-include::config/gpg.txt[]
+include::config/grep.adoc[]
 
-include::config/grep.txt[]
+include::config/gui.adoc[]
 
-include::config/gui.txt[]
+include::config/guitool.adoc[]
 
-include::config/guitool.txt[]
+include::config/help.adoc[]
 
-include::config/help.txt[]
+include::config/http.adoc[]
 
-include::config/http.txt[]
+include::config/i18n.adoc[]
 
-include::config/i18n.txt[]
+include::config/imap.adoc[]
 
-include::config/imap.txt[]
+include::config/includeif.adoc[]
 
-include::config/includeif.txt[]
+include::config/index.adoc[]
 
-include::config/index.txt[]
+include::config/init.adoc[]
 
-include::config/init.txt[]
+include::config/instaweb.adoc[]
 
-include::config/instaweb.txt[]
+include::config/interactive.adoc[]
 
-include::config/interactive.txt[]
+include::config/log.adoc[]
 
-include::config/log.txt[]
+include::config/lsrefs.adoc[]
 
-include::config/lsrefs.txt[]
+include::config/mailinfo.adoc[]
 
-include::config/mailinfo.txt[]
+include::config/mailmap.adoc[]
 
-include::config/mailmap.txt[]
+include::config/maintenance.adoc[]
 
-include::config/maintenance.txt[]
+include::config/man.adoc[]
 
-include::config/man.txt[]
+include::config/merge.adoc[]
 
-include::config/merge.txt[]
+include::config/mergetool.adoc[]
 
-include::config/mergetool.txt[]
+include::config/notes.adoc[]
 
-include::config/notes.txt[]
+include::config/pack.adoc[]
 
-include::config/pack.txt[]
+include::config/pager.adoc[]
 
-include::config/pager.txt[]
+include::config/pretty.adoc[]
 
-include::config/pretty.txt[]
+include::config/promisor.adoc[]
 
-include::config/promisor.txt[]
+include::config/protocol.adoc[]
 
-include::config/protocol.txt[]
+include::config/pull.adoc[]
 
-include::config/pull.txt[]
+include::config/push.adoc[]
 
-include::config/push.txt[]
+include::config/rebase.adoc[]
 
-include::config/rebase.txt[]
+include::config/receive.adoc[]
 
-include::config/receive.txt[]
+include::config/reftable.adoc[]
 
-include::config/reftable.txt[]
+include::config/remote.adoc[]
 
-include::config/remote.txt[]
+include::config/remotes.adoc[]
 
-include::config/remotes.txt[]
+include::config/repack.adoc[]
 
-include::config/repack.txt[]
+include::config/rerere.adoc[]
 
-include::config/rerere.txt[]
+include::config/revert.adoc[]
 
-include::config/revert.txt[]
+include::config/safe.adoc[]
 
-include::config/safe.txt[]
+include::config/sendemail.adoc[]
 
-include::config/sendemail.txt[]
+include::config/sequencer.adoc[]
 
-include::config/sequencer.txt[]
+include::config/showbranch.adoc[]
 
-include::config/showbranch.txt[]
+include::config/sparse.adoc[]
 
-include::config/sparse.txt[]
+include::config/splitindex.adoc[]
 
-include::config/splitindex.txt[]
+include::config/ssh.adoc[]
 
-include::config/ssh.txt[]
+include::config/stash.adoc[]
 
-include::config/stash.txt[]
+include::config/status.adoc[]
 
-include::config/status.txt[]
+include::config/submodule.adoc[]
 
-include::config/submodule.txt[]
+include::config/tag.adoc[]
 
-include::config/tag.txt[]
+include::config/tar.adoc[]
 
-include::config/tar.txt[]
+include::config/trace2.adoc[]
 
-include::config/trace2.txt[]
+include::config/trailer.adoc[]
 
-include::config/transfer.txt[]
+include::config/transfer.adoc[]
 
-include::config/uploadarchive.txt[]
+include::config/uploadarchive.adoc[]
 
-include::config/uploadpack.txt[]
+include::config/uploadpack.adoc[]
 
-include::config/url.txt[]
+include::config/url.adoc[]
 
-include::config/user.txt[]
+include::config/user.adoc[]
 
-include::config/versionsort.txt[]
+include::config/versionsort.adoc[]
 
-include::config/web.txt[]
+include::config/web.adoc[]
 
-include::config/worktree.txt[]
+include::config/worktree.adoc[]
diff --git a/Documentation/config/add.txt b/Documentation/config/add.adoc
index 7497533cbc..7497533cbc 100644
--- a/Documentation/config/add.txt
+++ b/Documentation/config/add.adoc
diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.adoc
index 257db58918..257db58918 100644
--- a/Documentation/config/advice.txt
+++ b/Documentation/config/advice.adoc
diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.adoc
index 2c5db0ad84..80ce17d2de 100644
--- a/Documentation/config/alias.txt
+++ b/Documentation/config/alias.adoc
@@ -3,7 +3,8 @@ alias.*::
 	after defining `alias.last = cat-file commit HEAD`, the invocation
 	`git last` is equivalent to `git cat-file commit HEAD`. To avoid
 	confusion and troubles with script usage, aliases that
-	hide existing Git commands are ignored. Arguments are split by
+	hide existing Git commands are ignored except for deprecated
+	commands.  Arguments are split by
 	spaces, the usual shell quoting and escaping are supported.
 	A quote pair or a backslash can be used to quote them.
 +
@@ -38,6 +39,6 @@ it will be treated as a shell command.  For example, defining
 ** A convenient way to deal with this is to write your script
    operations in an inline function that is then called with any
    arguments from the command-line.  For example `alias.cmd = "!c() {
-   echo $1 | grep $2 ; }; c" will correctly execute the prior example.
+   echo $1 | grep $2 ; }; c"` will correctly execute the prior example.
 ** Setting `GIT_TRACE=1` can help you debug the command being run for
    your alias.
diff --git a/Documentation/config/am.txt b/Documentation/config/am.adoc
index 5bcad2efb1..5bcad2efb1 100644
--- a/Documentation/config/am.txt
+++ b/Documentation/config/am.adoc
diff --git a/Documentation/config/apply.txt b/Documentation/config/apply.adoc
index f9908e210a..f9908e210a 100644
--- a/Documentation/config/apply.txt
+++ b/Documentation/config/apply.adoc
diff --git a/Documentation/config/attr.txt b/Documentation/config/attr.adoc
index c4a5857993..c4a5857993 100644
--- a/Documentation/config/attr.txt
+++ b/Documentation/config/attr.adoc
diff --git a/Documentation/config/bitmap-pseudo-merge.txt b/Documentation/config/bitmap-pseudo-merge.adoc
index 1f264eca99..1f264eca99 100644
--- a/Documentation/config/bitmap-pseudo-merge.txt
+++ b/Documentation/config/bitmap-pseudo-merge.adoc
diff --git a/Documentation/config/blame.txt b/Documentation/config/blame.adoc
index 4d047c1790..4d047c1790 100644
--- a/Documentation/config/blame.txt
+++ b/Documentation/config/blame.adoc
diff --git a/Documentation/config/branch.adoc b/Documentation/config/branch.adoc
new file mode 100644
index 0000000000..a4db9fa5c8
--- /dev/null
+++ b/Documentation/config/branch.adoc
@@ -0,0 +1,104 @@
+`branch.autoSetupMerge`::
+	Tells `git branch`, `git switch` and `git checkout` to set up new branches
+	so that linkgit:git-pull[1] will appropriately merge from the
+	starting point branch. Note that even if this option is not set,
+	this behavior can be chosen per-branch using the `--track`
+	and `--no-track` options.  This option defaults to `true`. The valid settings
+	are:
+`false`;; no automatic setup is done
+`true`;; automatic setup is done when the starting point is a remote-tracking branch
+`always`;; automatic setup is done when the starting point is either a
+	local branch or remote-tracking branch
+`inherit`;; if the starting point has a tracking configuration, it is copied to the new
+	branch
+`simple`;; automatic setup is done only when the starting point
+	is a remote-tracking branch and the new branch has the same name as the
+	remote branch.
+
+`branch.autoSetupRebase`::
+	When a new branch is created with `git branch`, `git switch` or `git checkout`
+	that tracks another branch, this variable tells Git to set
+	up pull to rebase instead of merge (see `branch.<name>.rebase`).
+	The valid settings are:
+`never`;; rebase is never automatically set to true.
+`local`;; rebase is set to true for tracked branches of other local branches.
+`remote`;; rebase is set to true for tracked branches of remote-tracking branches.
+`always`;; rebase will be set to true for all tracking branches.
+
++
+See `branch.autoSetupMerge` for details on how to set up a branch to track another branch.
+This option defaults to `never`.
+
+`branch.sort`::
+	This variable controls the sort ordering of branches when displayed by
+	linkgit:git-branch[1]. Without the `--sort=<value>` option provided, the
+	value of this variable will be used as the default.
+	See linkgit:git-for-each-ref[1] field names for valid values.
+
+`branch.<name>.remote`::
+	When on branch _<name>_, it tells `git fetch` and `git push`
+	which remote to fetch from or push to.  The remote to push to
+	may be overridden with `remote.pushDefault` (for all branches).
+	The remote to push to, for the current branch, may be further
+	overridden by `branch.<name>.pushRemote`.  If no remote is
+	configured, or if you are not on any branch and there is more than
+	one remote defined in the repository, it defaults to `origin` for
+	fetching and `remote.pushDefault` for pushing.
+	Additionally, `.` (a period) is the current local repository
+	(a dot-repository), see `branch.<name>.merge`'s final note below.
+
+`branch.<name>.pushRemote`::
+	When on branch _<name>_, it overrides `branch.<name>.remote` for
+	pushing.  It also overrides `remote.pushDefault` for pushing
+	from branch _<name>_.  When you pull from one place (e.g. your
+	upstream) and push to another place (e.g. your own publishing
+	repository), you would want to set `remote.pushDefault` to
+	specify the remote to push to for all branches, and use this
+	option to override it for a specific branch.
+
+`branch.<name>.merge`::
+	Defines, together with `branch.<name>.remote`, the upstream branch
+	for the given branch. It tells `git fetch`/`git pull`/`git rebase` which
+	branch to merge and can also affect `git push` (see `push.default`).
+	When in branch _<name>_, it tells `git fetch` the default
+	refspec to be marked for merging in `FETCH_HEAD`. The value is
+	handled like the remote part of a refspec, and must match a
+	ref which is fetched from the remote given by
+	`branch.<name>.remote`.
+	The merge information is used by `git pull` (which first calls
+	`git fetch`) to lookup the default branch for merging. Without
+	this option, `git pull` defaults to merge the first refspec fetched.
+	Specify multiple values to get an octopus merge.
+	If you wish to setup `git pull` so that it merges into _<name>_ from
+	another branch in the local repository, you can point
+	`branch.<name>.merge` to the desired branch, and use the relative path
+	setting `.` (a period) for `branch.<name>.remote`.
+
+`branch.<name>.mergeOptions`::
+	Sets default options for merging into branch _<name>_. The syntax and
+	supported options are the same as those of linkgit:git-merge[1], but
+	option values containing whitespace characters are currently not
+	supported.
+
+`branch.<name>.rebase`::
+	When true, rebase the branch _<name>_ on top of the fetched branch,
+	instead of merging the default branch from the default remote when
+	`git pull` is run. See `pull.rebase` for doing this in a non
+	branch-specific manner.
++
+When `merges` (or just `m`), pass the `--rebase-merges` option to `git rebase`
+so that the local merge commits are included in the rebase (see
+linkgit:git-rebase[1] for details).
++
+When the value is `interactive` (or just `i`), the rebase is run in interactive
+mode.
++
+*NOTE*: this is a possibly dangerous operation; do *not* use
+it unless you understand the implications (see linkgit:git-rebase[1]
+for details).
+
+`branch.<name>.description`::
+	Branch description, can be edited with
+	`git branch --edit-description`. Branch description is
+	automatically added to the `format-patch` cover letter or
+	`request-pull` summary.
diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt
deleted file mode 100644
index 432b9cd2c0..0000000000
--- a/Documentation/config/branch.txt
+++ /dev/null
@@ -1,103 +0,0 @@
-branch.autoSetupMerge::
-	Tells 'git branch', 'git switch' and 'git checkout' to set up new branches
-	so that linkgit:git-pull[1] will appropriately merge from the
-	starting point branch. Note that even if this option is not set,
-	this behavior can be chosen per-branch using the `--track`
-	and `--no-track` options. The valid settings are: `false` -- no
-	automatic setup is done; `true` -- automatic setup is done when the
-	starting point is a remote-tracking branch; `always` --
-	automatic setup is done when the starting point is either a
-	local branch or remote-tracking branch; `inherit` -- if the starting point
-	has a tracking configuration, it is copied to the new
-	branch; `simple` -- automatic setup is done only when the starting point
-	is a remote-tracking branch and the new branch has the same name as the
-	remote branch. This option defaults to true.
-
-branch.autoSetupRebase::
-	When a new branch is created with 'git branch', 'git switch' or 'git checkout'
-	that tracks another branch, this variable tells Git to set
-	up pull to rebase instead of merge (see "branch.<name>.rebase").
-	When `never`, rebase is never automatically set to true.
-	When `local`, rebase is set to true for tracked branches of
-	other local branches.
-	When `remote`, rebase is set to true for tracked branches of
-	remote-tracking branches.
-	When `always`, rebase will be set to true for all tracking
-	branches.
-	See "branch.autoSetupMerge" for details on how to set up a
-	branch to track another branch.
-	This option defaults to never.
-
-branch.sort::
-	This variable controls the sort ordering of branches when displayed by
-	linkgit:git-branch[1]. Without the "--sort=<value>" option provided, the
-	value of this variable will be used as the default.
-	See linkgit:git-for-each-ref[1] field names for valid values.
-
-branch.<name>.remote::
-	When on branch <name>, it tells 'git fetch' and 'git push'
-	which remote to fetch from or push to.  The remote to push to
-	may be overridden with `remote.pushDefault` (for all branches).
-	The remote to push to, for the current branch, may be further
-	overridden by `branch.<name>.pushRemote`.  If no remote is
-	configured, or if you are not on any branch and there is more than
-	one remote defined in the repository, it defaults to `origin` for
-	fetching and `remote.pushDefault` for pushing.
-	Additionally, `.` (a period) is the current local repository
-	(a dot-repository), see `branch.<name>.merge`'s final note below.
-
-branch.<name>.pushRemote::
-	When on branch <name>, it overrides `branch.<name>.remote` for
-	pushing.  It also overrides `remote.pushDefault` for pushing
-	from branch <name>.  When you pull from one place (e.g. your
-	upstream) and push to another place (e.g. your own publishing
-	repository), you would want to set `remote.pushDefault` to
-	specify the remote to push to for all branches, and use this
-	option to override it for a specific branch.
-
-branch.<name>.merge::
-	Defines, together with branch.<name>.remote, the upstream branch
-	for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which
-	branch to merge and can also affect 'git push' (see push.default).
-	When in branch <name>, it tells 'git fetch' the default
-	refspec to be marked for merging in FETCH_HEAD. The value is
-	handled like the remote part of a refspec, and must match a
-	ref which is fetched from the remote given by
-	"branch.<name>.remote".
-	The merge information is used by 'git pull' (which first calls
-	'git fetch') to lookup the default branch for merging. Without
-	this option, 'git pull' defaults to merge the first refspec fetched.
-	Specify multiple values to get an octopus merge.
-	If you wish to setup 'git pull' so that it merges into <name> from
-	another branch in the local repository, you can point
-	branch.<name>.merge to the desired branch, and use the relative path
-	setting `.` (a period) for branch.<name>.remote.
-
-branch.<name>.mergeOptions::
-	Sets default options for merging into branch <name>. The syntax and
-	supported options are the same as those of linkgit:git-merge[1], but
-	option values containing whitespace characters are currently not
-	supported.
-
-branch.<name>.rebase::
-	When true, rebase the branch <name> on top of the fetched branch,
-	instead of merging the default branch from the default remote when
-	"git pull" is run. See "pull.rebase" for doing this in a non
-	branch-specific manner.
-+
-When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase'
-so that the local merge commits are included in the rebase (see
-linkgit:git-rebase[1] for details).
-+
-When the value is `interactive` (or just 'i'), the rebase is run in interactive
-mode.
-+
-*NOTE*: this is a possibly dangerous operation; do *not* use
-it unless you understand the implications (see linkgit:git-rebase[1]
-for details).
-
-branch.<name>.description::
-	Branch description, can be edited with
-	`git branch --edit-description`. Branch description is
-	automatically added to the format-patch cover letter or
-	request-pull summary.
diff --git a/Documentation/config/browser.txt b/Documentation/config/browser.adoc
index 195df207a6..195df207a6 100644
--- a/Documentation/config/browser.txt
+++ b/Documentation/config/browser.adoc
diff --git a/Documentation/config/bundle.txt b/Documentation/config/bundle.adoc
index 3faae38685..3faae38685 100644
--- a/Documentation/config/bundle.txt
+++ b/Documentation/config/bundle.adoc
diff --git a/Documentation/config/checkout.txt b/Documentation/config/checkout.adoc
index a323022993..e35d212969 100644
--- a/Documentation/config/checkout.txt
+++ b/Documentation/config/checkout.adoc
@@ -1,9 +1,9 @@
-checkout.defaultRemote::
+`checkout.defaultRemote`::
 	When you run `git checkout <something>`
 	or `git switch <something>` and only have one
 	remote, it may implicitly fall back on checking out and
 	tracking e.g. `origin/<something>`. This stops working as soon
-	as you have more than one remote with a `<something>`
+	as you have more than one remote with a _<something>_
 	reference. This setting allows for setting the name of a
 	preferred remote that should always win when it comes to
 	disambiguation. The typical use-case is to set this to
@@ -12,17 +12,17 @@ checkout.defaultRemote::
 Currently this is used by linkgit:git-switch[1] and
 linkgit:git-checkout[1] when `git checkout <something>`
 or `git switch <something>`
-will checkout the `<something>` branch on another remote,
+will checkout the _<something>_ branch on another remote,
 and by linkgit:git-worktree[1] when `git worktree add` refers to a
 remote branch. This setting might be used for other checkout-like
 commands or functionality in the future.
 
-checkout.guess::
+`checkout.guess`::
 	Provides the default value for the `--guess` or `--no-guess`
 	option in `git checkout` and `git switch`. See
 	linkgit:git-switch[1] and linkgit:git-checkout[1].
 
-checkout.workers::
+`checkout.workers`::
 	The number of parallel workers to use when updating the working tree.
 	The default is one, i.e. sequential execution. If set to a value less
 	than one, Git will use as many workers as the number of logical cores
@@ -30,13 +30,13 @@ checkout.workers::
 	all commands that perform checkout. E.g. checkout, clone, reset,
 	sparse-checkout, etc.
 +
-Note: Parallel checkout usually delivers better performance for repositories
+NOTE: Parallel checkout usually delivers better performance for repositories
 located on SSDs or over NFS. For repositories on spinning disks and/or machines
 with a small number of cores, the default sequential checkout often performs
 better. The size and compression level of a repository might also influence how
 well the parallel version performs.
 
-checkout.thresholdForParallelism::
+`checkout.thresholdForParallelism`::
 	When running parallel checkout with a small number of files, the cost
 	of subprocess spawning and inter-process communication might outweigh
 	the parallelization gains. This setting allows you to define the minimum
diff --git a/Documentation/config/clean.txt b/Documentation/config/clean.adoc
index c0188ead4e..c0188ead4e 100644
--- a/Documentation/config/clean.txt
+++ b/Documentation/config/clean.adoc
diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.adoc
index 0a10efd174..0a10efd174 100644
--- a/Documentation/config/clone.txt
+++ b/Documentation/config/clone.adoc
diff --git a/Documentation/config/color.txt b/Documentation/config/color.adoc
index 2f2275ac69..2f2275ac69 100644
--- a/Documentation/config/color.txt
+++ b/Documentation/config/color.adoc
diff --git a/Documentation/config/column.txt b/Documentation/config/column.adoc
index 01e4198429..01e4198429 100644
--- a/Documentation/config/column.txt
+++ b/Documentation/config/column.adoc
diff --git a/Documentation/config/commit.txt b/Documentation/config/commit.adoc
index 62f0d92fda..208ae76c81 100644
--- a/Documentation/config/commit.txt
+++ b/Documentation/config/commit.adoc
@@ -1,29 +1,35 @@
-commit.cleanup::
+ifdef::git-commit[]
+:see-git-commit:
+endif::git-commit[]
+ifndef::git-commit[]
+:see-git-commit: See linkgit:git-commit[1] for details.
+endif::git-commit[]
+`commit.cleanup`::
 	This setting overrides the default of the `--cleanup` option in
-	`git commit`. See linkgit:git-commit[1] for details. Changing the
-	default can be useful when you always want to keep lines that begin
-	with the comment character `#` in your log message, in which case you
+	`git commit`. {see-git-commit} Changing the default can be useful
+	when you always want to keep lines that begin
+	with the comment character (`core.commentChar`, default `#`)
+	in your log message, in which case you
 	would do `git config commit.cleanup whitespace` (note that you will
-	have to remove the help lines that begin with `#` in the commit log
-	template yourself, if you do this).
-
-commit.gpgSign::
+	have to remove the help lines that begin with the comment character
+	in the commit log template yourself, if you do this).
 
+`commit.gpgSign`::
 	A boolean to specify whether all commits should be GPG signed.
 	Use of this option when doing operations such as rebase can
 	result in a large number of commits being signed. It may be
 	convenient to use an agent to avoid typing your GPG passphrase
 	several times.
 
-commit.status::
+`commit.status`::
 	A boolean to enable/disable inclusion of status information in the
 	commit message template when using an editor to prepare the commit
-	message.  Defaults to true.
+	message.  Defaults to `true`.
 
-commit.template::
+`commit.template`::
 	Specify the pathname of a file to use as the template for
 	new commit messages.
 
-commit.verbose::
+`commit.verbose`::
 	A boolean or int to specify the level of verbosity with `git commit`.
-	See linkgit:git-commit[1].
+	{see-git-commit}
diff --git a/Documentation/config/commitgraph.txt b/Documentation/config/commitgraph.adoc
index 7f8c9d6638..70a56c53d2 100644
--- a/Documentation/config/commitgraph.txt
+++ b/Documentation/config/commitgraph.adoc
@@ -8,6 +8,17 @@ commitGraph.maxNewFilters::
 	Specifies the default value for the `--max-new-filters` option of `git
 	commit-graph write` (c.f., linkgit:git-commit-graph[1]).
 
+commitGraph.changedPaths::
+	If true, then `git commit-graph write` will compute and write
+	changed-path Bloom filters by default, equivalent to passing
+	`--changed-paths`. If false or unset, changed-paths Bloom filters will
+	be written during `git commit-graph write` only if the filters already
+	exist in the current commit-graph file. This matches the default
+	behavior of `git commit-graph write` without any `--[no-]changed-paths`
+	option. To rewrite a commit-graph file without any filters, use the
+	`--no-changed-paths` option. Command-line option `--[no-]changed-paths`
+	always takes precedence over this configuration. Defaults to unset.
+
 commitGraph.readChangedPaths::
 	Deprecated. Equivalent to commitGraph.changedPathsVersion=-1 if true, and
 	commitGraph.changedPathsVersion=0 if false. (If commitGraph.changedPathVersion
diff --git a/Documentation/config/completion.txt b/Documentation/config/completion.adoc
index 4d99bf33c9..4d99bf33c9 100644
--- a/Documentation/config/completion.txt
+++ b/Documentation/config/completion.adoc
diff --git a/Documentation/config/core.txt b/Documentation/config/core.adoc
index 8f6d8e7754..11efad189e 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.adoc
@@ -75,8 +75,8 @@ The built-in file system monitor is currently available only on a
 limited set of supported platforms.  Currently, this includes Windows
 and MacOS.
 +
-	Otherwise, this variable contains the pathname of the "fsmonitor"
-	hook command.
+Otherwise, this variable contains the pathname of the "fsmonitor"
+hook command.
 +
 This hook command is used to identify all files that may have changed
 since the requested date/time. This information is used to speed up
@@ -290,6 +290,9 @@ core.preferSymlinkRefs::
 	and other symbolic reference files, use symbolic links.
 	This is sometimes needed to work with old scripts that
 	expect HEAD to be a symbolic link.
++
+This configuration is deprecated and will be removed in Git 3.0. Symbolic refs
+will always be written as textual symrefs.
 
 core.alternateRefsCommand::
 	When advertising tips of available history from an alternate, use the shell to
@@ -512,6 +515,11 @@ centrally configure your Git hooks instead of configuring them on a
 per-repository basis, or as a more flexible and centralized
 alternative to having an `init.templateDir` where you've changed
 default hooks.
++
+You can also disable all hooks entirely by setting `core.hooksPath`
+to `/dev/null`. This is usually only advisable for expert users and
+on a per-command basis using configuration parameters of the form
+`git -c core.hooksPath=/dev/null ...`.
 
 core.editor::
 	Commands such as `commit` and `tag` that let you edit
@@ -526,9 +534,25 @@ core.commentString::
 	commented, and removes them after the editor returns
 	(default '#').
 +
-If set to "auto", `git-commit` would select a character that is not
+ifndef::with-breaking-changes[]
+If set to "auto", `git-commit` will select a character that is not
 the beginning character of any line in existing commit messages.
-+
+Support for this value is deprecated and will be removed in Git 3.0
+due to the following limitations:
++
+--
+* It is incompatible with adding comments in a commit message
+  template. This includes the conflicts comments added to
+  the commit message by `cherry-pick`, `merge`, `rebase` and
+  `revert`.
+* It is incompatible with adding comments to the commit message
+  in the `prepare-commit-msg` hook.
+* It is incompatible with the `fixup` and `squash` commands when
+  rebasing,
+* It is not respected by `git notes`
+--
++
+endif::with-breaking-changes[]
 Note that these two variables are aliases of each other, and in modern
 versions of Git you are free to use a string (e.g., `//` or `⁑⁕⁑`) with
 `commentChar`. Versions of Git prior to v2.45.0 will ignore
@@ -691,12 +715,6 @@ core.unsetenvvars::
 	Defaults to `PERL5LIB` to account for the fact that Git for
 	Windows insists on using its own Perl interpreter.
 
-core.restrictinheritedhandles::
-	Windows-only: override whether spawned processes inherit only standard
-	file handles (`stdin`, `stdout` and `stderr`) or all handles. Can be
-	`auto`, `true` or `false`. Defaults to `auto`, which means `true` on
-	Windows 7 and later, and `false` on older Windows versions.
-
 core.createObject::
 	You can set this to 'link', in which case a hardlink followed by
 	a delete of the source are used to make sure that object creation
diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.adoc
index 80a7c77772..80a7c77772 100644
--- a/Documentation/config/credential.txt
+++ b/Documentation/config/credential.adoc
diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.adoc
index fdae13a212..1135a62a0a 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.adoc
@@ -218,8 +218,6 @@ endif::git-diff[]
 	Set this option to `true` to make the diff driver cache the text
 	conversion outputs.  See linkgit:gitattributes[5] for details.
 
-include::{build_dir}/mergetools-diff.txt[]
-
 `diff.indentHeuristic`::
 	Set this option to `false` to disable the default heuristics
 	that shift diff hunk boundaries to make patches easier to read.
diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.adoc
index 447c40d85a..4f7d40ce24 100644
--- a/Documentation/config/difftool.txt
+++ b/Documentation/config/difftool.adoc
@@ -13,6 +13,8 @@ diff.guitool::
 	and requires that a corresponding difftool.<guitool>.cmd variable
 	is defined.
 
+include::{build_dir}/mergetools-diff.adoc[]
+
 difftool.<tool>.cmd::
 	Specify the command to invoke the specified diff tool.
 	The specified command is evaluated in shell with the following
diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.adoc
index 5cb4721a0e..532456644b 100644
--- a/Documentation/config/extensions.txt
+++ b/Documentation/config/extensions.adoc
@@ -3,8 +3,7 @@ extensions.*::
 	`core.repositoryFormatVersion` is not `1`. See
 	linkgit:gitrepository-layout[5].
 +
---
-compatObjectFormat::
+compatObjectFormat:::
 	Specify a compatibility hash algorithm to use.  The acceptable values
 	are `sha1` and `sha256`.  The value specified must be different from the
 	value of `extensions.objectFormat`.  This allows client level
@@ -14,19 +13,23 @@ compatObjectFormat::
 	compatObjectFormat.  As well as being able to use oids encoded in
 	compatObjectFormat in addition to oids encoded with objectFormat to
 	locally specify objects.
++
+Note that the functionality enabled by this extension is incomplete and subject
+to change.  It currently exists only to allow development and testing of
+the underlying feature and is not designed to be enabled by end users.
 
-noop::
+noop:::
 	This extension does not change git's behavior at all. It is useful only
 	for testing format-1 compatibility.
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-noop-v1::
+noop-v1:::
 	This extension does not change git's behavior at all. It is useful only
 	for testing format-1 compatibility.
 
-objectFormat::
+objectFormat:::
 	Specify the hash algorithm to use.  The acceptable values are `sha1` and
 	`sha256`.  If not specified, `sha1` is assumed.
 +
@@ -34,7 +37,7 @@ Note that this setting should only be set by linkgit:git-init[1] or
 linkgit:git-clone[1].  Trying to change it after initialization will not
 work and will produce hard-to-diagnose issues.
 
-partialClone::
+partialClone:::
 	When enabled, indicates that the repo was created with a partial clone
 	(or later performed a partial fetch) and that the remote may have
 	omitted sending certain unwanted objects.  Such a remote is called a
@@ -46,30 +49,31 @@ The value of this key is the name of the promisor remote.
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-preciousObjects::
+preciousObjects:::
 	If enabled, indicates that objects in the repository MUST NOT be deleted
 	(e.g., by `git-prune` or `git repack -d`).
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-refStorage::
+refStorage:::
 	Specify the ref storage format to use. The acceptable values are:
 +
-include::../ref-storage-format.txt[]
-
+--
+include::../ref-storage-format.adoc[]
+--
 +
 Note that this setting should only be set by linkgit:git-init[1] or
 linkgit:git-clone[1]. Trying to change it after initialization will not
 work and will produce hard-to-diagnose issues.
 
-relativeWorktrees::
+relativeWorktrees:::
 	If enabled, indicates at least one worktree has been linked with
 	relative paths. Automatically set if a worktree has been created or
 	repaired with either the `--relative-paths` option or with the
 	`worktree.useRelativePaths` config set to `true`.
 
-worktreeConfig::
+worktreeConfig:::
 	If enabled, then worktrees will load config settings from the
 	`$GIT_DIR/config.worktree` file in addition to the
 	`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
@@ -83,11 +87,12 @@ When enabling this extension, you must be careful to move
 certain values from the common config file to the main working tree's
 `config.worktree` file, if present:
 +
+--
 * `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to
   `$GIT_COMMON_DIR/config.worktree`.
 * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
   to `$GIT_COMMON_DIR/config.worktree`.
-
+--
 +
 It may also be beneficial to adjust the locations of `core.sparseCheckout`
 and `core.sparseCheckoutCone` depending on your desire for customizable
@@ -100,4 +105,3 @@ details.
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
---
diff --git a/Documentation/config/fastimport.txt b/Documentation/config/fastimport.adoc
index 903677d7ef..903677d7ef 100644
--- a/Documentation/config/fastimport.txt
+++ b/Documentation/config/fastimport.adoc
diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.adoc
index f061b64b74..924f5ff4e3 100644
--- a/Documentation/config/feature.txt
+++ b/Documentation/config/feature.adoc
@@ -20,6 +20,16 @@ walking fewer objects.
 +
 * `pack.allowPackReuse=multi` may improve the time it takes to create a pack by
 reusing objects from multiple packs instead of just one.
++
+* `pack.usePathWalk` may speed up packfile creation and make the packfiles be
+significantly smaller in the presence of certain filename collisions with Git's
+default name-hash.
++
+* `init.defaultRefFormat=reftable` causes newly initialized repositories to use
+the reftable format for storing references. This new format solves issues with
+case-insensitive filesystems, compresses better and performs significantly
+better with many use cases. Refer to Documentation/technical/reftable.adoc for
+more information on this new storage format.
 
 feature.manyFiles::
 	Enable config options that optimize for repos with many files in the
diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.adoc
index d7dc461bd1..d7dc461bd1 100644
--- a/Documentation/config/fetch.txt
+++ b/Documentation/config/fetch.adoc
diff --git a/Documentation/config/filter.txt b/Documentation/config/filter.adoc
index 90dfe0ba5a..90dfe0ba5a 100644
--- a/Documentation/config/filter.txt
+++ b/Documentation/config/filter.adoc
diff --git a/Documentation/config/fmt-merge-msg.txt b/Documentation/config/fmt-merge-msg.adoc
index 3fbf40e24f..696ba0531a 100644
--- a/Documentation/config/fmt-merge-msg.txt
+++ b/Documentation/config/fmt-merge-msg.adoc
@@ -1,19 +1,19 @@
-merge.branchdesc::
+`merge.branchdesc`::
 	In addition to branch names, populate the log message with
 	the branch description text associated with them.  Defaults
 	to false.
 
-merge.log::
+`merge.log`::
 	In addition to branch names, populate the log message with at
 	most the specified number of one-line descriptions from the
 	actual commits that are being merged.  Defaults to false, and
 	true is a synonym for 20.
 
-merge.suppressDest::
+`merge.suppressDest`::
 	By adding a glob that matches the names of integration
 	branches to this multi-valued configuration variable, the
 	default merge message computed for merges into these
-	integration branches will omit "into <branch name>" from
+	integration branches will omit "into _<branch-name>_" from
 	its title.
 +
 An element with an empty value can be used to clear the list
diff --git a/Documentation/config/format.txt b/Documentation/config/format.adoc
index 7410e930e5..ab0710e86a 100644
--- a/Documentation/config/format.txt
+++ b/Documentation/config/format.adoc
@@ -68,9 +68,15 @@ format.encodeEmailHeaders::
 	Defaults to true.
 
 format.pretty::
+ifndef::with-breaking-changes[]
 	The default pretty format for log/show/whatchanged command.
 	See linkgit:git-log[1], linkgit:git-show[1],
 	linkgit:git-whatchanged[1].
+endif::with-breaking-changes[]
+ifdef::with-breaking-changes[]
+	The default pretty format for log/show command.
+	See linkgit:git-log[1], linkgit:git-show[1].
+endif::with-breaking-changes[]
 
 format.thread::
 	The default threading style for 'git format-patch'.  Can be
diff --git a/Documentation/config/fsck.txt b/Documentation/config/fsck.adoc
index 8e9e508933..8e9e508933 100644
--- a/Documentation/config/fsck.txt
+++ b/Documentation/config/fsck.adoc
diff --git a/Documentation/config/fsmonitor--daemon.txt b/Documentation/config/fsmonitor--daemon.adoc
index 671f9b9462..671f9b9462 100644
--- a/Documentation/config/fsmonitor--daemon.txt
+++ b/Documentation/config/fsmonitor--daemon.adoc
diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.adoc
index 21d56db279..21d56db279 100644
--- a/Documentation/config/gc.txt
+++ b/Documentation/config/gc.adoc
diff --git a/Documentation/config/gitcvs.txt b/Documentation/config/gitcvs.adoc
index 02da427fd9..31d7be3992 100644
--- a/Documentation/config/gitcvs.txt
+++ b/Documentation/config/gitcvs.adoc
@@ -47,7 +47,8 @@ gitcvs.dbDriver::
 	May not contain double colons (`:`). Default: 'SQLite'.
 	See linkgit:git-cvsserver[1].
 
-gitcvs.dbUser, gitcvs.dbPass::
+gitcvs.dbUser::
+gitcvs.dbPass::
 	Database user and password. Only useful if setting `gitcvs.dbDriver`,
 	since SQLite has no concept of database users and/or passwords.
 	'gitcvs.dbUser' supports variable substitution (see
diff --git a/Documentation/config/gitweb.txt b/Documentation/config/gitweb.adoc
index 1b51475108..1b51475108 100644
--- a/Documentation/config/gitweb.txt
+++ b/Documentation/config/gitweb.adoc
diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.adoc
index 5cf32b179d..240e46c050 100644
--- a/Documentation/config/gpg.txt
+++ b/Documentation/config/gpg.adoc
@@ -1,5 +1,5 @@
 gpg.program::
-	Use this custom program instead of "`gpg`" found on `$PATH` when
+	Pathname of the program to use instead of "`gpg`" when
 	making or verifying a PGP signature. The program must support the
 	same command-line interface as GPG, namely, to verify a detached
 	signature, "`gpg --verify $signature - <$file`" is run, and the
diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.adoc
index 10041f27b0..10041f27b0 100644
--- a/Documentation/config/grep.txt
+++ b/Documentation/config/grep.adoc
diff --git a/Documentation/config/gui.txt b/Documentation/config/gui.adoc
index 171be774d2..171be774d2 100644
--- a/Documentation/config/gui.txt
+++ b/Documentation/config/gui.adoc
diff --git a/Documentation/config/guitool.txt b/Documentation/config/guitool.adoc
index 43fb9466ff..43fb9466ff 100644
--- a/Documentation/config/guitool.txt
+++ b/Documentation/config/guitool.adoc
diff --git a/Documentation/config/help.txt b/Documentation/config/help.adoc
index 610701f9a3..b369589cec 100644
--- a/Documentation/config/help.txt
+++ b/Documentation/config/help.adoc
@@ -11,13 +11,14 @@ help.autoCorrect::
 	If git detects typos and can identify exactly one valid command similar
 	to the error, git will try to suggest the correct command or even
 	run the suggestion automatically. Possible config values are:
-	 - 0 (default): show the suggested command.
-	 - positive number: run the suggested command after specified
+	 - 0, "false", "off", "no", "show": show the suggested command (default).
+	 - 1, "true", "on", "yes", "immediate": run the suggested command
+immediately.
+	 - positive number > 1: run the suggested command after specified
 deciseconds (0.1 sec).
-	 - "immediate": run the suggested command immediately.
+	 - "never": don't run or show any suggested command.
 	 - "prompt": show the suggestion and prompt for confirmation to run
 the command.
-	 - "never": don't run or show any suggested command.
 
 help.htmlPath::
 	Specify the path where the HTML documentation resides. File system paths
diff --git a/Documentation/config/http.txt b/Documentation/config/http.adoc
index a14371b5c9..9da5c298cc 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.adoc
@@ -216,6 +216,21 @@ http.sslBackend::
 	This option is ignored if cURL lacks support for choosing the SSL
 	backend at runtime.
 
+http.sslCertType::
+	Type of client certificate used when fetching or pushing over HTTPS.
+	"PEM", "DER" are supported when using openssl or gnutls backends. "P12"
+	is supported on "openssl", "schannel", "securetransport", and gnutls 8.11+.
+	See also libcurl `CURLOPT_SSLCERTTYPE`. Can be overridden by the
+	`GIT_SSL_CERT_TYPE` environment variable.
+
+http.sslKeyType::
+	Type of client private key used when fetching or pushing over HTTPS. (e.g.
+	"PEM", "DER", or "ENG"). Only applicable when using "openssl" backend. "DER"
+	is not supported with openssl. Particularly useful when set to "ENG" for
+	authenticating with PKCS#11 tokens, with a PKCS#11 URL in sslCert option.
+	See also libcurl `CURLOPT_SSLKEYTYPE`. Can be overridden by the
+	`GIT_SSL_KEY_TYPE` environment variable.
+
 http.schannelCheckRevoke::
 	Used to enforce or disable certificate revocation checks in cURL
 	when http.sslBackend is set to "schannel". Defaults to `true` if
@@ -274,13 +289,32 @@ for most push problems, but can increase memory consumption
 significantly since the entire buffer is allocated even for small
 pushes.
 
-http.lowSpeedLimit, http.lowSpeedTime::
+http.lowSpeedLimit::
+http.lowSpeedTime::
 	If the HTTP transfer speed, in bytes per second, is less than
 	'http.lowSpeedLimit' for longer than 'http.lowSpeedTime' seconds,
 	the transfer is aborted.
 	Can be overridden by the `GIT_HTTP_LOW_SPEED_LIMIT` and
 	`GIT_HTTP_LOW_SPEED_TIME` environment variables.
 
+http.keepAliveIdle::
+	Specifies how long in seconds to wait on an idle connection
+	before sending TCP keepalive probes (if supported by the OS). If
+	unset, curl's default value is used. Can be overridden by the
+	`GIT_HTTP_KEEPALIVE_IDLE` environment variable.
+
+http.keepAliveInterval::
+	Specifies how long in seconds to wait between TCP keepalive
+	probes (if supported by the OS). If unset, curl's default value
+	is used. Can be overridden by the `GIT_HTTP_KEEPALIVE_INTERVAL`
+	environment variable.
+
+http.keepAliveCount::
+	Specifies how many TCP keepalive probes to send before giving up
+	and terminating the connection (if supported by the OS). If
+	unset, curl's default value is used. Can be overridden by the
+	`GIT_HTTP_KEEPALIVE_COUNT` environment variable.
+
 http.noEPSV::
 	A boolean which disables using of EPSV ftp command by curl.
 	This can be helpful with some "poor" ftp servers which don't
diff --git a/Documentation/config/i18n.txt b/Documentation/config/i18n.adoc
index 6e72fdb45b..6e72fdb45b 100644
--- a/Documentation/config/i18n.txt
+++ b/Documentation/config/i18n.adoc
diff --git a/Documentation/config/imap.txt b/Documentation/config/imap.adoc
index 3d28f72643..4682a6bd03 100644
--- a/Documentation/config/imap.txt
+++ b/Documentation/config/imap.adoc
@@ -1,7 +1,9 @@
 imap.folder::
 	The folder to drop the mails into, which is typically the Drafts
-	folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
-	"[Gmail]/Drafts". Required.
+	folder. For example: `INBOX.Drafts`, `INBOX/Drafts` or
+	`[Gmail]/Drafts`. The IMAP folder to interact with MUST be specified;
+	the value of this configuration variable is used as the fallback
+	default value when the `--folder` option is not given.
 
 imap.tunnel::
 	Command used to set up a tunnel to the IMAP server through which
@@ -40,5 +42,6 @@ imap.authMethod::
 	Specify the authentication method for authenticating with the IMAP server.
 	If Git was built with the NO_CURL option, or if your curl version is older
 	than 7.34.0, or if you're running git-imap-send with the `--no-curl`
-	option, the only supported method is 'CRAM-MD5'. If this is not set
-	then 'git imap-send' uses the basic IMAP plaintext LOGIN command.
+	option, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER`
+	and `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP
+	plaintext `LOGIN` command.
diff --git a/Documentation/config/includeif.txt b/Documentation/config/includeif.adoc
index 82fe431c34..82fe431c34 100644
--- a/Documentation/config/includeif.txt
+++ b/Documentation/config/includeif.adoc
diff --git a/Documentation/config/index.txt b/Documentation/config/index.adoc
index 3eff420360..3eff420360 100644
--- a/Documentation/config/index.txt
+++ b/Documentation/config/index.adoc
diff --git a/Documentation/config/init.txt b/Documentation/config/init.adoc
index e45b2a8121..e45b2a8121 100644
--- a/Documentation/config/init.txt
+++ b/Documentation/config/init.adoc
diff --git a/Documentation/config/instaweb.txt b/Documentation/config/instaweb.adoc
index 50cb2f7d62..50cb2f7d62 100644
--- a/Documentation/config/instaweb.txt
+++ b/Documentation/config/instaweb.adoc
diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.adoc
index 8b876cb4eb..8b876cb4eb 100644
--- a/Documentation/config/interactive.txt
+++ b/Documentation/config/interactive.adoc
diff --git a/Documentation/config/log.txt b/Documentation/config/log.adoc
index 9003a82191..f20cc25cd7 100644
--- a/Documentation/config/log.txt
+++ b/Documentation/config/log.adoc
@@ -1,64 +1,76 @@
-log.abbrevCommit::
-	If true, makes linkgit:git-log[1], linkgit:git-show[1], and
-	linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
+`log.abbrevCommit`::
+	If `true`, make
+ifndef::with-breaking-changes[]
+	linkgit:git-log[1], linkgit:git-show[1], and
+	linkgit:git-whatchanged[1]
+endif::with-breaking-changes[]
+ifdef::with-breaking-changes[]
+	linkgit:git-log[1] and linkgit:git-show[1]
+endif::with-breaking-changes[]
+	assume `--abbrev-commit`. You may
 	override this option with `--no-abbrev-commit`.
 
-log.date::
-	Set the default date-time mode for the 'log' command.
-	Setting a value for log.date is similar to using 'git log''s
+`log.date`::
+	Set the default date-time mode for the `log` command.
+	Setting a value for log.date is similar to using `git log`'s
 	`--date` option.  See linkgit:git-log[1] for details.
 +
 If the format is set to "auto:foo" and the pager is in use, format
 "foo" will be used for the date format. Otherwise, "default" will
 be used.
 
-log.decorate::
+`log.decorate`::
 	Print out the ref names of any commits that are shown by the log
-	command. If 'short' is specified, the ref name prefixes 'refs/heads/',
-	'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is
-	specified, the full ref name (including prefix) will be printed.
-	If 'auto' is specified, then if the output is going to a terminal,
-	the ref names are shown as if 'short' were given, otherwise no ref
-	names are shown. This is the same as the `--decorate` option
-	of the `git log`.
+	command. Possible values are:
++
+--
+`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and
+	`refs/remotes/` are not printed.
+`full`;; the full ref name (including prefix) are printed.
+`auto`;; if the output is going to a terminal,
+	the ref names are shown as if `short` were given, otherwise no ref
+	names are shown.
+--
++
+This is the same as the `--decorate` option of the `git log`.
 
-log.initialDecorationSet::
+`log.initialDecorationSet`::
 	By default, `git log` only shows decorations for certain known ref
 	namespaces. If 'all' is specified, then show all refs as
 	decorations.
 
-log.excludeDecoration::
+`log.excludeDecoration`::
 	Exclude the specified patterns from the log decorations. This is
 	similar to the `--decorate-refs-exclude` command-line option, but
 	the config option can be overridden by the `--decorate-refs`
 	option.
 
-log.diffMerges::
+`log.diffMerges`::
 	Set diff format to be used when `--diff-merges=on` is
 	specified, see `--diff-merges` in linkgit:git-log[1] for
 	details. Defaults to `separate`.
 
-log.follow::
+`log.follow`::
 	If `true`, `git log` will act as if the `--follow` option was used when
 	a single <path> is given.  This has the same limitations as `--follow`,
 	i.e. it cannot be used to follow multiple files and does not work well
 	on non-linear history.
 
-log.graphColors::
+`log.graphColors`::
 	A list of colors, separated by commas, that can be used to draw
 	history lines in `git log --graph`.
 
-log.showRoot::
+`log.showRoot`::
 	If true, the initial commit will be shown as a big creation event.
 	This is equivalent to a diff against an empty tree.
 	Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which
 	normally hide the root commit will now show it. True by default.
 
-log.showSignature::
+`log.showSignature`::
 	If true, makes linkgit:git-log[1], linkgit:git-show[1], and
 	linkgit:git-whatchanged[1] assume `--show-signature`.
 
-log.mailmap::
+`log.mailmap`::
 	If true, makes linkgit:git-log[1], linkgit:git-show[1], and
 	linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise
 	assume `--no-use-mailmap`. True by default.
diff --git a/Documentation/config/lsrefs.txt b/Documentation/config/lsrefs.adoc
index 3d88fb0bad..3d88fb0bad 100644
--- a/Documentation/config/lsrefs.txt
+++ b/Documentation/config/lsrefs.adoc
diff --git a/Documentation/config/mailinfo.txt b/Documentation/config/mailinfo.adoc
index ec3a5d81f7..ec3a5d81f7 100644
--- a/Documentation/config/mailinfo.txt
+++ b/Documentation/config/mailinfo.adoc
diff --git a/Documentation/config/mailmap.txt b/Documentation/config/mailmap.adoc
index 48cbc30722..48cbc30722 100644
--- a/Documentation/config/mailmap.txt
+++ b/Documentation/config/mailmap.adoc
diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc
new file mode 100644
index 0000000000..d0c38f03fa
--- /dev/null
+++ b/Documentation/config/maintenance.adoc
@@ -0,0 +1,135 @@
+maintenance.auto::
+	This boolean config option controls whether some commands run
+	`git maintenance run --auto` after doing their normal work. Defaults
+	to true.
+
+maintenance.autoDetach::
+	Many Git commands trigger automatic maintenance after they have
+	written data into the repository. This boolean config option
+	controls whether this automatic maintenance shall happen in the
+	foreground or whether the maintenance process shall detach and
+	continue to run in the background.
++
+If unset, the value of `gc.autoDetach` is used as a fallback. Defaults
+to true if both are unset, meaning that the maintenance process will
+detach.
+
+maintenance.strategy::
+	This string config option provides a way to specify one of a few
+	recommended strategies for repository maintenance. This affects
+	which tasks are run during `git maintenance run`, provided no
+	`--task=<task>` arguments are provided. This setting impacts manual
+	maintenance, auto-maintenance as well as scheduled maintenance. The
+	tasks that run may be different depending on the maintenance type.
++
+The maintenance strategy can be further tweaked by setting
+`maintenance.<task>.enabled` and `maintenance.<task>.schedule`. If set, these
+values are used instead of the defaults provided by `maintenance.strategy`.
++
+The possible strategies are:
++
+* `none`: This strategy implies no tasks are run at all. This is the default
+  strategy for scheduled maintenance.
+* `gc`: This strategy runs the `gc` task. This is the default strategy for
+  manual maintenance.
+* `geometric`: This strategy performs geometric repacking of packfiles and
+  keeps auxiliary data structures up-to-date. The strategy expires data in the
+  reflog and removes worktrees that cannot be located anymore. When the
+  geometric repacking strategy would decide to do an all-into-one repack, then
+  the strategy generates a cruft pack for all unreachable objects. Objects that
+  are already part of a cruft pack will be expired.
++
+This repacking strategy is a full replacement for the `gc` strategy and is
+recommended for large repositories.
+* `incremental`: This setting optimizes for performing small maintenance
+  activities that do not delete any data. This does not schedule the `gc`
+  task, but runs the `prefetch` and `commit-graph` tasks hourly, the
+  `loose-objects` and `incremental-repack` tasks daily, and the `pack-refs`
+  task weekly. Manual repository maintenance uses the `gc` task.
+
+maintenance.<task>.enabled::
+	This boolean config option controls whether the maintenance task
+	with name `<task>` is run when no `--task` option is specified to
+	`git maintenance run`. These config values are ignored if a
+	`--task` option exists. By default, only `maintenance.gc.enabled`
+	is true.
+
+maintenance.<task>.schedule::
+	This config option controls whether or not the given `<task>` runs
+	during a `git maintenance run --schedule=<frequency>` command. The
+	value must be one of "hourly", "daily", or "weekly".
+
+maintenance.commit-graph.auto::
+	This integer config option controls how often the `commit-graph` task
+	should be run as part of `git maintenance run --auto`. If zero, then
+	the `commit-graph` task will not run with the `--auto` option. A
+	negative value will force the task to run every time. Otherwise, a
+	positive value implies the command should run when the number of
+	reachable commits that are not in the commit-graph file is at least
+	the value of `maintenance.commit-graph.auto`. The default value is
+	100.
+
+maintenance.loose-objects.auto::
+	This integer config option controls how often the `loose-objects` task
+	should be run as part of `git maintenance run --auto`. If zero, then
+	the `loose-objects` task will not run with the `--auto` option. A
+	negative value will force the task to run every time. Otherwise, a
+	positive value implies the command should run when the number of
+	loose objects is at least the value of `maintenance.loose-objects.auto`.
+	The default value is 100.
+
+maintenance.loose-objects.batchSize::
+	This integer config option controls the maximum number of loose objects
+	written into a packfile during the `loose-objects` task. The default is
+	fifty thousand. Use value `0` to indicate no limit.
+
+maintenance.incremental-repack.auto::
+	This integer config option controls how often the `incremental-repack`
+	task should be run as part of `git maintenance run --auto`. If zero,
+	then the `incremental-repack` task will not run with the `--auto`
+	option. A negative value will force the task to run every time.
+	Otherwise, a positive value implies the command should run when the
+	number of pack-files not in the multi-pack-index is at least the value
+	of `maintenance.incremental-repack.auto`. The default value is 10.
+
+maintenance.geometric-repack.auto::
+	This integer config option controls how often the `geometric-repack`
+	task should be run as part of `git maintenance run --auto`. If zero,
+	then the `geometric-repack` task will not run with the `--auto`
+	option. A negative value will force the task to run every time.
+	Otherwise, a positive value implies the command should run either when
+	there are packfiles that need to be merged together to retain the
+	geometric progression, or when there are at least this many loose
+	objects that would be written into a new packfile. The default value is
+	100.
+
+maintenance.geometric-repack.splitFactor::
+	This integer config option controls the factor used for the geometric
+	sequence. See the `--geometric=` option in linkgit:git-repack[1] for
+	more details. Defaults to `2`.
+
+maintenance.reflog-expire.auto::
+	This integer config option controls how often the `reflog-expire` task
+	should be run as part of `git maintenance run --auto`. If zero, then
+	the `reflog-expire` task will not run with the `--auto` option. A
+	negative value will force the task to run every time. Otherwise, a
+	positive value implies the command should run when the number of
+	expired reflog entries in the "HEAD" reflog is at least the value of
+	`maintenance.loose-objects.auto`. The default value is 100.
+
+maintenance.rerere-gc.auto::
+	This integer config option controls how often the `rerere-gc` task
+	should be run as part of `git maintenance run --auto`. If zero, then
+	the `rerere-gc` task will not run with the `--auto` option. A negative
+	value will force the task to run every time. Otherwise, any positive
+	value implies the command will run when the "rr-cache" directory exists
+	and has at least one entry, regardless of whether it is stale or not.
+	This heuristic may be refined in the future. The default value is 1.
+
+maintenance.worktree-prune.auto::
+	This integer config option controls how often the `worktree-prune` task
+	should be run as part of `git maintenance run --auto`. If zero, then
+	the `worktree-prune` task will not run with the `--auto` option. A
+	negative value will force the task to run every time. Otherwise, a
+	positive value implies the command should run when the number of
+	prunable worktrees exceeds the value. The default value is 1.
diff --git a/Documentation/config/maintenance.txt b/Documentation/config/maintenance.txt
deleted file mode 100644
index 72a9d6cf81..0000000000
--- a/Documentation/config/maintenance.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-maintenance.auto::
-	This boolean config option controls whether some commands run
-	`git maintenance run --auto` after doing their normal work. Defaults
-	to true.
-
-maintenance.autoDetach::
-	Many Git commands trigger automatic maintenance after they have
-	written data into the repository. This boolean config option
-	controls whether this automatic maintenance shall happen in the
-	foreground or whether the maintenance process shall detach and
-	continue to run in the background.
-+
-If unset, the value of `gc.autoDetach` is used as a fallback. Defaults
-to true if both are unset, meaning that the maintenance process will
-detach.
-
-maintenance.strategy::
-	This string config option provides a way to specify one of a few
-	recommended schedules for background maintenance. This only affects
-	which tasks are run during `git maintenance run --schedule=X`
-	commands, provided no `--task=<task>` arguments are provided.
-	Further, if a `maintenance.<task>.schedule` config value is set,
-	then that value is used instead of the one provided by
-	`maintenance.strategy`. The possible strategy strings are:
-+
-* `none`: This default setting implies no tasks are run at any schedule.
-* `incremental`: This setting optimizes for performing small maintenance
-  activities that do not delete any data. This does not schedule the `gc`
-  task, but runs the `prefetch` and `commit-graph` tasks hourly, the
-  `loose-objects` and `incremental-repack` tasks daily, and the `pack-refs`
-  task weekly.
-
-maintenance.<task>.enabled::
-	This boolean config option controls whether the maintenance task
-	with name `<task>` is run when no `--task` option is specified to
-	`git maintenance run`. These config values are ignored if a
-	`--task` option exists. By default, only `maintenance.gc.enabled`
-	is true.
-
-maintenance.<task>.schedule::
-	This config option controls whether or not the given `<task>` runs
-	during a `git maintenance run --schedule=<frequency>` command. The
-	value must be one of "hourly", "daily", or "weekly".
-
-maintenance.commit-graph.auto::
-	This integer config option controls how often the `commit-graph` task
-	should be run as part of `git maintenance run --auto`. If zero, then
-	the `commit-graph` task will not run with the `--auto` option. A
-	negative value will force the task to run every time. Otherwise, a
-	positive value implies the command should run when the number of
-	reachable commits that are not in the commit-graph file is at least
-	the value of `maintenance.commit-graph.auto`. The default value is
-	100.
-
-maintenance.loose-objects.auto::
-	This integer config option controls how often the `loose-objects` task
-	should be run as part of `git maintenance run --auto`. If zero, then
-	the `loose-objects` task will not run with the `--auto` option. A
-	negative value will force the task to run every time. Otherwise, a
-	positive value implies the command should run when the number of
-	loose objects is at least the value of `maintenance.loose-objects.auto`.
-	The default value is 100.
-
-maintenance.incremental-repack.auto::
-	This integer config option controls how often the `incremental-repack`
-	task should be run as part of `git maintenance run --auto`. If zero,
-	then the `incremental-repack` task will not run with the `--auto`
-	option. A negative value will force the task to run every time.
-	Otherwise, a positive value implies the command should run when the
-	number of pack-files not in the multi-pack-index is at least the value
-	of `maintenance.incremental-repack.auto`. The default value is 10.
diff --git a/Documentation/config/man.txt b/Documentation/config/man.adoc
index 5a0f82cc23..5a0f82cc23 100644
--- a/Documentation/config/man.txt
+++ b/Documentation/config/man.adoc
diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.adoc
index 82554d65a0..15a4c14c38 100644
--- a/Documentation/config/merge.txt
+++ b/Documentation/config/merge.adoc
@@ -1,9 +1,9 @@
-merge.conflictStyle::
+`merge.conflictStyle`::
 	Specify the style in which conflicted hunks are written out to
 	working tree files upon merge.  The default is "merge", which
-	shows a `<<<<<<<` conflict marker, changes made by one side,
+	shows a +<<<<<<<+ conflict marker, changes made by one side,
 	a `=======` marker, changes made by the other side, and then
-	a `>>>>>>>` marker.  An alternate style, "diff3", adds a `|||||||`
+	a +>>>>>>>+ marker.  An alternate style, "diff3", adds a +|||||||+
 	marker and the original text before the `=======` marker.  The
 	"merge" style tends to produce smaller conflict regions than diff3,
 	both because of the exclusion of the original text, and because
@@ -13,17 +13,17 @@ merge.conflictStyle::
 	the conflict region when those matching lines appear near either
 	the beginning or end of a conflict region.
 
-merge.defaultToUpstream::
+`merge.defaultToUpstream`::
 	If merge is called without any commit argument, merge the upstream
 	branches configured for the current branch by using their last
 	observed values stored in their remote-tracking branches.
 	The values of the `branch.<current branch>.merge` that name the
-	branches at the remote named by `branch.<current branch>.remote`
+	branches at the remote named by `branch.<current-branch>.remote`
 	are consulted, and then they are mapped via `remote.<remote>.fetch`
 	to their corresponding remote-tracking branches, and the tips of
 	these tracking branches are merged. Defaults to true.
 
-merge.ff::
+`merge.ff`::
 	By default, Git does not create an extra merge commit when merging
 	a commit that is a descendant of the current commit. Instead, the
 	tip of the current branch is fast-forwarded. When set to `false`,
@@ -33,77 +33,92 @@ merge.ff::
 	allowed (equivalent to giving the `--ff-only` option from the
 	command line).
 
-merge.verifySignatures::
-	If true, this is equivalent to the --verify-signatures command
+`merge.verifySignatures`::
+	If true, this is equivalent to the `--verify-signatures` command
 	line option. See linkgit:git-merge[1] for details.
 
-include::fmt-merge-msg.txt[]
+include::fmt-merge-msg.adoc[]
 
-merge.renameLimit::
+`merge.renameLimit`::
 	The number of files to consider in the exhaustive portion of
 	rename detection during a merge.  If not specified, defaults
-	to the value of diff.renameLimit.  If neither
-	merge.renameLimit nor diff.renameLimit are specified,
+	to the value of `diff.renameLimit`.  If neither
+	`merge.renameLimit` nor `diff.renameLimit` are specified,
 	currently defaults to 7000.  This setting has no effect if
 	rename detection is turned off.
 
-merge.renames::
-	Whether Git detects renames.  If set to "false", rename detection
-	is disabled. If set to "true", basic rename detection is enabled.
+`merge.renames`::
+	Whether Git detects renames.  If set to `false`, rename detection
+	is disabled. If set to `true`, basic rename detection is enabled.
 	Defaults to the value of diff.renames.
 
-merge.directoryRenames::
+`merge.directoryRenames`::
 	Whether Git detects directory renames, affecting what happens at
 	merge time to new files added to a directory on one side of
 	history when that directory was renamed on the other side of
-	history.  If merge.directoryRenames is set to "false", directory
-	rename detection is disabled, meaning that such new files will be
-	left behind in the old directory.  If set to "true", directory
-	rename detection is enabled, meaning that such new files will be
-	moved into the new directory.  If set to "conflict", a conflict
-	will be reported for such paths.  If merge.renames is false,
-	merge.directoryRenames is ignored and treated as false.  Defaults
-	to "conflict".
-
-merge.renormalize::
+	history. Possible values are:
++
+--
+`false`;; Directory rename detection is disabled, meaning that such new files will be
+	left behind in the old directory.
+`true`;; Directory rename detection is enabled, meaning that such new files will be
+	moved into the new directory.
+`conflict`;; A conflict will be reported for such paths.
+--
++
+If `merge.renames` is `false`, `merge.directoryRenames` is ignored and treated
+as `false`. Defaults to `conflict`.
+
+`merge.renormalize`::
 	Tell Git that canonical representation of files in the
 	repository has changed over time (e.g. earlier commits record
-	text files with CRLF line endings, but recent ones use LF line
-	endings).  In such a repository, Git can convert the data
+	text files with _CRLF_ line endings, but recent ones use _LF_ line
+	endings).  In such a repository, for each file where a
+	three-way content merge is needed, Git can convert the data
 	recorded in commits to a canonical form before performing a
 	merge to reduce unnecessary conflicts.  For more information,
 	see section "Merging branches with differing checkin/checkout
 	attributes" in linkgit:gitattributes[5].
 
-merge.stat::
-	Whether to print the diffstat between ORIG_HEAD and the merge result
-	at the end of the merge.  True by default.
-
-merge.autoStash::
-	When set to true, automatically create a temporary stash entry
+`merge.stat`::
+	What, if anything, to print between `ORIG_HEAD` and the merge result
+	at the end of the merge.  Possible values are:
++
+--
+`false`;; Show nothing.
+`true`;; Show `git diff --diffstat --summary ORIG_HEAD`.
+`compact`;; Show `git diff --compact-summary ORIG_HEAD`.
+--
++
+but any unrecognised value (e.g., a value added by a future version of
+Git) is taken as `true` instead of triggering an error.  Defaults to
+`true`.
+
+`merge.autoStash`::
+	When set to `true`, automatically create a temporary stash entry
 	before the operation begins, and apply it after the operation
 	ends.  This means that you can run merge on a dirty worktree.
 	However, use with care: the final stash application after a
 	successful merge might result in non-trivial conflicts.
 	This option can be overridden by the `--no-autostash` and
 	`--autostash` options of linkgit:git-merge[1].
-	Defaults to false.
+	Defaults to `false`.
 
-merge.tool::
+`merge.tool`::
 	Controls which merge tool is used by linkgit:git-mergetool[1].
 	The list below shows the valid built-in values.
 	Any other value is treated as a custom merge tool and requires
-	that a corresponding mergetool.<tool>.cmd variable is defined.
+	that a corresponding `mergetool.<tool>.cmd` variable is defined.
 
-merge.guitool::
+`merge.guitool`::
 	Controls which merge tool is used by linkgit:git-mergetool[1] when the
-	-g/--gui flag is specified. The list below shows the valid built-in values.
+	`-g`/`--gui` flag is specified. The list below shows the valid built-in values.
 	Any other value is treated as a custom merge tool and requires that a
-	corresponding mergetool.<guitool>.cmd variable is defined.
+	corresponding `mergetool.<guitool>.cmd` variable is defined.
 
-include::{build_dir}/mergetools-merge.txt[]
+include::{build_dir}/mergetools-merge.adoc[]
 
-merge.verbosity::
+`merge.verbosity`::
 	Controls the amount of output shown by the recursive merge
 	strategy.  Level 0 outputs nothing except a final error
 	message if conflicts were detected. Level 1 outputs only
@@ -111,15 +126,15 @@ merge.verbosity::
 	above outputs debugging information.  The default is level 2.
 	Can be overridden by the `GIT_MERGE_VERBOSITY` environment variable.
 
-merge.<driver>.name::
+`merge.<driver>.name`::
 	Defines a human-readable name for a custom low-level
 	merge driver.  See linkgit:gitattributes[5] for details.
 
-merge.<driver>.driver::
+`merge.<driver>.driver`::
 	Defines the command that implements a custom low-level
 	merge driver.  See linkgit:gitattributes[5] for details.
 
-merge.<driver>.recursive::
+`merge.<driver>.recursive`::
 	Names a low-level merge driver to be used when
 	performing an internal merge between common ancestors.
 	See linkgit:gitattributes[5] for details.
diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.adoc
index 00bf665aa0..7064f5a462 100644
--- a/Documentation/config/mergetool.txt
+++ b/Documentation/config/mergetool.adoc
@@ -1,24 +1,24 @@
-mergetool.<tool>.path::
+`mergetool.<tool>.path`::
 	Override the path for the given tool.  This is useful in case
-	your tool is not in the PATH.
+	your tool is not in the `$PATH`.
 
-mergetool.<tool>.cmd::
+`mergetool.<tool>.cmd`::
 	Specify the command to invoke the specified merge tool.  The
 	specified command is evaluated in shell with the following
-	variables available: 'BASE' is the name of a temporary file
+	variables available: `BASE` is the name of a temporary file
 	containing the common base of the files to be merged, if available;
-	'LOCAL' is the name of a temporary file containing the contents of
-	the file on the current branch; 'REMOTE' is the name of a temporary
+	`LOCAL` is the name of a temporary file containing the contents of
+	the file on the current branch; `REMOTE` is the name of a temporary
 	file containing the contents of the file from the branch being
-	merged; 'MERGED' contains the name of the file to which the merge
+	merged; `MERGED` contains the name of the file to which the merge
 	tool should write the results of a successful merge.
 
-mergetool.<tool>.hideResolved::
+`mergetool.<tool>.hideResolved`::
 	Allows the user to override the global `mergetool.hideResolved` value
 	for a specific tool. See `mergetool.hideResolved` for the full
 	description.
 
-mergetool.<tool>.trustExitCode::
+`mergetool.<tool>.trustExitCode`::
 	For a custom merge command, specify whether the exit code of
 	the merge command can be used to determine whether the merge was
 	successful.  If this is not set to true then the merge target file
@@ -26,7 +26,7 @@ mergetool.<tool>.trustExitCode::
 	if the file has been updated; otherwise, the user is prompted to
 	indicate the success of the merge.
 
-mergetool.meld.hasOutput::
+`mergetool.meld.hasOutput`::
 	Older versions of `meld` do not support the `--output` option.
 	Git will attempt to detect whether `meld` supports `--output`
 	by inspecting the output of `meld --help`.  Configuring
@@ -35,7 +35,7 @@ mergetool.meld.hasOutput::
 	to `true` tells Git to unconditionally use the `--output` option,
 	and `false` avoids using `--output`.
 
-mergetool.meld.useAutoMerge::
+`mergetool.meld.useAutoMerge`::
 	When the `--auto-merge` is given, meld will merge all non-conflicting
 	parts automatically, highlight the conflicting parts, and wait for
 	user decision.  Setting `mergetool.meld.useAutoMerge` to `true` tells
@@ -45,15 +45,15 @@ mergetool.meld.useAutoMerge::
 	value of `false` avoids using `--auto-merge` altogether, and is the
 	default value.
 
-mergetool.<vimdiff variant>.layout::
-	Configure the split window layout for vimdiff's `<variant>`, which is any of `vimdiff`,
+`mergetool.<variant>.layout`::
+	Configure the split window layout for vimdiff's _<variant>_, which is any of `vimdiff`,
 	`nvimdiff`, `gvimdiff`.
 	Upon launching `git mergetool` with `--tool=<variant>` (or without `--tool`
-	if `merge.tool` is configured as `<variant>`), Git will consult
+	if `merge.tool` is configured as _<variant>_), Git will consult
 	`mergetool.<variant>.layout` to determine the tool's layout. If the
-	variant-specific configuration is not available, `vimdiff`'s is used as
+	variant-specific configuration is not available, `vimdiff` ' s is used as
 	fallback.  If that too is not available, a default layout with 4 windows
-	will be used.  To configure the layout, see the `BACKEND SPECIFIC HINTS`
+	will be used.  To configure the layout, see the 'BACKEND SPECIFIC HINTS'
 ifdef::git-mergetool[]
 	section.
 endif::[]
@@ -61,39 +61,39 @@ ifndef::git-mergetool[]
 	section in linkgit:git-mergetool[1].
 endif::[]
 
-mergetool.hideResolved::
+`mergetool.hideResolved`::
 	During a merge, Git will automatically resolve as many conflicts as
-	possible and write the 'MERGED' file containing conflict markers around
-	any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally
-	represent the versions of the file from before Git's conflict
-	resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so
+	possible and write the `$MERGED` file containing conflict markers around
+	any conflicts that it cannot resolve; `$LOCAL` and `$REMOTE` normally
+	are the versions of the file from before Git's conflict
+	resolution. This flag causes `$LOCAL` and `$REMOTE` to be overwritten so
 	that only the unresolved conflicts are presented to the merge tool. Can
 	be configured per-tool via the `mergetool.<tool>.hideResolved`
 	configuration variable. Defaults to `false`.
 
-mergetool.keepBackup::
+`mergetool.keepBackup`::
 	After performing a merge, the original file with conflict markers
 	can be saved as a file with a `.orig` extension.  If this variable
 	is set to `false` then this file is not preserved.  Defaults to
 	`true` (i.e. keep the backup files).
 
-mergetool.keepTemporaries::
+`mergetool.keepTemporaries`::
 	When invoking a custom merge tool, Git uses a set of temporary
 	files to pass to the tool. If the tool returns an error and this
 	variable is set to `true`, then these temporary files will be
 	preserved; otherwise, they will be removed after the tool has
 	exited. Defaults to `false`.
 
-mergetool.writeToTemp::
-	Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of
+`mergetool.writeToTemp`::
+	Git writes temporary `BASE`, `LOCAL`, and `REMOTE` versions of
 	conflicting files in the worktree by default.  Git will attempt
 	to use a temporary directory for these files when set `true`.
 	Defaults to `false`.
 
-mergetool.prompt::
+`mergetool.prompt`::
 	Prompt before each invocation of the merge resolution program.
 
-mergetool.guiDefault::
+`mergetool.guiDefault`::
 	Set `true` to use the `merge.guitool` by default (equivalent to
 	specifying the `--gui` argument), or `auto` to select `merge.guitool`
 	or `merge.tool` depending on the presence of a `DISPLAY` environment
diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.adoc
index 43db8e808d..b7e536496f 100644
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.adoc
@@ -1,4 +1,4 @@
-notes.mergeStrategy::
+`notes.mergeStrategy`::
 	Which merge strategy to choose by default when resolving notes
 	conflicts.  Must be one of `manual`, `ours`, `theirs`, `union`, or
 	`cat_sort_uniq`.  Defaults to `manual`.  See the "NOTES MERGE STRATEGIES"
@@ -7,17 +7,17 @@ notes.mergeStrategy::
 This setting can be overridden by passing the `--strategy` option to
 linkgit:git-notes[1].
 
-notes.<name>.mergeStrategy::
+`notes.<name>.mergeStrategy`::
 	Which merge strategy to choose when doing a notes merge into
-	refs/notes/<name>.  This overrides the more general
-	"notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section in
+	`refs/notes/<name>`.  This overrides the more general
+	`notes.mergeStrategy`.  See the "NOTES MERGE STRATEGIES" section in
 	linkgit:git-notes[1] for more information on the available strategies.
 
-notes.displayRef::
+`notes.displayRef`::
 	Which ref (or refs, if a glob or specified more than once), in
 	addition to the default set by `core.notesRef` or
 	`GIT_NOTES_REF`, to read notes from when showing commit
-	messages with the 'git log' family of commands.
+	messages with the `git log` family of commands.
 +
 This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
 environment variable, which must be a colon separated list of refs or
@@ -26,27 +26,27 @@ globs.
 A warning will be issued for refs that do not exist,
 but a glob that does not match any refs is silently ignored.
 +
-This setting can be disabled by the `--no-notes` option to the 'git
-log' family of commands, or by the `--notes=<ref>` option accepted by
+This setting can be disabled by the `--no-notes` option to the linkgit:git-log[1]
+family of commands, or by the `--notes=<ref>` option accepted by
 those commands.
 +
-The effective value of "core.notesRef" (possibly overridden by
-GIT_NOTES_REF) is also implicitly added to the list of refs to be
+The effective value of `core.notesRef` (possibly overridden by
+`GIT_NOTES_REF`) is also implicitly added to the list of refs to be
 displayed.
 
-notes.rewrite.<command>::
-	When rewriting commits with <command> (currently `amend` or
+`notes.rewrite.<command>`::
+	When rewriting commits with _<command>_ (currently `amend` or
 	`rebase`), if this variable is `false`, git will not copy
 	notes from the original to the rewritten commit.  Defaults to
-	`true`.  See also "`notes.rewriteRef`" below.
+	`true`.  See also `notes.rewriteRef` below.
 +
 This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
 environment variable, which must be a colon separated list of refs or
 globs.
 
-notes.rewriteMode::
+`notes.rewriteMode`::
 	When copying notes during a rewrite (see the
-	"notes.rewrite.<command>" option), determines what to do if
+	`notes.rewrite.<command>` option), determines what to do if
 	the target commit already has a note.  Must be one of
 	`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.
 	Defaults to `concatenate`.
@@ -54,7 +54,7 @@ notes.rewriteMode::
 This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
 environment variable.
 
-notes.rewriteRef::
+`notes.rewriteRef`::
 	When copying notes during a rewrite, specifies the (fully
 	qualified) ref whose notes should be copied.  May be a glob,
 	in which case notes in all matching refs will be copied.  You
diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.adoc
index da527377fa..75402d5579 100644
--- a/Documentation/config/pack.txt
+++ b/Documentation/config/pack.adoc
@@ -155,6 +155,10 @@ pack.useSparse::
 	commits contain certain types of direct renames. Default is
 	`true`.
 
+pack.usePathWalk::
+	Enable the `--path-walk` option by default for `git pack-objects`
+	processes. See linkgit:git-pack-objects[1] for full details.
+
 pack.preferBitmapTips::
 	When selecting which commits will receive bitmaps, prefer a
 	commit at the tip of any reference that is a suffix of any value
diff --git a/Documentation/config/pager.txt b/Documentation/config/pager.adoc
index d3731cf66c..d3731cf66c 100644
--- a/Documentation/config/pager.txt
+++ b/Documentation/config/pager.adoc
diff --git a/Documentation/config/pretty.txt b/Documentation/config/pretty.adoc
index 063c6b63d9..063c6b63d9 100644
--- a/Documentation/config/pretty.txt
+++ b/Documentation/config/pretty.adoc
diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc
new file mode 100644
index 0000000000..93e5e0d9b5
--- /dev/null
+++ b/Documentation/config/promisor.adoc
@@ -0,0 +1,91 @@
+promisor.quiet::
+	If set to "true" assume `--quiet` when fetching additional
+	objects for a partial clone.
+
+promisor.advertise::
+	If set to "true", a server will use the "promisor-remote"
+	capability, see linkgit:gitprotocol-v2[5], to advertise the
+	promisor remotes it is using, if it uses some. Default is
+	"false", which means the "promisor-remote" capability is not
+	advertised.
+
+promisor.sendFields::
+	A comma or space separated list of additional remote related
+	field names. A server sends these field names and the
+	associated field values from its configuration when
+	advertising its promisor remotes using the "promisor-remote"
+	capability, see linkgit:gitprotocol-v2[5]. Currently, only the
+	"partialCloneFilter" and "token" field names are supported.
++
+`partialCloneFilter`:: contains the partial clone filter
+used for the remote.
++
+`token`:: contains an authentication token for the remote.
++
+When a field name is part of this list and a corresponding
+"remote.foo.<field-name>" config variable is set on the server to a
+non-empty value, then the field name and value are sent when
+advertising the promisor remote "foo".
++
+This list has no effect unless the "promisor.advertise" config
+variable is set to "true", and the "name" and "url" fields are always
+advertised regardless of this setting.
+
+promisor.acceptFromServer::
+	If set to "all", a client will accept all the promisor remotes
+	a server might advertise using the "promisor-remote"
+	capability. If set to "knownName" the client will accept
+	promisor remotes which are already configured on the client
+	and have the same name as those advertised by the client. This
+	is not very secure, but could be used in a corporate setup
+	where servers and clients are trusted to not switch name and
+	URLs. If set to "knownUrl", the client will accept promisor
+	remotes which have both the same name and the same URL
+	configured on the client as the name and URL advertised by the
+	server. This is more secure than "all" or "knownName", so it
+	should be used if possible instead of those options. Default
+	is "none", which means no promisor remote advertised by a
+	server will be accepted. By accepting a promisor remote, the
+	client agrees that the server might omit objects that are
+	lazily fetchable from this promisor remote from its responses
+	to "fetch" and "clone" requests from the client. Name and URL
+	comparisons are case sensitive. See linkgit:gitprotocol-v2[5].
+
+promisor.checkFields::
+	A comma or space separated list of additional remote related
+	field names. A client checks if the values of these fields
+	transmitted by a server correspond to the values of these
+	fields in its own configuration before accepting a promisor
+	remote. Currently, "partialCloneFilter" and "token" are the
+	only supported field names.
++
+If one of these field names (e.g., "token") is being checked for an
+advertised promisor remote (e.g., "foo"), three conditions must be met
+for the check of this specific field to pass:
++
+1. The corresponding local configuration (e.g., `remote.foo.token`)
+   must be set.
+2. The server must advertise the "token" field for remote "foo".
+3. The value of the locally configured `remote.foo.token` must exactly
+   match the value advertised by the server for the "token" field.
++
+If any of these conditions is not met for any field name listed in
+`promisor.checkFields`, the advertised remote "foo" is rejected.
++
+For the "partialCloneFilter" field, this allows the client to ensure
+that the server's filter matches what it expects locally, preventing
+inconsistencies in filtering behavior. For the "token" field, this can
+be used to verify that authentication credentials match expected
+values.
++
+Field values are compared case-sensitively.
++
+The "name" and "url" fields are always checked according to the
+`promisor.acceptFromServer` policy, independently of this setting.
++
+The field names and values should be passed by the server through the
+"promisor-remote" capability by using the `promisor.sendFields` config
+variable. The fields are checked only if the
+`promisor.acceptFromServer` config variable is not set to "None". If
+set to "None", this config variable has no effect. See
+linkgit:gitprotocol-v2[5].
diff --git a/Documentation/config/promisor.txt b/Documentation/config/promisor.txt
deleted file mode 100644
index 98c5cb2ec2..0000000000
--- a/Documentation/config/promisor.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-promisor.quiet::
-	If set to "true" assume `--quiet` when fetching additional
-	objects for a partial clone.
diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.adoc
index a9bf187a93..a9bf187a93 100644
--- a/Documentation/config/protocol.txt
+++ b/Documentation/config/protocol.adoc
diff --git a/Documentation/config/pull.txt b/Documentation/config/pull.adoc
index 9349e09261..125c930f72 100644
--- a/Documentation/config/pull.txt
+++ b/Documentation/config/pull.adoc
@@ -29,5 +29,21 @@ pull.octopus::
 	The default merge strategy to use when pulling multiple branches
 	at once.
 
+pull.autoStash::
+	When set to true, automatically create a temporary stash entry
+	to record the local changes before the operation begins, and
+	restore them after the operation completes.  When your "git
+	pull" rebases (instead of merges), this may be convenient, since
+	unlike merging pull that tolerates local changes that do not
+	interfere with the merge, rebasing pull refuses to work with any
+	local changes.
++
+If `pull.autostash` is set (either to true or false),
+`merge.autostash` and `rebase.autostash` are ignored.  If
+`pull.autostash` is not set at all, depending on the value of
+`pull.rebase`, `merge.autostash` or `rebase.autostash` is used
+instead.  Can be overridden by the `--[no-]autostash` command line
+option.
+
 pull.twohead::
 	The default merge strategy to use when pulling a single branch.
diff --git a/Documentation/config/push.txt b/Documentation/config/push.adoc
index 0acbbea18a..0acbbea18a 100644
--- a/Documentation/config/push.txt
+++ b/Documentation/config/push.adoc
diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.adoc
index c6187ab28b..c6187ab28b 100644
--- a/Documentation/config/rebase.txt
+++ b/Documentation/config/rebase.adoc
diff --git a/Documentation/config/receive.txt b/Documentation/config/receive.adoc
index 36a1e6f2d2..36a1e6f2d2 100644
--- a/Documentation/config/receive.txt
+++ b/Documentation/config/receive.adoc
diff --git a/Documentation/config/reftable.txt b/Documentation/config/reftable.adoc
index 57087803a5..57087803a5 100644
--- a/Documentation/config/reftable.txt
+++ b/Documentation/config/reftable.adoc
diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.adoc
index 4118c219c1..91e46f66f5 100644
--- a/Documentation/config/remote.txt
+++ b/Documentation/config/remote.adoc
@@ -101,21 +101,22 @@ remote.<name>.serverOption::
 	The default set of server options used when fetching from this remote.
 	These server options can be overridden by the `--server-option=` command
 	line arguments.
++
+This is a multi-valued variable, and an empty value can be used in a higher
+priority configuration file (e.g. `.git/config` in a repository) to clear
+the values inherited from a lower priority configuration files (e.g.
+`$HOME/.gitconfig`).
 
 remote.<name>.followRemoteHEAD::
-	How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`.
+	How linkgit:git-fetch[1] should handle updates to `remotes/<name>/HEAD`
+	when fetching using the configured refspecs of a remote.
 	The default value is "create", which will create `remotes/<name>/HEAD`
-	if it exists on the remote, but not locally, but will not touch an
-	already existing local reference. Setting to "warn" will print
-	a message if the remote has a different value, than the local one and
+	if it exists on the remote, but not locally; this will not touch an
+	already existing local reference. Setting it to "warn" will print
+	a message if the remote has a different value than the local one;
 	in case there is no local reference, it behaves like "create".
 	A variant on "warn" is "warn-if-not-$branch", which behaves like
 	"warn", but if `HEAD` on the remote is `$branch` it will be silent.
-	Setting to "always" will silently update it to the value on the remote.
-	Finally, setting it to "never" will never change or create the local
-	reference.
-+
-This is a multi-valued variable, and an empty value can be used in a higher
-priority configuration file (e.g. `.git/config` in a repository) to clear
-the values inherited from a lower priority configuration files (e.g.
-`$HOME/.gitconfig`).
+	Setting it to "always" will silently update `remotes/<name>/HEAD` to
+	the value on the remote.  Finally, setting it to "never" will never
+	change or create the local reference.
diff --git a/Documentation/config/remotes.txt b/Documentation/config/remotes.adoc
index 4cfe03221e..4cfe03221e 100644
--- a/Documentation/config/remotes.txt
+++ b/Documentation/config/remotes.adoc
diff --git a/Documentation/config/repack.txt b/Documentation/config/repack.adoc
index c79af6d7b8..e9e78dcb19 100644
--- a/Documentation/config/repack.txt
+++ b/Documentation/config/repack.adoc
@@ -39,3 +39,10 @@ repack.cruftThreads::
 	a cruft pack and the respective parameters are not given over
 	the command line. See similarly named `pack.*` configuration
 	variables for defaults and meaning.
+
+repack.midxMustContainCruft::
+	When set to true, linkgit:git-repack[1] will unconditionally include
+	cruft pack(s), if any, in the multi-pack index when invoked with
+	`--write-midx`. When false, cruft packs are only included in the MIDX
+	when necessary (e.g., because they might be required to form a
+	reachability closure with MIDX bitmaps). Defaults to true.
diff --git a/Documentation/config/rerere.txt b/Documentation/config/rerere.adoc
index 3a78b5ebb1..3a78b5ebb1 100644
--- a/Documentation/config/rerere.txt
+++ b/Documentation/config/rerere.adoc
diff --git a/Documentation/config/revert.txt b/Documentation/config/revert.adoc
index 802d6faca2..802d6faca2 100644
--- a/Documentation/config/revert.txt
+++ b/Documentation/config/revert.adoc
diff --git a/Documentation/config/safe.txt b/Documentation/config/safe.adoc
index 2d45c98b12..2d45c98b12 100644
--- a/Documentation/config/safe.txt
+++ b/Documentation/config/safe.adoc
diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.adoc
index 5ffcfc9f2a..90164c734d 100644
--- a/Documentation/config/sendemail.txt
+++ b/Documentation/config/sendemail.adoc
@@ -1,38 +1,38 @@
 sendemail.identity::
 	A configuration identity. When given, causes values in the
-	'sendemail.<identity>' subsection to take precedence over
-	values in the 'sendemail' section. The default identity is
+	`sendemail.<identity>` subsection to take precedence over
+	values in the `sendemail` section. The default identity is
 	the value of `sendemail.identity`.
 
 sendemail.smtpEncryption::
 	See linkgit:git-send-email[1] for description.  Note that this
-	setting is not subject to the 'identity' mechanism.
+	setting is not subject to the `identity` mechanism.
 
 sendemail.smtpSSLCertPath::
 	Path to ca-certificates (either a directory or a single file).
 	Set it to an empty string to disable certificate verification.
 
 sendemail.<identity>.*::
-	Identity-specific versions of the 'sendemail.*' parameters
+	Identity-specific versions of the `sendemail.*` parameters
 	found below, taking precedence over those when this
 	identity is selected, through either the command-line or
 	`sendemail.identity`.
 
 sendemail.multiEdit::
-	If true (default), a single editor instance will be spawned to edit
+	If `true` (default), a single editor instance will be spawned to edit
 	files you have to edit (patches when `--annotate` is used, and the
-	summary when `--compose` is used). If false, files will be edited one
+	summary when `--compose` is used). If `false`, files will be edited one
 	after the other, spawning a new editor each time.
 
 sendemail.confirm::
 	Sets the default for whether to confirm before sending. Must be
-	one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
+	one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm`
 	in the linkgit:git-send-email[1] documentation for the meaning of these
 	values.
 
 sendemail.mailmap::
-	If true, makes linkgit:git-send-email[1] assume `--mailmap`,
-	otherwise assume `--no-mailmap`. False by default.
+	If `true`, makes linkgit:git-send-email[1] assume `--mailmap`,
+	otherwise assume `--no-mailmap`. `False` by default.
 
 sendemail.mailmap.file::
 	The location of a linkgit:git-send-email[1] specific augmenting
@@ -51,7 +51,7 @@ sendemail.aliasesFile::
 
 sendemail.aliasFileType::
 	Format of the file(s) specified in sendemail.aliasesFile. Must be
-	one of 'mutt', 'mailrc', 'pine', 'elm', 'gnus', or 'sendmail'.
+	one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`.
 +
 What an alias file in each format looks like can be found in
 the documentation of the email program of the same name. The
@@ -88,6 +88,8 @@ sendemail.smtpServer::
 sendemail.smtpServerPort::
 sendemail.smtpServerOption::
 sendemail.smtpUser::
+sendemail.imapSentFolder::
+sendemail.useImapOnly::
 sendemail.thread::
 sendemail.transferEncoding::
 sendemail.validate::
@@ -96,12 +98,17 @@ sendemail.xmailer::
 	linkgit:git-send-email[1] command-line options. See its
 	documentation for details.
 
+sendemail.outlookidfix::
+	If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`,
+	and if `false` assume `--no-outlook-id-fix`. If not specified, it will
+	behave the same way as if `--outlook-id-fix` is not specified.
+
 sendemail.signedOffCc (deprecated)::
 	Deprecated alias for `sendemail.signedOffByCc`.
 
 sendemail.smtpBatchSize::
 	Number of messages to be sent per connection, after that a relogin
-	will happen.  If the value is 0 or undefined, send all messages in
+	will happen.  If the value is `0` or undefined, send all messages in
 	one connection.
 	See also the `--batch-size` option of linkgit:git-send-email[1].
 
@@ -111,5 +118,5 @@ sendemail.smtpReloginDelay::
 
 sendemail.forbidSendmailVariables::
 	To avoid common misconfiguration mistakes, linkgit:git-send-email[1]
-	will abort with a warning if any configuration options for "sendmail"
+	will abort with a warning if any configuration options for `sendmail`
 	exist. Set this variable to bypass the check.
diff --git a/Documentation/config/sequencer.txt b/Documentation/config/sequencer.adoc
index e664eef01d..e664eef01d 100644
--- a/Documentation/config/sequencer.txt
+++ b/Documentation/config/sequencer.adoc
diff --git a/Documentation/config/showbranch.txt b/Documentation/config/showbranch.adoc
index e79ecd9ee9..e79ecd9ee9 100644
--- a/Documentation/config/showbranch.txt
+++ b/Documentation/config/showbranch.adoc
diff --git a/Documentation/config/sparse.txt b/Documentation/config/sparse.adoc
index aff49a8d3a..aff49a8d3a 100644
--- a/Documentation/config/sparse.txt
+++ b/Documentation/config/sparse.adoc
diff --git a/Documentation/config/splitindex.txt b/Documentation/config/splitindex.adoc
index cfaa29610b..cfaa29610b 100644
--- a/Documentation/config/splitindex.txt
+++ b/Documentation/config/splitindex.adoc
diff --git a/Documentation/config/ssh.txt b/Documentation/config/ssh.adoc
index 2ca4bf93e1..2ca4bf93e1 100644
--- a/Documentation/config/ssh.txt
+++ b/Documentation/config/ssh.adoc
diff --git a/Documentation/config/stash.adoc b/Documentation/config/stash.adoc
new file mode 100644
index 0000000000..a1197ffd7d
--- /dev/null
+++ b/Documentation/config/stash.adoc
@@ -0,0 +1,32 @@
+ifndef::git-stash[]
+:see-show: See the description of the 'show' command in linkgit:git-stash[1].
+endif::git-stash[]
+
+ifdef::git-stash[]
+:see-show:
+endif::git-stash[]
+
+`stash.index`::
+	If this is set to true, `git stash apply` and `git stash pop` will
+	behave as if `--index` was supplied. Defaults to false.
+ifndef::git-stash[]
+See the descriptions in linkgit:git-stash[1].
++
+This also affects invocations of linkgit:git-stash[1] via `--autostash` from
+commands like linkgit:git-merge[1], linkgit:git-rebase[1], and
+linkgit:git-pull[1].
+endif::git-stash[]
+
+`stash.showIncludeUntracked`::
+	If this is set to true, the `git stash show` command will show
+	the untracked files of a stash entry. Defaults to false. {see-show}
+
+`stash.showPatch`::
+	If this is set to true, the `git stash show` command without an
+	option will show the stash entry in patch form.  Defaults to false.
+	{see-show}
+
+`stash.showStat`::
+	If this is set to true, the `git stash show` command without an
+	option will show a diffstat of the stash entry.  Defaults to true.
+	{see-show}
diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt
deleted file mode 100644
index ec1edaeba6..0000000000
--- a/Documentation/config/stash.txt
+++ /dev/null
@@ -1,14 +0,0 @@
-stash.showIncludeUntracked::
-	If this is set to true, the `git stash show` command will show
-	the untracked files of a stash entry.  Defaults to false. See
-	the description of the 'show' command in linkgit:git-stash[1].
-
-stash.showPatch::
-	If this is set to true, the `git stash show` command without an
-	option will show the stash entry in patch form.  Defaults to false.
-	See the description of the 'show' command in linkgit:git-stash[1].
-
-stash.showStat::
-	If this is set to true, the `git stash show` command without an
-	option will show a diffstat of the stash entry.  Defaults to true.
-	See the description of the 'show' command in linkgit:git-stash[1].
diff --git a/Documentation/config/status.txt b/Documentation/config/status.adoc
index 8caf90f51c..8caf90f51c 100644
--- a/Documentation/config/status.txt
+++ b/Documentation/config/status.adoc
diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.adoc
index 0672d99117..0672d99117 100644
--- a/Documentation/config/submodule.txt
+++ b/Documentation/config/submodule.adoc
diff --git a/Documentation/config/tag.adoc b/Documentation/config/tag.adoc
new file mode 100644
index 0000000000..d878da98d4
--- /dev/null
+++ b/Documentation/config/tag.adoc
@@ -0,0 +1,23 @@
+`tag.forceSignAnnotated`::
+	A boolean to specify whether annotated tags created should be GPG signed.
+	If `--annotate` is specified on the command line, it takes
+	precedence over this option.
+
+`tag.sort`::
+ifdef::git-tag[]
+This variable controls the sort ordering of tags when displayed by `git-tag`.
+endif::git-tag[]
+ifndef::git-tag[]
+This variable controls the sort ordering of tags when displayed by
+linkgit:git-tag[1].
+endif::git-tag[]
+Without the `--sort=<value>` option provided, the value of this variable will
+be used as the default.
+
+`tag.gpgSign`::
+	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
+	several times. Note that this option doesn't affect tag signing
+	behavior enabled by `-u <keyid>` or `--local-user=<keyid>` options.
diff --git a/Documentation/config/tag.txt b/Documentation/config/tag.txt
deleted file mode 100644
index 5062a057ff..0000000000
--- a/Documentation/config/tag.txt
+++ /dev/null
@@ -1,17 +0,0 @@
-tag.forceSignAnnotated::
-	A boolean to specify whether annotated tags created should be GPG signed.
-	If `--annotate` is specified on the command line, it takes
-	precedence over this option.
-
-tag.sort::
-	This variable controls the sort ordering of tags when displayed by
-	linkgit:git-tag[1]. Without the "--sort=<value>" option provided, the
-	value of this variable will be used as the default.
-
-tag.gpgSign::
-	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
-	several times. Note that this option doesn't affect tag signing
-	behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options.
diff --git a/Documentation/config/tar.txt b/Documentation/config/tar.adoc
index de8ff48ea9..de8ff48ea9 100644
--- a/Documentation/config/tar.txt
+++ b/Documentation/config/tar.adoc
diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.adoc
index 3b6bca2b7a..05639ce33f 100644
--- a/Documentation/config/trace2.txt
+++ b/Documentation/config/trace2.adoc
@@ -17,7 +17,7 @@ trace2.eventTarget::
 	It may be overridden by the `GIT_TRACE2_EVENT` environment variable.
 	The following table shows possible values.
 +
-include::../trace2-target-values.txt[]
+include::../trace2-target-values.adoc[]
 
 trace2.normalBrief::
 	Boolean.  When true `time`, `filename`, and `line` fields are
diff --git a/Documentation/config/trailer.adoc b/Documentation/config/trailer.adoc
new file mode 100644
index 0000000000..60bc221c88
--- /dev/null
+++ b/Documentation/config/trailer.adoc
@@ -0,0 +1,136 @@
+trailer.separators::
+	This option tells which characters are recognized as trailer
+	separators. By default only ':' is recognized as a trailer
+	separator, except that '=' is always accepted on the command
+	line for compatibility with other git commands.
++
+The first character given by this option will be the default character
+used when another separator is not specified in the config for this
+trailer.
++
+For example, if the value for this option is "%=$", then only lines
+using the format '<key><sep><value>' with <sep> containing '%', '='
+or '$' and then spaces will be considered trailers. And '%' will be
+the default separator used, so by default trailers will appear like:
+'<key>% <value>' (one percent sign and one space will appear between
+the key and the value).
+
+trailer.where::
+	This option tells where a new trailer will be added.
++
+This can be `end`, which is the default, `start`, `after` or `before`.
++
+If it is `end`, then each new trailer will appear at the end of the
+existing trailers.
++
+If it is `start`, then each new trailer will appear at the start,
+instead of the end, of the existing trailers.
++
+If it is `after`, then each new trailer will appear just after the
+last trailer with the same <key>.
++
+If it is `before`, then each new trailer will appear just before the
+first trailer with the same <key>.
+
+trailer.ifexists::
+	This option makes it possible to choose what action will be
+	performed when there is already at least one trailer with the
+	same <key> in the input.
++
+The valid values for this option are: `addIfDifferentNeighbor` (this
+is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
++
+With `addIfDifferentNeighbor`, a new trailer will be added only if no
+trailer with the same (<key>, <value>) pair is above or below the line
+where the new trailer will be added.
++
+With `addIfDifferent`, a new trailer will be added only if no trailer
+with the same (<key>, <value>) pair is already in the input.
++
+With `add`, a new trailer will be added, even if some trailers with
+the same (<key>, <value>) pair are already in the input.
++
+With `replace`, an existing trailer with the same <key> will be
+deleted and the new trailer will be added. The deleted trailer will be
+the closest one (with the same <key>) to the place where the new one
+will be added.
++
+With `doNothing`, nothing will be done; that is no new trailer will be
+added if there is already one with the same <key> in the input.
+
+trailer.ifmissing::
+	This option makes it possible to choose what action will be
+	performed when there is not yet any trailer with the same
+	<key> in the input.
++
+The valid values for this option are: `add` (this is the default) and
+`doNothing`.
++
+With `add`, a new trailer will be added.
++
+With `doNothing`, nothing will be done.
+
+trailer.<keyAlias>.key::
+	Defines a <keyAlias> for the <key>. The <keyAlias> must be a
+	prefix (case does not matter) of the <key>. For example, in `git
+	config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and
+	the "ack" is the <keyAlias>. This configuration allows the shorter
+	`--trailer "ack:..."` invocation on the command line using the "ack"
+	<keyAlias> instead of the longer `--trailer "Acked-by:..."`.
++
+At the end of the <key>, a separator can appear and then some
+space characters. By default the only valid separator is ':',
+but this can be changed using the `trailer.separators` config
+variable.
++
+If there is a separator in the key, then it overrides the default
+separator when adding the trailer.
+
+trailer.<keyAlias>.where::
+	This option takes the same values as the 'trailer.where'
+	configuration variable and it overrides what is specified by
+	that option for trailers with the specified <keyAlias>.
+
+trailer.<keyAlias>.ifexists::
+	This option takes the same values as the 'trailer.ifexists'
+	configuration variable and it overrides what is specified by
+	that option for trailers with the specified <keyAlias>.
+
+trailer.<keyAlias>.ifmissing::
+	This option takes the same values as the 'trailer.ifmissing'
+	configuration variable and it overrides what is specified by
+	that option for trailers with the specified <keyAlias>.
+
+trailer.<keyAlias>.command::
+	Deprecated in favor of 'trailer.<keyAlias>.cmd'.
+	This option behaves in the same way as 'trailer.<keyAlias>.cmd', except
+	that it doesn't pass anything as argument to the specified command.
+	Instead the first occurrence of substring $ARG is replaced by the
+	<value> that would be passed as argument.
++
+Note that $ARG in the user's command is
+only replaced once and that the original way of replacing $ARG is not safe.
++
+When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given
+for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and
+'trailer.<keyAlias>.command' is ignored.
+
+trailer.<keyAlias>.cmd::
+	This option can be used to specify a shell command that will be called
+	once to automatically add a trailer with the specified <keyAlias>, and then
+	called each time a '--trailer <keyAlias>=<value>' argument is specified to
+	modify the <value> of the trailer that this option would produce.
++
+When the specified command is first called to add a trailer
+with the specified <keyAlias>, the behavior is as if a special
+'--trailer <keyAlias>=<value>' argument was added at the beginning
+of the "git interpret-trailers" command, where <value>
+is taken to be the standard output of the command with any
+leading and trailing whitespace trimmed off.
++
+If some '--trailer <keyAlias>=<value>' arguments are also passed
+on the command line, the command is called again once for each
+of these arguments with the same <keyAlias>. And the <value> part
+of these arguments, if any, will be passed to the command as its
+first argument. This way the command can produce a <value> computed
+from the <value> passed in the '--trailer <keyAlias>=<value>' argument.
diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.adoc
index f1ce50f4a6..f1ce50f4a6 100644
--- a/Documentation/config/transfer.txt
+++ b/Documentation/config/transfer.adoc
diff --git a/Documentation/config/uploadarchive.txt b/Documentation/config/uploadarchive.adoc
index e0698e8c1d..e0698e8c1d 100644
--- a/Documentation/config/uploadarchive.txt
+++ b/Documentation/config/uploadarchive.adoc
diff --git a/Documentation/config/uploadpack.txt b/Documentation/config/uploadpack.adoc
index 0e1dda944a..0e1dda944a 100644
--- a/Documentation/config/uploadpack.txt
+++ b/Documentation/config/uploadpack.adoc
diff --git a/Documentation/config/url.txt b/Documentation/config/url.adoc
index e5566c371d..e5566c371d 100644
--- a/Documentation/config/url.txt
+++ b/Documentation/config/url.adoc
diff --git a/Documentation/config/user.txt b/Documentation/config/user.adoc
index 2ffc38d164..2ffc38d164 100644
--- a/Documentation/config/user.txt
+++ b/Documentation/config/user.adoc
diff --git a/Documentation/config/versionsort.txt b/Documentation/config/versionsort.adoc
index 0cff090819..0cff090819 100644
--- a/Documentation/config/versionsort.txt
+++ b/Documentation/config/versionsort.adoc
diff --git a/Documentation/config/web.txt b/Documentation/config/web.adoc
index beec8d1303..beec8d1303 100644
--- a/Documentation/config/web.txt
+++ b/Documentation/config/web.adoc
diff --git a/Documentation/config/worktree.txt b/Documentation/config/worktree.adoc
index 5e35c7d018..a248076ea5 100644
--- a/Documentation/config/worktree.txt
+++ b/Documentation/config/worktree.adoc
@@ -1,4 +1,4 @@
-worktree.guessRemote::
+`worktree.guessRemote`::
 	If no branch is specified and neither `-b` nor `-B` nor
 	`--detach` is used, then `git worktree add` defaults to
 	creating a new branch from HEAD.  If `worktree.guessRemote` is
@@ -6,14 +6,14 @@ worktree.guessRemote::
 	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.
+	back to creating a new branch from the current `HEAD`.
 
-worktree.useRelativePaths::
-	Link worktrees using relative paths (when "true") or absolute
-	paths (when "false"). This is particularly useful for setups
+`worktree.useRelativePaths`::
+	Link worktrees using relative paths (when "`true`") or absolute
+	paths (when "`false`"). This is particularly useful for setups
 	where the repository and worktrees may be moved between
-	different locations or environments. Defaults to "false".
+	different locations or environments. Defaults to "`false`".
 +
-Note that setting `worktree.useRelativePaths` to "true" implies enabling the
-`extension.relativeWorktrees` config (see linkgit:git-config[1]),
+Note that setting `worktree.useRelativePaths` to "`true`" implies enabling the
+`extensions.relativeWorktrees` config (see linkgit:git-config[1]),
 thus making it incompatible with older versions of Git.
diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.adoc
index e24517c496..e24517c496 100644
--- a/Documentation/date-formats.txt
+++ b/Documentation/date-formats.adoc
diff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc
new file mode 100644
index 0000000000..e161260358
--- /dev/null
+++ b/Documentation/diff-context-options.adoc
@@ -0,0 +1,10 @@
+`-U<n>`::
+`--unified=<n>`::
+	Generate diffs with _<n>_ lines of context. Defaults to `diff.context`
+	or 3 if the config option is unset.
+
+`--inter-hunk-context=<n>`::
+	Show the context between diff hunks, up to the specified _<number>_
+	of lines, thereby fusing hunks that are close to each other.
+	Defaults to `diff.interHunkContext` or 0 if the config option
+	is unset.
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.adoc
index c72fb37986..9f7e988241 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.adoc
@@ -103,6 +103,7 @@ if the file was renamed on any side of history.  With
 followed by the name of the path in the merge commit.
 
 Examples for `-c` and `--cc` without `--combined-all-paths`:
+
 ------------------------------------------------
 ::100644 100644 100644 fabadb8 cc95eb0 4866510 MM	desc.c
 ::100755 100755 100755 52b7a2d 6d1ac04 d2ac7d7 RM	bar.sh
@@ -121,7 +122,7 @@ Note that 'combined diff' lists only files which were modified from
 all parents.
 
 
-include::diff-generate-patch.txt[]
+include::diff-generate-patch.adoc[]
 
 
 other diff formats
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.adoc
index e5c813c96f..7b6cdd1980 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.adoc
@@ -138,7 +138,7 @@ or like this (when the `--cc` option is used):
 +
 [synopsis]
 index <hash>,<hash>..<hash>
-mode <mode>,<mode>`..`<mode>
+mode <mode>,<mode>..<mode>
 new file mode <mode>
 deleted file mode <mode>,<mode>
 +
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.adoc
index 640eb6e7db..ae31520f7f 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.adoc
@@ -37,32 +37,32 @@ endif::git-diff[]
 endif::git-format-patch[]
 
 ifdef::git-log[]
--m::
+`-m`::
 	Show diffs for merge commits in the default format. This is
 	similar to `--diff-merges=on`, except `-m` will
 	produce no output unless `-p` is given as well.
 
--c::
+`-c`::
 	Produce combined diff output for merge commits.
 	Shortcut for `--diff-merges=combined -p`.
 
---cc::
+`--cc`::
 	Produce dense combined diff output for merge commits.
 	Shortcut for `--diff-merges=dense-combined -p`.
 
---dd::
+`--dd`::
 	Produce diff with respect to first parent for both merge and
 	regular commits.
 	Shortcut for `--diff-merges=first-parent -p`.
 
---remerge-diff::
+`--remerge-diff`::
 	Produce remerge-diff output for merge commits.
 	Shortcut for `--diff-merges=remerge -p`.
 
---no-diff-merges::
+`--no-diff-merges`::
 	Synonym for `--diff-merges=off`.
 
---diff-merges=<format>::
+`--diff-merges=<format>`::
 	Specify diff format to be used for merge commits. Default is
 	{diff-merges-default} unless `--first-parent` is in use, in
 	which case `first-parent` is the default.
@@ -70,48 +70,54 @@ ifdef::git-log[]
 The following formats are supported:
 +
 --
-off, none::
+`off`::
+`none`::
 	Disable output of diffs for merge commits. Useful to override
 	implied value.
 
-on, m::
+`on`::
+`m`::
 	Make diff output for merge commits to be shown in the default
 	format. The default format can be changed using
 	`log.diffMerges` configuration variable, whose default value
 	is `separate`.
 
-first-parent, 1::
+`first-parent`::
+`1`::
 	Show full diff with respect to first parent. This is the same
 	format as `--patch` produces for non-merge commits.
 
-separate::
+`separate`::
 	Show full diff with respect to each of parents.
 	Separate log entry and diff is generated for each parent.
 
-combined, c::
+`combined`::
+`c`::
 	Show differences from each of the parents to the merge
 	result simultaneously instead of showing pairwise diff between
 	a parent and the result one at a time. Furthermore, it lists
 	only files which were modified from all parents.
 
-dense-combined, cc::
+`dense-combined`::
+`cc`::
 	Further compress output produced by `--diff-merges=combined`
 	by omitting uninteresting hunks whose contents in the parents
 	have only two variants and the merge result picks one of them
 	without modification.
 
-remerge, r::
-	Remerge two-parent merge commits to create a temporary tree
+`remerge`::
+`r`:: Remerge two-parent merge commits to create a temporary tree
 	object--potentially containing files with conflict markers
 	and such.  A diff is then shown between that temporary tree
 	and the actual merge commit.
+--
 +
 The output emitted when this option is used is subject to change, and
 so is its interaction with other options (unless explicitly
 documented).
---
 
---combined-all-paths::
+
+`--combined-all-paths`::
 	Cause combined diffs (used for merge commits) to
 	list the name of the file from all parents.  It thus only has
 	effect when `--diff-merges=[dense-]combined` is in use, and
@@ -499,7 +505,8 @@ endif::git-format-patch[]
 	Turn off rename detection, even when the configuration
 	file gives the default to do so.
 
-`--[no-]rename-empty`::
+`--rename-empty`::
+`--no-rename-empty`::
 	Whether to use empty blobs as rename source.
 
 ifndef::git-format-patch[]
@@ -887,5 +894,33 @@ endif::git-format-patch[]
 	reverted with `--ita-visible-in-index`. Both options are
 	experimental and could be removed in future.
 
+--max-depth=<depth>::
+	For each pathspec given on command line, descend at most `<depth>`
+	levels of directories. A value of `-1` means no limit.
+	Cannot be combined with wildcards in the pathspec.
+	Given a tree containing `foo/bar/baz`, the following list shows the
+	matches generated by each set of options:
++
+--
+ - `--max-depth=0 -- foo`: `foo`
+
+ - `--max-depth=1 -- foo`: `foo/bar`
+
+ - `--max-depth=1 -- foo/bar`: `foo/bar/baz`
+
+ - `--max-depth=1 -- foo foo/bar`: `foo/bar/baz`
+
+ - `--max-depth=2 -- foo`: `foo/bar/baz`
+--
++
+If no pathspec is given, the depth is measured as if all
+top-level entries were specified. Note that this is different
+than measuring from the root, in that `--max-depth=0` would
+still return `foo`. This allows you to still limit depth while
+asking for a subset of the top-level entries.
++
+Note that this option is only supported for diffs between tree objects,
+not against the index or working tree.
+
 For more detailed explanation on these common options, see also
 linkgit:gitdiffcore[7].
diff --git a/Documentation/everyday.txto b/Documentation/everyday.adoco
index ae555bd47e..ae555bd47e 100644
--- a/Documentation/everyday.txto
+++ b/Documentation/everyday.adoco
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.adoc
index b01372e4b3..ad1e1f49be 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.adoc
@@ -1,7 +1,8 @@
---[no-]all::
+--all::
+--no-all::
 	Fetch all remotes, except for the ones that has the
 	`remote.<name>.skipFetchAll` configuration variable set.
-	This overrides the configuration variable fetch.all`.
+	This overrides the configuration variable `fetch.all`.
 
 -a::
 --append::
@@ -88,7 +89,8 @@ This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes
 precedence over the `fetch.output` config option.
 
 ifndef::git-pull[]
---[no-]write-fetch-head::
+--write-fetch-head::
+--no-write-fetch-head::
 	Write the list of remote refs fetched in the `FETCH_HEAD`
 	file directly under `$GIT_DIR`.  This is the default.
 	Passing `--no-write-fetch-head` from the command line tells
@@ -118,13 +120,16 @@ ifndef::git-pull[]
 	Allow several <repository> and <group> arguments to be
 	specified. No <refspec>s may be specified.
 
---[no-]auto-maintenance::
---[no-]auto-gc::
+--auto-maintenance::
+--no-auto-maintenance::
+--auto-gc::
+--no-auto-gc::
 	Run `git maintenance run --auto` at the end to perform automatic
 	repository maintenance if needed. (`--[no-]auto-gc` is a synonym.)
 	This is enabled by default.
 
---[no-]write-commit-graph::
+--write-commit-graph::
+--no-write-commit-graph::
 	Write a commit-graph after fetching. This overrides the config
 	setting `fetch.writeCommitGraph`.
 endif::git-pull[]
diff --git a/Documentation/fix-texi.perl b/Documentation/fix-texi.perl
deleted file mode 100755
index ff7d78f620..0000000000
--- a/Documentation/fix-texi.perl
+++ /dev/null
@@ -1,15 +0,0 @@
-#!/usr/bin/perl -w
-
-while (<>) {
-	if (/^\@setfilename/) {
-		$_ = "\@setfilename git.info\n";
-	} elsif (/^\@direntry/) {
-		print '@dircategory Development
-@direntry
-* Git: (git).           A fast distributed revision control system
-@end direntry
-';	}
-	unless (/^\@direntry/../^\@end direntry/) {
-		print;
-	}
-}
diff --git a/Documentation/fix-texi.sh b/Documentation/fix-texi.sh
new file mode 100755
index 0000000000..bc300f7b0f
--- /dev/null
+++ b/Documentation/fix-texi.sh
@@ -0,0 +1,21 @@
+#!/bin/sh
+
+awk '
+	/^@setfilename/{
+		print "@setfilename git.info"
+		next
+	}
+	/^@direntry/{
+		direntry=1
+		print "@dircategory Development"
+		print "@direntry"
+		print "* Git: (git).           A fast distributed revision control system"
+		print "@end direntry"
+		next
+	}
+	/^@end direntry/{
+		direntry=0
+		next
+	}
+	!direntry
+'
diff --git a/Documentation/for-each-ref-options.adoc b/Documentation/for-each-ref-options.adoc
new file mode 100644
index 0000000000..f13efb5f25
--- /dev/null
+++ b/Documentation/for-each-ref-options.adoc
@@ -0,0 +1,85 @@
+`<pattern>...`::
+	If one or more _<pattern>_ parameters are given, only refs are shown that
+	match against at least one pattern, either using `fnmatch`(3) or
+	literally, in the latter case matching completely or from the
+	beginning up to a slash.
+
+`--stdin`::
+	The list of patterns is read from standard input instead of from
+	the argument list.
+
+`--count=<count>`::
+	Stop after showing _<count>_ refs.
+
+`--sort=<key>`::
+	Sort on the field name _<key>_.  Prefix `-` to sort in
+	descending order of the value.  When unspecified,
+	`refname` is used.  You may use the `--sort=<key>` option
+	multiple times, in which case the last key becomes the primary
+	key.
+
+`--format[=<format>]`::
+	A string that interpolates `%(fieldname)` from a ref being shown and
+	the object it points at. In addition, the string literal `%%`
+	renders as `%` and `%xx` - where `xx` are hex digits - renders as
+	the character with hex code `xx`. For example, `%00` interpolates to
+	`\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_).
+
+When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype)
+TAB %(refname)`.
+
+`--color[=<when>]`::
+	Respect any colors specified in the `--format` option. The
+	_<when__ field must be one of `always`, `never`, or `auto` (if
+	`<when>` is absent, behave as if `always` was given).
+
+`--shell`::
+`--perl`::
+`--python`::
+`--tcl`::
+	If given, strings that substitute `%(fieldname)`
+	placeholders are quoted as string literals suitable for
+	the specified host language.  This is meant to produce
+	a scriptlet that can directly be "eval"ed.
+
+`--points-at=<object>`::
+	Only list refs which points at the given object.
+
+`--merged[=<object>]`::
+	Only list refs whose tips are reachable from the
+	specified commit (`HEAD` if not specified).
+
+`--no-merged[=<object>]`::
+	Only list refs whose tips are not reachable from _<object>_(`HEAD` if not
+	specified).
+
+`--contains[=<object>]`::
+	Only list refs which contain _<object>_(`HEAD` if not specified).
+
+`--no-contains[=<object>]`::
+	Only list refs which don't contain _<object>_ (`HEAD`
+	if not specified).
+
+`--ignore-case`::
+	Sorting and filtering refs are case insensitive.
+
+`--omit-empty`::
+	Do not print a newline after formatted refs where the format expands
+	to the empty string.
+
+`--exclude=<excluded-pattern>`::
+	If one or more `--exclude` options are given, only refs which do not
+	match any _<excluded-pattern>_ parameters are shown. Matching is done
+	using the same rules as _<pattern>_ above.
+
+`--include-root-refs`::
+	List root refs (`HEAD` and pseudorefs) apart from regular refs.
+
+`--start-after=<marker>`::
+    Allows paginating the output by skipping references up to and including the
+    specified marker. When paging, it should be noted that references may be
+    deleted, modified or added between invocations. Output will only yield those
+    references which follow the marker lexicographically. Output begins from the
+    first reference that would come after the marker alphabetically. Cannot be
+    used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s)
+    to limit the refs.
diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.adoc
index b14bc44ca4..acac9683af 100644
--- a/Documentation/fsck-msgids.txt
+++ b/Documentation/fsck-msgids.adoc
@@ -10,12 +10,25 @@
 `badFilemode`::
 	(INFO) A tree contains a bad filemode entry.
 
+`badGpgsig`::
+	(ERROR) A tag contains a bad (truncated) signature (e.g., `gpgsig`) header.
+
+`badHeaderContinuation`::
+	(ERROR) A continuation header (such as for `gpgsig`) is unexpectedly truncated.
+
 `badName`::
 	(ERROR) An author/committer name is empty.
 
 `badObjectSha1`::
 	(ERROR) An object has a bad sha1.
 
+`badPackedRefEntry`::
+	(ERROR) The "packed-refs" file contains an invalid entry.
+
+`badPackedRefHeader`::
+	(ERROR) The "packed-refs" file contains an invalid
+	header.
+
 `badParentSha1`::
 	(ERROR) A commit object has a bad parent sha1.
 
@@ -31,6 +44,9 @@
 `badReferentName`::
 	(ERROR) The referent name of a symref is invalid.
 
+`badReftableTableName`::
+	(WARN) A reftable table has an invalid name.
+
 `badTagName`::
 	(INFO) A tag has an invalid format.
 
@@ -52,6 +68,12 @@
 `emptyName`::
 	(WARN) A path contains an empty name.
 
+`emptyPackedRefsFile`::
+	(INFO) "packed-refs" file is empty. Report to the
+	git@vger.kernel.org mailing list if you see this error. As only
+	very early versions of Git would create such an empty
+	"packed_refs" file, we might tighten this rule in the future.
+
 `extraHeaderEntry`::
 	(IGNORE) Extra headers found after `tagger`.
 
@@ -91,9 +113,6 @@
 `gitmodulesParse`::
 	(INFO) Could not parse `.gitmodules` blob.
 
-`gitmodulesLarge`;
-	(ERROR) `.gitmodules` blob is too large to parse.
-
 `gitmodulesPath`::
 	(ERROR) `.gitmodules` path is invalid.
 
@@ -176,6 +195,13 @@
 `nullSha1`::
 	(WARN) Tree contains entries pointing to a null sha1.
 
+`packedRefEntryNotTerminated`::
+	(ERROR) The "packed-refs" file contains an entry that is
+	not terminated by a newline.
+
+`packedRefUnsorted`::
+	(ERROR) The "packed-refs" file is not sorted.
+
 `refMissingNewline`::
 	(INFO) A loose ref that does not end with newline(LF). As
 	valid implementations of Git never created such a loose ref
diff --git a/Documentation/git-add.txt b/Documentation/git-add.adoc
index 5f2c3592b8..6192daeb03 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.adoc
@@ -16,18 +16,18 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
 
 DESCRIPTION
 -----------
-This command updates the index using the current content found in
-the working tree, to prepare the content staged for the next commit.
-It typically adds the current content of existing paths as a whole,
-but with some options it can also be used to add content with
-only part of the changes made to the working tree files applied, or
-remove paths that do not exist in the working tree anymore.
-
-The "index" holds a snapshot of the content of the working tree, and it
-is this snapshot that is taken as the contents of the next commit.  Thus
-after making any changes to the working tree, and before running
-the commit command, you must use the `add` command to add any new or
-modified files to the index.
+Add contents of new or changed files to the index. The "index" (also
+known as the "staging area") is what you use to prepare the contents of
+the next commit.
+
+When you run `git commit` without any other arguments, it will only
+commit staged changes. For example, if you've edited `file.c` and want
+to commit your changes to that file, you can run:
+
+   git add file.c
+   git commit
+
+You can also add only part of your changes to a file with `git add -p`.
 
 This command can be performed multiple times before a commit.  It only
 adds the content of the specified file(s) at the time the add command is
@@ -37,12 +37,10 @@ you must run `git add` again to add the new content to the index.
 The `git status` command can be used to obtain a summary of which
 files have changes that are staged for the next commit.
 
-The `git add` command will not add ignored files by default.  If any
-ignored files were explicitly specified on the command line, `git add`
-will fail with a list of ignored files.  Ignored files reached by
-directory recursion or filename globbing performed by Git (quote your
-globs before the shell) will be silently ignored.  The `git add` command can
-be used to add ignored files with the `-f` (force) option.
+The `git add` command will not add ignored files by default. You can
+use the `--force` option to add ignored files. If you specify the exact
+filename of an ignored file, `git add` will fail with a list of ignored
+files. Otherwise it will silently ignore the file.
 
 Please see linkgit:git-commit[1] for alternative ways to add content to a
 commit.
@@ -104,6 +102,8 @@ This effectively runs `add --interactive`, but bypasses the
 initial command menu and directly jumps to the `patch` subcommand.
 See ``Interactive mode'' for details.
 
+include::diff-context-options.adoc[]
+
 `-e`::
 `--edit`::
 	Open the diff vs. the index in an editor and let the user
@@ -342,13 +342,14 @@ patch::
        d - do not stage this hunk or any of the later hunks in the file
        g - select a hunk to go to
        / - search for a hunk matching the given regex
-       j - leave this hunk undecided, see next undecided hunk
-       J - leave this hunk undecided, see next hunk
-       k - leave this hunk undecided, see previous undecided hunk
-       K - leave this hunk undecided, see previous hunk
+       j - go to the next undecided hunk, roll over at the bottom
+       J - go to the next hunk, roll over at the bottom
+       k - go to the previous undecided hunk, roll over at the top
+       K - go to the previous hunk, roll over at the top
        s - split the current hunk into smaller hunks
        e - manually edit the current hunk
        p - print the current hunk
+       P - print the current hunk using the pager
        ? - print help
 +
 After deciding the fate for all hunks, if there is any hunk
@@ -437,10 +438,10 @@ they will make the patch impossible to apply:
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
 :git-add: 1
-include::config/add.txt[]
+include::config/add.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-am.txt b/Documentation/git-am.adoc
index 69d5cc9f21..b23b4fba20 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.adoc
@@ -48,7 +48,8 @@ OPTIONS
 --keep-non-patch::
 	Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
 
---[no-]keep-cr::
+--keep-cr::
+--no-keep-cr::
 	With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1])
 	with the same option, to prevent it from stripping CR at the end of
 	lines. `am.keepcr` configuration variable can be used to specify the
@@ -120,7 +121,7 @@ default.   You can use `--no-utf8` to override this.
 	am.threeWay configuration variable. For more information,
 	see am.threeWay in linkgit:git-config[1].
 
-include::rerere-options.txt[]
+include::rerere-options.adoc[]
 
 --ignore-space-change::
 --ignore-whitespace::
@@ -284,9 +285,9 @@ information.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/am.txt[]
+include::config/am.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.adoc
index 5ae8aabe0f..965bc676af 100644
--- a/Documentation/git-annotate.txt
+++ b/Documentation/git-annotate.adoc
@@ -22,7 +22,7 @@ familiar command name for people coming from other SCM systems.
 
 OPTIONS
 -------
-include::blame-options.txt[]
+include::blame-options.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.adoc
index dd4a61ef28..6c71ee69da 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.adoc
@@ -75,13 +75,14 @@ OPTIONS
 	tree. If `--check` is in effect, merely check that it would
 	apply cleanly to the index entry.
 
+-N::
 --intent-to-add::
 	When applying the patch only to the working tree, mark new
 	files to be added to the index later (see `--intent-to-add`
-	option in linkgit:git-add[1]). This option is ignored unless
-	running in a Git repository and `--index` is not specified.
-	Note that `--index` could be implied by other options such
-	as `--cached` or `--3way`.
+	option in linkgit:git-add[1]). This option is ignored if
+	`--index` or `--cached` are used, and has no effect outside a Git
+	repository. Note that `--index` could be implied by other options
+	such as `--3way`.
 
 -3::
 --3way::
@@ -270,9 +271,9 @@ has no effect when `--index` or `--cached` is in use.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/apply.txt[]
+include::config/apply.adoc[]
 
 SUBMODULES
 ----------
diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.adoc
index 847777fd17..847777fd17 100644
--- a/Documentation/git-archimport.txt
+++ b/Documentation/git-archimport.adoc
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.adoc
index a0e3fe7996..a0e3fe7996 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.adoc
diff --git a/Documentation/git-backfill.adoc b/Documentation/git-backfill.adoc
new file mode 100644
index 0000000000..b8394dcf22
--- /dev/null
+++ b/Documentation/git-backfill.adoc
@@ -0,0 +1,72 @@
+git-backfill(1)
+===============
+
+NAME
+----
+git-backfill - Download missing objects in a partial clone
+
+
+SYNOPSIS
+--------
+[synopsis]
+git backfill [--min-batch-size=<n>] [--[no-]sparse]
+
+DESCRIPTION
+-----------
+
+Blobless partial clones are created using `git clone --filter=blob:none`
+and then configure the local repository such that the Git client avoids
+downloading blob objects unless they are required for a local operation.
+This initially means that the clone and later fetches download reachable
+commits and trees but no blobs. Later operations that change the `HEAD`
+pointer, such as `git checkout` or `git merge`, may need to download
+missing blobs in order to complete their operation.
+
+In the worst cases, commands that compute blob diffs, such as `git blame`,
+become very slow as they download the missing blobs in single-blob
+requests to satisfy the missing object as the Git command needs it. This
+leads to multiple download requests and no ability for the Git server to
+provide delta compression across those objects.
+
+The `git backfill` command provides a way for the user to request that
+Git downloads the missing blobs (with optional filters) such that the
+missing blobs representing historical versions of files can be downloaded
+in batches. The `backfill` command attempts to optimize the request by
+grouping blobs that appear at the same path, hopefully leading to good
+delta compression in the packfile sent by the server.
+
+In this way, `git backfill` provides a mechanism to break a large clone
+into smaller chunks. Starting with a blobless partial clone with `git
+clone --filter=blob:none` and then running `git backfill` in the local
+repository provides a way to download all reachable objects in several
+smaller network calls than downloading the entire repository at clone
+time.
+
+By default, `git backfill` downloads all blobs reachable from the `HEAD`
+commit. This set can be restricted or expanded using various options.
+
+THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE.
+
+
+OPTIONS
+-------
+
+`--min-batch-size=<n>`::
+	Specify a minimum size for a batch of missing objects to request
+	from the server. This size may be exceeded by the last set of
+	blobs seen at a given path. The default minimum batch size is
+	50,000.
+
+`--sparse`::
+`--no-sparse`::
+	Only download objects if they appear at a path that matches the
+	current sparse-checkout. If the sparse-checkout feature is enabled,
+	then `--sparse` is assumed and can be disabled with `--no-sparse`.
+
+SEE ALSO
+--------
+linkgit:git-clone[1].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.adoc
index 0bc165788e..0bc165788e 100644
--- a/Documentation/git-bisect-lk2009.txt
+++ b/Documentation/git-bisect-lk2009.adoc
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.adoc
index 82f944dc03..58dbb74a15 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.adoc
@@ -495,6 +495,7 @@ $ git bisect old HEAD~10 # the tenth commit from now is marked as old
 ------------
 +
 or:
++
 ------------
 $ git bisect start --term-old broken --term-new fixed
 $ git bisect fixed
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.adoc
index b1d7fb539d..e438d28625 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.adoc
@@ -48,7 +48,7 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
 
 OPTIONS
 -------
-include::blame-options.txt[]
+include::blame-options.adoc[]
 
 -c::
 	Use the same output mode as linkgit:git-annotate[1] (Default: off).
@@ -135,10 +135,11 @@ header elements later.
 The porcelain format generally suppresses commit information that has
 already been seen. For example, two lines that are blamed to the same
 commit will both be shown, but the details for that commit will be shown
-only once. This is more efficient, but may require more state be kept by
-the reader. The `--line-porcelain` option can be used to output full
-commit information for each line, allowing simpler (but less efficient)
-usage like:
+only once. Information which is specific to individual lines will not be
+grouped together, like revs to be marked 'ignored' or 'unblamable'. This
+is more efficient, but may require more state be kept by the reader. The
+`--line-porcelain` option can be used to output full commit information
+for each line, allowing simpler (but less efficient) usage like:
 
 	# count the number of lines attributed to each author
 	git blame --line-porcelain file |
@@ -244,9 +245,9 @@ See linkgit:gitmailmap[5].
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/blame.txt[]
+include::config/blame.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.adoc
index 0b08442932..c0afddc424 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.adoc
@@ -7,23 +7,23 @@ git-branch - List, create, or delete branches
 
 SYNOPSIS
 --------
-[verse]
-'git branch' [--color[=<when>] | --no-color] [--show-current]
-	[-v [--abbrev=<n> | --no-abbrev]]
-	[--column[=<options>] | --no-column] [--sort=<key>]
-	[--merged [<commit>]] [--no-merged [<commit>]]
-	[--contains [<commit>]] [--no-contains [<commit>]]
-	[--points-at <object>] [--format=<format>]
-	[(-r | --remotes) | (-a | --all)]
-	[--list] [<pattern>...]
-'git branch' [--track[=(direct|inherit)] | --no-track] [-f]
-	[--recurse-submodules] <branchname> [<start-point>]
-'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
-'git branch' --unset-upstream [<branchname>]
-'git branch' (-m | -M) [<oldbranch>] <newbranch>
-'git branch' (-c | -C) [<oldbranch>] <newbranch>
-'git branch' (-d | -D) [-r] <branchname>...
-'git branch' --edit-description [<branchname>]
+[synopsis]
+git branch [--color[=<when>] | --no-color] [--show-current]
+	   [-v [--abbrev=<n> | --no-abbrev]]
+	   [--column[=<options>] | --no-column] [--sort=<key>]
+	   [--merged [<commit>]] [--no-merged [<commit>]]
+	   [--contains [<commit>]] [--no-contains [<commit>]]
+	   [--points-at <object>] [--format=<format>]
+	   [(-r|--remotes) | (-a|--all)]
+	   [--list] [<pattern>...]
+git branch [--track[=(direct|inherit)] | --no-track] [-f]
+	   [--recurse-submodules] <branch-name> [<start-point>]
+git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>]
+git branch --unset-upstream [<branch-name>]
+git branch (-m|-M) [<old-branch>] <new-branch>
+git branch (-c|-C) [<old-branch>] <new-branch>
+git branch (-d|-D) [-r] <branch-name>...
+git branch --edit-description [<branch-name>]
 
 DESCRIPTION
 -----------
@@ -49,173 +49,184 @@ With `--contains`, shows only the branches that contain the named commit
 named commit), `--no-contains` inverts it. With `--merged`, only branches
 merged into the named commit (i.e. the branches whose tip commits are
 reachable from the named commit) will be listed.  With `--no-merged` only
-branches not merged into the named commit will be listed.  If the <commit>
+branches not merged into the named commit will be listed.  If the _<commit>_
 argument is missing it defaults to `HEAD` (i.e. the tip of the current
 branch).
 
-The command's second form creates a new branch head named <branchname>
-which points to the current `HEAD`, or <start-point> if given. As a
-special case, for <start-point>, you may use `"A...B"` as a shortcut for
-the merge base of `A` and `B` if there is exactly one merge base. You
-can leave out at most one of `A` and `B`, in which case it defaults to
-`HEAD`.
+The command's second form creates a new branch head named _<branch-name>_
+which points to the current `HEAD`, or _<start-point>_ if given. As a
+special case, for _<start-point>_, you may use `<rev-A>...<rev-B>` as a
+shortcut for the merge base of _<rev-A>_ and _<rev-B>_ if there is exactly
+one merge base. You can leave out at most one of _<rev-A>_ and _<rev-B>_,
+in which case it defaults to `HEAD`.
 
 Note that this will create the new branch, but it will not switch the
-working tree to it; use "git switch <newbranch>" to switch to the
+working tree to it; use `git switch <new-branch>` to switch to the
 new branch.
 
 When a local branch is started off a remote-tracking branch, Git sets up the
 branch (specifically the `branch.<name>.remote` and `branch.<name>.merge`
-configuration entries) so that 'git pull' will appropriately merge from
+configuration entries) so that `git pull` will appropriately merge from
 the remote-tracking branch. This behavior may be changed via the global
 `branch.autoSetupMerge` configuration flag. That setting can be
 overridden by using the `--track` and `--no-track` options, and
 changed later using `git branch --set-upstream-to`.
 
-With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>.
-If <oldbranch> had a corresponding reflog, it is renamed to match
-<newbranch>, and a reflog entry is created to remember the branch
-renaming. If <newbranch> exists, -M must be used to force the rename
+With a `-m` or `-M` option, _<old-branch>_ will be renamed to _<new-branch>_.
+If _<old-branch>_ had a corresponding reflog, it is renamed to match
+_<new-branch>_, and a reflog entry is created to remember the branch
+renaming. If _<new-branch>_ exists, `-M` must be used to force the rename
 to happen.
 
 The `-c` and `-C` options have the exact same semantics as `-m` and
 `-M`, except instead of the branch being renamed, it will be copied to a
 new name, along with its config and reflog.
 
-With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
+With a `-d` or `-D` option, _<branch-name>_ will be deleted.  You may
 specify more than one branch for deletion.  If the branch currently
 has a reflog then the reflog will also be deleted.
 
 Use `-r` together with `-d` to delete remote-tracking branches. Note, that it
 only makes sense to delete remote-tracking branches if they no longer exist
-in the remote repository or if 'git fetch' was configured not to fetch
-them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a
+in the remote repository or if `git fetch` was configured not to fetch
+them again. See also the `prune` subcommand of linkgit:git-remote[1] for a
 way to clean up all obsolete remote-tracking branches.
 
 
 OPTIONS
 -------
--d::
---delete::
+`-d`::
+`--delete`::
 	Delete a branch. The branch must be fully merged in its
 	upstream branch, or in `HEAD` if no upstream was set with
 	`--track` or `--set-upstream-to`.
 
--D::
+`-D`::
 	Shortcut for `--delete --force`.
 
---create-reflog::
+`--create-reflog`::
 	Create the branch's reflog.  This activates recording of
 	all changes made to the branch ref, enabling use of date
-	based sha1 expressions such as "<branchname>@\{yesterday}".
+	based sha1 expressions such as `<branch-name>@{yesterday}`.
 	Note that in non-bare repositories, reflogs are usually
 	enabled by default by the `core.logAllRefUpdates` config option.
 	The negated form `--no-create-reflog` only overrides an earlier
 	`--create-reflog`, but currently does not negate the setting of
 	`core.logAllRefUpdates`.
 
--f::
---force::
-	Reset <branchname> to <start-point>, even if <branchname> exists
-	already. Without `-f`, 'git branch' refuses to change an existing branch.
+`-f`::
+`--force`::
+	Reset _<branch-name>_ to _<start-point>_, even if _<branch-name>_ exists
+	already. Without `-f`, `git branch` refuses to change an existing branch.
 	In combination with `-d` (or `--delete`), allow deleting the
 	branch irrespective of its merged status, or whether it even
 	points to a valid commit. In combination with
 	`-m` (or `--move`), allow renaming the branch even if the new
 	branch name already exists, the same applies for `-c` (or `--copy`).
 +
-Note that 'git branch -f <branchname> [<start-point>]', even with '-f',
-refuses to change an existing branch `<branchname>` that is checked out
+Note that `git branch -f <branch-name> [<start-point>]`, even with `-f`,
+refuses to change an existing branch _<branch-name>_ that is checked out
 in another worktree linked to the same repository.
 
--m::
---move::
+`-m`::
+`--move`::
 	Move/rename a branch, together with its config and reflog.
 
--M::
+`-M`::
 	Shortcut for `--move --force`.
 
--c::
---copy::
+`-c`::
+`--copy`::
 	Copy a branch, together with its config and reflog.
 
--C::
+`-C`::
 	Shortcut for `--copy --force`.
 
---color[=<when>]::
+`--color[=<when>]`::
 	Color branches to highlight current, local, and
 	remote-tracking branches.
-	The value must be always (the default), never, or auto.
+	The value must be `always` (the default), `never`, or `auto`.
 
---no-color::
+`--no-color`::
 	Turn off branch colors, even when the configuration file gives the
 	default to color output.
 	Same as `--color=never`.
 
--i::
---ignore-case::
+`-i`::
+`--ignore-case`::
 	Sorting and filtering branches are case insensitive.
 
---omit-empty::
+`--omit-empty`::
 	Do not print a newline after formatted refs where the format expands
 	to the empty string.
 
---column[=<options>]::
---no-column::
+`--column[=<options>]`::
+`--no-column`::
 	Display branch listing in columns. See configuration variable
 	`column.branch` for option syntax. `--column` and `--no-column`
-	without options are equivalent to 'always' and 'never' respectively.
+	without options are equivalent to `always` and `never` respectively.
 +
 This option is only applicable in non-verbose mode.
 
--r::
---remotes::
-	List or delete (if used with -d) the remote-tracking branches.
+`--sort=<key>`::
+	Sort based on _<key>_. Prefix `-` to sort in descending
+	order of the value. You may use the `--sort=<key>` option
+	multiple times, in which case the last key becomes the primary
+	key. The keys supported are the same as those in linkgit:git-for-each-ref[1].
+	Sort order defaults to the value configured for the
+	`branch.sort` variable if it exists, or to sorting based on the
+	full refname (including `refs/...` prefix). This lists
+	detached `HEAD` (if present) first, then local branches and
+	finally remote-tracking branches. See linkgit:git-config[1].
+
+`-r`::
+`--remotes`::
+	List or delete (if used with `-d`) the remote-tracking branches.
 	Combine with `--list` to match the optional pattern(s).
 
--a::
---all::
+`-a`::
+`--all`::
 	List both remote-tracking branches and local branches.
 	Combine with `--list` to match optional pattern(s).
 
--l::
---list::
+`-l`::
+`--list`::
 	List branches.  With optional `<pattern>...`, e.g. `git
 	branch --list 'maint-*'`, list only the branches that match
 	the pattern(s).
 
---show-current::
-	Print the name of the current branch. In detached HEAD state,
+`--show-current`::
+	Print the name of the current branch. In detached `HEAD` state,
 	nothing is printed.
 
--v::
--vv::
---verbose::
+`-v`::
+`-vv`::
+`--verbose`::
 	When in list mode,
 	show sha1 and commit subject line for each head, along with
 	relationship to upstream branch (if any). If given twice, print
 	the path of the linked worktree (if any) and the name of the upstream
 	branch, as well (see also `git remote show <remote>`).  Note that the
-	current worktree's HEAD will not have its path printed (it will always
+	current worktree's `HEAD` will not have its path printed (it will always
 	be your current directory).
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Be more quiet when creating or deleting a branch, suppressing
 	non-error messages.
 
---abbrev=<n>::
+`--abbrev=<n>`::
 	In the verbose listing that show the commit object name,
-	show the shortest prefix that is at least '<n>' hexdigits
+	show the shortest prefix that is at least _<n>_ hexdigits
 	long that uniquely refers the object.
 	The default value is 7 and can be overridden by the `core.abbrev`
 	config option.
 
---no-abbrev::
+`--no-abbrev`::
 	Display the full sha1s in the output listing rather than abbreviating them.
 
--t::
---track[=(direct|inherit)]::
+`-t`::
+`--track[=(direct|inherit)]`::
 	When creating a new branch, set up `branch.<name>.remote` and
 	`branch.<name>.merge` configuration entries to set "upstream" tracking
 	configuration for the new branch. This
@@ -229,7 +240,7 @@ The exact upstream branch is chosen depending on the optional argument:
 itself as the upstream; `--track=inherit` means to copy the upstream
 configuration of the start-point branch.
 +
-The branch.autoSetupMerge configuration variable specifies how `git switch`,
+The `branch.autoSetupMerge` configuration variable specifies how `git switch`,
 `git checkout` and `git branch` should behave when neither `--track` nor
 `--no-track` are specified:
 +
@@ -238,106 +249,94 @@ were given whenever the start-point is a remote-tracking branch.
 `false` behaves as if `--no-track` were given. `always` behaves as though
 `--track=direct` were given. `inherit` behaves as though `--track=inherit`
 were given. `simple` behaves as though `--track=direct` were given only when
-the start-point is a remote-tracking branch and the new branch has the same
+the _<start-point>_ is a remote-tracking branch and the new branch has the same
 name as the remote branch.
 +
 See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on
 how the `branch.<name>.remote` and `branch.<name>.merge` options are used.
 
---no-track::
+`--no-track`::
 	Do not set up "upstream" configuration, even if the
-	branch.autoSetupMerge configuration variable is set.
+	`branch.autoSetupMerge` configuration variable is set.
 
---recurse-submodules::
-	THIS OPTION IS EXPERIMENTAL! Causes the current command to
+`--recurse-submodules`::
+	THIS OPTION IS EXPERIMENTAL! Cause the current command to
 	recurse into submodules if `submodule.propagateBranches` is
 	enabled. See `submodule.propagateBranches` in
 	linkgit:git-config[1]. Currently, only branch creation is
 	supported.
 +
-When used in branch creation, a new branch <branchname> will be created
+When used in branch creation, a new branch _<branch-name>_ will be created
 in the superproject and all of the submodules in the superproject's
-<start-point>. In submodules, the branch will point to the submodule
-commit in the superproject's <start-point> but the branch's tracking
+_<start-point>_. In submodules, the branch will point to the submodule
+commit in the superproject's _<start-point>_ but the branch's tracking
 information will be set up based on the submodule's branches and remotes
 e.g. `git branch --recurse-submodules topic origin/main` will create the
 submodule branch "topic" that points to the submodule commit in the
 superproject's "origin/main", but tracks the submodule's "origin/main".
 
---set-upstream::
+`--set-upstream`::
 	As this option had confusing syntax, it is no longer supported.
 	Please use `--track` or `--set-upstream-to` instead.
 
--u <upstream>::
---set-upstream-to=<upstream>::
-	Set up <branchname>'s tracking information so <upstream> is
-	considered <branchname>'s upstream branch. If no <branchname>
+`-u <upstream>`::
+`--set-upstream-to=<upstream>`::
+	Set up _<branch-name>_'s tracking information so _<upstream>_ is
+	considered _<branch-name>_'s upstream branch. If no _<branch-name>_
 	is specified, then it defaults to the current branch.
 
---unset-upstream::
-	Remove the upstream information for <branchname>. If no branch
+`--unset-upstream`::
+	Remove the upstream information for _<branch-name>_. If no branch
 	is specified it defaults to the current branch.
 
---edit-description::
+`--edit-description`::
 	Open an editor and edit the text to explain what the branch is
 	for, to be used by various other commands (e.g. `format-patch`,
 	`request-pull`, and `merge` (if enabled)). Multi-line explanations
 	may be used.
 
---contains [<commit>]::
-	Only list branches which contain the specified commit (HEAD
+`--contains [<commit>]`::
+	Only list branches which contain _<commit>_ (`HEAD`
 	if not specified). Implies `--list`.
 
---no-contains [<commit>]::
-	Only list branches which don't contain the specified commit
-	(HEAD if not specified). Implies `--list`.
+`--no-contains [<commit>]`::
+	Only list branches which don't contain _<commit>_
+	(`HEAD` if not specified). Implies `--list`.
 
---merged [<commit>]::
-	Only list branches whose tips are reachable from the
-	specified commit (HEAD if not specified). Implies `--list`.
+`--merged [<commit>]`::
+	Only list branches whose tips are reachable from
+	_<commit>_ (`HEAD` if not specified). Implies `--list`.
 
---no-merged [<commit>]::
-	Only list branches whose tips are not reachable from the
-	specified commit (HEAD if not specified). Implies `--list`.
+`--no-merged [<commit>]`::
+	Only list branches whose tips are not reachable from
+	_<commit>_ (`HEAD` if not specified). Implies `--list`.
 
-<branchname>::
+`--points-at <object>`::
+	Only list branches of _<object>_.
+
+`--format <format>`::
+	A string that interpolates `%(fieldname)` from a branch ref being shown
+	and the object it points at.  _<format>_ is the same as
+	that of linkgit:git-for-each-ref[1].
+
+_<branch-name>_::
 	The name of the branch to create or delete.
 	The new branch name must pass all checks defined by
 	linkgit:git-check-ref-format[1].  Some of these checks
 	may restrict the characters allowed in a branch name.
 
-<start-point>::
+_<start-point>_::
 	The new branch head will point to this commit.  It may be
 	given as a branch name, a commit-id, or a tag.  If this
-	option is omitted, the current HEAD will be used instead.
+	option is omitted, the current `HEAD` will be used instead.
 
-<oldbranch>::
+_<old-branch>_::
 	The name of an existing branch.  If this option is omitted,
 	the name of the current branch will be used instead.
 
-<newbranch>::
+_<new-branch>_::
 	The new name for an existing branch. The same restrictions as for
-	<branchname> apply.
-
---sort=<key>::
-	Sort based on the key given. Prefix `-` to sort in descending
-	order of the value. You may use the --sort=<key> option
-	multiple times, in which case the last key becomes the primary
-	key. The keys supported are the same as those in `git
-	for-each-ref`. Sort order defaults to the value configured for the
-	`branch.sort` variable if it exists, or to sorting based on the
-	full refname (including `refs/...` prefix). This lists
-	detached HEAD (if present) first, then local branches and
-	finally remote-tracking branches. See linkgit:git-config[1].
-
-
---points-at <object>::
-	Only list branches of the given object.
-
---format <format>::
-	A string that interpolates `%(fieldname)` from a branch ref being shown
-	and the object it points at.  The format is the same as
-	that of linkgit:git-for-each-ref[1].
+	_<branch-name>_ apply.
 
 CONFIGURATION
 -------------
@@ -345,9 +344,9 @@ CONFIGURATION
 `--list` is used or implied. The default is to use a pager.
 See linkgit:git-config[1].
 
-include::includes/cmd-config-section-rest.txt[]
+include::includes/cmd-config-section-rest.adoc[]
 
-include::config/branch.txt[]
+include::config/branch.adoc[]
 
 EXAMPLES
 --------
@@ -374,7 +373,7 @@ $ git branch -D test                                    <2>
 ------------
 +
 <1> Delete the remote-tracking branches "todo", "html" and "man". The next
-    'fetch' or 'pull' will create them again unless you configure them not to.
+    `git fetch` or `git pull` will create them again unless you configure them not to.
     See linkgit:git-fetch[1].
 <2> Delete the "test" branch even if the "master" branch (or whichever branch
     is currently checked out) does not have all commits from the test branch.
@@ -386,8 +385,8 @@ $ git branch -r -l '<remote>/<pattern>'                 <1>
 $ git for-each-ref 'refs/remotes/<remote>/<pattern>'    <2>
 ------------
 +
-<1> Using `-a` would conflate <remote> with any local branches you happen to
-    have been prefixed with the same <remote> pattern.
+<1> Using `-a` would conflate _<remote>_ with any local branches you happen to
+    have been prefixed with the same _<remote>_ pattern.
 <2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1]
 
 Patterns will normally need quoting.
@@ -396,34 +395,34 @@ NOTES
 -----
 
 If you are creating a branch that you want to switch to immediately,
-it is easier to use the "git switch" command with its `-c` option to
+it is easier to use the `git switch` command with its `-c` option to
 do the same thing with a single command.
 
 The options `--contains`, `--no-contains`, `--merged` and `--no-merged`
 serve four related but different purposes:
 
 - `--contains <commit>` is used to find all branches which will need
-  special attention if <commit> were to be rebased or amended, since those
-  branches contain the specified <commit>.
+  special attention if _<commit>_ were to be rebased or amended, since those
+  branches contain the specified _<commit>_.
 
 - `--no-contains <commit>` is the inverse of that, i.e. branches that don't
-  contain the specified <commit>.
+  contain the specified _<commit>_.
 
 - `--merged` is used to find all branches which can be safely deleted,
-  since those branches are fully contained by HEAD.
+  since those branches are fully contained by `HEAD`.
 
 - `--no-merged` is used to find branches which are candidates for merging
-  into HEAD, since those branches are not fully contained by HEAD.
+  into `HEAD`, since those branches are not fully contained by `HEAD`.
 
-include::ref-reachability-filters.txt[]
+include::ref-reachability-filters.adoc[]
 
 SEE ALSO
 --------
 linkgit:git-check-ref-format[1],
 linkgit:git-fetch[1],
 linkgit:git-remote[1],
-link:user-manual.html#what-is-a-branch[``Understanding history: What is
-a branch?''] in the Git User's Manual.
+link:user-manual.html#what-is-a-branch["Understanding history: What is
+a branch?"] in the Git User's Manual.
 
 GIT
 ---
diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.adoc
index 112658b3c3..112658b3c3 100644
--- a/Documentation/git-bugreport.txt
+++ b/Documentation/git-bugreport.adoc
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.adoc
index 03cd36fe8d..03cd36fe8d 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.adoc
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.adoc
index d5890ae368..c139f55a16 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.adoc
@@ -9,8 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git cat-file' <type> <object>
-'git cat-file' (-e | -p) <object>
-'git cat-file' (-t | -s) [--allow-unknown-type] <object>
+'git cat-file' (-e | -p | -t | -s) <object>
 'git cat-file' (--textconv | --filters)
 	     [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
 'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]
@@ -63,8 +62,10 @@ OPTIONS
 	or to ask for a "blob" with `<object>` being a tag object that
 	points at it.
 
---[no-]mailmap::
---[no-]use-mailmap::
+--mailmap::
+--no-mailmap::
+--use-mailmap::
+--no-use-mailmap::
        Use mailmap file to map author, committer and tagger names
        and email addresses to canonical real names and email addresses.
        See linkgit:git-shortlog[1].
@@ -81,6 +82,25 @@ OPTIONS
 	end-of-line conversion, etc). In this case, `<object>` has to be of
 	the form `<tree-ish>:<path>`, or `:<path>`.
 
+--filter=<filter-spec>::
+--no-filter::
+	Omit objects from the list of printed objects. This can only be used in
+	combination with one of the batched modes. Excluded objects that have
+	been explicitly requested via any of the batch modes that read objects
+	via standard input (`--batch`, `--batch-check`) will be reported as
+	"filtered". Excluded objects in `--batch-all-objects` mode will not be
+	printed at all. The '<filter-spec>' may be one of the following:
++
+The form '--filter=blob:none' omits all blobs.
++
+The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n
+bytes or units.  n may be zero.  The suffixes k, m, and g can be used to name
+units in KiB, MiB, or GiB.  For example, 'blob:limit=1k' is the same as
+'blob:limit=1024'.
++
+The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects which
+are not of the requested type.
+
 --path=<path>::
 	For use with `--textconv` or `--filters`, to allow specifying an object
 	name and a path separately, e.g. when it is difficult to figure out
@@ -183,9 +203,6 @@ flush::
 	only once, even if it is stored multiple times in the
 	repository.
 
---allow-unknown-type::
-	Allow `-s` or `-t` to query broken/corrupt objects of unknown type.
-
 --follow-symlinks::
 	With `--batch` or `--batch-check`, follow symlinks inside the
 	repository when requesting objects with extended SHA-1
@@ -292,6 +309,11 @@ newline. The available atoms are:
 `objecttype`::
 	The type of the object (the same as `cat-file -t` reports).
 
+`objectmode`::
+	If the specified object has mode information (such as a tree or
+	index entry), the mode expressed as an octal integer. Otherwise,
+	empty string.
+
 `objectsize`::
 	The size, in bytes, of the object (the same as `cat-file -s`
 	reports).
@@ -322,10 +344,10 @@ of `%(objectsize)` bytes), followed by a newline.
 
 For example, `--batch` without a custom format would produce:
 
-------------
+-----------
 <oid> SP <type> SP <size> LF
 <contents> LF
-------------
+-----------
 
 Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
 
@@ -340,12 +362,27 @@ the repository, then `cat-file` will ignore any custom format and print:
 <object> SP missing LF
 ------------
 
+If a name is specified on stdin that is filtered out via `--filter=`,
+then `cat-file` will ignore any custom format and print:
+
+------------
+<object> SP excluded LF
+------------
+
 If a name is specified that might refer to more than one object (an ambiguous short sha), then `cat-file` will ignore any custom format and print:
 
 ------------
 <object> SP ambiguous LF
 ------------
 
+If a name is specified that refers to a submodule entry in a tree and the
+target object does not exist in the repository, then `cat-file` will ignore
+any custom format and print (with the object ID of the submodule):
+
+------------
+<oid> SP submodule LF
+------------
+
 If `--follow-symlinks` is used, and a symlink in the repository points
 outside the repository, then `cat-file` will ignore any custom format
 and print:
diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.adoc
index cb5a6c8f33..15a37a38e3 100644
--- a/Documentation/git-check-attr.txt
+++ b/Documentation/git-check-attr.adoc
@@ -19,7 +19,8 @@ For every pathname, this command will list if each attribute is 'unspecified',
 
 OPTIONS
 -------
--a, --all::
+-a::
+--all::
 	List all attributes that are associated with the specified
 	paths.  If this option is used, then 'unspecified' attributes
 	will not be included in the output.
@@ -76,6 +77,7 @@ EXAMPLES
 --------
 
 In the examples, the following '.gitattributes' file is used:
+
 ---------------
 *.java diff=java -crlf myAttr
 NoMyAttr.java !myAttr
@@ -83,12 +85,14 @@ README caveat=unspecified
 ---------------
 
 * Listing a single attribute:
++
 ---------------
 $ git check-attr diff org/example/MyClass.java
 org/example/MyClass.java: diff: java
 ---------------
 
 * Listing multiple attributes for a file:
++
 ---------------
 $ git check-attr crlf diff myAttr -- org/example/MyClass.java
 org/example/MyClass.java: crlf: unset
@@ -97,6 +101,7 @@ org/example/MyClass.java: myAttr: set
 ---------------
 
 * Listing all attributes for a file:
++
 ---------------
 $ git check-attr --all -- org/example/MyClass.java
 org/example/MyClass.java: diff: java
@@ -104,6 +109,7 @@ org/example/MyClass.java: myAttr: set
 ---------------
 
 * Listing an attribute for multiple files:
++
 ---------------
 $ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java
 org/example/MyClass.java: myAttr: set
@@ -111,6 +117,7 @@ org/example/NoMyAttr.java: myAttr: unspecified
 ---------------
 
 * Not all values are equally unambiguous:
++
 ---------------
 $ git check-attr caveat README
 README: caveat: unspecified
diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.adoc
index 3e3b4e3446..a6c6c1b6e5 100644
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.adoc
@@ -25,11 +25,13 @@ subject to exclude rules; but see `--no-index'.
 
 OPTIONS
 -------
--q, --quiet::
+-q::
+--quiet::
 	Don't output anything, just set exit status.  This is only
 	valid with a single pathname.
 
--v, --verbose::
+-v::
+--verbose::
 	Instead of printing the paths that are excluded, for each path
 	that matches an exclude pattern, print the exclude pattern
 	together with the path.  (Matching an exclude pattern usually
@@ -49,7 +51,8 @@ linkgit:gitignore[5].
 	below).  If `--stdin` is also given, input paths are separated
 	with a NUL character instead of a linefeed character.
 
--n, --non-matching::
+-n::
+--non-matching::
 	Show given paths which don't match any pattern.  This only
 	makes sense when `--verbose` is enabled, otherwise it would
 	not be possible to distinguish between paths which match a
diff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.adoc
index 966c91c46a..966c91c46a 100644
--- a/Documentation/git-check-mailmap.txt
+++ b/Documentation/git-check-mailmap.adoc
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.adoc
index 2aacfd1808..0c3abf9146 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.adoc
@@ -98,7 +98,8 @@ a branch.
 
 OPTIONS
 -------
---[no-]allow-onelevel::
+--allow-onelevel::
+--no-allow-onelevel::
 	Controls whether one-level refnames are accepted (i.e.,
 	refnames that do not contain multiple `/`-separated
 	components).  The default is `--no-allow-onelevel`.
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.adoc
index faf8d6ca36..faf8d6ca36 100644
--- a/Documentation/git-checkout-index.txt
+++ b/Documentation/git-checkout-index.adoc
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.adoc
index bf26655764..6f281b298e 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.adoc
@@ -7,120 +7,119 @@ git-checkout - Switch branches or restore working tree files
 
 SYNOPSIS
 --------
-[verse]
-'git checkout' [-q] [-f] [-m] [<branch>]
-'git checkout' [-q] [-f] [-m] --detach [<branch>]
-'git checkout' [-q] [-f] [-m] [--detach] <commit>
-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
-'git checkout' [-f] <tree-ish> [--] <pathspec>...
-'git checkout' [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
-'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
+[synopsis]
+git checkout [-q] [-f] [-m] [<branch>]
+git checkout [-q] [-f] [-m] --detach [<branch>]
+git checkout [-q] [-f] [-m] [--detach] <commit>
+git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
+git checkout <tree-ish> [--] <pathspec>...
+git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
+git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
+git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
-Updates files in the working tree to match the version in the index
-or the specified tree.  If no pathspec was given, 'git checkout' will
-also update `HEAD` to set the specified branch as the current
-branch.
-
-'git checkout' [<branch>]::
-	To prepare for working on `<branch>`, switch to it by updating
-	the index and the files in the working tree, and by pointing
-	`HEAD` at the branch. Local modifications to the files in the
-	working tree are kept, so that they can be committed to the
-	`<branch>`.
+
+`git checkout` has two main modes:
+
+1. **Switch branches**, with `git checkout <branch>`
+2. **Restore a different version of a file**, for example with
+   `git checkout <commit> <filename>` or `git checkout <filename>`
+
+See ARGUMENT DISAMBIGUATION below for how Git decides which one to do.
+
+`git checkout [<branch>]`::
+	Switch to _<branch>_. This sets the current branch to _<branch>_ and
+	updates the files in your working directory. The checkout will fail
+	if there are uncommitted changes to any files where _<branch>_ and
+	your current commit have different content. Uncommitted changes will
+	otherwise be kept.
 +
-If `<branch>` is not found but there does exist a tracking branch in
-exactly one remote (call it `<remote>`) with a matching name and
+If _<branch>_ is not found but there does exist a tracking branch in
+exactly one remote (call it _<remote>_) with a matching name and
 `--no-guess` is not specified, treat as equivalent to
 +
 ------------
 $ git checkout -b <branch> --track <remote>/<branch>
 ------------
 +
-You could omit `<branch>`, in which case the command degenerates to
-"check out the current branch", which is a glorified no-op with
-rather expensive side-effects to show only the tracking information,
-if it exists, for the current branch.
-
-'git checkout' -b|-B <new-branch> [<start-point>]::
-
-	Specifying `-b` causes a new branch to be created as if
-	linkgit:git-branch[1] were called and then checked out.  In
-	this case you can use the `--track` or `--no-track` options,
-	which will be passed to 'git branch'.  As a convenience,
-	`--track` without `-b` implies branch creation; see the
-	description of `--track` below.
-+
-If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it
-is reset. This is the transactional equivalent of
-+
-------------
-$ git branch -f <branch> [<start-point>]
-$ git checkout <branch>
-------------
+Running `git checkout` without specifying a branch has no effect except
+to print out the tracking information for the current branch.
+
+`git checkout -b <new-branch> [<start-point>]`::
+
+	Create a new branch named _<new-branch>_, start it at _<start-point>_
+	(defaults to the current commit), and check out the new branch.
+	You can use the `--track` or `--no-track` options to set the branch's
+	upstream tracking information.
 +
-that is to say, the branch is not reset/created unless "git checkout" is
-successful (e.g., when the branch is in use in another worktree, not
-just the current branch stays the same, but the branch is not reset to
-the start-point, either).
-
-'git checkout' --detach [<branch>]::
-'git checkout' [--detach] <commit>::
-
-	Prepare to work on top of `<commit>`, by detaching `HEAD` at it
-	(see "DETACHED HEAD" section), and updating the index and the
-	files in the working tree.  Local modifications to the files
-	in the working tree are kept, so that the resulting working
-	tree will be the state recorded in the commit plus the local
-	modifications.
+This will fail if there's an error checking out _<new-branch>_, for
+example if checking out the `<start-point>` commit would overwrite your
+uncommitted changes.
+
+`git checkout -B <branch> [<start-point>]`::
+
+	The same as `-b`, except that if the branch already exists it
+	resets _<branch>_ to the start point instead of failing.
+
+`git checkout --detach [<branch>]`::
+`git checkout [--detach] <commit>`::
+
+	The same as `git checkout <branch>`, except that instead of pointing
+	`HEAD` at the branch, it points `HEAD` at the commit ID.
+	See the "DETACHED HEAD" section below for more.
 +
-When the `<commit>` argument is a branch name, the `--detach` option can
-be used to detach `HEAD` at the tip of the branch (`git checkout
-<branch>` would check out that branch without detaching `HEAD`).
+Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
+
+`git checkout <tree-ish> [--] <pathspec>...`::
+`git checkout <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]`::
+
+	Replace the specified files and/or directories with the version from
+	the given commit or tree and add them to the index
+	(also known as "staging area").
 +
-Omitting `<branch>` detaches `HEAD` at the tip of the current branch.
+For example, `git checkout main file.txt` will replace `file.txt`
+with the version from `main`.
 
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...::
-'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]::
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
+`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
 
-	Overwrite the contents of the files that match the pathspec.
-	When the `<tree-ish>` (most often a commit) is not given,
-	overwrite working tree with the contents in the index.
-	When the `<tree-ish>` is given, overwrite both the index and
-	the working tree with the contents at the `<tree-ish>`.
+	Replace the specified files and/or directories with the version from
+	the index.
 +
-The index may contain unmerged entries because of a previous failed merge.
-By default, if you try to check out such an entry from the index, the
-checkout operation will fail and nothing will be checked out.
-Using `-f` will ignore these unmerged entries.  The contents from a
-specific side of the merge can be checked out of the index by
-using `--ours` or `--theirs`.  With `-m`, changes made to the working tree
-file can be discarded to re-create the original conflicted merge result.
-
-'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]::
-	This is similar to the previous mode, but lets you use the
+For example, if you check out a commit, edit `file.txt`, and then
+decide those changes were a mistake, `git checkout file.txt` will
+discard any unstaged changes to `file.txt`.
++
+This will fail if the file has a merge conflict and you haven't yet run
+`git add file.txt` (or something equivalent) to mark it as resolved.
+You can use `-f` to ignore the unmerged files instead of failing, use
+`--ours` or `--theirs` to replace them with the version from a specific
+side of the merge, or use `-m` to replace them with the original
+conflicted merge result.
+
+`git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
+	This is similar to the previous two modes, but lets you use the
 	interactive interface to show the "diff" output and choose which
 	hunks to use in the result.  See below for the description of
 	`--patch` option.
 
 OPTIONS
 -------
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Quiet, suppress feedback messages.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Progress status is reported on the standard error stream
 	by default when it is attached to a terminal, unless `--quiet`
 	is specified. This flag enables progress reporting even if not
 	attached to a terminal, regardless of `--quiet`.
 
--f::
---force::
+`-f`::
+`--force`::
 	When switching branches, proceed even if the index or the
 	working tree differs from `HEAD`, and even if there are untracked
 	files in the way.  This is used to throw away local changes and
@@ -129,13 +128,13 @@ OPTIONS
 When checking out paths from the index, do not fail upon unmerged
 entries; instead, unmerged entries are ignored.
 
---ours::
---theirs::
+`--ours`::
+`--theirs`::
 	When checking out paths from the index, check out stage #2
-	('ours') or #3 ('theirs') for unmerged paths.
+	(`ours`) or #3 (`theirs`) for unmerged paths.
 +
-Note that during `git rebase` and `git pull --rebase`, 'ours' and
-'theirs' may appear swapped; `--ours` gives the version from the
+Note that during `git rebase` and `git pull --rebase`, `ours` and
+`theirs` may appear swapped; `--ours` gives the version from the
 branch the changes are rebased onto, while `--theirs` gives the
 version from the branch that holds your work that is being rebased.
 +
@@ -149,22 +148,20 @@ as `ours` (i.e. "our shared canonical history"), while what you did
 on your side branch as `theirs` (i.e. "one contributor's work on top
 of it").
 
--b <new-branch>::
-	Create a new branch named `<new-branch>`, start it at
-	`<start-point>`, and check the resulting branch out;
+`-b <new-branch>`::
+	Create a new branch named _<new-branch>_, start it at
+	_<start-point>_, and check the resulting branch out;
 	see linkgit:git-branch[1] for details.
 
--B <new-branch>::
-	Creates the branch `<new-branch>`, start it at `<start-point>`;
-	if it already exists, then reset it to `<start-point>`. And then
-	check the resulting branch out.  This is equivalent to running
-	"git branch" with "-f" followed by "git checkout" of that branch;
-	see linkgit:git-branch[1] for details.
+`-B <new-branch>`::
+	The same as `-b`, except that if the branch already exists it
+	resets _<branch>_ to the start point instead of failing.
 
--t::
---track[=(direct|inherit)]::
+`-t`::
+`--track[=(direct|inherit)]`::
 	When creating a new branch, set up "upstream" configuration. See
-	"--track" in linkgit:git-branch[1] for details.
+	`--track` in linkgit:git-branch[1] for details. As a convenience,
+	--track without -b implies branch creation.
 +
 If no `-b` option is given, the name of the new branch will be
 derived from the remote-tracking branch, by looking at the local part of
@@ -176,14 +173,14 @@ off of `origin/hack` (or `remotes/origin/hack`, or even
 guessing results in an empty name, the guessing is aborted.  You can
 explicitly give a name with `-b` in such a case.
 
---no-track::
+`--no-track`::
 	Do not set up "upstream" configuration, even if the
 	`branch.autoSetupMerge` configuration variable is true.
 
---guess::
---no-guess::
-	If `<branch>` is not found but there does exist a tracking
-	branch in exactly one remote (call it `<remote>`) with a
+`--guess`::
+`--no-guess`::
+	If _<branch>_ is not found but there does exist a tracking
+	branch in exactly one remote (call it _<remote>_) with a
 	matching name, treat as equivalent to
 +
 ------------
@@ -192,10 +189,10 @@ $ git checkout -b <branch> --track <remote>/<branch>
 +
 If the branch exists in multiple remotes and one of them is named by
 the `checkout.defaultRemote` configuration variable, we'll use that
-one for the purposes of disambiguation, even if the `<branch>` isn't
+one for the purposes of disambiguation, even if the _<branch>_ isn't
 unique across all remotes. Set it to
 e.g. `checkout.defaultRemote=origin` to always checkout remote
-branches from there if `<branch>` is ambiguous but exists on the
+branches from there if _<branch>_ is ambiguous but exists on the
 'origin' remote. See also `checkout.defaultRemote` in
 linkgit:git-config[1].
 +
@@ -204,28 +201,28 @@ linkgit:git-config[1].
 The default behavior can be set via the `checkout.guess` configuration
 variable.
 
--l::
+`-l`::
 	Create the new branch's reflog; see linkgit:git-branch[1] for
 	details.
 
--d::
---detach::
+`-d`::
+`--detach`::
 	Rather than checking out a branch to work on it, check out a
 	commit for inspection and discardable experiments.
 	This is the default behavior of `git checkout <commit>` when
-	`<commit>` is not a branch name.  See the "DETACHED HEAD" section
+	_<commit>_ is not a branch name.  See the "DETACHED HEAD" section
 	below for details.
 
---orphan <new-branch>::
-	Create a new unborn branch, named `<new-branch>`, started from
-	`<start-point>` and switch to it.  The first commit made on this
+`--orphan <new-branch>`::
+	Create a new unborn branch, named _<new-branch>_, started from
+	_<start-point>_ and switch to it.  The first commit made on this
 	new branch will have no parents and it will be the root of a new
 	history totally disconnected from all the other branches and
 	commits.
 +
 The index and the working tree are adjusted as if you had previously run
 `git checkout <start-point>`.  This allows you to start a new history
-that records a set of paths similar to `<start-point>` by easily running
+that records a set of paths similar to _<start-point>_ by easily running
 `git commit -a` to make the root commit.
 +
 This can be useful when you want to publish the tree from a commit
@@ -235,20 +232,20 @@ whose full history contains proprietary or otherwise encumbered bits of
 code.
 +
 If you want to start a disconnected history that records a set of paths
-that is totally different from the one of `<start-point>`, then you should
+that is totally different from the one of _<start-point>_, then you should
 clear the index and the working tree right after creating the orphan
 branch by running `git rm -rf .` from the top level of the working tree.
 Afterwards you will be ready to prepare your new files, repopulating the
 working tree, by copying them from elsewhere, extracting a tarball, etc.
 
---ignore-skip-worktree-bits::
-	In sparse checkout mode, `git checkout -- <paths>` would
-	update only entries matched by `<paths>` and sparse patterns
+`--ignore-skip-worktree-bits`::
+	In sparse checkout mode, `git checkout -- <path>...` would
+	update only entries matched by _<paths>_ and sparse patterns
 	in `$GIT_DIR/info/sparse-checkout`. This option ignores
-	the sparse patterns and adds back any files in `<paths>`.
+	the sparse patterns and adds back any files in `<path>...`.
 
--m::
---merge::
+`-m`::
+`--merge`::
 	When switching branches,
 	if you have local modifications to one or more files that
 	are different between the current branch and the branch to
@@ -269,40 +266,42 @@ used when checking out paths from a tree-ish.
 +
 When switching branches with `--merge`, staged changes may be lost.
 
---conflict=<style>::
+`--conflict=<style>`::
 	The same as `--merge` option above, but changes the way the
 	conflicting hunks are presented, overriding the
 	`merge.conflictStyle` configuration variable.  Possible values are
-	"merge" (default), "diff3", and "zdiff3".
+	`merge` (default), `diff3`, and `zdiff3`.
 
--p::
---patch::
+`-p`::
+`--patch`::
 	Interactively select hunks in the difference between the
-	`<tree-ish>` (or the index, if unspecified) and the working
+	_<tree-ish>_ (or the index, if unspecified) and the working
 	tree.  The chosen hunks are then applied in reverse to the
-	working tree (and if a `<tree-ish>` was specified, the index).
+	working tree (and if a _<tree-ish>_ was specified, the index).
 +
 This means that you can use `git checkout -p` to selectively discard
-edits from your current working tree. See the ``Interactive Mode''
+edits from your current working tree. See the "Interactive Mode"
 section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
 +
 Note that this option uses the no overlay mode by default (see also
 `--overlay`), and currently doesn't support overlay mode.
 
---ignore-other-worktrees::
+include::diff-context-options.adoc[]
+
+`--ignore-other-worktrees`::
 	`git checkout` refuses when the wanted branch is already checked
 	out or otherwise in use by another worktree. This option makes
 	it check the branch out anyway. In other words, the branch can
 	be in use by more than one worktree.
 
---overwrite-ignore::
---no-overwrite-ignore::
+`--overwrite-ignore`::
+`--no-overwrite-ignore`::
 	Silently overwrite ignored files when switching branches. This
 	is the default behavior. Use `--no-overwrite-ignore` to abort
 	the operation when the new branch contains ignored files.
 
---recurse-submodules::
---no-recurse-submodules::
+`--recurse-submodules`::
+`--no-recurse-submodules`::
 	Using `--recurse-submodules` will update the content of all active
 	submodules according to the commit recorded in the superproject. If
 	local modifications in a submodule would be overwritten the checkout
@@ -311,28 +310,28 @@ Note that this option uses the no overlay mode by default (see also
 	Just like linkgit:git-submodule[1], this will detach `HEAD` of the
 	submodule.
 
---overlay::
---no-overlay::
+`--overlay`::
+`--no-overlay`::
 	In the default overlay mode, `git checkout` never
 	removes files from the index or the working tree.  When
 	specifying `--no-overlay`, files that appear in the index and
-	working tree, but not in `<tree-ish>` are removed, to make them
-	match `<tree-ish>` exactly.
+	working tree, but not in _<tree-ish>_ are removed, to make them
+	match _<tree-ish>_ exactly.
 
---pathspec-from-file=<file>::
-	Pathspec is passed in `<file>` instead of commandline args. If
-	`<file>` is exactly `-` then standard input is used. Pathspec
-	elements are separated by LF or CR/LF. Pathspec elements can be
+`--pathspec-from-file=<file>`::
+	Pathspec is passed in _<file>_ instead of commandline args. If
+	_<file>_ is exactly `-` then standard input is used. Pathspec
+	elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
 	quoted as explained for the configuration variable `core.quotePath`
 	(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
 	global `--literal-pathspecs`.
 
---pathspec-file-nul::
+`--pathspec-file-nul`::
 	Only meaningful with `--pathspec-from-file`. Pathspec elements are
-	separated with NUL character and all other characters are taken
+	separated with _NUL_ character and all other characters are taken
 	literally (including newlines and quotes).
 
-<branch>::
+`<branch>`::
 	Branch to checkout; if it refers to a branch (i.e., a name that,
 	when prepended with "refs/heads/", is a valid ref), then that
 	branch is checked out. Otherwise, if it refers to a valid
@@ -343,33 +342,33 @@ You can use the `@{-N}` syntax to refer to the N-th last
 branch/commit checked out using "git checkout" operation. You may
 also specify `-` which is synonymous to `@{-1}`.
 +
-As a special case, you may use `A...B` as a shortcut for the
-merge base of `A` and `B` if there is exactly one merge base. You can
-leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the
+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
 
-<new-branch>::
+_<new-branch>_::
 	Name for the new branch.
 
-<start-point>::
+_<start-point>_::
 	The name of a commit at which to start the new branch; see
 	linkgit:git-branch[1] for details. Defaults to `HEAD`.
 +
-As a special case, you may use `"A...B"` as a shortcut for the
-merge base of `A` and `B` if there is exactly one merge base. You can
-leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the
+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
 
-<tree-ish>::
+_<tree-ish>_::
 	Tree to checkout from (when paths are given). If not specified,
 	the index will be used.
 +
-As a special case, you may use `"A...B"` as a shortcut for the
-merge base of `A` and `B` if there is exactly one merge base. You can
-leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the
+merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
+leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
 
-\--::
+`--`::
 	Do not interpret any more arguments as options.
 
-<pathspec>...::
+`<pathspec>...`::
 	Limits the paths affected by the operation.
 +
 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
@@ -391,7 +390,7 @@ a---b---c  branch 'master' (refers to commit 'c')
 ------------
 
 When a commit is created in this state, the branch is updated to refer to
-the new commit. Specifically, 'git commit' creates a new commit `d`, whose
+the new commit. Specifically, `git commit` creates a new commit `d`, whose
 parent is commit `c`, and then updates branch `master` to refer to new
 commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers
 to commit `d`:
@@ -509,14 +508,18 @@ $ git log -g -2 HEAD
 ARGUMENT DISAMBIGUATION
 -----------------------
 
-When there is only one argument given and it is not `--` (e.g. `git
-checkout abc`), and when the argument is both a valid `<tree-ish>`
-(e.g. a branch `abc` exists) and a valid `<pathspec>` (e.g. a file
-or a directory whose name is "abc" exists), Git would usually ask
-you to disambiguate.  Because checking out a branch is so common an
-operation, however, `git checkout abc` takes "abc" as a `<tree-ish>`
-in such a situation.  Use `git checkout -- <pathspec>` if you want
-to checkout these paths out of the index.
+When you run `git checkout <something>`, Git tries to guess whether
+`<something>` is intended to be a branch, a commit, or a set of file(s),
+and then either switches to that branch or commit, or restores the
+specified files.
+
+If there's any ambiguity, Git will treat `<something>` as a branch or
+commit, but you can use the double dash `--` to force Git to treat the
+parameter as a list of files and/or directories, like this:
+
+----------
+git checkout -- file.txt
+----------
 
 EXAMPLES
 --------
@@ -612,9 +615,9 @@ $ git add frotz
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/checkout.txt[]
+include::config/checkout.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.adoc
index 81ace900fc..42b41923d5 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.adoc
@@ -172,11 +172,11 @@ fail unless one of `--empty=keep` or `--allow-empty` are specified.
 	Pass the merge strategy-specific option through to the
 	merge strategy.  See linkgit:git-merge[1] for details.
 
-include::rerere-options.txt[]
+include::rerere-options.adoc[]
 
 SEQUENCER SUBCOMMANDS
 ---------------------
-include::sequencer.txt[]
+include::sequencer.adoc[]
 
 EXAMPLES
 --------
diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.adoc
index 0ea921a593..0ea921a593 100644
--- a/Documentation/git-cherry.txt
+++ b/Documentation/git-cherry.adoc
diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.adoc
index c7a11c36c1..c7a11c36c1 100644
--- a/Documentation/git-citool.txt
+++ b/Documentation/git-citool.adoc
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.adoc
index fd17165416..bed52c203b 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.adoc
@@ -140,9 +140,9 @@ help::
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/clean.txt[]
+include::config/clean.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.adoc
index de8d8f5893..57cdfb7620 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.adoc
@@ -13,10 +13,10 @@ git clone [--template=<template-directory>]
 	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
 	  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
 	  [--dissociate] [--separate-git-dir <git-dir>]
-	  [--depth <depth>] [--[no-]single-branch] [--no-tags]
+	  [--depth <depth>] [--[no-]single-branch] [--[no-]tags]
 	  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
 	  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
-	  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+	  [--filter=<filter-spec> [--also-filter-submodules]] [--] <repository>
 	  [<directory>]
 
 DESCRIPTION
@@ -221,6 +221,15 @@ objects from the source repository into a pack in the cloned repository.
 	`--branch` can also take tags and detaches the `HEAD` at that commit
 	in the resulting repository.
 
+`--revision=<rev>`::
+	Create a new repository, and fetch the history leading to the given
+	revision _<rev>_ (and nothing else), without making any remote-tracking
+	branch, and without making any local branch, and detach `HEAD` to
+	_<rev>_. The argument can be a ref name (e.g. `refs/heads/main` or
+	`refs/tags/v1.0`) that peels down to a commit, or a hexadecimal object
+	name.
+	This option is incompatible with `--branch` and `--mirror`.
+
 `-u` _<upload-pack>_::
 `--upload-pack` _<upload-pack>_::
 	When given, and the repository to clone from is accessed
@@ -263,7 +272,8 @@ corresponding `--mirror` and `--no-tags` options instead.
 	reachable from a specified remote branch or tag.  This option
 	can be specified multiple times.
 
-`--[no-]single-branch`::
+`--single-branch`::
+`--no-single-branch`::
 	Clone only the history leading to the tip of a single branch,
 	either specified by the `--branch` option or the primary
 	branch remote's `HEAD` points at.
@@ -273,12 +283,16 @@ corresponding `--mirror` and `--no-tags` options instead.
 	branch when `--single-branch` clone was made, no remote-tracking
 	branch is created.
 
+`--tags`::
 `--no-tags`::
-	Don't clone any tags, and set
-	`remote.<remote>.tagOpt=--no-tags` in the config, ensuring
-	that future `git pull` and `git fetch` operations won't follow
-	any tags. Subsequent explicit tag fetches will still work,
-	(see linkgit:git-fetch[1]).
+	Control whether or not tags will be cloned. When `--no-tags` is
+	given, the option will be become permanent by setting the
+	`remote.<remote>.tagOpt=--no-tags` configuration. This ensures that
+	future `git pull` and `git fetch` won't follow any tags. Subsequent
+	explicit tag fetches will still work (see linkgit:git-fetch[1]).
++
+By default, tags are cloned and passing `--tags` is thus typically a
+no-op, unless it cancels out a previous `--no-tags`.
 +
 Can be used in conjunction with `--single-branch` to clone and
 maintain a branch with no references other than a single cloned
@@ -301,10 +315,12 @@ the clone is finished. This option is ignored if the cloned repository does
 not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
 or `--mirror` is given)
 
-`--[no-]shallow-submodules`::
+`--shallow-submodules`::
+`--no-shallow-submodules`::
 	All submodules which are cloned will be shallow with a depth of 1.
 
-`--[no-]remote-submodules`::
+`--remote-submodules`::
+`--no-remote-submodules`::
 	All submodules which are cloned will use the status of the submodule's
 	remote-tracking branch to update the submodule, rather than the
 	superproject's recorded SHA-1. Equivalent to passing `--remote` to
@@ -321,7 +337,7 @@ or `--mirror` is given)
 
 Specify the given ref storage format for the repository. The valid values are:
 +
-include::ref-storage-format.txt[]
+include::ref-storage-format.adoc[]
 
 `-j` _<n>_::
 `--jobs` _<n>_::
@@ -348,7 +364,7 @@ _<directory>_::
 	`--shallow-since`, and `--shallow-exclude`.
 
 :git-clone: 1
-include::urls.txt[]
+include::urls.adoc[]
 
 EXAMPLES
 --------
@@ -396,11 +412,11 @@ $ git clone --no-local /home/otheruser/proj.git /pub/scm/proj.git
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/init.txt[]
+include::config/init.adoc[]
 
-include::config/clone.txt[]
+include::config/clone.adoc[]
 
 
 GIT
diff --git a/Documentation/git-column.txt b/Documentation/git-column.adoc
index 18431647a2..8e0047214d 100644
--- a/Documentation/git-column.txt
+++ b/Documentation/git-column.adoc
@@ -50,6 +50,7 @@ EXAMPLES
 --------
 
 Format data by columns:
+
 ------------
 $ seq 1 24 | git column --mode=column --padding=5
 1      4      7      10     13     16     19     22
@@ -58,6 +59,7 @@ $ seq 1 24 | git column --mode=column --padding=5
 ------------
 
 Format data by rows:
+
 ------------
 $ seq 1 21 | git column --mode=row --padding=5
 1      2      3      4      5      6      7
@@ -66,6 +68,7 @@ $ seq 1 21 | git column --mode=row --padding=5
 ------------
 
 List some tags in a table with unequal column widths:
+
 ------------
 $ git tag --list 'v2.4.*' --column=row,dense
 v2.4.0  v2.4.0-rc0  v2.4.0-rc1  v2.4.0-rc2  v2.4.0-rc3
@@ -77,9 +80,9 @@ v2.4.8  v2.4.9
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/column.txt[]
+include::config/column.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.adoc
index 903b16830e..6d19026035 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.adoc
@@ -34,7 +34,8 @@ OPTIONS
 	object directory, `git commit-graph ...` will exit with non-zero
 	status.
 
---[no-]progress::
+--progress::
+--no-progress::
 	Turn progress on/off explicitly. If neither is specified, progress is
 	shown if standard error is connected to a terminal.
 
@@ -70,7 +71,7 @@ take a while on large repositories. It provides significant performance gains
 for getting history of a directory or a file with `git log -- <path>`. If
 this option is given, future commit-graph writes will automatically assume
 that this option was intended. Use `--no-changed-paths` to stop storing this
-data.
+data. `--changed-paths` is implied by config `commitGraph.changedPaths=true`.
 +
 With the `--max-new-filters=<n>` option, generate at most `n` new Bloom
 filters (if `--changed-paths` is specified). If `n` is `-1`, no limit is
@@ -148,9 +149,9 @@ $ git rev-parse HEAD | git commit-graph write --stdin-commits --append
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/commitgraph.txt[]
+include::config/commitgraph.adoc[]
 
 
 FILE FORMAT
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.adoc
index 2e2c581098..6472921e14 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.adoc
@@ -80,12 +80,12 @@ A commit comment is read from stdin. If a changelog
 entry is not provided via "<" redirection, 'git commit-tree' will just wait
 for one to be entered and terminated with ^D.
 
-include::date-formats.txt[]
+include::date-formats.adoc[]
 
 Discussion
 ----------
 
-include::i18n.txt[]
+include::i18n.adoc[]
 
 FILES
 -----
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.adoc
index c822113c11..54c207ad45 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.adoc
@@ -7,8 +7,8 @@ git-commit - Record changes to the repository
 
 SYNOPSIS
 --------
-[verse]
-'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
+[synopsis]
+git commit [-a | --interactive | --patch] [-s] [-v] [-u[<mode>]] [--amend]
 	   [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>]
 	   [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
 	   [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
@@ -23,31 +23,31 @@ Create a new commit containing the current contents of the index and
 the given log message describing the changes. The new commit is a
 direct child of HEAD, usually the tip of the current branch, and the
 branch is updated to point to it (unless no branch is associated with
-the working tree, in which case HEAD is "detached" as described in
+the working tree, in which case `HEAD` is "detached" as described in
 linkgit:git-checkout[1]).
 
 The content to be committed can be specified in several ways:
 
 1. by using linkgit:git-add[1] to incrementally "add" changes to the
-   index before using the 'commit' command (Note: even modified files
+   index before using the `commit` command (Note: even modified files
    must be "added");
 
 2. by using linkgit:git-rm[1] to remove files from the working tree
-   and the index, again before using the 'commit' command;
+   and the index, again before using the `commit` command;
 
-3. by listing files as arguments to the 'commit' command
-   (without --interactive or --patch switch), in which
+3. by listing files as arguments to the `commit` command
+   (without `--interactive` or `--patch` switch), in which
    case the commit will ignore changes staged in the index, and instead
    record the current content of the listed files (which must already
    be known to Git);
 
-4. by using the -a switch with the 'commit' command to automatically
+4. by using the `-a` switch with the `commit` command to automatically
    "add" changes from all known files (i.e. all files that are already
    listed in the index) and to automatically "rm" files in the index
    that have been removed from the working tree, and then perform the
    actual commit;
 
-5. by using the --interactive or --patch switches with the 'commit' command
+5. by using the `--interactive` or `--patch` switches with the `commit` command
    to decide one by one which files or hunks should be part of the commit
    in addition to contents in the index,
    before finalizing the operation. See the ``Interactive Mode'' section of
@@ -58,139 +58,141 @@ summary of what is included by any of the above for the next
 commit by giving the same set of parameters (options and paths).
 
 If you make a commit and then find a mistake immediately after
-that, you can recover from it with 'git reset'.
+that, you can recover from it with `git reset`.
 
 :git-commit: 1
 
 OPTIONS
 -------
--a::
---all::
-	Tell the command to automatically stage files that have
+`-a`::
+`--all`::
+	Automatically stage files that have
 	been modified and deleted, but new files you have not
 	told Git about are not affected.
 
--p::
---patch::
+`-p`::
+`--patch`::
 	Use the interactive patch selection interface to choose
 	which changes to commit. See linkgit:git-add[1] for
 	details.
 
--C <commit>::
---reuse-message=<commit>::
-	Take an existing commit object, and reuse the log message
+include::diff-context-options.adoc[]
+
+`-C <commit>`::
+`--reuse-message=<commit>`::
+	Take an existing _<commit>_ object, and reuse the log message
 	and the authorship information (including the timestamp)
 	when creating the commit.
 
--c <commit>::
---reedit-message=<commit>::
-	Like '-C', but with `-c` the editor is invoked, so that
+`-c <commit>`::
+`--reedit-message=<commit>`::
+	Like `-C`, but with `-c` the editor is invoked, so that
 	the user can further edit the commit message.
 
---fixup=[(amend|reword):]<commit>::
-	Create a new commit which "fixes up" `<commit>` when applied with
+`--fixup=[(amend|reword):]<commit>`::
+	Create a new commit which "fixes up" _<commit>_ when applied with
 	`git rebase --autosquash`. Plain `--fixup=<commit>` creates a
-	"fixup!" commit which changes the content of `<commit>` but leaves
+	"fixup!" commit which changes the content of _<commit>_ but leaves
 	its log message untouched. `--fixup=amend:<commit>` is similar but
 	creates an "amend!" commit which also replaces the log message of
-	`<commit>` with the log message of the "amend!" commit.
+	_<commit>_ with the log message of the "amend!" commit.
 	`--fixup=reword:<commit>` creates an "amend!" commit which
-	replaces the log message of `<commit>` with its own log message
-	but makes no changes to the content of `<commit>`.
+	replaces the log message of _<commit>_ with its own log message
+	but makes no changes to the content of _<commit>_.
 +
-The commit created by plain `--fixup=<commit>` has a subject
-composed of "fixup!" followed by the subject line from <commit>,
+The commit created by plain `--fixup=<commit>` has a title
+composed of "fixup!" followed by the title of _<commit>_,
 and is recognized specially by `git rebase --autosquash`. The `-m`
 option may be used to supplement the log message of the created
 commit, but the additional commentary will be thrown away once the
-"fixup!" commit is squashed into `<commit>` by
+"fixup!" commit is squashed into _<commit>_ by
 `git rebase --autosquash`.
 +
 The commit created by `--fixup=amend:<commit>` is similar but its
-subject is instead prefixed with "amend!". The log message of
-<commit> is copied into the log message of the "amend!" commit and
+title is instead prefixed with "amend!". The log message of
+_<commit>_ is copied into the log message of the "amend!" commit and
 opened in an editor so it can be refined. When `git rebase
---autosquash` squashes the "amend!" commit into `<commit>`, the
-log message of `<commit>` is replaced by the refined log message
+--autosquash` squashes the "amend!" commit into _<commit>_, the
+log message of _<commit>_ is replaced by the refined log message
 from the "amend!" commit. It is an error for the "amend!" commit's
 log message to be empty unless `--allow-empty-message` is
 specified.
 +
 `--fixup=reword:<commit>` is shorthand for `--fixup=amend:<commit>
---only`. It creates an "amend!" commit with only a log message
+ --only`. It creates an "amend!" commit with only a log message
 (ignoring any changes staged in the index). When squashed by `git
-rebase --autosquash`, it replaces the log message of `<commit>`
+rebase --autosquash`, it replaces the log message of _<commit>_
 without making any other changes.
 +
 Neither "fixup!" nor "amend!" commits change authorship of
-`<commit>` when applied by `git rebase --autosquash`.
+_<commit>_ when applied by `git rebase --autosquash`.
 See linkgit:git-rebase[1] for details.
 
---squash=<commit>::
-	Construct a commit message for use with `rebase --autosquash`.
-	The commit message subject line is taken from the specified
+`--squash=<commit>`::
+	Construct a commit message for use with `git rebase --autosquash`.
+	The commit message title is taken from the specified
 	commit with a prefix of "squash! ".  Can be used with additional
 	commit message options (`-m`/`-c`/`-C`/`-F`). See
 	linkgit:git-rebase[1] for details.
 
---reset-author::
-	When used with -C/-c/--amend options, or when committing after a
+`--reset-author`::
+	When used with `-C`/`-c`/`--amend` options, or when committing after a
 	conflicting cherry-pick, declare that the authorship of the
 	resulting commit now belongs to the committer. This also renews
 	the author timestamp.
 
---short::
+`--short`::
 	When doing a dry-run, give the output in the short-format. See
 	linkgit:git-status[1] for details. Implies `--dry-run`.
 
---branch::
+`--branch`::
 	Show the branch and tracking info even in short-format.
 
---porcelain::
+`--porcelain`::
 	When doing a dry-run, give the output in a porcelain-ready
 	format. See linkgit:git-status[1] for details. Implies
 	`--dry-run`.
 
---long::
+`--long`::
 	When doing a dry-run, give the output in the long-format.
 	Implies `--dry-run`.
 
--z::
---null::
+`-z`::
+`--null`::
 	When showing `short` or `porcelain` status output, print the
-	filename verbatim and terminate the entries with NUL, instead of LF.
+	filename verbatim and terminate the entries with _NUL_, instead of _LF_.
 	If no format is given, implies the `--porcelain` output format.
 	Without the `-z` option, filenames with "unusual" characters are
 	quoted as explained for the configuration variable `core.quotePath`
 	(see linkgit:git-config[1]).
 
--F <file>::
---file=<file>::
-	Take the commit message from the given file.  Use '-' to
+`-F <file>`::
+`--file=<file>`::
+	Take the commit message from _<file>_.  Use '-' to
 	read the message from the standard input.
 
---author=<author>::
+`--author=<author>`::
 	Override the commit author. Specify an explicit author using the
-	standard `A U Thor <author@example.com>` format. Otherwise <author>
+	standard `A U Thor <author@example.com>` format. Otherwise _<author>_
 	is assumed to be a pattern and is used to search for an existing
-	commit by that author (i.e. rev-list --all -i --author=<author>);
+	commit by that author (i.e. `git rev-list --all -i --author=<author>`);
 	the commit author is then copied from the first such commit found.
 
---date=<date>::
+`--date=<date>`::
 	Override the author date used in the commit.
 
--m <msg>::
---message=<msg>::
-	Use the given <msg> as the commit message.
+`-m <msg>`::
+`--message=<msg>`::
+	Use _<msg>_ as the commit message.
 	If multiple `-m` options are given, their values are
 	concatenated as separate paragraphs.
 +
 The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`.
 
--t <file>::
---template=<file>::
+`-t <file>`::
+`--template=<file>`::
 	When editing the commit message, start the editor with the
-	contents in the given file.  The `commit.template` configuration
+	contents in _<file>_.  The `commit.template` configuration
 	variable is often used to give this option implicitly to the
 	command.  This mechanism can be used by projects that want to
 	guide participants with some hints on what to write in the message
@@ -198,58 +200,57 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`.
 	message, the commit is aborted.  This has no effect when a message
 	is given by other means, e.g. with the `-m` or `-F` options.
 
-include::signoff-option.txt[]
+include::signoff-option.adoc[]
 
---trailer <token>[(=|:)<value>]::
-	Specify a (<token>, <value>) pair that should be applied as a
+`--trailer <token>[(=|:)<value>]`::
+	Specify a (_<token>_, _<value>_) pair that should be applied as a
 	trailer. (e.g. `git commit --trailer "Signed-off-by:C O Mitter \
 	<committer@example.com>" --trailer "Helped-by:C O Mitter \
-	<committer@example.com>"` will add the "Signed-off-by" trailer
-	and the "Helped-by" trailer to the commit message.)
+	<committer@example.com>"` will add the `Signed-off-by` trailer
+	and the `Helped-by` trailer to the commit message.)
 	The `trailer.*` configuration variables
 	(linkgit:git-interpret-trailers[1]) can be used to define if
 	a duplicated trailer is omitted, where in the run of trailers
 	each trailer would appear, and other details.
 
--n::
---[no-]verify::
-	By default, the pre-commit and commit-msg hooks are run.
-	When any of `--no-verify` or `-n` is given, these are bypassed.
+`-n`::
+`--verify`::
+`--no-verify`::
+	Bypass the `pre-commit` and `commit-msg` hooks.
 	See also linkgit:githooks[5].
 
---allow-empty::
+`--allow-empty`::
 	Usually recording a commit that has the exact same tree as its
 	sole parent commit is a mistake, and the command prevents you
 	from making such a commit.  This option bypasses the safety, and
 	is primarily for use by foreign SCM interface scripts.
 
---allow-empty-message::
-       Like --allow-empty this command is primarily for use by foreign
-       SCM interface scripts. It allows you to create a commit with an
-       empty commit message without using plumbing commands like
-       linkgit:git-commit-tree[1].
+`--allow-empty-message`::
+	Create a commit with an empty commit message without using plumbing
+	commands like linkgit:git-commit-tree[1]. Like `--allow-empty`, this
+	command is primarily for use by foreign SCM interface scripts.
 
---cleanup=<mode>::
-	This option determines how the supplied commit message should be
+`--cleanup=<mode>`::
+	Determine how the supplied commit message should be
 	cleaned up before committing.  The '<mode>' can be `strip`,
 	`whitespace`, `verbatim`, `scissors` or `default`.
 +
 --
-strip::
+`strip`::
 	Strip leading and trailing empty lines, trailing whitespace,
 	commentary and collapse consecutive empty lines.
-whitespace::
+`whitespace`::
 	Same as `strip` except #commentary is not removed.
-verbatim::
+`verbatim`::
 	Do not change the message at all.
-scissors::
+`scissors`::
 	Same as `whitespace` except that everything from (and including)
 	the line found below is truncated, if the message is to be edited.
-	"`#`" can be customized with core.commentChar.
+	"`#`" can be customized with `core.commentChar`.
 
 		# ------------------------ >8 ------------------------
 
-default::
+`default`::
 	Same as `strip` if the message is to be edited.
 	Otherwise `whitespace`.
 --
@@ -257,19 +258,18 @@ default::
 The default can be changed by the `commit.cleanup` configuration
 variable (see linkgit:git-config[1]).
 
--e::
---edit::
-	The message taken from file with `-F`, command line with
-	`-m`, and from commit object with `-C` are usually used as
-	the commit log message unmodified. This option lets you
-	further edit the message taken from these sources.
+`-e`::
+`--edit`::
+	Let the user further edit the message taken from _<file>_
+	with `-F <file>`, command line with `-m <message>`, and
+	from _<commit>_ with `-C <commit>`.
 
---no-edit::
+`--no-edit`::
 	Use the selected commit message without launching an editor.
 	For example, `git commit --amend --no-edit` amends a commit
 	without changing its commit message.
 
---amend::
+`--amend`::
 	Replace the tip of the current branch by creating a new
 	commit. The recorded tree is prepared as usual (including
 	the effect of the `-i` and `-o` options and explicit
@@ -282,6 +282,7 @@ variable (see linkgit:git-config[1]).
 +
 --
 It is a rough equivalent for:
+
 ------
 	$ git reset --soft HEAD^
 	$ ... do something else to come up with the right tree ...
@@ -295,23 +296,23 @@ You should understand the implications of rewriting history if you
 amend a commit that has already been published.  (See the "RECOVERING
 FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 
---no-post-rewrite::
-	Bypass the post-rewrite hook.
+`--no-post-rewrite`::
+	Bypass the `post-rewrite` hook.
 
--i::
---include::
+`-i`::
+`--include`::
 	Before making a commit out of staged contents so far,
 	stage the contents of paths given on the command line
 	as well.  This is usually not what you want unless you
 	are concluding a conflicted merge.
 
--o::
---only::
+`-o`::
+`--only`::
 	Make a commit by taking the updated working tree contents
 	of the paths specified on the
 	command line, disregarding any contents that have been
 	staged for other paths. This is the default mode of operation of
-	'git commit' if any paths are given on the command line,
+	`git commit` if any paths are given on the command line,
 	in which case this option can be omitted.
 	If this option is specified together with `--amend`, then
 	no paths need to be specified, which can be used to amend
@@ -319,48 +320,48 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 	already been staged. If used together with `--allow-empty`
 	paths are also not required, and an empty commit will be created.
 
---pathspec-from-file=<file>::
-	Pathspec is passed in `<file>` instead of commandline args. If
-	`<file>` is exactly `-` then standard input is used. Pathspec
-	elements are separated by LF or CR/LF. Pathspec elements can be
+`--pathspec-from-file=<file>`::
+	Pass pathspec in _<file>_ instead of commandline args. If
+	_<file>_ is exactly `-` then standard input is used. Pathspec
+	elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
 	quoted as explained for the configuration variable `core.quotePath`
 	(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
 	global `--literal-pathspecs`.
 
---pathspec-file-nul::
+`--pathspec-file-nul`::
 	Only meaningful with `--pathspec-from-file`. Pathspec elements are
-	separated with NUL character and all other characters are taken
+	separated with _NUL_ character and all other characters are taken
 	literally (including newlines and quotes).
 
--u[<mode>]::
---untracked-files[=<mode>]::
+`-u[<mode>]`::
+`--untracked-files[=<mode>]`::
 	Show untracked files.
 +
 --
-The mode parameter is optional (defaults to 'all'), and is used to
-specify the handling of untracked files; when -u is not used, the
-default is 'normal', i.e. show untracked files and directories.
+The _<mode>_ parameter is optional (defaults to `all`), and is used to
+specify the handling of untracked files; when `-u` is not used, the
+default is `normal`, i.e. show untracked files and directories.
 
 The possible options are:
 
-	- 'no'     - Show no untracked files
-	- 'normal' - Shows untracked files and directories
-	- 'all'    - Also shows individual files in untracked directories.
+`no`:: Show no untracked files
+`normal`:: Shows untracked files and directories
+`all`:: Also shows individual files in untracked directories.
 
 All usual spellings for Boolean value `true` are taken as `normal`
 and `false` as `no`.
-The default can be changed using the status.showUntrackedFiles
+The default can be changed using the `status.showUntrackedFiles`
 configuration variable documented in linkgit:git-config[1].
 --
 
--v::
---verbose::
-	Show unified diff between the HEAD commit and what
+`-v`::
+`--verbose`::
+	Show unified diff between the `HEAD` commit and what
 	would be committed at the bottom of the commit message
 	template to help the user describe the commit by reminding
 	what changes the commit has.
 	Note that this diff output doesn't have its
-	lines prefixed with '#'. This diff will not be a part
+	lines prefixed with `#`. This diff will not be a part
 	of the commit message. See the `commit.verbose` configuration
 	variable in linkgit:git-config[1].
 +
@@ -368,40 +369,40 @@ If specified twice, show in addition the unified diff between
 what would be committed and the worktree files, i.e. the unstaged
 changes to tracked files.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Suppress commit summary message.
 
---dry-run::
+`--dry-run`::
 	Do not create a commit, but show a list of paths that are
 	to be committed, paths with local changes that will be left
 	uncommitted and paths that are untracked.
 
---status::
+`--status`::
 	Include the output of linkgit:git-status[1] in the commit
 	message template when using an editor to prepare the commit
 	message.  Defaults to on, but can be used to override
-	configuration variable commit.status.
+	configuration variable `commit.status`.
 
---no-status::
+`--no-status`::
 	Do not include the output of linkgit:git-status[1] in the
 	commit message template when using an editor to prepare the
 	default commit message.
 
--S[<keyid>]::
---gpg-sign[=<keyid>]::
---no-gpg-sign::
-	GPG-sign commits. The `keyid` argument is optional and
+`-S[<key-id>]`::
+`--gpg-sign[=<key-id>]`::
+`--no-gpg-sign`::
+	GPG-sign commits. The _<key-id>_ is optional and
 	defaults to the committer identity; if specified, it must be
 	stuck to the option without a space. `--no-gpg-sign` is useful to
 	countermand both `commit.gpgSign` configuration variable, and
 	earlier `--gpg-sign`.
 
-\--::
+`--`::
 	Do not interpret any more arguments as options.
 
-<pathspec>...::
-	When pathspec is given on the command line, commit the contents of
+`<pathspec>...`::
+	When _<pathspec>_ is given on the command line, commit the contents of
 	the files that match the pathspec without recording the changes
 	already added to the index. The contents of these files are also
 	staged for the next commit on top of what have been staged before.
@@ -412,10 +413,10 @@ EXAMPLES
 --------
 When recording your own work, the contents of modified files in
 your working tree are temporarily stored to a staging area
-called the "index" with 'git add'.  A file can be
+called the "index" with `git add`.  A file can be
 reverted back, only in the index but not in the working tree,
 to that of the last commit with `git restore --staged <file>`,
-which effectively reverts 'git add' and prevents the changes to
+which effectively reverts `git add` and prevents the changes to
 this file from participating in the next commit.  After building
 the state to be committed incrementally with these commands,
 `git commit` (without any pathname parameter) is used to record what
@@ -443,7 +444,7 @@ $ git commit -a
 ------------
 
 The command `git commit -a` first looks at your working tree,
-notices that you have modified hello.c and removed goodbye.c,
+notices that you have modified `hello.c` and removed `goodbye.c`,
 and performs necessary `git add` and `git rm` for you.
 
 After staging changes to many files, you can alter the order the
@@ -471,13 +472,13 @@ $ git commit
 this second commit would record the changes to `hello.c` and
 `hello.h` as expected.
 
-After a merge (initiated by 'git merge' or 'git pull') stops
+After a merge (initiated by `git merge` or `git pull`) stops
 because of conflicts, cleanly merged
 paths are already staged to be committed for you, and paths that
 conflicted are left in unmerged state.  You would have to first
-check which paths are conflicting with 'git status'
+check which paths are conflicting with `git status`
 and after fixing them manually in your working tree, you would
-stage the result as usual with 'git add':
+stage the result as usual with `git add`:
 
 ------------
 $ git status | grep unmerged
@@ -507,12 +508,12 @@ COMMIT INFORMATION
 Author and committer information is taken from the following environment
 variables, if set:
 
-	GIT_AUTHOR_NAME
-	GIT_AUTHOR_EMAIL
-	GIT_AUTHOR_DATE
-	GIT_COMMITTER_NAME
-	GIT_COMMITTER_EMAIL
-	GIT_COMMITTER_DATE
+ * `GIT_AUTHOR_NAME`
+ * `GIT_AUTHOR_EMAIL`
+ * `GIT_AUTHOR_DATE`
+ * `GIT_COMMITTER_NAME`
+ * `GIT_COMMITTER_EMAIL`
+ * `GIT_COMMITTER_DATE`
 
 (nb "<", ">" and "\n"s are stripped)
 
@@ -524,7 +525,7 @@ that, see the `credential.username` variable in linkgit:git-config[1].
 
 In case (some of) these environment variables are not set, the information
 is taken from the configuration items `user.name` and `user.email`, or, if not
-present, the environment variable EMAIL, or, if that is not set,
+present, the environment variable `EMAIL`, or, if that is not set,
 system user name and the hostname used for outgoing mail (taken
 from `/etc/mailname` and falling back to the fully qualified hostname when
 that file does not exist).
@@ -537,7 +538,7 @@ The typical usage is to set just the `user.name` and `user.email` variables;
 the other options are provided for more complex use cases.
 
 :git-commit: 1
-include::date-formats.txt[]
+include::date-formats.adoc[]
 
 DISCUSSION
 ----------
@@ -550,18 +551,18 @@ as the commit title, and that title is used throughout Git.
 For example, linkgit:git-format-patch[1] turns a commit into email, and it uses
 the title on the Subject line and the rest of the commit in the body.
 
-include::i18n.txt[]
+include::i18n.adoc[]
 
 ENVIRONMENT AND CONFIGURATION VARIABLES
 ---------------------------------------
 The editor used to edit the commit log message will be chosen from the
-`GIT_EDITOR` environment variable, the core.editor configuration variable, the
+`GIT_EDITOR` environment variable, the `core.editor` configuration variable, the
 `VISUAL` environment variable, or the `EDITOR` environment variable (in that
 order).  See linkgit:git-var[1] for details.
 
-include::includes/cmd-config-section-rest.txt[]
+include::includes/cmd-config-section-rest.adoc[]
 
-include::config/commit.txt[]
+include::config/commit.adoc[]
 
 HOOKS
 -----
diff --git a/Documentation/git-config.txt b/Documentation/git-config.adoc
index 3e420177c1..cc054fa7e1 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.adoc
@@ -10,9 +10,9 @@ SYNOPSIS
 --------
 [verse]
 'git config list' [<file-option>] [<display-option>] [--includes]
-'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name>
-'git config set' [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>
-'git config unset' [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>
+'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>
+'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
+'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
 'git config rename-section' [<file-option>] <old-name> <new-name>
 'git config remove-section' [<file-option>] <name>
 'git config edit' [<file-option>]
@@ -26,7 +26,7 @@ escaped.
 
 Multiple lines can be added to an option by using the `--append` option.
 If you want to update or unset an option which can occur on multiple
-lines, a `value-pattern` (which is an extended regular expression,
+lines, `--value=<pattern>` (which is an extended regular expression,
 unless the `--fixed-value` option is given) needs to be given.  Only the
 existing values that match the pattern are updated or unset.  If
 you want to handle the lines that do *not* match the pattern, just
@@ -109,7 +109,7 @@ OPTIONS
 
 --replace-all::
 	Default behavior is to replace at most one line. This replaces
-	all lines matching the key (and optionally the `value-pattern`).
+	all lines matching the key (and optionally `--value=<pattern>`).
 
 --append::
 	Adds a new line to the option without altering any existing
@@ -117,15 +117,15 @@ OPTIONS
 
 --comment <message>::
 	Append a comment at the end of new or modified lines.
-
-	If _<message>_ begins with one or more whitespaces followed
-	by "#", it is used as-is.  If it begins with "#", a space is
-	prepended before it is used.  Otherwise, a string " # " (a
-	space followed by a hash followed by a space) is prepended
-	to it.  And the resulting string is placed immediately after
-	the value defined for the variable.  The _<message>_ must
-	not contain linefeed characters (no multi-line comments are
-	permitted).
++
+If _<message>_ begins with one or more whitespaces followed
+by "#", it is used as-is.  If it begins with "#", a space is
+prepended before it is used.  Otherwise, a string " # " (a
+space followed by a hash followed by a space) is prepended
+to it.  And the resulting string is placed immediately after
+the value defined for the variable.  The _<message>_ must
+not contain linefeed characters (no multi-line comments are
+permitted).
 
 --all::
 	With `get`, return all values for a multi-valued key.
@@ -200,11 +200,19 @@ See also <<FILES>>.
 	section in linkgit:gitrevisions[7] for a more complete list of
 	ways to spell blob names.
 
+`--value=<pattern>`::
+`--no-value`::
+	With `get`, `set`, and `unset`, match only against
+	_<pattern>_. The pattern is an extended regular expression unless
+	`--fixed-value` is given.
++
+Use `--no-value` to unset _<pattern>_.
+
 --fixed-value::
-	When used with the `value-pattern` argument, treat `value-pattern` as
+	When used with `--value=<pattern>`, treat _<pattern>_ as
 	an exact string instead of a regular expression. This will restrict
 	the name/value pairs that are matched to only those where the value
-	is exactly equal to the `value-pattern`.
+	is exactly equal to _<pattern>_.
 
 --type <type>::
   'git config' will ensure that any input or output is valid under the given
@@ -213,7 +221,9 @@ See also <<FILES>>.
 +
 Valid `<type>`'s include:
 +
-- 'bool': canonicalize values as either "true" or "false".
+- 'bool': canonicalize values `true`, `yes`,`on`, and positive
+  numbers as "true", and values `false`, `no`, `off` and `0` as
+  "false".
 - 'int': canonicalize values as simple decimal numbers. An optional suffix of
   'k', 'm', or 'g' will cause the value to be multiplied by 1024, 1048576, or
   1073741824 upon input.
@@ -257,6 +267,12 @@ Valid `<type>`'s include:
 	Output only the names of config variables for `list` or
 	`get`.
 
+`--show-names`::
+`--no-show-names`::
+	With `get`, show config keys in addition to their values. The
+	default is `--no-show-names` unless `--url` is given and there
+	are no subsections in _<name>_.
+
 --show-origin::
 	Augment the output of all queried config options with the
 	origin type (file, standard input, blob, command line) and
@@ -279,7 +295,8 @@ Valid `<type>`'s include:
 	When the color setting for `name` is undefined, the command uses
 	`color.ui` as fallback.
 
---[no-]includes::
+--includes::
+--no-includes::
 	Respect `include.*` directives in config files when looking up
 	values. Defaults to `off` when a specific file is given (e.g.,
 	using `--file`, `--global`, etc) and `on` when searching all
@@ -610,7 +627,7 @@ http.cookieFile /tmp/cookie.txt
 http.sslverify false
 ------------
 
-include::config.txt[]
+include::config.adoc[]
 
 BUGS
 ----
diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.adoc
index 97f9f12610..eeee6b9f7f 100644
--- a/Documentation/git-count-objects.txt
+++ b/Documentation/git-count-objects.adoc
@@ -28,6 +28,8 @@ size: disk space consumed by loose objects, in KiB (unless -H is specified)
 +
 in-pack: the number of in-pack objects
 +
+packs: the number of pack files
++
 size-pack: disk space consumed by the packs, in KiB (unless -H is specified)
 +
 prune-packable: the number of loose objects that are also present in
diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.adoc
index 650a15a7ed..650a15a7ed 100644
--- a/Documentation/git-credential-cache--daemon.txt
+++ b/Documentation/git-credential-cache--daemon.adoc
diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.adoc
index 487cc557a8..54fa7a27e1 100644
--- a/Documentation/git-credential-cache.txt
+++ b/Documentation/git-credential-cache.adoc
@@ -78,6 +78,23 @@ variable (this example increases the cache time to 1 hour):
 $ git config credential.helper 'cache --timeout=3600'
 -------------------------------------------------------
 
+PERSONAL ACCESS TOKENS
+----------------------
+
+Some remotes accept personal access tokens, which are randomly
+generated and hard to memorise. They typically have a lifetime of weeks
+or months.
+
+git-credential-cache is inherently unsuitable for persistent storage of
+personal access tokens. The credential will be forgotten after the cache
+timeout. Even if you configure a long timeout, credentials will be
+forgotten if the daemon dies.
+
+To avoid frequently regenerating personal access tokens, configure a
+credential helper with persistent storage. Alternatively, configure an
+OAuth credential helper to generate credentials automatically. See
+linkgit:gitcredentials[7], sections "Available helpers" and "OAuth".
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.adoc
index 71864a8726..71864a8726 100644
--- a/Documentation/git-credential-store.txt
+++ b/Documentation/git-credential-store.adoc
diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.adoc
index e41493292f..e41493292f 100644
--- a/Documentation/git-credential.txt
+++ b/Documentation/git-credential.adoc
diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.adoc
index 41c8a8a05c..41c8a8a05c 100644
--- a/Documentation/git-cvsexportcommit.txt
+++ b/Documentation/git-cvsexportcommit.adoc
diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.adoc
index 90fdc2551a..90fdc2551a 100644
--- a/Documentation/git-cvsimport.txt
+++ b/Documentation/git-cvsimport.adoc
diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.adoc
index 4c475efeab..fe822f571d 100644
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.adoc
@@ -125,9 +125,11 @@ creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or
 pwhash in NetBSD) and paste it in the right location.
 
 Then provide your password via the pserver method, for example:
+
 ------
    cvs -d:pserver:someuser:somepassword@server:/path/repo.git co <HEAD_name>
 ------
+
 No special setup is needed for SSH access, other than having Git tools
 in the PATH. If you have clients that do not accept the CVS_SERVER
 environment variable, you can rename 'git-cvsserver' to `cvs`.
@@ -138,6 +140,7 @@ CVS_SERVER directly in CVSROOT like
 ------
    cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name>
 ------
+
 This has the advantage that it will be saved in your 'CVS/Root' files and
 you don't need to worry about always setting the correct environment
 variable.  SSH users restricted to 'git-shell' don't need to override the default
@@ -168,6 +171,7 @@ All configuration variables can also be overridden for a specific method of
 access. Valid method names are "ext" (for SSH access) and "pserver". The
 following example configuration would disable pserver access while still
 allowing access over SSH.
+
 ------
    [gitcvs]
         enabled=0
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.adoc
index ede7b935d6..99389f0388 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.adoc
@@ -7,21 +7,21 @@ git-daemon - A really simple server for Git repositories
 
 SYNOPSIS
 --------
-[verse]
-'git daemon' [--verbose] [--syslog] [--export-all]
-	     [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
-	     [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
-	     [--user-path | --user-path=<path>]
-	     [--interpolated-path=<pathtemplate>]
-	     [--reuseaddr] [--detach] [--pid-file=<file>]
-	     [--enable=<service>] [--disable=<service>]
-	     [--allow-override=<service>] [--forbid-override=<service>]
-	     [--access-hook=<path>] [--[no-]informative-errors]
-	     [--inetd |
-	      [--listen=<host-or-ipaddr>] [--port=<n>]
-	      [--user=<user> [--group=<group>]]]
-	     [--log-destination=(stderr|syslog|none)]
-	     [<directory>...]
+[synopsis]
+git daemon [--verbose] [--syslog] [--export-all]
+	   [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
+	   [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
+	   [--user-path | --user-path=<path>]
+	   [--interpolated-path=<pathtemplate>]
+	   [--reuseaddr] [--detach] [--pid-file=<file>]
+	   [--enable=<service>] [--disable=<service>]
+	   [--allow-override=<service>] [--forbid-override=<service>]
+	   [--access-hook=<path>] [--[no-]informative-errors]
+	   [--inetd |
+	     [--listen=<host-or-ipaddr>] [--port=<n>]
+	     [--user=<user> [--group=<group>]]]
+	   [--log-destination=(stderr|syslog|none)]
+	   [<directory>...]
 
 DESCRIPTION
 -----------
@@ -32,111 +32,111 @@ that service if it is enabled.
 It verifies that the directory has the magic file "git-daemon-export-ok", and
 it will refuse to export any Git directory that hasn't explicitly been marked
 for export this way (unless the `--export-all` parameter is specified). If you
-pass some directory paths as 'git daemon' arguments, the offers are limited to
+pass some directory paths as `git daemon` arguments, the offers are limited to
 repositories within those directories.
 
 By default, only `upload-pack` service is enabled, which serves
-'git fetch-pack' and 'git ls-remote' clients, which are invoked
-from 'git fetch', 'git pull', and 'git clone'.
+`git fetch-pack` and `git ls-remote` clients, which are invoked
+from `git fetch`, `git pull`, and `git clone`.
 
 This is ideally suited for read-only updates, i.e., pulling from
 Git repositories.
 
-An `upload-archive` also exists to serve 'git archive'.
+An `upload-archive` also exists to serve `git archive`.
 
 OPTIONS
 -------
---strict-paths::
+`--strict-paths`::
 	Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
 	"/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
-	'git daemon' will refuse to start when this option is enabled and no
+	`git daemon` will refuse to start when this option is enabled and no
 	directory arguments are provided.
 
---base-path=<path>::
+`--base-path=<path>`::
 	Remap all the path requests as relative to the given path.
-	This is sort of "Git root" - if you run 'git daemon' with
-	'--base-path=/srv/git' on example.com, then if you later try to pull
-	'git://example.com/hello.git', 'git daemon' will interpret the path
-	as `/srv/git/hello.git`.
-
---base-path-relaxed::
-	If --base-path is enabled and repo lookup fails, with this option
-	'git daemon' will attempt to lookup without prefixing the base path.
-	This is useful for switching to --base-path usage, while still
+	This is sort of "Git root" - if you run `git daemon` with
+	`--base-path=/srv/git` on `example.com`, then if you later try
+	to pull from `git://example.com/hello.git`, `git daemon` will
+	interpret the path as `/srv/git/hello.git`.
+
+`--base-path-relaxed`::
+	If `--base-path` is enabled and repo lookup fails, with this option
+	`git daemon` will attempt to lookup without prefixing the base path.
+	This is useful for switching to `--base-path` usage, while still
 	allowing the old paths.
 
---interpolated-path=<pathtemplate>::
+`--interpolated-path=<pathtemplate>`::
 	To support virtual hosting, an interpolated path template can be
 	used to dynamically construct alternate paths.  The template
-	supports %H for the target hostname as supplied by the client but
-	converted to all lowercase, %CH for the canonical hostname,
-	%IP for the server's IP address, %P for the port number,
-	and %D for the absolute path of the named repository.
+	supports `%H` for the target hostname as supplied by the client but
+	converted to all lowercase, `%CH` for the canonical hostname,
+	`%IP` for the server's IP address, `%P` for the port number,
+	and `%D` for the absolute path of the named repository.
 	After interpolation, the path is validated against the directory
 	list.
 
---export-all::
+`--export-all`::
 	Allow pulling from all directories that look like Git repositories
 	(have the 'objects' and 'refs' subdirectories), even if they
-	do not have the 'git-daemon-export-ok' file.
+	do not have the `git-daemon-export-ok` file.
 
---inetd::
-	Have the server run as an inetd service. Implies --syslog (may be
-	overridden with `--log-destination=`).
-	Incompatible with --detach, --port, --listen, --user and --group
-	options.
+`--inetd`::
+	Have the server run as an inetd service. Implies `--syslog` (may
+	be overridden with `--log-destination=`).
+	Incompatible with `--detach`, `--port`, `--listen`, `--user` and
+	`--group` options.
 
---listen=<host-or-ipaddr>::
+`--listen=<host-or-ipaddr>`::
 	Listen on a specific IP address or hostname.  IP addresses can
 	be either an IPv4 address or an IPv6 address if supported.  If IPv6
-	is not supported, then --listen=<hostname> is also not supported and
-	--listen must be given an IPv4 address.
+	is not supported, then `--listen=<hostname>` is also not supported
+	and `--listen` must be given an IPv4 address.
 	Can be given more than once.
 	Incompatible with `--inetd` option.
 
---port=<n>::
+`--port=<n>`::
 	Listen on an alternative port.  Incompatible with `--inetd` option.
 
---init-timeout=<n>::
+`--init-timeout=<n>`::
 	Timeout (in seconds) between the moment the connection is established
 	and the client request is received (typically a rather low value, since
 	that should be basically immediate).
 
---timeout=<n>::
+`--timeout=<n>`::
 	Timeout (in seconds) for specific client sub-requests. This includes
 	the time it takes for the server to process the sub-request and the
 	time spent waiting for the next client's request.
 
---max-connections=<n>::
+`--max-connections=<n>`::
 	Maximum number of concurrent clients, defaults to 32.  Set it to
 	zero for no limit.
 
---syslog::
+`--syslog`::
 	Short for `--log-destination=syslog`.
 
---log-destination=<destination>::
+`--log-destination=<destination>`::
 	Send log messages to the specified destination.
-	Note that this option does not imply --verbose,
+	Note that this option does not imply `--verbose`,
 	thus by default only error conditions will be logged.
-	The <destination> must be one of:
+	The _<destination>_ must be one of:
 +
 --
-stderr::
+`stderr`::
 	Write to standard error.
 	Note that if `--detach` is specified,
 	the process disconnects from the real standard error,
 	making this destination effectively equivalent to `none`.
-syslog::
+`syslog`::
 	Write to syslog, using the `git-daemon` identifier.
-none::
+`none`::
 	Disable all logging.
 --
 +
 The default destination is `syslog` if `--inetd` or `--detach` is specified,
 otherwise `stderr`.
 
---user-path::
---user-path=<path>::
+`--user-path`::
+`--user-path=<path>`::
 	Allow {tilde}user notation to be used in requests.  When
 	specified with no parameter, a request to
 	git://host/{tilde}alice/foo is taken as a request to access
@@ -145,23 +145,23 @@ otherwise `stderr`.
 	taken as a request to access `<path>/foo` repository in
 	the home directory of user `alice`.
 
---verbose::
+`--verbose`::
 	Log details about the incoming connections and requested files.
 
---reuseaddr::
-	Use SO_REUSEADDR when binding the listening socket.
+`--reuseaddr`::
+	Use `SO_REUSEADDR` when binding the listening socket.
 	This allows the server to restart without waiting for
 	old connections to time out.
 
---detach::
-	Detach from the shell. Implies --syslog.
+`--detach`::
+	Detach from the shell. Implies `--syslog`.
 
---pid-file=<file>::
-	Save the process id in 'file'.  Ignored when the daemon
+`--pid-file=<file>`::
+	Save the process id in _<file>_.  Ignored when the daemon
 	is run under `--inetd`.
 
---user=<user>::
---group=<group>::
+`--user=<user>`::
+`--group=<group>`::
 	Change daemon's uid and gid before entering the service loop.
 	When only `--user` is given without `--group`, the
 	primary group ID for the user is used.  The values of
@@ -170,43 +170,44 @@ otherwise `stderr`.
 +
 Giving these options is an error when used with `--inetd`; use
 the facility of inet daemon to achieve the same before spawning
-'git daemon' if needed.
+`git daemon` if needed.
 +
 Like many programs that switch user id, the daemon does not reset
-environment variables such as `$HOME` when it runs git programs,
+environment variables such as `HOME` when it runs git programs,
 e.g. `upload-pack` and `receive-pack`. When using this option, you
 may also want to set and export `HOME` to point at the home
-directory of `<user>` before starting the daemon, and make sure any
-Git configuration files in that directory are readable by `<user>`.
+directory of _<user>_ before starting the daemon, and make sure any
+Git configuration files in that directory are readable by _<user>_.
 
---enable=<service>::
---disable=<service>::
+`--enable=<service>`::
+`--disable=<service>`::
 	Enable/disable the service site-wide per default.  Note
 	that a service disabled site-wide can still be enabled
 	per repository if it is marked overridable and the
 	repository enables the service with a configuration
 	item.
 
---allow-override=<service>::
---forbid-override=<service>::
+`--allow-override=<service>`::
+`--forbid-override=<service>`::
 	Allow/forbid overriding the site-wide default with per
 	repository configuration.  By default, all the services
 	may be overridden.
 
---[no-]informative-errors::
+`--informative-errors`::
+`--no-informative-errors`::
 	When informative errors are turned on, git-daemon will report
 	more verbose errors to the client, differentiating conditions
 	like "no such repository" from "repository not exported". This
 	is more convenient for clients, but may leak information about
 	the existence of unexported repositories.  When informative
 	errors are not enabled, all errors report "access denied" to the
-	client. The default is --no-informative-errors.
+	client. The default is `--no-informative-errors`.
 
---access-hook=<path>::
+`--access-hook=<path>`::
 	Every time a client connects, first run an external command
 	specified by the <path> with service name (e.g. "upload-pack"),
-	path to the repository, hostname (%H), canonical hostname
-	(%CH), IP address (%IP), and TCP port (%P) as its command-line
+	path to the repository, hostname (`%H`), canonical hostname
+	(`%CH`), IP address (`%IP`), and TCP port (`%P`) as its command-line
 	arguments. The external command can decide to decline the
 	service by exiting with a non-zero status (or to allow it by
 	exiting with a zero status).  It can also look at the $REMOTE_ADDR
@@ -217,7 +218,7 @@ The external command can optionally write a single line to its
 standard output to be sent to the requestor as an error message when
 it declines the service.
 
-<directory>::
+_<directory>_::
 	The remaining arguments provide a list of directories. If any
 	directories are specified, then the `git-daemon` process will
 	serve a requested directory only if it is contained in one of
@@ -229,24 +230,24 @@ SERVICES
 
 These services can be globally enabled/disabled using the
 command-line options of this command.  If finer-grained
-control is desired (e.g. to allow 'git archive' to be run
+control is desired (e.g. to allow `git archive` to be run
 against only in a few selected repositories the daemon serves),
 the per-repository configuration file can be used to enable or
 disable them.
 
 upload-pack::
-	This serves 'git fetch-pack' and 'git ls-remote'
+	This serves `git fetch-pack` and `git ls-remote`
 	clients.  It is enabled by default, but a repository can
 	disable it by setting `daemon.uploadpack` configuration
 	item to `false`.
 
 upload-archive::
-	This serves 'git archive --remote'.  It is disabled by
+	This serves `git archive --remote`.  It is disabled by
 	default, but a repository can enable it by setting
 	`daemon.uploadarch` configuration item to `true`.
 
 receive-pack::
-	This serves 'git send-pack' clients, allowing anonymous
+	This serves `git send-pack` clients, allowing anonymous
 	push.  It is disabled by default, as there is _no_
 	authentication in the protocol (in other words, anybody
 	can push anything into the repository, including removal
@@ -300,7 +301,7 @@ default repository could be made as well.
 
 
 'git daemon' as regular daemon for virtual hosts::
-	To set up 'git daemon' as a regular, non-inetd service that
+	To set up `git daemon` as a regular, non-inetd service that
 	handles repositories for multiple virtual hosts based on
 	their IP addresses, start the daemon like this:
 +
@@ -317,7 +318,7 @@ Repositories can still be accessed by hostname though, assuming
 they correspond to these IP addresses.
 
 selectively enable/disable services per repository::
-	To enable 'git archive --remote' and disable 'git fetch' against
+	To enable `git archive --remote` and disable `git fetch` against
 	a repository, have the following in the configuration file in the
 	repository (that is the file 'config' next to `HEAD`, 'refs' and
 	'objects').
@@ -331,8 +332,8 @@ selectively enable/disable services per repository::
 
 ENVIRONMENT
 -----------
-'git daemon' will set REMOTE_ADDR to the IP address of the client
-that connected to it, if the IP address is available. REMOTE_ADDR will
+`git daemon` will set `REMOTE_ADDR` to the IP address of the client
+that connected to it, if the IP address is available. `REMOTE_ADDR` will
 be available in the environment of hooks called when
 services are performed.
 
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.adoc
index 08ff715709..08ff715709 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.adoc
diff --git a/Documentation/git-diagnose.txt b/Documentation/git-diagnose.adoc
index 0711959e6f..0711959e6f 100644
--- a/Documentation/git-diagnose.txt
+++ b/Documentation/git-diagnose.adoc
diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.adoc
index bf78e31431..2b2358ca1c 100644
--- a/Documentation/git-diff-files.txt
+++ b/Documentation/git-diff-files.adoc
@@ -20,7 +20,7 @@ same as for 'git diff-index' and 'git diff-tree'.
 
 OPTIONS
 -------
-include::diff-options.txt[]
+include::diff-options.adoc[]
 
 -1 --base::
 -2 --ours::
@@ -45,7 +45,7 @@ omit diff output for unmerged entries and just show "Unmerged".
 	Remain silent even for nonexistent files
 
 
-include::diff-format.txt[]
+include::diff-format.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.adoc
index 4de1d4c8f1..911446a296 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.adoc
@@ -21,7 +21,7 @@ files are compared.
 
 OPTIONS
 -------
-include::diff-options.txt[]
+include::diff-options.adoc[]
 
 <tree-ish>::
 	The id of a tree object to diff against.
@@ -40,7 +40,7 @@ include::diff-options.txt[]
 	'git diff-index' say that all non-checked-out files are up
 	to date.
 
-include::diff-format.txt[]
+include::diff-format.adoc[]
 
 OPERATING MODES
 ---------------
diff --git a/Documentation/git-diff-pairs.adoc b/Documentation/git-diff-pairs.adoc
new file mode 100644
index 0000000000..f99fcd1ead
--- /dev/null
+++ b/Documentation/git-diff-pairs.adoc
@@ -0,0 +1,60 @@
+git-diff-pairs(1)
+=================
+
+NAME
+----
+git-diff-pairs - Compare the content and mode of provided blob pairs
+
+SYNOPSIS
+--------
+[synopsis]
+git diff-pairs -z [<diff-options>]
+
+DESCRIPTION
+-----------
+Show changes for file pairs provided on stdin. Input for this command must be
+in the NUL-terminated raw output format as generated by commands such as `git
+diff-tree -z -r --raw`. By default, the outputted diffs are computed and shown
+in the patch format when stdin closes.
+
+A single NUL byte may be written to stdin between raw input lines to compute
+file pair diffs up to that point instead of waiting for stdin to close. A NUL
+byte is also written to the output to delimit between these batches of diffs.
+
+Usage of this command enables the traditional diff pipeline to be broken up
+into separate stages where `diff-pairs` acts as the output phase. Other
+commands, such as `diff-tree`, may serve as a frontend to compute the raw
+diff format used as input.
+
+Instead of computing diffs via `git diff-tree -p -M` in one step, `diff-tree`
+can compute the file pairs and rename information without the blob diffs. This
+output can be fed to `diff-pairs` to generate the underlying blob diffs as done
+in the following example:
+
+-----------------------------
+git diff-tree -z -r -M $a $b |
+git diff-pairs -z
+-----------------------------
+
+Computing the tree diff upfront with rename information allows patch output
+from `diff-pairs` to be progressively computed over the course of potentially
+multiple invocations.
+
+Pathspecs are not currently supported by `diff-pairs`. Pathspec limiting should
+be performed by the upstream command generating the raw diffs used as input.
+
+Tree objects are not currently supported as input and are rejected.
+
+Abbreviated object IDs in the `diff-pairs` input are not supported. Outputted
+object IDs can be abbreviated using the `--abbrev` option.
+
+OPTIONS
+-------
+
+include::diff-options.adoc[]
+
+include::diff-generate-patch.adoc[]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.adoc
index 09286a85eb..f1e3134bde 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.adoc
@@ -24,7 +24,7 @@ Note that 'git diff-tree' can use the tree encapsulated in a commit object.
 
 OPTIONS
 -------
-include::diff-options.txt[]
+include::diff-options.adoc[]
 
 <tree-ish>::
 	The id of a tree object.
@@ -84,7 +84,7 @@ commits (but not trees).
 	This flag causes 'git diff-tree --stdin' to also show
 	the commit message before the differences.
 
-include::pretty-options.txt[]
+include::pretty-options.adoc[]
 
 --no-commit-id::
 	'git diff-tree' outputs a line with the commit ID when
@@ -122,9 +122,9 @@ include::pretty-options.txt[]
 	if the diff itself is empty.
 
 
-include::pretty-formats.txt[]
+include::pretty-formats.adoc[]
 
-include::diff-format.txt[]
+include::diff-format.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.adoc
index e19f31e8b9..272331afba 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.adoc
@@ -14,7 +14,7 @@ git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
 git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]
 git diff [<options>] <commit>...<commit> [--] [<path>...]
 git diff [<options>] <blob> <blob>
-git diff [<options>] --no-index [--] <path> <path>
+git diff [<options>] --no-index [--] <path> <path> [<pathspec>...]
 
 DESCRIPTION
 -----------
@@ -31,14 +31,18 @@ files on disk.
 	further add to the index but you still haven't.  You can
 	stage these changes by using linkgit:git-add[1].
 
-`git diff [<options>] --no-index [--] <path> <path>`::
+`git diff [<options>] --no-index [--] <path> <path> [<pathspec>...]`::
 
 	This form is to compare the given two paths on the
 	filesystem.  You can omit the `--no-index` option when
 	running the command in a working tree controlled by Git and
 	at least one of the paths points outside the working tree,
 	or when running the command outside a working tree
-	controlled by Git. This form implies `--exit-code`.
+	controlled by Git. This form implies `--exit-code`. If both
+	paths point to directories, additional pathspecs may be
+	provided. These will limit the files included in the
+	difference. All such pathspecs must be relative as they
+	apply to both sides of the diff.
 
 `git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]`::
 
@@ -123,7 +127,7 @@ do not mean a range as defined in the
 OPTIONS
 -------
 :git-diff: 1
-include::diff-options.txt[]
+include::diff-options.adoc[]
 
 `-1`::
 `--base`::
@@ -154,7 +158,7 @@ section "3-Way Merge" for detailed information.
 	names and get diff for all files under them).
 
 
-include::diff-format.txt[]
+include::diff-format.adoc[]
 
 EXAMPLES
 --------
@@ -232,10 +236,10 @@ $ git diff -R                          <2>
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
 :git-diff: 1
-include::config/diff.txt[]
+include::config/diff.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.adoc
index a616f8b2e6..064bc68347 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.adoc
@@ -77,7 +77,8 @@ with custom merge tool commands and has the same value as `$MERGED`.
 --tool-help::
 	Print a list of diff tools that may be used with `--tool`.
 
---[no-]symlinks::
+--symlinks::
+--no-symlinks::
 	'git difftool''s default behavior is to create symlinks to the
 	working tree when run in `--dir-diff` mode and the right-hand
 	side of the comparison yields the same content as the file in
@@ -94,7 +95,8 @@ instead.  `--no-symlinks` is the default on Windows.
 	Additionally, `$BASE` is set in the environment.
 
 -g::
---[no-]gui::
+--gui::
+--no-gui::
 	When 'git-difftool' is invoked with the `-g` or `--gui` option
 	the default diff tool will be read from the configured
 	`diff.guitool` variable instead of `diff.tool`. This may be
@@ -104,7 +106,8 @@ instead.  `--no-symlinks` is the default on Windows.
 	fallback in the order of `merge.guitool`, `diff.tool`,
 	`merge.tool` until a tool is found.
 
---[no-]trust-exit-code::
+--trust-exit-code::
+--no-trust-exit-code::
 	Errors reported by the diff tool are ignored by default.
 	Use `--trust-exit-code` to make 'git-difftool' exit when an
 	invoked diff tool returns a non-zero exit code.
@@ -119,9 +122,9 @@ CONFIGURATION
 'git difftool' falls back to 'git mergetool' config variables when the
 difftool equivalents have not been defined.
 
-include::includes/cmd-config-section-rest.txt[]
+include::includes/cmd-config-section-rest.adoc[]
 
-include::config/difftool.txt[]
+include::config/difftool.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.adoc
index 752e4b9b01..297b57bb2e 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.adoc
@@ -27,17 +27,48 @@ OPTIONS
 	Insert 'progress' statements every <n> objects, to be shown by
 	'git fast-import' during import.
 
---signed-tags=(verbatim|warn|warn-strip|strip|abort)::
+--signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)::
 	Specify how to handle signed tags.  Since any transformation
-	after the export can change the tag names (which can also happen
-	when excluding revisions) the signatures will not match.
+	after the export (or during the export, such as excluding
+	revisions) can change the hashes being signed, the signatures
+	may become invalid.
 +
 When asking to 'abort' (which is the default), this program will die
 when encountering a signed tag.  With 'strip', the tags will silently
 be made unsigned, with 'warn-strip' they will be made unsigned but a
 warning will be displayed, with 'verbatim', they will be silently
-exported and with 'warn', they will be exported, but you will see a
-warning.
+exported and with 'warn-verbatim' (or 'warn', a deprecated synonym),
+they will be exported, but you will see a warning.  'verbatim' and
+'warn-verbatim' should only be used if you know that no transformation
+affecting tags or any commit in their history will be performed by you
+or by fast-export or fast-import, or if you do not care that the
+resulting tag will have an invalid signature.
+
+--signed-commits=(verbatim|warn-verbatim|warn-strip|strip|abort)::
+	Specify how to handle signed commits.  Behaves exactly as
+	'--signed-tags', but for commits.  Default is 'strip', which
+	is the same as how earlier versions of this command without
+	this option behaved.
++
+When exported, a signature starts with:
++
+gpgsig <git-hash-algo> <signature-format>
++
+where <git-hash-algo> is the Git object hash so either "sha1" or
+"sha256", and <signature-format> is the signature type, so "openpgp",
+"x509", "ssh" or "unknown".
++
+For example, an OpenPGP signature on a SHA-1 commit starts with
+`gpgsig sha1 openpgp`, while an SSH signature on a SHA-256 commit
+starts with `gpgsig sha256 ssh`.
++
+While all the signatures of a commit are exported, an importer may
+choose to accept only some of them. For example
+linkgit:git-fast-import[1] currently stores at most one signature per
+Git hash algorithm in each commit.
++
+NOTE: This is highly experimental and the format of the data stream may
+change in the future without compatibility guarantees.
 
 --tag-of-filtered-object=(abort|drop|rewrite)::
 	Specify how to handle tags whose tagged object is filtered out.
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.adoc
index 3d435157a6..b74179a6c8 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.adoc
@@ -61,10 +61,20 @@ OPTIONS
 	currently impacts only the `export-marks`, `import-marks`, and
 	`import-marks-if-exists` feature commands.
 +
-	Only enable this option if you trust the program generating the
-	fast-import stream! This option is enabled automatically for
-	remote-helpers that use the `import` capability, as they are
-	already trusted to run their own code.
+Only enable this option if you trust the program generating the
+fast-import stream! This option is enabled automatically for
+remote-helpers that use the `import` capability, as they are
+already trusted to run their own code.
+
+--signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)::
+	Specify how to handle signed tags.  Behaves in the same way
+	as the same option in linkgit:git-fast-export[1], except that
+	default is 'verbatim' (instead of 'abort').
+
+--signed-commits=(verbatim|warn-verbatim|warn-strip|strip|abort)::
+	Specify how to handle signed commits.  Behaves in the same way
+	as the same option in linkgit:git-fast-export[1], except that
+	default is 'verbatim' (instead of 'abort').
 
 Options for Frontends
 ~~~~~~~~~~~~~~~~~~~~~
@@ -111,7 +121,8 @@ Locations of Marks Files
 	Like --import-marks but instead of erroring out, silently
 	skips the file if it does not exist.
 
---[no-]relative-marks::
+--relative-marks::
+--no-relative-marks::
 	After specifying --relative-marks the paths specified
 	with --import-marks= and --export-marks= are relative
 	to an internal directory in the current repository.
@@ -182,7 +193,7 @@ amount of memory usage and processing time.  Assuming the frontend
 is able to keep up with fast-import and feed it a constant stream of data,
 import times for projects holding 10+ years of history and containing
 100,000+ individual commits are generally completed in just 1-2
-hours on quite modest (~$2,000 USD) hardware.
+hours on quite modest hardware (~$2,000 USD in 2007).
 
 Most bottlenecks appear to be in foreign source data access (the
 source just cannot extract revisions fast enough) or disk IO (fast-import
@@ -431,13 +442,22 @@ and control the current import process.  More detailed discussion
 Create or update a branch with a new commit, recording one logical
 change to the project.
 
+////
+Yes, it's intentional that the 'gpgsig' line doesn't have a trailing
+`LF`; the definition of `data` has a byte-count prefix, so it
+doesn't need an `LF` to act as a terminator (and `data` also already
+includes an optional trailing `LF?` just in case you want to include
+one).
+////
+
 ....
 	'commit' SP <ref> LF
 	mark?
 	original-oid?
 	('author' (SP <name>)? SP LT <email> GT SP <when> LF)?
 	'committer' (SP <name>)? SP LT <email> GT SP <when> LF
-	('encoding' SP <encoding>)?
+	('gpgsig' SP <algo> SP <format> LF data)?
+	('encoding' SP <encoding> LF)?
 	data
 	('from' SP <commit-ish> LF)?
 	('merge' SP <commit-ish> LF)*
@@ -505,6 +525,44 @@ that was selected by the --date-format=<fmt> command-line option.
 See ``Date Formats'' above for the set of supported formats, and
 their syntax.
 
+`gpgsig`
+^^^^^^^^
+
+The optional `gpgsig` command is used to include a PGP/GPG signature
+or other cryptographic signature that signs the commit data.
+
+....
+	'gpgsig' SP <git-hash-algo> SP <signature-format> LF data
+....
+
+The `gpgsig` command takes two arguments:
+
+* `<git-hash-algo>` specifies which Git object format this signature
+  applies to, either `sha1` or `sha256`. This allows to know which
+  representation of the commit was signed (the SHA-1 or the SHA-256
+  version) which helps with both signature verification and
+  interoperability between repos with different hash functions.
+
+* `<signature-format>` specifies the type of signature, such as
+  `openpgp`, `x509`, `ssh`, or `unknown`. This is a convenience for
+  tools that process the stream, so they don't have to parse the ASCII
+  armor to identify the signature type.
+
+A commit may have at most one signature for the SHA-1 object format
+(stored in the "gpgsig" header) and one for the SHA-256 object format
+(stored in the "gpgsig-sha256" header).
+
+See below for a detailed description of the `data` command which
+contains the raw signature data.
+
+Signatures are not yet checked in the current implementation
+though. (Already setting the `extensions.compatObjectFormat`
+configuration option might help with verifying both SHA-1 and SHA-256
+object format signatures when it will be implemented.)
+
+NOTE: This is highly experimental and the format of the `gpgsig`
+command may change in the future without compatibility guarantees.
+
 `encoding`
 ^^^^^^^^^^
 The optional `encoding` command indicates the encoding of the commit
@@ -558,9 +616,11 @@ Marks must be declared (via `mark`) before they can be used.
 
 The special case of restarting an incremental import from the
 current branch value should be written as:
+
 ----
 	from refs/heads/branch^0
 ----
+
 The `^0` suffix is necessary as fast-import does not permit a branch to
 start from itself, and the branch is created in memory before the
 `from` command is even read from the input.  Adding `^0` will force
@@ -597,7 +657,7 @@ External data format::
 +
 Here usually `<dataref>` must be either a mark reference (`:<idnum>`)
 set by a prior `blob` command, or a full 40-byte SHA-1 of an
-existing Git blob object.  If `<mode>` is `040000`` then
+existing Git blob object.  If `<mode>` is `040000` then
 `<dataref>` must be the full 40-byte SHA-1 of an existing
 Git tree object or a mark reference set with `--import-marks`.
 
@@ -1578,9 +1638,9 @@ compression.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/fastimport.txt[]
+include::config/fastimport.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.adoc
index b5223576a7..b5223576a7 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.adoc
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.adoc
index 50900a50da..16f5d9d69a 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.adoc
@@ -44,15 +44,15 @@ may be used by scripts or other git commands, such as linkgit:git-pull[1].
 
 OPTIONS
 -------
-include::fetch-options.txt[]
+include::fetch-options.adoc[]
 
-include::pull-fetch-param.txt[]
+include::pull-fetch-param.adoc[]
 
 --stdin::
 	Read refspecs, one per line, from stdin in addition to those provided
 	as arguments. The "tag <name>" format is not supported.
 
-include::urls-remotes.txt[]
+include::urls-remotes.adoc[]
 
 
 CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
@@ -292,14 +292,14 @@ The first command fetches the `maint` branch from the repository at
 objects will eventually be removed by git's built-in housekeeping (see
 linkgit:git-gc[1]).
 
-include::transfer-data-leaks.txt[]
+include::transfer-data-leaks.adoc[]
 
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/fetch.txt[]
+include::config/fetch.adoc[]
 
 BUGS
 ----
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.adoc
index 5a4f853785..5a4f853785 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.adoc
diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.adoc
index 6f28812f38..6d91620be9 100644
--- a/Documentation/git-fmt-merge-msg.txt
+++ b/Documentation/git-fmt-merge-msg.adoc
@@ -35,7 +35,8 @@ OPTIONS
 	Do not list one-line descriptions from the actual commits being
 	merged.
 
---[no-]summary::
+--summary::
+--no-summary::
 	Synonyms to --log and --no-log; these are deprecated and will be
 	removed in the future.
 
@@ -55,7 +56,7 @@ OPTIONS
 
 CONFIGURATION
 -------------
-include::config/fmt-merge-msg.txt[]
+include::config/fmt-merge-msg.adoc[]
 
 merge.summary::
 	Synonym to `merge.log`; this is deprecated and will be removed in
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.adoc
index d3764401a2..c02cb7f886 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.adoc
@@ -7,106 +7,28 @@ git-for-each-ref - Output information on each ref
 
 SYNOPSIS
 --------
-[verse]
-'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
+[synopsis]
+git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
 		   [(--sort=<key>)...] [--format=<format>]
-		   [--include-root-refs] [ --stdin | <pattern>... ]
-		   [--points-at=<object>]
+		   [--include-root-refs] [--points-at=<object>]
 		   [--merged[=<object>]] [--no-merged[=<object>]]
 		   [--contains[=<object>]] [--no-contains[=<object>]]
-		   [--exclude=<pattern> ...]
+		   [(--exclude=<pattern>)...] [--start-after=<marker>]
+		   [ --stdin | (<pattern>...)]
 
 DESCRIPTION
 -----------
 
-Iterate over all refs that match `<pattern>` and show them
-according to the given `<format>`, after sorting them according
-to the given set of `<key>`.  If `<count>` is given, stop after
-showing that many refs.  The interpolated values in `<format>`
+Iterate over all refs that match _<pattern>_ and show them
+according to the given _<format>_, after sorting them according
+to the given set of _<key>_.  If _<count>_ is given, stop after
+showing that many refs.  The interpolated values in _<format>_
 can optionally be quoted as string literals in the specified
 host language allowing their direct evaluation in that language.
 
 OPTIONS
 -------
-<pattern>...::
-	If one or more patterns are given, only refs are shown that
-	match against at least one pattern, either using fnmatch(3) or
-	literally, in the latter case matching completely or from the
-	beginning up to a slash.
-
---stdin::
-	If `--stdin` is supplied, then the list of patterns is read from
-	standard input instead of from the argument list.
-
---count=<count>::
-	By default the command shows all refs that match
-	`<pattern>`.  This option makes it stop after showing
-	that many refs.
-
---sort=<key>::
-	A field name to sort on.  Prefix `-` to sort in
-	descending order of the value.  When unspecified,
-	`refname` is used.  You may use the --sort=<key> option
-	multiple times, in which case the last key becomes the primary
-	key.
-
---format=<format>::
-	A string that interpolates `%(fieldname)` from a ref being shown and
-	the object it points at. In addition, the string literal `%%`
-	renders as `%` and `%xx` - where `xx` are hex digits - renders as
-	the character with hex code `xx`. For example, `%00` interpolates to
-	`\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
-+
-When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
-TAB %(refname)`.
-
---color[=<when>]::
-	Respect any colors specified in the `--format` option. The
-	`<when>` field must be one of `always`, `never`, or `auto` (if
-	`<when>` is absent, behave as if `always` was given).
-
---shell::
---perl::
---python::
---tcl::
-	If given, strings that substitute `%(fieldname)`
-	placeholders are quoted as string literals suitable for
-	the specified host language.  This is meant to produce
-	a scriptlet that can directly be `eval`ed.
-
---points-at=<object>::
-	Only list refs which points at the given object.
-
---merged[=<object>]::
-	Only list refs whose tips are reachable from the
-	specified commit (HEAD if not specified).
-
---no-merged[=<object>]::
-	Only list refs whose tips are not reachable from the
-	specified commit (HEAD if not specified).
-
---contains[=<object>]::
-	Only list refs which contain the specified commit (HEAD if not
-	specified).
-
---no-contains[=<object>]::
-	Only list refs which don't contain the specified commit (HEAD
-	if not specified).
-
---ignore-case::
-	Sorting and filtering refs are case insensitive.
-
---omit-empty::
-	Do not print a newline after formatted refs where the format expands
-	to the empty string.
-
---exclude=<pattern>::
-	If one or more patterns are given, only refs which do not match
-	any excluded pattern(s) are shown. Matching is done using the
-	same rules as `<pattern>` above.
-
---include-root-refs::
-	List root refs (HEAD and pseudorefs) apart from regular refs.
+include::for-each-ref-options.adoc[]
 
 FIELD NAMES
 -----------
@@ -117,44 +39,44 @@ keys.
 
 For all objects, the following names can be used:
 
-refname::
-	The name of the ref (the part after $GIT_DIR/).
+`refname`::
+	The name of the ref (the part after `$GIT_DIR/`).
 	For a non-ambiguous short name of the ref append `:short`.
-	The option core.warnAmbiguousRefs is used to select the strict
-	abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>`
+	The option `core.warnAmbiguousRefs` is used to select the strict
+	abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_
 	slash-separated path components from the front (back) of the refname
 	(e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and
 	`%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).
-	If `<N>` is a negative number, strip as many path components as
-	necessary from the specified end to leave `-<N>` path components
+	If _<n>_ is a negative number, strip as many path components as
+	necessary from the specified end to leave `-<n>` path components
 	(e.g. `%(refname:lstrip=-2)` turns
 	`refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
 	turns `refs/tags/foo` into `refs`). When the ref does not have
 	enough components, the result becomes an empty string if
-	stripping with positive <N>, or it becomes the full refname if
-	stripping with negative <N>.  Neither is an error.
+	stripping with positive _<n>_, or it becomes the full refname if
+	stripping with negative _<N>_.  Neither is an error.
 +
 `strip` can be used as a synonym to `lstrip`.
 
-objecttype::
+`objecttype`::
 	The type of the object (`blob`, `tree`, `commit`, `tag`).
 
-objectsize::
+`objectsize`::
 	The size of the object (the same as 'git cat-file -s' reports).
 	Append `:disk` to get the size, in bytes, that the object takes up on
-	disk. See the note about on-disk sizes in the `CAVEATS` section below.
-objectname::
+	disk. See the note about on-disk sizes in the 'CAVEATS' section below.
+`objectname`::
 	The object name (aka SHA-1).
 	For a non-ambiguous abbreviation of the object name append `:short`.
 	For an abbreviation of the object name with desired length append
-	`:short=<length>`, where the minimum length is MINIMUM_ABBREV. The
+	`:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The
 	length may be exceeded to ensure unique object names.
-deltabase::
+`deltabase`::
 	This expands to the object name of the delta base for the
 	given object, if it is stored as a delta.  Otherwise it
 	expands to the null object name (all zeroes).
 
-upstream::
+`upstream`::
 	The name of a local ref which can be considered ``upstream''
 	from the displayed ref. Respects `:short`, `:lstrip` and
 	`:rstrip` in the same way as `refname` above.  Additionally
@@ -176,100 +98,103 @@ Has no effect if the ref does not have tracking information associated
 with it.  All the options apart from `nobracket` are mutually exclusive,
 but if used together the last option is selected.
 
-push::
+`push`::
 	The name of a local ref which represents the `@{push}`
 	location for the displayed ref. Respects `:short`, `:lstrip`,
 	`:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref`
 	options as `upstream` does. Produces an empty string if no `@{push}`
 	ref is configured.
 
-HEAD::
-	'*' if HEAD matches current ref (the checked out branch), ' '
+`HEAD`::
+	`*` if `HEAD` matches current ref (the checked out branch), ' '
 	otherwise.
 
-color::
+`color`::
 	Change output color. Followed by `:<colorname>`, where color
 	names are described under Values in the "CONFIGURATION FILE"
 	section of linkgit:git-config[1].  For example,
 	`%(color:bold red)`.
 
-align::
+`align`::
 	Left-, middle-, or right-align the content between
-	%(align:...) and %(end). The "align:" is followed by
+	`%(align:...)` and `%(end)`. The "`align:`" is followed by
 	`width=<width>` and `position=<position>` in any order
-	separated by a comma, where the `<position>` is either left,
-	right or middle, default being left and `<width>` is the total
+	separated by a comma, where the _<position>_ is either `left`,
+	`right` or `middle`, default being `left` and _<width>_ is the total
 	length of the content with alignment. For brevity, the
 	"width=" and/or "position=" prefixes may be omitted, and bare
-	<width> and <position> used instead.  For instance,
+	_<width>_ and _<position>_ used instead.  For instance,
 	`%(align:<width>,<position>)`. If the contents length is more
 	than the width then no alignment is performed. If used with
-	`--quote` everything in between %(align:...) and %(end) is
+	`--quote` everything in between `%(align:...)` and `%(end)` is
 	quoted, but if nested then only the topmost level performs
 	quoting.
 
-if::
-	Used as %(if)...%(then)...%(end) or
-	%(if)...%(then)...%(else)...%(end).  If there is an atom with
-	value or string literal after the %(if) then everything after
-	the %(then) is printed, else if the %(else) atom is used, then
+`if`::
+	Used as `%(if)...%(then)...%(end)` or
+	`%(if)...%(then)...%(else)...%(end)`.  If there is an atom with
+	value or string literal after the `%(if)` then everything after
+	the `%(then)` is printed, else if the `%(else)` atom is used, then
 	everything after %(else) is printed. We ignore space when
-	evaluating the string before %(then), this is useful when we
-	use the %(HEAD) atom which prints either "*" or " " and we
-	want to apply the 'if' condition only on the 'HEAD' ref.
-	Append ":equals=<string>" or ":notequals=<string>" to compare
-	the value between the %(if:...) and %(then) atoms with the
+	evaluating the string before `%(then)`, this is useful when we
+	use the `%(HEAD)` atom which prints either "`*`" or " " and we
+	want to apply the 'if' condition only on the `HEAD` ref.
+	Append "`:equals=<string>`" or "`:notequals=<string>`" to compare
+	the value between the `%(if:...)` and `%(then)` atoms with the
 	given string.
 
-symref::
+`symref`::
 	The ref which the given symbolic ref refers to. If not a
 	symbolic ref, nothing is printed. Respects the `:short`,
 	`:lstrip` and `:rstrip` options in the same way as `refname`
 	above.
 
-signature::
+`signature`::
 	The GPG signature of a commit.
 
-signature:grade::
-	Show "G" for a good (valid) signature, "B" for a bad
-	signature, "U" for a good signature with unknown validity, "X"
-	for a good signature that has expired, "Y" for a good
-	signature made by an expired key, "R" for a good signature
-	made by a revoked key, "E" if the signature cannot be
-	checked (e.g. missing key) and "N" for no signature.
-
-signature:signer::
+`signature:grade`::
+	Show
+`G`;; for a good (valid) signature
+`B`;; for a bad signature
+`U`;; for a good signature with unknown validity
+`X`;;	for a good signature that has expired
+`Y`;; for a good signature made by an expired key
+`R`;; for a good signature made by a revoked key
+`E`;; if the signature cannot be checked (e.g. missing key)
+`N`;; for no signature.
+
+`signature:signer`::
 	The signer of the GPG signature of a commit.
 
-signature:key::
+`signature:key`::
 	The key of the GPG signature of a commit.
 
-signature:fingerprint::
+`signature:fingerprint`::
 	The fingerprint of the GPG signature of a commit.
 
-signature:primarykeyfingerprint::
+`signature:primarykeyfingerprint`::
 	The primary key fingerprint of the GPG signature of a commit.
 
-signature:trustlevel::
+`signature:trustlevel`::
 	The trust level of the GPG signature of a commit. Possible
 	outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`.
 
-worktreepath::
+`worktreepath`::
 	The absolute path to the worktree in which the ref is checked
 	out, if it is checked out in any linked worktree. Empty string
 	otherwise.
 
-ahead-behind:<committish>::
+`ahead-behind:<commit-ish>`::
 	Two integers, separated by a space, demonstrating the number of
 	commits ahead and behind, respectively, when comparing the output
-	ref to the `<committish>` specified in the format.
+	ref to the _<committish>_ specified in the format.
 
-is-base:<committish>::
-	In at most one row, `(<committish>)` will appear to indicate the ref
+`is-base:<commit-ish>`::
+	In at most one row, `(<commit-ish>)` will appear to indicate the ref
 	that is most likely the ref used as a starting point for the branch
-	that produced `<committish>`. This choice is made using a heuristic:
+	that produced _<commit-ish>_. This choice is made using a heuristic:
 	choose the ref that minimizes the number of commits in the
-	first-parent history of `<committish>` and not in the first-parent
+	first-parent history of _<commit-ish>_ and not in the first-parent
 	history of the ref.
 +
 For example, consider the following figure of first-parent histories of
@@ -303,29 +228,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the
 earliest ref in the sorted order.
 +
 Note that this token will not appear if the first-parent history of
-`<committish>` does not intersect the first-parent histories of the
+_<commit-ish>_ does not intersect the first-parent histories of the
 filtered refs.
 
-describe[:options]::
+`describe[:<option>,...]`::
 	A human-readable name, like linkgit:git-describe[1];
 	empty string for undescribable commits. The `describe` string may
 	be followed by a colon and one or more comma-separated options.
 +
 --
-tags=<bool-value>;;
+`tags=<bool-value>`;;
 	Instead of only considering annotated tags, consider
 	lightweight tags as well; see the corresponding option in
 	linkgit:git-describe[1] for details.
-abbrev=<number>;;
-	Use at least <number> hexadecimal digits; see the corresponding
+`abbrev=<number>`;;
+	Use at least _<number>_ hexadecimal digits; see the corresponding
 	option in linkgit:git-describe[1] for details.
-match=<pattern>;;
-	Only consider tags matching the given `glob(7)` pattern,
-	excluding the "refs/tags/" prefix; see the corresponding option
+`match=<pattern>`;;
+	Only consider tags matching the `glob`(7) _<pattern>_,
+	excluding the `refs/tags/` prefix; see the corresponding option
 	in linkgit:git-describe[1] for details.
-exclude=<pattern>;;
-	Do not consider tags matching the given `glob(7)` pattern,
-	excluding the "refs/tags/" prefix; see the corresponding option
+`exclude=<pattern>`;;
+	Do not consider tags matching the `glob`(7) _<pattern>_,
+	excluding the `refs/tags/` prefix; see the corresponding option
 	in linkgit:git-describe[1] for details.
 --
 
@@ -357,7 +282,7 @@ variable (see linkgit:gitmailmap[5]).
 
 The raw data in an object is `raw`.
 
-raw:size::
+`raw:size`::
 	The raw data size of the object.
 
 Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`,
@@ -367,10 +292,10 @@ variable type.
 The message in a commit or a tag object is `contents`, from which
 `contents:<part>` can be used to extract various parts out of:
 
-contents:size::
+`contents:size`::
 	The size in bytes of the commit or tag message.
 
-contents:subject::
+`contents:subject`::
 	The first paragraph of the message, which typically is a
 	single line, is taken as the "subject" of the commit or the
 	tag message.
@@ -378,19 +303,19 @@ contents:subject::
 	obtain same results. `:sanitize` can be appended to `subject` for
 	subject line suitable for filename.
 
-contents:body::
+`contents:body`::
 	The remainder of the commit or the tag message that follows
 	the "subject".
 
-contents:signature::
+`contents:signature`::
 	The optional GPG signature of the tag.
 
-contents:lines=N::
-	The first `N` lines of the message.
+`contents:lines=<n>`::
+	The first _<n>_ lines of the message.
 
 Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
-are obtained as `trailers[:options]` (or by using the historical alias
-`contents:trailers[:options]`). For valid [:option] values see `trailers`
+are obtained as `trailers[:<option>,...]` (or by using the historical alias
+`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers`
 section of linkgit:git-log[1].
 
 For sorting purposes, fields with numeric values sort in numeric order
@@ -410,8 +335,8 @@ option to linkgit:git-rev-list[1] takes). If this formatting is provided in
 a `--sort` key, references will be sorted according to the byte-value of the
 formatted string rather than the numeric value of the underlying timestamp.
 
-Some atoms like %(align) and %(if) always require a matching %(end).
-We call them "opening atoms" and sometimes denote them as %($open).
+Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`.
+We call them "opening atoms" and sometimes denote them as `%($open)`.
 
 When a scripting language specific quoting is in effect, everything
 between a top-level opening atom and its matching %(end) is evaluated
@@ -429,7 +354,7 @@ An example directly producing formatted text.  Show the most recent
 #!/bin/sh
 
 git for-each-ref --count=3 --sort='-*authordate' \
---format='From: %(*authorname) %(*authoremail)
+`--format='From: %(*authorname) %(*authoremail)
 Subject: %(*subject)
 Date: %(*authordate)
 Ref: %(*refname)
@@ -440,7 +365,8 @@ Ref: %(*refname)
 
 
 A simple example showing the use of shell eval on the output,
-demonstrating the use of --shell.  List the prefixes of all heads:
+demonstrating the use of `--shell`.  List the prefixes of all heads:
+
 ------------
 #!/bin/sh
 
@@ -455,6 +381,7 @@ done
 
 A bit more elaborate report on tags, demonstrating that the format
 may be an entire script:
+
 ------------
 #!/bin/sh
 
@@ -506,7 +433,7 @@ eval "$eval"
 ------------
 
 
-An example to show the usage of %(if)...%(then)...%(else)...%(end).
+An example to show the usage of `%(if)...%(then)...%(else)...%(end)`.
 This prefixes the current branch with a star.
 
 ------------
@@ -514,7 +441,7 @@ git for-each-ref --format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)"
 ------------
 
 
-An example to show the usage of %(if)...%(then)...%(end).
+An example to show the usage of `%(if)...%(then)...%(end)`.
 This prints the authorname, if present.
 
 ------------
@@ -538,7 +465,7 @@ will be reported.
 NOTES
 -----
 
-include::ref-reachability-filters.txt[]
+include::ref-reachability-filters.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-for-each-repo.txt b/Documentation/git-for-each-repo.adoc
index abe3527aac..abe3527aac 100644
--- a/Documentation/git-for-each-repo.txt
+++ b/Documentation/git-for-each-repo.adoc
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.adoc
index 5dc7bb4cfc..9a7807ca71 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.adoc
@@ -105,7 +105,7 @@ reference.
 OPTIONS
 -------
 :git-format-patch: 1
-include::diff-options.txt[]
+include::diff-options.adoc[]
 
 -<n>::
 	Prepare patches from the topmost <n> commits.
@@ -295,7 +295,8 @@ header). Note also that `git send-email` already handles this
 transformation for you, and this option should not be used if you are
 feeding the result to `git send-email`.
 
---[no-]force-in-body-from::
+--force-in-body-from::
+--no-force-in-body-from::
 	With the e-mail sender specified via the `--from` option, by
 	default, an in-body "From:" to identify the real author of
 	the commit is added at the top of the commit log message if
@@ -314,7 +315,8 @@ feeding the result to `git send-email`.
 	`Cc:`, and custom) headers added so far from config or command
 	line.
 
---[no-]cover-letter::
+--cover-letter::
+--no-cover-letter::
 	In addition to the patches, generate a cover letter file
 	containing the branch description, shortlog and the overall diffstat.  You can
 	fill in a description in the file before sending it out.
@@ -379,7 +381,8 @@ configuration options in linkgit:git-notes[1] to use this workflow).
 The default is `--no-notes`, unless the `format.notes` configuration is
 set.
 
---[no-]signature=<signature>::
+--signature=<signature>::
+--no-signature::
 	Add a signature to each message produced. Per RFC 3676 the signature
 	is separated from the body by a line with '-- ' on it. If the
 	signature option is omitted the signature defaults to the Git version
@@ -411,7 +414,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
   Output an all-zero hash in each patch's From header instead
   of the hash of the commit.
 
---[no-]base[=<commit>]::
+--no-base::
+--base[=<commit>]::
 	Record the base tree information to identify the state the
 	patch series applies to.  See the BASE TREE INFORMATION section
 	below for details. If <commit> is "auto", a base commit is
@@ -587,13 +591,19 @@ an external editor to keep Thunderbird from mangling the patches.
 Approach #1 (add-on)
 ^^^^^^^^^^^^^^^^^^^^
 
-Install the Toggle Word Wrap add-on that is available from
-https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/
-It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu
+Install the Toggle Line Wrap add-on that is available from
+https://addons.thunderbird.net/thunderbird/addon/toggle-line-wrap
+It adds a button "Line Wrap" to the composer's toolbar
 that you can tick off. Now you can compose the message as you otherwise do
 (cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to
 insert line breaks manually in any text that you type.
 
+As a bonus feature, the add-on can detect patch text in the composer
+and warns when line wrapping has not yet been turned off.
+
+The add-on requires a few tweaks of the advanced configuration
+(about:config). These are listed on the download page.
+
 Approach #2 (configuration)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Three steps:
diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.adoc
index eec4bdb600..eec4bdb600 100644
--- a/Documentation/git-fsck-objects.txt
+++ b/Documentation/git-fsck-objects.adoc
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.adoc
index 5b82e4605c..1751f692d4 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.adoc
@@ -12,7 +12,7 @@ SYNOPSIS
 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
 	 [--[no-]full] [--strict] [--verbose] [--lost-found]
 	 [--[no-]dangling] [--[no-]progress] [--connectivity-only]
-	 [--[no-]name-objects] [<object>...]
+	 [--[no-]name-objects] [--[no-]references] [<object>...]
 
 DESCRIPTION
 -----------
@@ -31,7 +31,8 @@ index file, all SHA-1 references in the `refs` namespace, and all reflogs
 	Print out objects that exist but that aren't reachable from any
 	of the reference nodes.
 
---[no-]dangling::
+--dangling::
+--no-dangling::
 	Print objects that exist but that are never 'directly' used (default).
 	`--no-dangling` can be used to omit this information from the output.
 
@@ -97,19 +98,26 @@ care about this output and want to speed it up further.
 	compatible with linkgit:git-rev-parse[1], e.g.
 	`HEAD@{1234567890}~25^2:src/`.
 
---[no-]progress::
+--progress::
+--no-progress::
 	Progress status is reported on the standard error stream by
 	default when it is attached to a terminal, unless
 	--no-progress or --verbose is specified. --progress forces
 	progress status even if the standard error stream is not
 	directed to a terminal.
 
+--references::
+--no-references::
+	Control whether to check the references database consistency
+	via 'git refs verify'. See linkgit:git-refs[1] for details.
+	The default is to check the references database.
+
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/fsck.txt[]
+include::config/fsck.adoc[]
 
 DISCUSSION
 ----------
@@ -161,7 +169,7 @@ 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[]
+include::fsck-msgids.adoc[]
 
 
 Environment Variables
diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.adoc
index 8585d19f4d..8fe5241b08 100644
--- a/Documentation/git-fsmonitor--daemon.txt
+++ b/Documentation/git-fsmonitor--daemon.adoc
@@ -97,9 +97,9 @@ error that will cause the daemon and the currently running command to exit.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/fsmonitor--daemon.txt[]
+include::config/fsmonitor--daemon.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.adoc
index 370e22faae..6fed646dd8 100644
--- a/Documentation/git-gc.txt
+++ b/Documentation/git-gc.adoc
@@ -53,11 +53,13 @@ configuration options such as `gc.auto` and `gc.autoPackLimit`, all
 other housekeeping tasks (e.g. rerere, working trees, reflog...) will
 be performed as well.
 
---[no-]detach::
+--detach::
+--no-detach::
 	Run in the background if the system supports it. This option overrides
 	the `gc.autoDetach` config.
 
---[no-]cruft::
+--cruft::
+--no-cruft::
 	When expiring unreachable objects, pack them separately into a
 	cruft pack instead of storing them as loose objects. `--cruft`
 	is on by default.
@@ -69,6 +71,13 @@ be performed as well.
 	the `--max-cruft-size` option of linkgit:git-repack[1] for
 	more.
 
+--expire-to=<dir>::
+	When packing unreachable objects into a cruft pack, write a cruft
+	pack containing pruned objects (if any) to the directory `<dir>`.
+	This option only has an effect when used together with `--cruft`.
+	See the `--expire-to` option of linkgit:git-repack[1] for
+	more information.
+
 --prune=<date>::
 	Prune loose objects older than date (default is 2 weeks ago,
 	overridable by the config variable `gc.pruneExpire`).
@@ -122,9 +131,9 @@ users and their repositories.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/gc.txt[]
+include::config/gc.adoc[]
 
 NOTES
 -----
diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.adoc
index b537bb45b1..b537bb45b1 100644
--- a/Documentation/git-get-tar-commit-id.txt
+++ b/Documentation/git-get-tar-commit-id.adoc
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.adoc
index 1e6d7b65c8..a548585d4c 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.adoc
@@ -351,9 +351,9 @@ experienced in this case, it might be desirable to use `--threads=1`.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/grep.txt[]
+include::config/grep.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.adoc
index f5b02ef114..f5b02ef114 100644
--- a/Documentation/git-gui.txt
+++ b/Documentation/git-gui.adoc
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.adoc
index ef4719ae41..ef4719ae41 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.adoc
diff --git a/Documentation/git-help.txt b/Documentation/git-help.adoc
index f0bedc1f96..f0bedc1f96 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.adoc
diff --git a/Documentation/git-hook.txt b/Documentation/git-hook.adoc
index f6cc72d2ca..f6cc72d2ca 100644
--- a/Documentation/git-hook.txt
+++ b/Documentation/git-hook.adoc
diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.adoc
index f37ddaded8..1dea426852 100644
--- a/Documentation/git-http-backend.txt
+++ b/Documentation/git-http-backend.adoc
@@ -56,6 +56,10 @@ http.receivepack::
 	disabled by setting this item to `false`, or enabled for all
 	users, including anonymous users, by setting it to `true`.
 
+http.uploadarchive::
+	This serves 'git archive' clients for remote archive over HTTP/HTTPS
+	protocols. It is disabled by default. It only works in protocol v2.
+
 URL TRANSLATION
 ---------------
 To determine the location of the repository on disk, 'git http-backend'
diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.adoc
index 4ec7c68d3b..2200f073c4 100644
--- a/Documentation/git-http-fetch.txt
+++ b/Documentation/git-http-fetch.adoc
@@ -25,8 +25,11 @@ commit-id::
         Either the hash or the filename under [URL]/refs/ to
         pull.
 
--a, -c, -t::
+-a::
+-c::
+-t::
 	These options are ignored for historical reasons.
+
 -v::
 	Report what is downloaded.
 
diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.adoc
index ce0d808212..ce0d808212 100644
--- a/Documentation/git-http-push.txt
+++ b/Documentation/git-http-push.adoc
diff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc
new file mode 100644
index 0000000000..278e5ccd36
--- /dev/null
+++ b/Documentation/git-imap-send.adoc
@@ -0,0 +1,224 @@
+git-imap-send(1)
+================
+
+NAME
+----
+git-imap-send - Send a collection of patches from stdin to an IMAP folder
+
+
+SYNOPSIS
+--------
+[verse]
+'git imap-send' [-v] [-q] [--[no-]curl] [(--folder|-f) <folder>]
+'git imap-send' --list
+
+
+DESCRIPTION
+-----------
+This command uploads a mailbox generated with `git format-patch`
+into an IMAP drafts folder.  This allows patches to be sent as
+other email is when using mail clients that cannot read mailbox
+files directly. The command also works with any general mailbox
+in which emails have the fields `From`, `Date`, and `Subject` in
+that order.
+
+Typical usage is something like:
+
+------
+$ git format-patch --signoff --stdout --attach origin | git imap-send
+------
+
+
+OPTIONS
+-------
+
+-v::
+--verbose::
+	Be verbose.
+
+-q::
+--quiet::
+	Be quiet.
+
+-f <folder>::
+--folder=<folder>::
+	Specify the folder in which the emails have to saved.
+	For example: `--folder=[Gmail]/Drafts` or `-f INBOX/Drafts`.
+
+--curl::
+	Use libcurl to communicate with the IMAP server, unless tunneling
+	into it.  Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND
+	option set.
+
+--no-curl::
+	Talk to the IMAP server using git's own IMAP routines instead of
+	using libcurl.  Ignored if Git was built with the NO_OPENSSL option
+	set.
+
+--list::
+	Run the IMAP LIST command to output a list of all the folders present.
+
+CONFIGURATION
+-------------
+
+To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set
+to appropriate values.
+
+include::includes/cmd-config-section-rest.adoc[]
+
+include::config/imap.adoc[]
+
+GETTING A LIST OF AVAILABLE FOLDERS
+-----------------------------------
+
+In order to send an email to a specific folder, you need to know the correct name of
+intended folder in your mailbox. The names like "Junk", "Trash" etc. displayed by
+various email clients need not be the actual names of the folders stored in the mail
+server of your email provider.
+
+In order to get the correct folder name to be used with `git imap-send`, you can run
+`git imap-send --list`. This will display a list of valid folder names. An example
+of such an output when run on a Gmail account is:
+
+.........................
+* LIST (\HasNoChildren) "/" "INBOX"
+* LIST (\HasChildren \Noselect) "/" "[Gmail]"
+* LIST (\All \HasNoChildren) "/" "[Gmail]/All Mail"
+* LIST (\Drafts \HasNoChildren) "/" "[Gmail]/Drafts"
+* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important"
+* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail"
+* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam"
+* LIST (\Flagged \HasNoChildren) "/" "[Gmail]/Starred"
+* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash"
+.........................
+
+Here, you can observe that the correct name for the "Junk" folder is `[Gmail]/Spam`
+and for the "Trash" folder is `[Gmail]/Trash`. Similar logic can be used to determine
+other folders as well.
+
+EXAMPLES
+--------
+Using tunnel mode:
+
+..........................
+[imap]
+    folder = "INBOX.Drafts"
+    tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
+..........................
+
+Using direct mode:
+
+.........................
+[imap]
+    folder = "INBOX.Drafts"
+    host = imap://imap.example.com
+    user = bob
+    pass = p4ssw0rd
+.........................
+
+Using direct mode with SSL:
+
+.........................
+[imap]
+    folder = "INBOX.Drafts"
+    host = imaps://imap.example.com
+    user = bob
+    pass = p4ssw0rd
+    port = 123
+    ; sslVerify = false
+.........................
+
+
+[NOTE]
+You may want to use `sslVerify=false`
+while troubleshooting, if you suspect that the reason you are
+having trouble connecting is because the certificate you use at
+the private server `example.com` you are trying to set up (or
+have set up) may not be verified correctly.
+
+Using Gmail's IMAP interface:
+
+---------
+[imap]
+    folder = "[Gmail]/Drafts"
+    host = imaps://imap.gmail.com
+    user = user@gmail.com
+    port = 993
+---------
+
+Gmail does not allow using your regular password for `git imap-send`.
+If you have multi-factor authentication set up on your Gmail account, you
+can generate an app-specific password for use with `git imap-send`.
+Visit https://security.google.com/settings/security/apppasswords to create
+it. Alternatively, use OAuth2.0 authentication as described below.
+
+[NOTE]
+You might need to instead use: `folder = "[Google Mail]/Drafts"` if you get an error
+that the "Folder doesn't exist". You can also run `git imap-send --list` to get a
+list of available folders.
+
+[NOTE]
+If your Gmail account is set to another language than English, the name of the "Drafts"
+folder will be localized.
+
+If you want to use OAuth2.0 based authentication, you can specify
+`OAUTHBEARER` or `XOAUTH2` mechanism in your config. It is more secure
+than using app-specific passwords, and also does not enforce the need of
+having multi-factor authentication. You will have to use an OAuth2.0
+access token in place of your password when using this authentication.
+
+---------
+[imap]
+    folder = "[Gmail]/Drafts"
+    host = imaps://imap.gmail.com
+    user = user@gmail.com
+    port = 993
+    authmethod = OAUTHBEARER
+---------
+
+Using Outlook's IMAP interface:
+
+Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it
+supports only `XOAUTH2` as the mechanism.
+
+---------
+[imap]
+    folder = "Drafts"
+    host = imaps://outlook.office365.com
+    user = user@outlook.com
+    port = 993
+    authmethod = XOAUTH2
+---------
+
+Once the commits are ready to be sent, run the following command:
+
+  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+
+Just make sure to disable line wrapping in the email client (Gmail's web
+interface will wrap lines no matter what, so you need to use a real
+IMAP client).
+
+In case you are using OAuth2.0 authentication, it is easier to use credential
+helpers to generate tokens. Credential helpers suggested in
+linkgit:git-send-email[1] can be used for `git imap-send` as well.
+
+CAUTION
+-------
+It is still your responsibility to make sure that the email message
+sent by your email program meets the standards of your project.
+Many projects do not like patches to be attached.  Some mail
+agents will transform patches (e.g. wrap lines, send them as
+format=flowed) in ways that make them fail.  You will get angry
+flames ridiculing you if you don't check this.
+
+Thunderbird in particular is known to be problematic.  Thunderbird
+users may wish to visit this web page for more information:
+  https://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email
+
+SEE ALSO
+--------
+linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
deleted file mode 100644
index c8a89d7243..0000000000
--- a/Documentation/git-imap-send.txt
+++ /dev/null
@@ -1,146 +0,0 @@
-git-imap-send(1)
-================
-
-NAME
-----
-git-imap-send - Send a collection of patches from stdin to an IMAP folder
-
-
-SYNOPSIS
---------
-[verse]
-'git imap-send' [-v] [-q] [--[no-]curl]
-
-
-DESCRIPTION
------------
-This command uploads a mailbox generated with 'git format-patch'
-into an IMAP drafts folder.  This allows patches to be sent as
-other email is when using mail clients that cannot read mailbox
-files directly. The command also works with any general mailbox
-in which emails have the fields "From", "Date", and "Subject" in
-that order.
-
-Typical usage is something like:
-
-git format-patch --signoff --stdout --attach origin | git imap-send
-
-
-OPTIONS
--------
-
--v::
---verbose::
-	Be verbose.
-
--q::
---quiet::
-	Be quiet.
-
---curl::
-	Use libcurl to communicate with the IMAP server, unless tunneling
-	into it.  Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND
-	option set.
-
---no-curl::
-	Talk to the IMAP server using git's own IMAP routines instead of
-	using libcurl.  Ignored if Git was built with the NO_OPENSSL option
-	set.
-
-
-CONFIGURATION
--------------
-
-To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set
-to appropriate values.
-
-include::includes/cmd-config-section-rest.txt[]
-
-include::config/imap.txt[]
-
-EXAMPLES
---------
-Using tunnel mode:
-
-..........................
-[imap]
-    folder = "INBOX.Drafts"
-    tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
-..........................
-
-Using direct mode:
-
-.........................
-[imap]
-    folder = "INBOX.Drafts"
-    host = imap://imap.example.com
-    user = bob
-    pass = p4ssw0rd
-.........................
-
-Using direct mode with SSL:
-
-.........................
-[imap]
-    folder = "INBOX.Drafts"
-    host = imaps://imap.example.com
-    user = bob
-    pass = p4ssw0rd
-    port = 123
-    ; sslVerify = false
-.........................
-
-
-[NOTE]
-You may want to use `sslVerify=false`
-while troubleshooting, if you suspect that the reason you are
-having trouble connecting is because the certificate you use at
-the private server `example.com` you are trying to set up (or
-have set up) may not be verified correctly.
-
-Using Gmail's IMAP interface:
-
----------
-[imap]
-	folder = "[Gmail]/Drafts"
-	host = imaps://imap.gmail.com
-	user = user@gmail.com
-	port = 993
----------
-
-[NOTE]
-You might need to instead use: `folder = "[Google Mail]/Drafts"` if you get an error
-that the "Folder doesn't exist".
-
-[NOTE]
-If your Gmail account is set to another language than English, the name of the "Drafts"
-folder will be localized.
-
-Once the commits are ready to be sent, run the following command:
-
-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
-
-Just make sure to disable line wrapping in the email client (Gmail's web
-interface will wrap lines no matter what, so you need to use a real
-IMAP client).
-
-CAUTION
--------
-It is still your responsibility to make sure that the email message
-sent by your email program meets the standards of your project.
-Many projects do not like patches to be attached.  Some mail
-agents will transform patches (e.g. wrap lines, send them as
-format=flowed) in ways that make them fail.  You will get angry
-flames ridiculing you if you don't check this.
-
-Thunderbird in particular is known to be problematic.  Thunderbird
-users may wish to visit this web page for more information:
-  https://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email
-
-SEE ALSO
---------
-linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)
-
-GIT
----
-Part of the linkgit:git[1] suite
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.adoc
index 58dd5b5f0e..18036953c0 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.adoc
@@ -36,7 +36,8 @@ OPTIONS
 	fails if the name of packed archive does not end
 	with .pack).
 
---[no-]rev-index::
+--rev-index::
+--no-rev-index::
 	When this flag is provided, generate a reverse index
 	(a `.rev` file) corresponding to the given pack. If
 	`--verify` is given, ensure that the existing
@@ -130,7 +131,7 @@ information on the possible values of `<msg-id>` and `<severity>`.
 +
 This option cannot be used with --stdin.
 +
-include::object-format-disclaimer.txt[]
+include::object-format-disclaimer.adoc[]
 
 --promisor[=<message>]::
 	Before committing the pack-index, create a .promisor file for this
diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.adoc
index 18bf1a3c8c..18bf1a3c8c 100644
--- a/Documentation/git-init-db.txt
+++ b/Documentation/git-init-db.adoc
diff --git a/Documentation/git-init.txt b/Documentation/git-init.adoc
index 315f7f7530..bab99b9b47 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.adoc
@@ -55,12 +55,12 @@ current working directory.
 Specify the given object _<format>_ (hash algorithm) for the repository.  The valid
 values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.
 +
-include::object-format-disclaimer.txt[]
+include::object-format-disclaimer.adoc[]
 
 `--ref-format=<format>`::
 Specify the given ref storage _<format>_ for the repository. The valid values are:
 +
-include::ref-storage-format.txt[]
+include::ref-storage-format.adoc[]
 
 `--template=<template-directory>`::
 Specify the directory from which templates will be used.  (See the "TEMPLATE
@@ -77,9 +77,15 @@ If this is a reinitialization, the repository will be moved to the specified pat
 `-b <branch-name>`::
 `--initial-branch=<branch-name>`::
 Use _<branch-name>_ for the initial branch in the newly created
-repository.  If not specified, fall back to the default name (currently
-`master`, but this is subject to change in the future; the name can be
-customized via the `init.defaultBranch` configuration variable).
+repository.  If not specified, fall back to the default name
+ifndef::with-breaking-changes[]
+(currently `master`, but this will change to `main` when Git 3.0 is released).
+endif::with-breaking-changes[]
+ifdef::with-breaking-changes[]
+`main`.
+endif::with-breaking-changes[]
+The default name can be customized via the `init.defaultBranch` configuration
+variable.
 
 `--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
 
@@ -178,11 +184,11 @@ $ git commit    <3>
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
 :git-init:
 
-include::config/init.txt[]
+include::config/init.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.adoc
index a54fe4401b..a54fe4401b 100644
--- a/Documentation/git-instaweb.txt
+++ b/Documentation/git-instaweb.adoc
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.adoc
index d9dfb75fef..fd335fe772 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.adoc
@@ -142,8 +142,8 @@ OPTIONS
 	provided with '--if-exists' overrides the `trailer.ifExists` and any
 	applicable `trailer.<keyAlias>.ifExists` configuration variables
 	and applies to all '--trailer' options until the next occurrence of
-	'--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists, clear the
-	effect of any previous use of '--if-exists, such that the relevant configuration
+	'--if-exists' or '--no-if-exists'. Upon encountering '--no-if-exists', clear the
+	effect of any previous use of '--if-exists', such that the relevant configuration
 	variables are no longer overridden. Possible actions are `addIfDifferent`,
 	`addIfDifferentNeighbor`, `add`, `replace` and `doNothing`.
 
@@ -154,8 +154,8 @@ OPTIONS
 	provided with '--if-missing' overrides the `trailer.ifMissing` and any
 	applicable `trailer.<keyAlias>.ifMissing` configuration variables
 	and applies to all '--trailer' options until the next occurrence of
-	'--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing,
-	clear the effect of any previous use of '--if-missing, such that the relevant
+	'--if-missing' or '--no-if-missing'. Upon encountering '--no-if-missing',
+	clear the effect of any previous use of '--if-missing', such that the relevant
 	configuration variables are no longer overridden. Possible actions are `doNothing`
 	or `add`.
 
@@ -186,142 +186,9 @@ OPTIONS
 CONFIGURATION VARIABLES
 -----------------------
 
-trailer.separators::
-	This option tells which characters are recognized as trailer
-	separators. By default only ':' is recognized as a trailer
-	separator, except that '=' is always accepted on the command
-	line for compatibility with other git commands.
-+
-The first character given by this option will be the default character
-used when another separator is not specified in the config for this
-trailer.
-+
-For example, if the value for this option is "%=$", then only lines
-using the format '<key><sep><value>' with <sep> containing '%', '='
-or '$' and then spaces will be considered trailers. And '%' will be
-the default separator used, so by default trailers will appear like:
-'<key>% <value>' (one percent sign and one space will appear between
-the key and the value).
-
-trailer.where::
-	This option tells where a new trailer will be added.
-+
-This can be `end`, which is the default, `start`, `after` or `before`.
-+
-If it is `end`, then each new trailer will appear at the end of the
-existing trailers.
-+
-If it is `start`, then each new trailer will appear at the start,
-instead of the end, of the existing trailers.
-+
-If it is `after`, then each new trailer will appear just after the
-last trailer with the same <key>.
-+
-If it is `before`, then each new trailer will appear just before the
-first trailer with the same <key>.
+include::includes/cmd-config-section-all.adoc[]
 
-trailer.ifexists::
-	This option makes it possible to choose what action will be
-	performed when there is already at least one trailer with the
-	same <key> in the input.
-+
-The valid values for this option are: `addIfDifferentNeighbor` (this
-is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
-+
-With `addIfDifferentNeighbor`, a new trailer will be added only if no
-trailer with the same (<key>, <value>) pair is above or below the line
-where the new trailer will be added.
-+
-With `addIfDifferent`, a new trailer will be added only if no trailer
-with the same (<key>, <value>) pair is already in the input.
-+
-With `add`, a new trailer will be added, even if some trailers with
-the same (<key>, <value>) pair are already in the input.
-+
-With `replace`, an existing trailer with the same <key> will be
-deleted and the new trailer will be added. The deleted trailer will be
-the closest one (with the same <key>) to the place where the new one
-will be added.
-+
-With `doNothing`, nothing will be done; that is no new trailer will be
-added if there is already one with the same <key> in the input.
-
-trailer.ifmissing::
-	This option makes it possible to choose what action will be
-	performed when there is not yet any trailer with the same
-	<key> in the input.
-+
-The valid values for this option are: `add` (this is the default) and
-`doNothing`.
-+
-With `add`, a new trailer will be added.
-+
-With `doNothing`, nothing will be done.
-
-trailer.<keyAlias>.key::
-	Defines a <keyAlias> for the <key>. The <keyAlias> must be a
-	prefix (case does not matter) of the <key>. For example, in `git
-	config trailer.ack.key "Acked-by"` the "Acked-by" is the <key> and
-	the "ack" is the <keyAlias>. This configuration allows the shorter
-	`--trailer "ack:..."` invocation on the command line using the "ack"
-	<keyAlias> instead of the longer `--trailer "Acked-by:..."`.
-+
-At the end of the <key>, a separator can appear and then some
-space characters. By default the only valid separator is ':',
-but this can be changed using the `trailer.separators` config
-variable.
-+
-If there is a separator in the key, then it overrides the default
-separator when adding the trailer.
-
-trailer.<keyAlias>.where::
-	This option takes the same values as the 'trailer.where'
-	configuration variable and it overrides what is specified by
-	that option for trailers with the specified <keyAlias>.
-
-trailer.<keyAlias>.ifexists::
-	This option takes the same values as the 'trailer.ifexists'
-	configuration variable and it overrides what is specified by
-	that option for trailers with the specified <keyAlias>.
-
-trailer.<keyAlias>.ifmissing::
-	This option takes the same values as the 'trailer.ifmissing'
-	configuration variable and it overrides what is specified by
-	that option for trailers with the specified <keyAlias>.
-
-trailer.<keyAlias>.command::
-	Deprecated in favor of 'trailer.<keyAlias>.cmd'.
-	This option behaves in the same way as 'trailer.<keyAlias>.cmd', except
-	that it doesn't pass anything as argument to the specified command.
-	Instead the first occurrence of substring $ARG is replaced by the
-	<value> that would be passed as argument.
-+
-Note that $ARG in the user's command is
-only replaced once and that the original way of replacing $ARG is not safe.
-+
-When both 'trailer.<keyAlias>.cmd' and 'trailer.<keyAlias>.command' are given
-for the same <keyAlias>, 'trailer.<keyAlias>.cmd' is used and
-'trailer.<keyAlias>.command' is ignored.
-
-trailer.<keyAlias>.cmd::
-	This option can be used to specify a shell command that will be called
-	once to automatically add a trailer with the specified <keyAlias>, and then
-	called each time a '--trailer <keyAlias>=<value>' argument is specified to
-	modify the <value> of the trailer that this option would produce.
-+
-When the specified command is first called to add a trailer
-with the specified <keyAlias>, the behavior is as if a special
-'--trailer <keyAlias>=<value>' argument was added at the beginning
-of the "git interpret-trailers" command, where <value>
-is taken to be the standard output of the command with any
-leading and trailing whitespace trimmed off.
-+
-If some '--trailer <keyAlias>=<value>' arguments are also passed
-on the command line, the command is called again once for each
-of these arguments with the same <keyAlias>. And the <value> part
-of these arguments, if any, will be passed to the command as its
-first argument. This way the command can produce a <value> computed
-from the <value> passed in the '--trailer <keyAlias>=<value>' argument.
+include::config/trailer.adoc[]
 
 EXAMPLES
 --------
diff --git a/Documentation/git-last-modified.adoc b/Documentation/git-last-modified.adoc
new file mode 100644
index 0000000000..602843e095
--- /dev/null
+++ b/Documentation/git-last-modified.adoc
@@ -0,0 +1,54 @@
+git-last-modified(1)
+====================
+
+NAME
+----
+git-last-modified - EXPERIMENTAL: Show when files were last modified
+
+
+SYNOPSIS
+--------
+[synopsis]
+git last-modified [--recursive] [--show-trees] [<revision-range>] [[--] <path>...]
+
+DESCRIPTION
+-----------
+
+Shows which commit last modified each of the relevant files and subdirectories.
+A commit renaming a path, or changing it's mode is also taken into account.
+
+THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
+
+OPTIONS
+-------
+
+`-r`::
+`--recursive`::
+	Instead of showing tree entries, step into subtrees and show all entries
+	inside them recursively.
+
+`-t`::
+`--show-trees`::
+	Show tree entries even when recursing into them. It has no effect
+	without `--recursive`.
+
+`<revision-range>`::
+	Only traverse commits in the specified revision range. When no
+	`<revision-range>` is specified, it defaults to `HEAD` (i.e. the whole
+	history leading to the current commit). For a complete list of ways to
+	spell `<revision-range>`, see the 'Specifying Ranges' section of
+	linkgit:gitrevisions[7].
+
+`[--] <path>...`::
+	For each _<path>_ given, the commit which last modified it is returned.
+	Without an optional path parameter, all files and subdirectories
+	in path traversal the are included in the output.
+
+SEE ALSO
+--------
+linkgit:git-blame[1],
+linkgit:git-log[1].
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-log.txt b/Documentation/git-log.adoc
index 579682172f..e304739c5e 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.adoc
@@ -8,15 +8,15 @@ git-log - Show commit logs
 
 SYNOPSIS
 --------
-[verse]
-'git log' [<options>] [<revision-range>] [[--] <path>...]
+[synopsis]
+git log [<options>] [<revision-range>] [[--] <path>...]
 
 DESCRIPTION
 -----------
 Shows the commit logs.
 
 :git-log: 1
-include::rev-list-description.txt[]
+include::rev-list-description.adoc[]
 
 The command takes options applicable to the linkgit:git-rev-list[1]
 command to control what is shown and how, and options applicable to
@@ -27,28 +27,34 @@ each commit introduces are shown.
 OPTIONS
 -------
 
---follow::
+`--follow`::
 	Continue listing the history of a file beyond renames
 	(works only for a single file).
 
---no-decorate::
---decorate[=short|full|auto|no]::
-	Print out the ref names of any commits that are shown. If 'short' is
-	specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and
-	'refs/remotes/' will not be printed. If 'full' is specified, the
-	full ref name (including prefix) will be printed. If 'auto' is
-	specified, then if the output is going to a terminal, the ref names
-	are shown as if 'short' were given, otherwise no ref names are
-	shown. The option `--decorate` is short-hand for `--decorate=short`.
-	Default to configuration value of `log.decorate` if configured,
-	otherwise, `auto`.
-
---decorate-refs=<pattern>::
---decorate-refs-exclude=<pattern>::
+`--no-decorate`::
+`--decorate[=(short|full|auto|no)]`::
+	Print out the ref names of any commits that are shown. Possible values
+	are:
++
+----
+`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and
+	`refs/remotes/` are not printed.
+`full`;; the full ref name (including prefix) is printed.
+`auto`:: if the output is going to a terminal, the ref names
+	are shown as if `short` were given, otherwise no ref names are
+	shown.
+----
++
+The option `--decorate` is short-hand for `--decorate=short`. Default to
+configuration value of `log.decorate` if configured, otherwise, `auto`.
+
+`--decorate-refs=<pattern>`::
+`--decorate-refs-exclude=<pattern>`::
 	For each candidate reference, do not use it for decoration if it
-	matches any patterns given to `--decorate-refs-exclude` or if it
-	doesn't match any of the patterns given to `--decorate-refs`. The
-	`log.excludeDecoration` config option allows excluding refs from
+	matches any of the _<pattern>_ parameters given to
+	`--decorate-refs-exclude` or if it doesn't match any of the
+	_<pattern>_ parameters given to `--decorate-refs`.
+	The `log.excludeDecoration` config option allows excluding refs from
 	the decorations, but an explicit `--decorate-refs` pattern will
 	override a match in `log.excludeDecoration`.
 +
@@ -56,51 +62,53 @@ If none of these options or config settings are given, then references are
 used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`,
 `refs/stash/`, or `refs/tags/`.
 
---clear-decorations::
+`--clear-decorations`::
 	When specified, this option clears all previous `--decorate-refs`
 	or `--decorate-refs-exclude` options and relaxes the default
 	decoration filter to include all references. This option is
 	assumed if the config value `log.initialDecorationSet` is set to
 	`all`.
 
---source::
+`--source`::
 	Print out the ref name given on the command line by which each
 	commit was reached.
 
---[no-]mailmap::
---[no-]use-mailmap::
+`--mailmap`::
+`--no-mailmap`::
+`--use-mailmap`::
+`--no-use-mailmap`::
 	Use mailmap file to map author and committer names and email
 	addresses to canonical real names and email addresses. See
 	linkgit:git-shortlog[1].
 
---full-diff::
+`--full-diff`::
 	Without this flag, `git log -p <path>...` shows commits that
 	touch the specified paths, and diffs about the same specified
 	paths.  With this, the full diff is shown for commits that touch
-	the specified paths; this means that "<path>..." limits only
+	the specified paths; this means that "`<path>...`" limits only
 	commits, and doesn't limit diff for those commits.
 +
 Note that this affects all diff-based output types, e.g. those
 produced by `--stat`, etc.
 
---log-size::
-	Include a line ``log size <number>'' in the output for each commit,
-	where <number> is the length of that commit's message in bytes.
+`--log-size`::
+	Include a line `log size <number>` in the output for each commit,
+	where _<number>_ is the length of that commit's message in bytes.
 	Intended to speed up tools that read log messages from `git log`
 	output by allowing them to allocate space in advance.
 
-include::line-range-options.txt[]
+include::line-range-options.adoc[]
 
-<revision-range>::
+_<revision-range>_::
 	Show only commits in the specified revision range.  When no
-	<revision-range> is specified, it defaults to `HEAD` (i.e. the
+	_<revision-range>_ is specified, it defaults to `HEAD` (i.e. the
 	whole history leading to the current commit).  `origin..HEAD`
 	specifies all the commits reachable from the current commit
 	(i.e. `HEAD`), but not from `origin`. For a complete list of
-	ways to spell <revision-range>, see the 'Specifying Ranges'
+	ways to spell _<revision-range>_, see the 'Specifying Ranges'
 	section of linkgit:gitrevisions[7].
 
-[--] <path>...::
+`[--] <path>...`::
 	Show only commits that are enough to explain how the files
 	that match the specified paths came to be.  See 'History
 	Simplification' below for details and other simplification
@@ -109,9 +117,9 @@ include::line-range-options.txt[]
 Paths may need to be prefixed with `--` to separate them from
 options or the revision range, when confusion arises.
 
-include::rev-list-options.txt[]
+include::rev-list-options.adoc[]
 
-include::pretty-formats.txt[]
+include::pretty-formats.adoc[]
 
 DIFF FORMATTING
 ---------------
@@ -128,9 +136,9 @@ the default format for merge commits.
 
 :git-log: 1
 :diff-merges-default: `off`
-include::diff-options.txt[]
+include::diff-options.adoc[]
 
-include::diff-generate-patch.txt[]
+include::diff-generate-patch.adoc[]
 
 EXAMPLES
 --------
@@ -145,14 +153,14 @@ EXAMPLES
 
 `git log --since="2 weeks ago" -- gitk`::
 
-	Show the changes during the last two weeks to the file 'gitk'.
+	Show the changes during the last two weeks to the file `gitk`.
 	The `--` is necessary to avoid confusion with the *branch* named
-	'gitk'
+	`gitk`
 
 `git log --name-status release..test`::
 
-	Show the commits that are in the "test" branch but not yet
-	in the "release" branch, along with the list of paths
+	Show the commits that are in the "`test`" branch but not yet
+	in the "`release`" branch, along with the list of paths
 	each commit modifies.
 
 `git log --follow builtin/rev-list.c`::
@@ -164,7 +172,7 @@ EXAMPLES
 `git log --branches --not --remotes=origin`::
 
 	Shows all commits that are in any of local branches but not in
-	any of remote-tracking branches for 'origin' (what you have that
+	any of remote-tracking branches for `origin` (what you have that
 	origin doesn't).
 
 `git log master --not --remotes=*/master`::
@@ -192,7 +200,7 @@ EXAMPLES
 DISCUSSION
 ----------
 
-include::i18n.txt[]
+include::i18n.adoc[]
 
 CONFIGURATION
 -------------
@@ -200,20 +208,20 @@ CONFIGURATION
 See linkgit:git-config[1] for core variables and linkgit:git-diff[1]
 for settings related to diff generation.
 
-format.pretty::
+`format.pretty`::
 	Default for the `--format` option.  (See 'Pretty Formats' above.)
 	Defaults to `medium`.
 
-i18n.logOutputEncoding::
+`i18n.logOutputEncoding`::
 	Encoding to use when displaying logs.  (See 'Discussion' above.)
 	Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
 	otherwise.
 
-include::includes/cmd-config-section-rest.txt[]
+include::includes/cmd-config-section-rest.adoc[]
 
-include::config/log.txt[]
+include::config/log.adoc[]
 
-include::config/notes.txt[]
+include::config/notes.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.adoc
index 58c529afbe..58c529afbe 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.adoc
diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.adoc
index d71c4ab3e2..d71c4ab3e2 100644
--- a/Documentation/git-ls-remote.txt
+++ b/Documentation/git-ls-remote.adoc
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.adoc
index 6572095d8d..6572095d8d 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.adoc
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.adoc
index 28060283c7..3b24c9abd9 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.adoc
@@ -118,9 +118,9 @@ If no such configuration option has been set, `warn` will be used.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/mailinfo.txt[]
+include::config/mailinfo.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.adoc
index 3f0a6662c8..3f0a6662c8 100644
--- a/Documentation/git-mailsplit.txt
+++ b/Documentation/git-mailsplit.adoc
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.adoc
index 6e6651309d..540b5cf68b 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.adoc
@@ -126,13 +126,17 @@ loose-objects::
 	objects that already exist in a pack-file; concurrent Git processes
 	will examine the pack-file for the object data instead of the loose
 	object. Second, it creates a new pack-file (starting with "loose-")
-	containing a batch of loose objects. The batch size is limited to 50
-	thousand objects to prevent the job from taking too long on a
-	repository with many loose objects. The `gc` task writes unreachable
-	objects as loose objects to be cleaned up by a later step only if
-	they are not re-added to a pack-file; for this reason it is not
-	advisable to enable both the `loose-objects` and `gc` tasks at the
-	same time.
+	containing a batch of loose objects.
++
+The batch size defaults to fifty thousand objects to prevent the job from
+taking too long on a repository with many loose objects. Use the
+`maintenance.loose-objects.batchSize` config option to adjust this size,
+including a value of `0` to remove the limit.
++
+The `gc` task writes unreachable objects as loose objects to be cleaned up
+by a later step only if they are not re-added to a pack-file; for this
+reason it is not advisable to enable both the `loose-objects` and `gc`
+tasks at the same time.
 
 incremental-repack::
 	The `incremental-repack` job repacks the object directory
@@ -158,6 +162,18 @@ pack-refs::
 	need to iterate across many references. See linkgit:git-pack-refs[1]
 	for more information.
 
+reflog-expire::
+	The `reflog-expire` task deletes any entries in the reflog older than the
+	expiry threshold. See linkgit:git-reflog[1] for more information.
+
+rerere-gc::
+	The `rerere-gc` task invokes garbage collection for stale entries in
+	the rerere cache. See linkgit:git-rerere[1] for more information.
+
+worktree-prune::
+	The `worktree-prune` task deletes stale or broken worktrees. See
+	linkgit:git-worktree[1] for more information.
+
 OPTIONS
 -------
 --auto::
@@ -409,9 +425,9 @@ custom tasks.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/maintenance.txt[]
+include::config/maintenance.adoc[]
 
 
 GIT
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.adoc
index 5ab957cfbc..5ab957cfbc 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.adoc
diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.adoc
index 71915a00fa..71915a00fa 100644
--- a/Documentation/git-merge-file.txt
+++ b/Documentation/git-merge-file.adoc
diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.adoc
index eea56b3154..eea56b3154 100644
--- a/Documentation/git-merge-index.txt
+++ b/Documentation/git-merge-index.adoc
diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.adoc
index 04e803d5d3..04e803d5d3 100644
--- a/Documentation/git-merge-one-file.txt
+++ b/Documentation/git-merge-one-file.adoc
diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.adoc
index 0b6a8a19b1..4391bbee47 100644
--- a/Documentation/git-merge-tree.txt
+++ b/Documentation/git-merge-tree.adoc
@@ -40,11 +40,17 @@ After the merge completes, a new toplevel tree object is created.  See
 OPTIONS
 -------
 
+--stdin::
+	Read the commits to merge from the standard input rather than
+	the command-line. See <<INPUT,INPUT FORMAT>> below for more
+	information.  Implies `-z`.
+
 -z::
 	Do not quote filenames in the <Conflicted file info> section,
 	and end each filename with a NUL character rather than
 	newline.  Also begin the messages section with a NUL character
-	instead of a newline.  See <<OUTPUT>> below for more information.
+	instead of a newline.  See <<OUTPUT,OUTPUT>> below for more
+	information.
 
 --name-only::
 	In the Conflicted file info section, instead of writing a list
@@ -53,12 +59,19 @@ OPTIONS
 	do not list filenames multiple times if they have multiple
 	conflicting stages).
 
---[no-]messages::
+--messages::
+--no-messages::
 	Write any informational messages such as "Auto-merging <path>"
 	or CONFLICT notices to the end of stdout.  If unspecified, the
 	default is to include these messages if there are merge
 	conflicts, and to omit them otherwise.
 
+--quiet::
+	Disable all output from the program.  Useful when you are only
+	interested in the exit status.  Allows merge-tree to exit
+	early when it finds a conflict, and allows it to avoid writing
+	most objects created by merges.
+
 --allow-unrelated-histories::
 	merge-tree will by default error out if the two branches specified
 	share no common history.  This flag can be given to override that
@@ -66,11 +79,17 @@ OPTIONS
 
 --merge-base=<tree-ish>::
 	Instead of finding the merge-bases for <branch1> and <branch2>,
-	specify a merge-base for the merge, and specifying multiple bases is
-	currently not supported. This option is incompatible with `--stdin`.
+	specify a merge-base for the merge.  This option is incompatible with
+	`--stdin`.
++
+Specifying multiple bases is currently not supported, which means that when
+merging two branches with more than one merge-base, using this option may
+cause merge results to differ from what `git merge` would compute.  This
+can include potentially losing some changes made on one side of the history
+in the resulting merge.
 +
-As the merge-base is provided directly, <branch1> and <branch2> do not need
-to specify commits; trees are enough.
+With this option, since the merge-base is provided directly, <branch1> and
+<branch2> do not need to specify commits; trees are enough.
 
 -X<option>::
 --strategy-option=<option>::
@@ -116,8 +135,6 @@ 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
@@ -235,6 +252,7 @@ with linkgit:git-merge[1]:
   * any messages that would have been printed to stdout (the
     <<IM,Informational messages>>)
 
+[[INPUT]]
 INPUT FORMAT
 ------------
 'git merge-tree --stdin' input format is fully text based. Each line
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.adoc
index 1ab69f61f5..a055384ad6 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.adoc
@@ -8,13 +8,13 @@ git-merge - Join two or more development histories together
 
 SYNOPSIS
 --------
-[verse]
-'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
+[synopsis]
+git merge [-n] [--stat] [--compact-summary] [--no-commit] [--squash] [--[no-]edit]
 	[--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
 	[--[no-]allow-unrelated-histories]
 	[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>]
 	[--into-name <branch>] [<commit>...]
-'git merge' (--continue | --abort | --quit)
+git merge (--continue | --abort | --quit)
 
 DESCRIPTION
 -----------
@@ -28,8 +28,8 @@ Assume the following history exists and the current branch is
 `master`:
 
 ------------
-	  A---B---C topic
-	 /
+          A---B---C topic
+         /
     D---E---F---G master
 ------------
 
@@ -38,11 +38,11 @@ Then `git merge topic` will replay the changes made on the
 its current commit (`C`) on top of `master`, and record the result
 in a new commit along with the names of the two parent commits and
 a log message from the user describing the changes. Before the operation,
-`ORIG_HEAD` is set to the tip of the current branch (`C`).
+`ORIG_HEAD` is set to the tip of the current branch (`G`).
 
 ------------
-	  A---B---C topic
-	 /         \
+          A---B---C topic
+         /         \
     D---E---F---G---H master
 ------------
 
@@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified
 after the merge was started), `git merge --abort` will in some cases be
 unable to reconstruct the original (pre-merge) changes. Therefore:
 
-*Warning*: Running `git merge` with non-trivial uncommitted changes is
+WARNING: Running `git merge` with non-trivial uncommitted changes is
 discouraged: while possible, it may leave you in a state that is hard to
 back out of in the case of a conflict.
 
@@ -65,9 +65,9 @@ OPTIONS
 -------
 :git-merge: 1
 
-include::merge-options.txt[]
+include::merge-options.adoc[]
 
--m <msg>::
+`-m <msg>`::
 	Set the commit message to be used for the merge commit (in
 	case one is created).
 +
@@ -78,27 +78,27 @@ The `git fmt-merge-msg` command can be
 used to give a good default for automated `git merge`
 invocations. The automated message can include the branch description.
 
---into-name <branch>::
+`--into-name <branch>`::
 	Prepare the default merge message as if merging to the branch
-	`<branch>`, instead of the name of the real branch to which
+	_<branch>_, instead of the name of the real branch to which
 	the merge is made.
 
--F <file>::
---file=<file>::
+`-F <file>`::
+`--file=<file>`::
 	Read the commit message to be used for the merge commit (in
 	case one is created).
 +
 If `--log` is specified, a shortlog of the commits being merged
 will be appended to the specified message.
 
-include::rerere-options.txt[]
+include::rerere-options.adoc[]
 
---overwrite-ignore::
---no-overwrite-ignore::
+`--overwrite-ignore`::
+`--no-overwrite-ignore`::
 	Silently overwrite ignored files from the merge result. This
 	is the default behavior. Use `--no-overwrite-ignore` to abort.
 
---abort::
+`--abort`::
 	Abort the current conflict resolution process, and
 	try to reconstruct the pre-merge state. If an autostash entry is
 	present, apply it to the worktree.
@@ -114,17 +114,17 @@ which case `git merge --abort` applies the stash entry to the worktree
 whereas `git reset --merge` will save the stashed changes in the stash
 list.
 
---quit::
+`--quit`::
 	Forget about the current merge in progress. Leave the index
 	and the working tree as-is. If `MERGE_AUTOSTASH` is present, the
 	stash entry will be saved to the stash list.
 
---continue::
+`--continue`::
 	After a `git merge` stops due to conflicts you can conclude the
 	merge by running `git merge --continue` (see "HOW TO RESOLVE
 	CONFLICTS" section below).
 
-<commit>...::
+`<commit>...`::
 	Commits, usually other branch heads, to merge into our branch.
 	Specifying more than one commit will create a merge with
 	more than two parents (affectionately called an Octopus merge).
@@ -152,7 +152,7 @@ To avoid recording unrelated changes in the merge commit,
 `git pull` and `git merge` will also abort if there are any changes
 registered in the index relative to the `HEAD` commit.  (Special
 narrow exceptions to this rule may exist depending on which merge
-strategy is in use, but generally, the index must match HEAD.)
+strategy is in use, but generally, the index must match `HEAD`.)
 
 If all named commits are already ancestors of `HEAD`, `git merge`
 will exit early with the message "Already up to date."
@@ -195,11 +195,11 @@ happens:
    stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
    can inspect the stages with `git ls-files -u`).  The working
    tree files contain the result of the merge operation; i.e. 3-way
-   merge results with familiar conflict markers `<<<` `===` `>>>`.
+   merge results with familiar conflict markers +<<<+ `===` +>>>+.
 5. A ref named `AUTO_MERGE` is written, pointing to a tree
    corresponding to the current content of the working tree (including
    conflict markers for textual conflicts).  Note that this ref is only
-   written when the 'ort' merge strategy is used (the default).
+   written when the `ort` merge strategy is used (the default).
 6. No other changes are made.  In particular, the local
    modifications you had before you started merge will stay the
    same and the index entries for them stay as they were,
@@ -231,7 +231,6 @@ git merge v1.2.3^0
 git merge --ff-only v1.2.3
 ----
 
-
 HOW CONFLICTS ARE PRESENTED
 ---------------------------
 
@@ -260,7 +259,7 @@ And here is another line that is cleanly resolved or unmodified.
 ------------
 
 The area where a pair of conflicting changes happened is marked with markers
-`<<<<<<<`, `=======`, and `>>>>>>>`.  The part before the `=======`
++<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`
 is typically your side, and the part afterwards is typically their side.
 
 The default format does not show what the original said in the conflicting
@@ -270,7 +269,7 @@ side wants to say it is hard and you'd prefer to go shopping, while the
 other side wants to claim it is easy.
 
 An alternative style can be used by setting the `merge.conflictStyle`
-configuration variable to either "diff3" or "zdiff3".  In "diff3"
+configuration variable to either `diff3` or `zdiff3`.  In `diff3`
 style, the above conflict may look like this:
 
 ------------
@@ -290,7 +289,7 @@ Git makes conflict resolution easy.
 And here is another line that is cleanly resolved or unmodified.
 ------------
 
-while in "zdiff3" style, it may look like this:
+while in `zdiff3` style, it may look like this:
 
 ------------
 Here are lines that are either unchanged from the common
@@ -308,8 +307,8 @@ Git makes conflict resolution easy.
 And here is another line that is cleanly resolved or unmodified.
 ------------
 
-In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
-another `|||||||` marker that is followed by the original text.  You can
+In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses
+another +|||||||+ marker that is followed by the original text.  You can
 tell that the original just stated a fact, and your side simply gave in to
 that statement and gave up, while the other side tried to have a more
 positive attitude.  You can sometimes come up with a better resolution by
@@ -385,19 +384,19 @@ changes into a merge commit.  Small fixups like bumping
 release/version name would be acceptable.
 
 
-include::merge-strategies.txt[]
+include::merge-strategies.adoc[]
 
 CONFIGURATION
 -------------
 
-branch.<name>.mergeOptions::
-	Sets default options for merging into branch <name>. The syntax and
+`branch.<name>.mergeOptions`::
+	Sets default options for merging into branch _<name>_. The syntax and
 	supported options are the same as those of `git merge`, but option
 	values containing whitespace characters are currently not supported.
 
-include::includes/cmd-config-section-rest.txt[]
+include::includes/cmd-config-section-rest.adoc[]
 
-include::config/merge.txt[]
+include::config/merge.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.adoc
index 0726b560d4..0726b560d4 100644
--- a/Documentation/git-mergetool--lib.txt
+++ b/Documentation/git-mergetool--lib.adoc
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.adoc
index b9e20c5dcd..77d0b50550 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.adoc
@@ -7,95 +7,95 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
 
 SYNOPSIS
 --------
-[verse]
-'git mergetool' [--tool=<tool>] [-y | --[no-]prompt] [<file>...]
+[synopsis]
+git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]
 
 DESCRIPTION
 -----------
 
 Use `git mergetool` to run one of several merge utilities to resolve
-merge conflicts.  It is typically run after 'git merge'.
+merge conflicts.  It is typically run after `git merge`.
 
 If one or more <file> parameters are given, the merge tool program will
 be run to resolve differences in each file (skipping those without
 conflicts).  Specifying a directory will include all unresolved files in
-that path.  If no <file> names are specified, 'git mergetool' will run
+that path.  If no _<file>_ names are specified, `git mergetool` will run
 the merge tool program on every file with merge conflicts.
 
 OPTIONS
 -------
--t <tool>::
---tool=<tool>::
-	Use the merge resolution program specified by <tool>.
-	Valid values include emerge, gvimdiff, kdiff3,
-	meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help`
-	for the list of valid <tool> settings.
+`-t <tool>`::
+`--tool=<tool>`::
+	Use the merge resolution program specified by _<tool>_.
+	Valid values include `emerge`, `gvimdiff`, `kdiff3`,
+	`meld`, `vimdiff`, and `tortoisemerge`. Run `git mergetool --tool-help`
+	for the list of valid _<tool>_ settings.
 +
-If a merge resolution program is not specified, 'git mergetool'
+If a merge resolution program is not specified, `git mergetool`
 will use the configuration variable `merge.tool`.  If the
-configuration variable `merge.tool` is not set, 'git mergetool'
+configuration variable `merge.tool` is not set, `git mergetool`
 will pick a suitable default.
 +
 You can explicitly provide a full path to the tool by setting the
 configuration variable `mergetool.<tool>.path`. For example, you
 can configure the absolute path to kdiff3 by setting
-`mergetool.kdiff3.path`. Otherwise, 'git mergetool' assumes the
-tool is available in PATH.
+`mergetool.kdiff3.path`. Otherwise, `git mergetool` assumes the
+tool is available in `$PATH`.
 +
 Instead of running one of the known merge tool programs,
-'git mergetool' can be customized to run an alternative program
+`git mergetool` can be customized to run an alternative program
 by specifying the command line to invoke in a configuration
 variable `mergetool.<tool>.cmd`.
 +
-When 'git mergetool' is invoked with this tool (either through the
+When `git mergetool` is invoked with this tool (either through the
 `-t` or `--tool` option or the `merge.tool` configuration
-variable), the configured command line will be invoked with `$BASE`
+variable), the configured command line will be invoked with `BASE`
 set to the name of a temporary file containing the common base for
-the merge, if available; `$LOCAL` set to the name of a temporary
+the merge, if available; `LOCAL` set to the name of a temporary
 file containing the contents of the file on the current branch;
-`$REMOTE` set to the name of a temporary file containing the
-contents of the file to be merged, and `$MERGED` set to the name
+`REMOTE` set to the name of a temporary file containing the
+contents of the file to be merged, and `MERGED` set to the name
 of the file to which the merge tool should write the result of the
 merge resolution.
 +
 If the custom merge tool correctly indicates the success of a
 merge resolution with its exit code, then the configuration
 variable `mergetool.<tool>.trustExitCode` can be set to `true`.
-Otherwise, 'git mergetool' will prompt the user to indicate the
+Otherwise, `git mergetool` will prompt the user to indicate the
 success of the resolution after the custom tool has exited.
 
---tool-help::
+`--tool-help`::
 	Print a list of merge tools that may be used with `--tool`.
 
--y::
---no-prompt::
+`-y`::
+`--no-prompt`::
 	Don't prompt before each invocation of the merge resolution
 	program.
 	This is the default if the merge resolution program is
 	explicitly specified with the `--tool` option or with the
 	`merge.tool` configuration variable.
 
---prompt::
+`--prompt`::
 	Prompt before each invocation of the merge resolution program
 	to give the user a chance to skip the path.
 
--g::
---gui::
-	When 'git-mergetool' is invoked with the `-g` or `--gui` option,
+`-g`::
+`--gui`::
+	When `git-mergetool` is invoked with the `-g` or `--gui` option,
 	the default merge tool will be read from the configured
 	`merge.guitool` variable instead of `merge.tool`. If
 	`merge.guitool` is not set, we will fallback to the tool
 	configured under `merge.tool`. This may be autoselected using
 	the configuration variable `mergetool.guiDefault`.
 
---no-gui::
+`--no-gui`::
 	This overrides a previous `-g` or `--gui` setting or
 	`mergetool.guiDefault` configuration and reads the default merge
 	tool from the configured `merge.tool` variable.
 
--O<orderfile>::
+`-O<orderfile>`::
 	Process files in the order specified in the
-	<orderfile>, which has one shell glob pattern per line.
+	_<orderfile>_, which has one shell glob pattern per line.
 	This overrides the `diff.orderFile` configuration variable
 	(see linkgit:git-config[1]).  To cancel `diff.orderFile`,
 	use `-O/dev/null`.
@@ -104,9 +104,9 @@ CONFIGURATION
 -------------
 :git-mergetool: 1
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/mergetool.txt[]
+include::config/mergetool.adoc[]
 
 TEMPORARY FILES
 ---------------
@@ -123,7 +123,7 @@ BACKEND SPECIFIC HINTS
 
 vimdiff
 ~~~~~~~
-include::mergetools/vimdiff.txt[]
+include::mergetools/vimdiff.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.adoc
index 006d759962..006d759962 100644
--- a/Documentation/git-mktag.txt
+++ b/Documentation/git-mktag.adoc
diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.adoc
index 383f09dd33..383f09dd33 100644
--- a/Documentation/git-mktree.txt
+++ b/Documentation/git-mktree.adoc
diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.adoc
index 631d5c7d15..2f642697e9 100644
--- a/Documentation/git-multi-pack-index.txt
+++ b/Documentation/git-multi-pack-index.adoc
@@ -25,10 +25,11 @@ OPTIONS
 +
 `<dir>` must be an alternate of the current repository.
 
---[no-]progress::
+--progress::
+--no-progress::
 	Turn progress on/off explicitly. If neither is specified, progress is
 	shown if standard error is connected to a terminal. Supported by
-	sub-commands `write`, `verify`, `expire`, and `repack.
+	sub-commands `write`, `verify`, `expire`, and `repack`.
 
 The following subcommands are available:
 
@@ -38,10 +39,13 @@ write::
 +
 --
 	--preferred-pack=<pack>::
-		Optionally specify the tie-breaking pack used when
-		multiple packs contain the same object. `<pack>` must
-		contain at least one object. If not given, ties are
-		broken in favor of the pack with the lowest mtime.
+		When specified, break ties in favor of this pack when
+		there are additional copies of its objects in other
+		packs. Ties for objects not found in the preferred
+		pack are always resolved in favor of the copy in the
+		pack with the highest mtime. If unspecified, the pack
+		with the lowest mtime is used by default. The
+		preferred pack must have at least one object.
 
 	--[no-]bitmap::
 		Control whether or not a multi-pack bitmap is written.
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.adoc
index dc1bf61534..f707e998f7 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.adoc
@@ -8,19 +8,18 @@ git-mv - Move or rename a file, a directory, or a symlink
 
 SYNOPSIS
 --------
-[verse]
-'git mv' [<options>] <source>... <destination>
+
+[synopsis]
+git mv [-v] [-f] [-n] [-k] <source> <destination>
+git mv [-v] [-f] [-n] [-k] <source>... <destination-directory>
 
 DESCRIPTION
 -----------
 Move or rename a file, directory, or symlink.
 
- git mv [-v] [-f] [-n] [-k] <source> <destination>
- git mv [-v] [-f] [-n] [-k] <source> ... <destination-directory>
-
-In the first form, it renames <source>, which must exist and be either
-a file, symlink or directory, to <destination>.
-In the second form, the last argument has to be an existing
+In the first form, it renames _<source>_, which must exist and be either
+a file, symlink or directory, to _<destination>_.
+In the second form, _<destination-directory>_ has to be an existing
 directory; the given sources will be moved into this directory.
 
 The index is updated after successful completion, but the change must still be
@@ -28,20 +27,20 @@ committed.
 
 OPTIONS
 -------
--f::
---force::
+`-f`::
+`--force`::
 	Force renaming or moving of a file even if the <destination> exists.
--k::
+`-k`::
 	Skip move or rename actions which would lead to an error
 	condition. An error happens when a source is neither existing nor
 	controlled by Git, or when it would overwrite an existing
 	file unless `-f` is given.
--n::
---dry-run::
+`-n`::
+`--dry-run`::
 	Do nothing; only show what would happen
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Report the names of files as they are moved.
 
 SUBMODULES
@@ -49,8 +48,8 @@ SUBMODULES
 Moving a submodule using a gitfile (which means they were cloned
 with a Git version 1.7.8 or newer) will update the gitfile and
 core.worktree setting to make the submodule work in the new location.
-It also will attempt to update the submodule.<name>.path setting in
-the linkgit:gitmodules[5] file and stage that file (unless -n is used).
+It also will attempt to update the `submodule.<name>.path` setting in
+the linkgit:gitmodules[5] file and stage that file (unless `-n` is used).
 
 BUGS
 ----
diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.adoc
index d4f1c4d594..d4f1c4d594 100644
--- a/Documentation/git-name-rev.txt
+++ b/Documentation/git-name-rev.adoc
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.adoc
index 84022f99d7..46a232ca71 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.adoc
@@ -7,19 +7,19 @@ git-notes - Add or inspect object notes
 
 SYNOPSIS
 --------
-[verse]
-'git notes' [list [<object>]]
-'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
-'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] )
-'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
-'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace]
-'git notes' show [<object>]
-'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref>
-'git notes' merge --commit [-v | -q]
-'git notes' merge --abort [-v | -q]
-'git notes' remove [--ignore-missing] [--stdin] [<object>...]
-'git notes' prune [-n] [-v]
-'git notes' get-ref
+[synopsis]
+git notes [list [<object>]]
+git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
+git notes copy [-f] ( --stdin | <from-object> [<to-object>] )
+git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
+git notes edit [--allow-empty] [<object>] [--[no-]stripspace]
+git notes show [<object>]
+git notes merge [-v | -q] [-s <strategy> ] <notes-ref>
+git notes merge --commit [-v | -q]
+git notes merge --abort [-v | -q]
+git notes remove [--ignore-missing] [--stdin] [<object>...]
+git notes prune [-n] [-v]
+git notes get-ref
 
 
 DESCRIPTION
@@ -33,34 +33,34 @@ ENVIRONMENT sections below.  If this ref does not exist, it will be
 quietly created when it is first needed to store a note.
 
 A typical use of notes is to supplement a commit message without
-changing the commit itself. Notes can be shown by 'git log' along with
+changing the commit itself. Notes can be shown by `git log` along with
 the original commit message. To distinguish these notes from the
 message stored in the commit object, the notes are indented like the
-message, after an unindented line saying "Notes (<refname>):" (or
+message, after an unindented line saying "Notes (_<refname>_):" (or
 "Notes:" for `refs/notes/commits`).
 
 Notes can also be added to patches prepared with `git format-patch` by
 using the `--notes` option. Such notes are added as a patch commentary
 after a three dash separator line.
 
-To change which notes are shown by 'git log', see the
-"notes.displayRef" discussion in <<CONFIGURATION>>.
+To change which notes are shown by `git log`, see the
+`notes.displayRef` discussion in <<CONFIGURATION,CONFIGURATION>>.
 
-See the "notes.rewrite.<command>" configuration for a way to carry
+See the `notes.rewrite.<command>` configuration for a way to carry
 notes across commands that rewrite commits.
 
 
 SUBCOMMANDS
 -----------
 
-list::
+`list`::
 	List the notes object for a given object. If no object is
 	given, show a list of all note objects and the objects they
-	annotate (in the format "<note-object> <annotated-object>").
+	annotate (in the format "`<note-object> <annotated-object>`").
 	This is the default subcommand if no subcommand is given.
 
-add::
-	Add notes for a given object (defaults to HEAD). Abort if the
+`add`::
+	Add notes for a given object (defaults to `HEAD`). Abort if the
 	object already has notes (use `-f` to overwrite existing notes).
 	However, if you're using `add` interactively (using an editor
 	to supply the notes contents), then - instead of aborting -
@@ -71,10 +71,10 @@ add::
 	fine-tune the message(s) supplied from `-m` and `-F` options
 	interactively (using an editor) before adding the note.
 
-copy::
+`copy`::
 	Copy the notes for the first object onto the second object (defaults to
-	HEAD). Abort if the second object already has notes, or if the first
-	object has none (use -f to overwrite existing notes to the
+	`HEAD`). Abort if the second object already has notes, or if the first
+	object has none (use `-f` to overwrite existing notes to the
 	second object). This subcommand is equivalent to:
 	`git notes add [-f] -C $(git notes list <from-object>) <to-object>`
 +
@@ -84,27 +84,30 @@ In `--stdin` mode, take lines in the format
 <from-object> SP <to-object> [ SP <rest> ] LF
 ----------
 +
-on standard input, and copy the notes from each <from-object> to its
-corresponding <to-object>.  (The optional `<rest>` is ignored so that
+on standard input, and copy the notes from each _<from-object>_ to its
+corresponding _<to-object>_.  (The optional _<rest>_ is ignored so that
 the command can read the input given to the `post-rewrite` hook.)
++
+`--stdin` cannot be combined with object names given on the command
+line.
 
-append::
+`append`::
 	Append new message(s) given by `-m` or `-F` options to an
 	existing note, or add them as a new note if one does not
-	exist, for the object (defaults to HEAD).  When appending to
+	exist, for the object (defaults to `HEAD`).  When appending to
 	an existing note, a blank line is added before each new
 	message as an inter-paragraph separator.  The separator can
 	be customized with the `--separator` option.
 	Edit the notes to be appended given by `-m` and `-F` options with
 	`-e` interactively (using an editor) before appending the note.
 
-edit::
-	Edit the notes for a given object (defaults to HEAD).
+`edit`::
+	Edit the notes for a given object (defaults to `HEAD`).
 
-show::
-	Show the notes for a given object (defaults to HEAD).
+`show`::
+	Show the notes for a given object (defaults to `HEAD`).
 
-merge::
+`merge`::
 	Merge the given notes ref into the current notes ref.
 	This will try to merge the changes made by the given
 	notes ref (called "remote") since the merge-base (if
@@ -112,131 +115,139 @@ merge::
 +
 If conflicts arise and a strategy for automatically resolving
 conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given,
-the "manual" resolver is used. This resolver checks out the
+the `manual` resolver is used. This resolver checks out the
 conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`),
 and instructs the user to manually resolve the conflicts there.
 When done, the user can either finalize the merge with
-'git notes merge --commit', or abort the merge with
-'git notes merge --abort'.
+`git notes merge --commit`, or abort the merge with
+`git notes merge --abort`.
 
-remove::
-	Remove the notes for given objects (defaults to HEAD). When
+`remove`::
+	Remove the notes for given objects (defaults to `HEAD`). When
 	giving zero or one object from the command line, this is
 	equivalent to specifying an empty note message to
 	the `edit` subcommand.
++
+In `--stdin` mode, also remove the object names given on standard
+input. In other words, `--stdin` can be combined with object names from
+the command line.
 
-prune::
+`prune`::
 	Remove all notes for non-existing/unreachable objects.
 
-get-ref::
+`get-ref`::
 	Print the current notes ref. This provides an easy way to
 	retrieve the current notes ref (e.g. from scripts).
 
 OPTIONS
 -------
--f::
---force::
+`-f`::
+`--force`::
 	When adding notes to an object that already has notes,
 	overwrite the existing notes (instead of aborting).
 
--m <msg>::
---message=<msg>::
+`-m <msg>`::
+`--message=<msg>`::
 	Use the given note message (instead of prompting).
 	If multiple `-m` options are given, their values
 	are concatenated as separate paragraphs.
-	Lines starting with `#` and empty lines other than a
-	single line between paragraphs will be stripped out.
-	If you wish to keep them verbatim, use `--no-stripspace`.
 
--F <file>::
---file=<file>::
-	Take the note message from the given file.  Use '-' to
+`-F <file>`::
+`--file=<file>`::
+	Take the note message from the given file.  Use `-` to
 	read the note message from the standard input.
-	Lines starting with `#` and empty lines other than a
-	single line between paragraphs will be stripped out.
-	If you wish to keep them verbatim, use `--no-stripspace`.
 
--C <object>::
---reuse-message=<object>::
+`-C <object>`::
+`--reuse-message=<object>`::
 	Take the given blob object (for example, another note) as the
 	note message. (Use `git notes copy <object>` instead to
-	copy notes between objects.).  By default, message will be
-	copied verbatim, but if you wish to strip out the lines
-	starting with `#` and empty lines other than a single line
-	between paragraphs, use with`--stripspace` option.
-
--c <object>::
---reedit-message=<object>::
-	Like '-C', but with `-c` the editor is invoked, so that
+	copy notes between objects.)  Implies `--no-stripspace` since
+	the default behavior is to copy the message verbatim.
+
+`-c <object>`::
+`--reedit-message=<object>`::
+	Like `-C`, but with `-c` the editor is invoked, so that
 	the user can further edit the note message.
 
---allow-empty::
+`--allow-empty`::
 	Allow an empty note object to be stored. The default behavior is
 	to automatically remove empty notes.
 
---[no-]separator, --separator=<paragraph-break>::
+`--separator=<paragraph-break>`::
+`--separator`::
+`--no-separator`::
 	Specify a string used as a custom inter-paragraph separator
 	(a newline is added at the end as needed). If `--no-separator`, no
 	separators will be added between paragraphs.  Defaults to a blank
 	line.
 
---[no-]stripspace::
-	Strip leading and trailing whitespace from the note message.
-	Also strip out empty lines other than a single line between
-	paragraphs. Lines starting with `#` will be stripped out
-	in non-editor cases like `-m`, `-F` and `-C`, but not in
-	editor case like `git notes edit`, `-c`, etc.
-
---ref <ref>::
-	Manipulate the notes tree in <ref>.  This overrides
-	`GIT_NOTES_REF` and the "core.notesRef" configuration.  The ref
+`--stripspace`::
+`--no-stripspace`::
+	Clean up whitespace. Specifically (see
+	linkgit:git-stripspace[1]):
++
+--
+- remove trailing whitespace from all lines
+- collapse multiple consecutive empty lines into one empty line
+- remove empty lines from the beginning and end of the input
+- add a missing `\n` to the last line if necessary.
+--
++
+`--stripspace` is the default except for
+`-C`/`--reuse-message`. However, keep in mind that this depends on the
+order of similar options. For example, for `-C <object> -m<message>`,
+`--stripspace` will be used because the default for `-m` overrides the
+previous `-C`. This is a known limitation that may be fixed in the
+future.
+
+`--ref=<ref>`::
+	Manipulate the notes tree in _<ref>_.  This overrides
+	`GIT_NOTES_REF` and the `core.notesRef` configuration.  The ref
 	specifies the full refname when it begins with `refs/notes/`; when it
 	begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed
 	to form a full name of the ref.
 
---ignore-missing::
+`--ignore-missing`::
 	Do not consider it an error to request removing notes from an
 	object that does not have notes attached to it.
 
---stdin::
-	Also read the object names to remove notes from the standard
-	input (there is no reason you cannot combine this with object
-	names from the command line).
+`--stdin`::
+	Only valid for `remove` and `copy`. See the respective subcommands.
 
--n::
---dry-run::
+`-n`::
+`--dry-run`::
 	Do not remove anything; just report the object names whose notes
 	would be removed.
 
--s <strategy>::
---strategy=<strategy>::
+`-s <strategy>`::
+`--strategy=<strategy>`::
 	When merging notes, resolve notes conflicts using the given
-	strategy. The following strategies are recognized: "manual"
-	(default), "ours", "theirs", "union" and "cat_sort_uniq".
-	This option overrides the "notes.mergeStrategy" configuration setting.
+	strategy. The following strategies are recognized: `manual`
+	(default), `ours`, `theirs`, `union` and `cat_sort_uniq`.
+	This option overrides the `notes.mergeStrategy` configuration setting.
 	See the "NOTES MERGE STRATEGIES" section below for more
 	information on each notes merge strategy.
 
---commit::
-	Finalize an in-progress 'git notes merge'. Use this option
-	when you have resolved the conflicts that 'git notes merge'
-	stored in .git/NOTES_MERGE_WORKTREE. This amends the partial
-	merge commit created by 'git notes merge' (stored in
-	.git/NOTES_MERGE_PARTIAL) by adding the notes in
-	.git/NOTES_MERGE_WORKTREE. The notes ref stored in the
-	.git/NOTES_MERGE_REF symref is updated to the resulting commit.
-
---abort::
-	Abort/reset an in-progress 'git notes merge', i.e. a notes merge
+`--commit`::
+	Finalize an in-progress `git notes merge`. Use this option
+	when you have resolved the conflicts that `git notes merge`
+	stored in `.git/NOTES_MERGE_WORKTREE`. This amends the partial
+	merge commit created by `git notes merge` (stored in
+	`.git/NOTES_MERGE_PARTIAL`) by adding the notes in
+	`.git/NOTES_MERGE_WORKTREE`. The notes ref stored in the
+	`.git/NOTES_MERGE_REF` symref is updated to the resulting commit.
+
+`--abort`::
+	Abort/reset an in-progress `git notes merge`, i.e. a notes merge
 	with conflicts. This simply removes all files related to the
 	notes merge.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	When merging notes, operate quietly.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	When merging notes, be more verbose.
 	When pruning notes, report all object names whose notes are
 	removed.
@@ -270,28 +281,28 @@ object, in which case the history of the notes can be read with
 NOTES MERGE STRATEGIES
 ----------------------
 
-The default notes merge strategy is "manual", which checks out
+The default notes merge strategy is `manual`, which checks out
 conflicting notes in a special work tree for resolving notes conflicts
 (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the
 conflicts in that work tree.
 When done, the user can either finalize the merge with
-'git notes merge --commit', or abort the merge with
-'git notes merge --abort'.
+`git notes merge --commit`, or abort the merge with
+`git notes merge --abort`.
 
 Users may select an automated merge strategy from among the following using
-either -s/--strategy option or configuring notes.mergeStrategy accordingly:
+either `-s`/`--strategy` option or configuring `notes.mergeStrategy` accordingly:
 
-"ours" automatically resolves conflicting notes in favor of the local
+`ours` automatically resolves conflicting notes in favor of the local
 version (i.e. the current notes ref).
 
-"theirs" automatically resolves notes conflicts in favor of the remote
+`theirs` automatically resolves notes conflicts in favor of the remote
 version (i.e. the given notes ref being merged into the current notes
 ref).
 
-"union" automatically resolves notes conflicts by concatenating the
+`union` automatically resolves notes conflicts by concatenating the
 local and remote versions.
 
-"cat_sort_uniq" is similar to "union", but in addition to concatenating
+`cat_sort_uniq` is similar to `union`, but in addition to concatenating
 the local and remote versions, this strategy also sorts the resulting
 lines, and removes duplicate lines from the result. This is equivalent
 to applying the "cat | sort | uniq" shell pipeline to the local and
@@ -320,7 +331,7 @@ Notes:
 
 In principle, a note is a regular Git blob, and any kind of
 (non-)format is accepted.  You can binary-safely create notes from
-arbitrary files using 'git hash-object':
+arbitrary files using `git hash-object`:
 
 ------------
 $ cc *.c
@@ -331,7 +342,7 @@ $ git notes --ref=built add --allow-empty -C "$blob" HEAD
 (You cannot simply use `git notes --ref=built add -F a.out HEAD`
 because that is not binary-safe.)
 Of course, it doesn't make much sense to display non-text-format notes
-with 'git log', so if you use such notes, you'll probably need to write
+with `git log`, so if you use such notes, you'll probably need to write
 some special-purpose tools to do something useful with them.
 
 
@@ -339,15 +350,15 @@ some special-purpose tools to do something useful with them.
 CONFIGURATION
 -------------
 
-core.notesRef::
+`core.notesRef`::
 	Notes ref to read and manipulate instead of
 	`refs/notes/commits`.  Must be an unabbreviated ref name.
 	This setting can be overridden through the environment and
 	command line.
 
-include::includes/cmd-config-section-rest.txt[]
+include::includes/cmd-config-section-rest.adoc[]
 
-include::config/notes.txt[]
+include::config/notes.adoc[]
 
 
 ENVIRONMENT
diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.adoc
index de5ee6748e..59edd24134 100644
--- a/Documentation/git-p4.txt
+++ b/Documentation/git-p4.adoc
@@ -66,6 +66,7 @@ Clone
 ~~~~~
 Generally, 'git p4 clone' is used to create a new Git directory
 from an existing p4 repository:
+
 ------------
 $ git p4 clone //depot/path/project
 ------------
@@ -80,6 +81,7 @@ This:
 
 To reproduce the entire p4 history in Git, use the '@all' modifier on
 the depot path:
+
 ------------
 $ git p4 clone //depot/path/project@all
 ------------
@@ -89,19 +91,23 @@ Sync
 ~~~~
 As development continues in the p4 repository, those changes can
 be included in the Git repository using:
+
 ------------
 $ git p4 sync
 ------------
+
 This command finds new changes in p4 and imports them as Git commits.
 
 P4 repositories can be added to an existing Git repository using
 'git p4 sync' too:
+
 ------------
 $ mkdir repo-git
 $ cd repo-git
 $ git init
 $ git p4 sync //path/in/your/perforce/depot
 ------------
+
 This imports the specified depot into
 'refs/remotes/p4/master' in an existing Git repository.  The
 `--branch` option can be used to specify a different branch to
@@ -125,6 +131,7 @@ and merge them with local uncommitted changes.  Often, the p4 repository
 is the ultimate location for all code, thus a rebase workflow makes
 sense.  This command does 'git p4 sync' followed by 'git rebase' to move
 local commits on top of updated p4 changes.
+
 ------------
 $ git p4 rebase
 ------------
@@ -140,16 +147,19 @@ will be created and populated if it does not already exist.
 
 To submit all changes that are in the current Git branch but not in
 the 'p4/master' branch, use:
+
 ------------
 $ git p4 submit
 ------------
 
 To specify a branch other than the current one, use:
+
 ------------
 $ git p4 submit topicbranch
 ------------
 
 To specify a single commit or a range of commits, use:
+
 ------------
 $ git p4 submit --commit <sha1>
 $ git p4 submit --commit <sha1..sha1>
@@ -510,20 +520,24 @@ when cloning or syncing to have 'git p4' automatically find
 subdirectories in p4, and to generate these as branches in Git.
 
 For example, if the P4 repository structure is:
+
 ----
 //depot/main/...
 //depot/branch1/...
 ----
 
 And "p4 branch -o branch1" shows a View line that looks like:
+
 ----
 //depot/main/... //depot/branch1/...
 ----
 
 Then this 'git p4 clone' command:
+
 ----
 git p4 clone --detect-branches //depot@all
 ----
+
 produces a separate branch in 'refs/remotes/p4/' for //depot/main,
 called 'master', and one for //depot/branch1 called 'depot/branch1'.
 
@@ -536,6 +550,7 @@ simple p4 branch specification, where the "source" and "destination" are
 the path elements in the p4 repository.  The example above relied on the
 presence of the p4 branch.  Without p4 branches, the same result will
 occur with:
+
 ----
 git init depot
 cd depot
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.adoc
index e32404c6aa..71b9682485 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.adoc
@@ -10,12 +10,13 @@ SYNOPSIS
 --------
 [verse]
 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]
-	[--no-reuse-delta] [--delta-base-offset] [--non-empty]
-	[--local] [--incremental] [--window=<n>] [--depth=<n>]
-	[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]
-	[--cruft] [--cruft-expiration=<time>]
-	[--stdout [--filter=<filter-spec>] | <base-name>]
-	[--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list>
+		   [--no-reuse-delta] [--delta-base-offset] [--non-empty]
+		   [--local] [--incremental] [--window=<n>] [--depth=<n>]
+		   [--revs [--unpacked | --all]] [--keep-pack=<pack-name>]
+		   [--cruft] [--cruft-expiration=<time>]
+		   [--stdout [--filter=<filter-spec>] | <base-name>]
+		   [--shallow] [--keep-true-parents] [--[no-]sparse]
+		   [--name-hash-version=<n>] [--path-walk] < <object-list>
 
 
 DESCRIPTION
@@ -86,13 +87,21 @@ base-name::
 	reference was included in the resulting packfile.  This
 	can be useful to send new tags to native Git clients.
 
---stdin-packs::
+--stdin-packs[=<mode>]::
 	Read the basenames of packfiles (e.g., `pack-1234abcd.pack`)
 	from the standard input, instead of object names or revision
 	arguments. The resulting pack contains all objects listed in the
 	included packs (those not beginning with `^`), excluding any
 	objects listed in the excluded packs (beginning with `^`).
 +
+When `mode` is "follow", objects from packs not listed on stdin receive
+special treatment. Objects within unlisted packs will be included if
+those objects are (1) reachable from the included packs, and (2) not
+found in any excluded packs. This mode is useful, for example, to
+resurrect once-unreachable objects found in cruft packs to generate
+packs which are closed under reachability up to the boundary set by the
+excluded packs.
++
 Incompatible with `--revs`, or options that imply `--revs` (such as
 `--all`), with the exception of `--unpacked`, which is compatible.
 
@@ -234,7 +243,8 @@ depth is 4095.
 	Add --no-reuse-object if you want to force a uniform compression
 	level on all data no matter the source.
 
---[no-]sparse::
+--sparse::
+--no-sparse::
 	Toggle the "sparse" algorithm to determine which objects to include in
 	the pack, when combined with the "--revs" option. This algorithm
 	only walks trees that appear in paths that introduce new objects.
@@ -345,6 +355,46 @@ raise an error.
 	Restrict delta matches based on "islands". See DELTA ISLANDS
 	below.
 
+--name-hash-version=<n>::
+	While performing delta compression, Git groups objects that may be
+	similar based on heuristics using the path to that object. While
+	grouping objects by an exact path match is good for paths with
+	many versions, there are benefits for finding delta pairs across
+	different full paths. Git collects objects by type and then by a
+	"name hash" of the path and then by size, hoping to group objects
+	that will compress well together.
++
+The default name hash version is `1`, which prioritizes hash locality by
+considering the final bytes of the path as providing the maximum magnitude
+to the hash function. This version excels at distinguishing short paths
+and finding renames across directories. However, the hash function depends
+primarily on the final 16 bytes of the path. If there are many paths in
+the repo that have the same final 16 bytes and differ only by parent
+directory, then this name-hash may lead to too many collisions and cause
+poor results. At the moment, this version is required when writing
+reachability bitmap files with `--write-bitmap-index`.
++
+The name hash version `2` has similar locality features as version `1`,
+except it considers each path component separately and overlays the hashes
+with a shift. This still prioritizes the final bytes of the path, but also
+"salts" the lower bits of the hash using the parent directory names. This
+method allows for some of the locality benefits of version `1` while
+breaking most of the collisions from a similarly-named file appearing in
+many different directories. At the moment, this version is not allowed
+when writing reachability bitmap files with `--write-bitmap-index` and it
+will be automatically changed to version `1`.
+
+--path-walk::
+	Perform compression by first organizing objects by path, then a
+	second pass that compresses across paths as normal. This has the
+	potential to improve delta compression especially in the presence
+	of filenames that cause collisions in Git's default name-hash
+	algorithm.
++
+Incompatible with `--delta-islands`, `--shallow`, or `--filter`. The
+`--use-bitmap-index` option will be ignored in the presence of
+`--path-walk.`
+
 
 DELTA ISLANDS
 -------------
diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.adoc
index 13c3eb5ec9..13c3eb5ec9 100644
--- a/Documentation/git-pack-redundant.txt
+++ b/Documentation/git-pack-redundant.adoc
diff --git a/Documentation/git-pack-refs.adoc b/Documentation/git-pack-refs.adoc
new file mode 100644
index 0000000000..fde9f2f294
--- /dev/null
+++ b/Documentation/git-pack-refs.adoc
@@ -0,0 +1,61 @@
+git-pack-refs(1)
+================
+
+NAME
+----
+git-pack-refs - Pack heads and tags for efficient repository access
+
+SYNOPSIS
+--------
+[verse]
+'git pack-refs' [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]
+
+DESCRIPTION
+-----------
+
+Traditionally, tips of branches and tags (collectively known as
+'refs') were stored one file per ref in a (sub)directory
+under `$GIT_DIR/refs`
+directory.  While many branch tips tend to be updated often,
+most tags and some branch tips are never updated.  When a
+repository has hundreds or thousands of tags, this
+one-file-per-ref format both wastes storage and hurts
+performance.
+
+This command is used to solve the storage and performance
+problem by storing the refs in a single file,
+`$GIT_DIR/packed-refs`.  When a ref is missing from the
+traditional `$GIT_DIR/refs` directory hierarchy, it is looked
+up in this
+file and used if found.
+
+Subsequent updates to branches always create new files under
+`$GIT_DIR/refs` directory hierarchy.
+
+A recommended practice to deal with a repository with too many
+refs is to pack its refs with `--all` once, and
+occasionally run `git pack-refs`.  Tags are by
+definition stationary and are not expected to change.  Branch
+heads will be packed with the initial `pack-refs --all`, but
+only the currently active branch heads will become unpacked,
+and the next `pack-refs` (without `--all`) will leave them
+unpacked.
+
+
+OPTIONS
+-------
+
+include::pack-refs-options.adoc[]
+
+
+BUGS
+----
+
+Older documentation written before the packed-refs mechanism was
+introduced may still say things like ".git/refs/heads/<branch> file
+exists" when it means "branch <branch> exists".
+
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.adoc
index 1d15fa45d5..92a1af36a2 100644
--- a/Documentation/git-patch-id.txt
+++ b/Documentation/git-patch-id.adoc
@@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch
 
 SYNOPSIS
 --------
-[verse]
-'git patch-id' [--stable | --unstable | --verbatim]
+[synopsis]
+git patch-id [--stable | --unstable | --verbatim]
 
 DESCRIPTION
 -----------
@@ -21,7 +21,7 @@ the same time also reasonably unique, i.e., two patches that have the same
 
 The main usecase for this command is to look for likely duplicate commits.
 
-When dealing with 'git diff-tree' output, it takes advantage of
+When dealing with `git diff-tree` output, it takes advantage of
 the fact that the patch is prefixed with the object name of the
 commit, and outputs two 40-byte hexadecimal strings.  The first
 string is the patch ID, and the second string is the commit ID.
@@ -30,39 +30,42 @@ This can be used to make a mapping from patch ID to commit ID.
 OPTIONS
 -------
 
---verbatim::
+`--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`.
 
-	This is the default if patchid.verbatim is true.
-
---stable::
+`--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.
-	   In particular, two patches produced by comparing the same two trees
-	   with two different settings for "-O<orderfile>" result in the same
-	   patch ID signature, thereby allowing the computed result to be used
-	   as a key to index some meta-information about the change between
-	   the two trees;
-
-	 - Result is different from the value produced by git 1.9 and older
-	   or produced when an "unstable" hash (see --unstable below) is
-	   configured - even when used on a diff output taken without any use
-	   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::
++
+--
+- Reordering file diffs that make up a patch does not affect the ID.
+  In particular, two patches produced by comparing the same two trees
+  with two different settings for `-O<orderfile>` result in the same
+  patch ID signature, thereby allowing the computed result to be used
+  as a key to index some meta-information about the change between
+  the two trees;
+
+- Result is different from the value produced by git 1.9 and older
+  or produced when an "unstable" hash (see `--unstable` below) is
+  configured - even when used on a diff output taken without any use
+  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 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.
++
+This is the default.
 
 GIT
 ---
diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.adoc
index db742dcfee..db742dcfee 100644
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.adoc
diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.adoc
index 9a45571b90..9a45571b90 100644
--- a/Documentation/git-prune.txt
+++ b/Documentation/git-prune.adoc
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.adoc
index b2ae496e48..cd3bbc90e3 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.adoc
@@ -15,68 +15,54 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Incorporates changes from a remote repository into the current branch.
-If the current branch is behind the remote, then by default it will
-fast-forward the current branch to match the remote.  If the current
-branch and the remote have diverged, the user needs to specify how to
-reconcile the divergent branches with `--rebase` or `--no-rebase` (or
-the corresponding configuration option in `pull.rebase`).
-
-More precisely, `git pull` runs `git fetch` with the given parameters
-and then depending on configuration options or command line flags,
-will call either `git rebase` or `git merge` to reconcile diverging
-branches.
-
-<repository> should be the name of a remote repository as
-passed to linkgit:git-fetch[1].  <refspec> can name an
-arbitrary remote ref (for example, the name of a tag) or even
-a collection of refs with corresponding remote-tracking branches
-(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}),
-but usually it is the name of a branch in the remote repository.
-
-Default values for <repository> and <branch> are read from the
-"remote" and "merge" configuration for the current branch
-as set by linkgit:git-branch[1] `--track`.
-
-Assume the following history exists and the current branch is
-"`master`":
+Integrate changes from a remote repository into the current branch.
 
-------------
-	  A---B---C master on origin
-	 /
-    D---E---F---G master
-	^
-	origin/master in your repository
-------------
+First, `git pull` runs `git fetch` with the same arguments
+(excluding merge options) to fetch remote branch(es).
+Then it decides which remote branch to integrate: if you run `git pull`
+with no arguments this defaults to the <<UPSTREAM-BRANCHES,upstream>>
+for the current branch.
+Then it integrates that branch into the current branch.
 
-Then "`git pull`" will fetch and replay the changes from the remote
-`master` branch since it diverged from the local `master` (i.e., `E`)
-until its current commit (`C`) on top of `master` and record the
-result in a new commit along with the names of the two parent commits
-and a log message from the user describing the changes.
-
-------------
-	  A---B---C origin/master
-	 /         \
-    D---E---F---G---H master
-------------
+There are 4 main options for integrating the remote branch:
 
-See linkgit:git-merge[1] for details, including how conflicts
-are presented and handled.
+1. `git pull --ff-only` will only do "fast-forward" updates: it
+   fails if your local branch has diverged from the remote branch.
+   This is the default.
+2. `git pull --rebase` runs `git rebase`
+3. `git pull --no-rebase` runs `git merge`.
+4. `git pull --squash` runs `git merge --squash`
 
-In Git 1.7.0 or later, to cancel a conflicting merge, use
-`git reset --merge`.  *Warning*: In older versions of Git, running 'git pull'
-with uncommitted changes is discouraged: while possible, it leaves you
-in a state that may be hard to back out of in the case of a conflict.
+You can also set the configuration options `pull.rebase`, `pull.squash`,
+or `pull.ff` with your preferred behaviour.
 
-If any of the remote changes overlap with local uncommitted changes,
-the merge will be automatically canceled and the work tree untouched.
-It is generally best to get any local changes in working order before
-pulling or stash them away with linkgit:git-stash[1].
+If there's a merge conflict during the merge or rebase that you don't
+want to handle, you can safely abort it with `git merge --abort` or `git
+--rebase abort`.
 
 OPTIONS
 -------
 
+<repository>::
+	The "remote" repository to pull from.  This can be either
+	a URL (see the section <<URLS,GIT URLS>> below) or the name
+	of a remote (see the section <<REMOTES,REMOTES>> below).
++
+Defaults to the configured upstream for the current branch, or `origin`.
+See <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> below for more on how to
+configure upstreams.
+
+<refspec>::
+	Which branch or other reference(s) to fetch and integrate into the
+	current branch, for example `main` in `git pull origin main`.
+	Defaults to the configured upstream for the current branch.
++
+This can be a branch, tag, or other collection of reference(s).
+See <<fetch-refspec,<refspec>>> below under "Options related to fetching"
+for the full syntax, and <<DEFAULT-BEHAVIOUR,DEFAULT BEHAVIOUR>> below
+for how `git pull` uses this argument to determine which remote branch
+to integrate.
+
 -q::
 --quiet::
 	This is passed to both underlying git-fetch to squelch reporting of
@@ -87,7 +73,8 @@ OPTIONS
 --verbose::
 	Pass --verbose to git-fetch and git-merge.
 
---[no-]recurse-submodules[=(yes|on-demand|no)]::
+--recurse-submodules[=(yes|on-demand|no)]::
+--no-recurse-submodules::
 	This option controls if new commits of populated submodules should
 	be fetched, and if the working trees of active submodules should be
 	updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and
@@ -102,7 +89,7 @@ Options related to merging
 
 :git-pull: 1
 
-include::merge-options.txt[]
+include::merge-options.adoc[]
 
 -r::
 --rebase[=(false|true|merges|interactive)]::
@@ -136,14 +123,15 @@ unless you have read linkgit:git-rebase[1] carefully.
 Options related to fetching
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-include::fetch-options.txt[]
+include::fetch-options.adoc[]
 
-include::pull-fetch-param.txt[]
+include::pull-fetch-param.adoc[]
 
-include::urls-remotes.txt[]
+include::urls-remotes.adoc[]
 
-include::merge-strategies.txt[]
+include::merge-strategies.adoc[]
 
+[[DEFAULT-BEHAVIOUR]]
 DEFAULT BEHAVIOUR
 -----------------
 
@@ -234,7 +222,7 @@ If you tried a pull which resulted in complex conflicts and
 would want to start over, you can recover with 'git reset'.
 
 
-include::transfer-data-leaks.txt[]
+include::transfer-data-leaks.adoc[]
 
 BUGS
 ----
diff --git a/Documentation/git-push.txt b/Documentation/git-push.adoc
index 9b7cfbc5c1..864b0d0467 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.adoc
@@ -19,30 +19,35 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Updates remote refs using local refs, while sending objects
-necessary to complete the given refs.
+Updates one or more branches, tags, or other references in a remote
+repository from your local repository, and sends all necessary data
+that isn't already on the remote.
 
-You can make interesting things happen to a repository
-every time you push into it, by setting up 'hooks' there.  See
-documentation for linkgit:git-receive-pack[1].
+The simplest way to push is `git push <remote> <branch>`.
+`git push origin main` will push the local `main` branch to the `main`
+branch on the remote named `origin`.
 
-When the command line does not specify where to push with the
-`<repository>` argument, `branch.*.remote` configuration for the
-current branch is consulted to determine where to push.  If the
-configuration is missing, it defaults to 'origin'.
+The `<repository>` argument defaults to the upstream for the current branch,
+or `origin` if there's no configured upstream.
 
-When the command line does not specify what to push with `<refspec>...`
-arguments or `--all`, `--mirror`, `--tags` options, the command finds
-the default `<refspec>` by consulting `remote.*.push` configuration,
-and if it is not found, honors `push.default` configuration to decide
-what to push (See linkgit:git-config[1] for the meaning of `push.default`).
+To decide which branches, tags, or other refs to push, Git uses
+(in order of precedence):
 
-When neither the command-line nor the configuration specifies what to
-push, the default behavior is used, which corresponds to the `simple`
-value for `push.default`: the current branch is pushed to the
-corresponding upstream branch, but as a safety measure, the push is
-aborted if the upstream branch does not have the same name as the
-local one.
+1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
+   or the `--all`, `--mirror`, or `--tags` options
+2. The `remote.*.push` configuration for the repository being pushed to
+3. The `push.default` configuration. The default is `push.default=simple`,
+   which will push to a branch with the same name as the current branch.
+   See the <<CONFIGURATION,CONFIGURATION>> section below for more on `push.default`.
+
+`git push` may fail if you haven't set an upstream for the current branch,
+depending on what `push.default` is set to.
+See the <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> section below for more
+on how to set and use upstreams.
+
+You can make interesting things happen to a repository
+every time you push into it, by setting up 'hooks' there.  See
+documentation for linkgit:git-receive-pack[1].
 
 
 OPTIONS[[OPTIONS]]
@@ -55,96 +60,66 @@ OPTIONS[[OPTIONS]]
 
 <refspec>...::
 	Specify what destination ref to update with what source object.
-	The format of a <refspec> parameter is an optional plus
-	`+`, followed by the source object <src>, followed
-	by a colon `:`, followed by the destination ref <dst>.
-+
-The <src> is often the name of the branch you would want to push, but
-it can be any arbitrary "SHA-1 expression", such as `master~4` or
-`HEAD` (see linkgit:gitrevisions[7]).
-+
-The <dst> tells which ref on the remote side is updated with this
-push. Arbitrary expressions cannot be used here, an actual ref must
-be named.
-If `git push [<repository>]` without any `<refspec>` argument is set to
-update some ref at the destination with `<src>` with
-`remote.<repository>.push` configuration variable, `:<dst>` part can
-be omitted--such a push will update a ref that `<src>` normally updates
-without any `<refspec>` on the command line.  Otherwise, missing
-`:<dst>` means to update the same ref as the `<src>`.
-+
-If <dst> doesn't start with `refs/` (e.g. `refs/heads/master`) we will
-try to infer where in `refs/*` on the destination <repository> it
-belongs based on the type of <src> being pushed and whether <dst>
-is ambiguous.
 +
---
-* If <dst> unambiguously refers to a ref on the <repository> remote,
-  then push to that ref.
-
-* If <src> resolves to a ref starting with refs/heads/ or refs/tags/,
-  then prepend that to <dst>.
-
-* Other ambiguity resolutions might be added in the future, but for
-  now any other cases will error out with an error indicating what we
-  tried, and depending on the `advice.pushUnqualifiedRefname`
-  configuration (see linkgit:git-config[1]) suggest what refs/
-  namespace you may have wanted to push to.
-
---
-+
-The object referenced by <src> is used to update the <dst> reference
-on the remote side. Whether this is allowed depends on where in
-`refs/*` the <dst> reference lives as described in detail below, in
-those sections "update" means any modifications except deletes, which
-as noted after the next few sections are treated differently.
-+
-The `refs/heads/*` namespace will only accept commit objects, and
-updates only if they can be fast-forwarded.
-+
-The `refs/tags/*` namespace will accept any kind of object (as
-commits, trees and blobs can be tagged), and any updates to them will
-be rejected.
-+
-It's possible to push any type of object to any namespace outside of
-`refs/{tags,heads}/*`. In the case of tags and commits, these will be
-treated as if they were the commits inside `refs/heads/*` for the
-purposes of whether the update is allowed.
-+
-I.e. a fast-forward of commits and tags outside `refs/{tags,heads}/*`
-is allowed, even in cases where what's being fast-forwarded is not a
-commit, but a tag object which happens to point to a new commit which
-is a fast-forward of the commit the last tag (or commit) it's
-replacing. Replacing a tag with an entirely different tag is also
-allowed, if it points to the same commit, as well as pushing a peeled
-tag, i.e. pushing the commit that existing tag object points to, or a
-new tag object which an existing commit points to.
-+
-Tree and blob objects outside of `refs/{tags,heads}/*` will be treated
-the same way as if they were inside `refs/tags/*`, any update of them
-will be rejected.
-+
-All of the rules described above about what's not allowed as an update
-can be overridden by adding an the optional leading `+` to a refspec
-(or using `--force` command line option). The only exception to this
-is that no amount of forcing will make the `refs/heads/*` namespace
-accept a non-commit object. Hooks and configuration can also override
-or amend these rules, see e.g. `receive.denyNonFastForwards` in
-linkgit:git-config[1] and `pre-receive` and `update` in
-linkgit:githooks[5].
-+
-Pushing an empty <src> allows you to delete the <dst> ref from the
-remote repository. Deletions are always accepted without a leading `+`
-in the refspec (or `--force`), except when forbidden by configuration
-or hooks. See `receive.denyDeletes` in linkgit:git-config[1] and
-`pre-receive` and `update` in linkgit:githooks[5].
-+
-The special refspec `:` (or `+:` to allow non-fast-forward updates)
-directs Git to push "matching" branches: for every branch that exists on
-the local side, the remote side is updated if a branch of the same name
-already exists on the remote side.
-+
-`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
+The format for a refspec is [+]<src>[:<dst>], for example `main`,
+`main:other`, or `HEAD^:refs/heads/main`.
++
+The `<src>` is often the name of the local branch to push, but it can be
+any arbitrary "SHA-1 expression" (see linkgit:gitrevisions[7]).
++
+The `<dst>` determines what ref to update on the remote side. It must be the
+name of a branch, tag, or other ref, not an arbitrary expression.
++
+The `+` is optional and does the same thing as `--force`.
++
+You can write a refspec using the fully expanded form (for
+example `refs/heads/main:refs/heads/main`) which specifies the exact source
+and destination, or with a shorter form (for example `main` or
+`main:other`). Here are the rules for how refspecs are expanded,
+as well as various other special refspec forms:
++
+ *  `<src>` without a `:<dst>` means to update the same ref as the
+    `<src>`, unless the `remote.<repository>.push` configuration specifies a
+    different <dst>. For example, if `main` is a branch, then the refspec
+    `main` expands to `main:refs/heads/main`.
+ *  If `<dst>` unambiguously refers to a ref on the <repository> remote,
+    then expand it to that ref. For example, if `v1.0` is a tag on the
+    remote, then `HEAD:v1.0` expands to `HEAD:refs/tags/v1.0`.
+ *  If `<src>` resolves to a ref starting with `refs/heads/` or `refs/tags/`,
+    then prepend that to <dst>. For example, if `main` is a branch, then
+    `main:other` expands to `main:refs/heads/other`
+ *  The special refspec `:` (or `+:` to allow non-fast-forward updates)
+    directs Git to push "matching" branches: for every branch that exists on
+    the local side, the remote side is updated if a branch of the same name
+    already exists on the remote side.
+ *  <src> may contain a * to indicate a simple pattern match.
+    This works like a glob that matches any ref matching the pattern.
+    There must be only one * in both the `<src>` and `<dst>`.
+    It will map refs to the destination by replacing the * with the
+    contents matched from the source. For example, `refs/heads/*:refs/heads/*`
+    will push all branches.
+ *  A refspec starting with `^` is a negative refspec.
+    This specifies refs to exclude. A ref will be considered to
+    match if it matches at least one positive refspec, and does not
+    match any negative refspec. Negative refspecs can be pattern refspecs.
+    They must only contain a `<src>`.
+    Fully spelled out hex object names are also not supported.
+    For example, `git push origin 'refs/heads/*' '^refs/heads/dev-*'`
+    will push all branches except for those starting with `dev-`
+ *  If `<src>` is empty, it deletes the `<dst>` ref from the remote
+    repository. For example, `git push origin :dev` will
+    delete the `dev` branch.
+ *  `tag <tag>` expands to `refs/tags/<tag>:refs/tags/<tag>`.
+	This is technically a special syntax for `git push` and not a refspec,
+	since in `git push origin tag v1.0` the arguments `tag` and `v1.0`
+	are separate.
+ *  If the refspec can't be expanded unambiguously, error out
+    with an error indicating what was tried, and depending
+    on the `advice.pushUnqualifiedRefname` configuration (see
+    linkgit:git-config[1]) suggest what refs/ namespace you may have
+    wanted to push to.
+
+Not all updates are allowed: see PUSH RULES below for the details.
 
 --all::
 --branches::
@@ -197,7 +172,8 @@ already exists on the remote side.
 	with configuration variable `push.followTags`.  For more
 	information, see `push.followTags` in linkgit:git-config[1].
 
---[no-]signed::
+--signed::
+--no-signed::
 --signed=(true|false|if-asked)::
 	GPG-sign the push request to update refs on the receiving
 	side, to allow it to be checked by the hooks and/or be
@@ -208,7 +184,8 @@ already exists on the remote side.
 	will also fail if the actual call to `gpg --sign` fails.  See
 	linkgit:git-receive-pack[1] for the details on the receiving end.
 
---[no-]atomic::
+--atomic::
+--no-atomic::
 	Use an atomic transaction on the remote side if available.
 	Either all refs are updated, or on error, no refs are updated.
 	If the server does not support atomic pushes the push will fail.
@@ -232,7 +209,8 @@ already exists on the remote side.
 	repository over ssh, and you do not have the program in
 	a directory on the default $PATH.
 
---[no-]force-with-lease::
+--force-with-lease::
+--no-force-with-lease::
 --force-with-lease=<refname>::
 --force-with-lease=<refname>:<expect>::
 	Usually, "git push" refuses to update a remote ref that is
@@ -332,14 +310,12 @@ allowing a forced update.
 
 -f::
 --force::
-	Usually, the command refuses to update a remote ref that is
-	not an ancestor of the local ref used to overwrite it.
-	Also, when `--force-with-lease` option is used, the command refuses
-	to update a remote ref whose current value does not match
-	what is expected.
+	Usually, `git push` will refuse to update a branch that is not an
+	ancestor of the commit being pushed.
 +
-This flag disables these checks, and can cause the remote repository
-to lose commits; use it with care.
+This flag disables that check, the other safety checks in PUSH RULES
+below, and the checks in --force-with-lease. It can cause the remote
+repository to lose commits; use it with care.
 +
 Note that `--force` applies to all the refs that are pushed, hence
 using it with `push.default` set to `matching` or with multiple push
@@ -350,7 +326,8 @@ one branch, use a `+` in front of the refspec to push (e.g `git push
 origin +master` to force a push to the `master` branch). See the
 `<refspec>...` section above for details.
 
---[no-]force-if-includes::
+--force-if-includes::
+--no-force-if-includes::
 	Force an update only if the tip of the remote-tracking ref
 	has been integrated locally.
 +
@@ -377,7 +354,8 @@ Specifying `--no-force-if-includes` disables this behavior.
 	linkgit:git-pull[1] and other commands. For more information,
 	see `branch.<name>.merge` in linkgit:git-config[1].
 
---[no-]thin::
+--thin::
+--no-thin::
 	These options are passed to linkgit:git-send-pack[1]. A thin transfer
 	significantly reduces the amount of sent data when the sender and
 	receiver share many of the same objects in common. The default is
@@ -419,7 +397,8 @@ When using 'on-demand' or 'only', if a submodule has a
 "push.recurseSubmodules={on-demand,only}" or "submodule.recurse" configuration,
 further recursion will occur. In this case, "only" is treated as "on-demand".
 
---[no-]verify::
+--verify::
+--no-verify::
 	Toggle the pre-push hook (see linkgit:githooks[5]).  The
 	default is --verify, giving the hook a chance to prevent the
 	push.  With --no-verify, the hook is bypassed completely.
@@ -432,7 +411,7 @@ further recursion will occur. In this case, "only" is treated as "on-demand".
 --ipv6::
 	Use IPv6 addresses only, ignoring IPv4 addresses.
 
-include::urls-remotes.txt[]
+include::urls-remotes.adoc[]
 
 OUTPUT
 ------
@@ -508,6 +487,45 @@ reason::
 	refs, no explanation is needed. For a failed ref, the reason for
 	failure is described.
 
+PUSH RULES
+----------
+
+As a safety feature, the `git push` command only allows certain kinds of
+updates to prevent you from accidentally losing data on the remote.
+
+Because branches and tags are intended to be used differently, the
+safety rules for pushing to a branch are different from the rules
+for pushing to a tag. In the following rules "update" means any
+modifications except deletions and creations. Deletions and creations
+are always allowed, except when forbidden by configuration or hooks.
+
+1. If the push destination is a **branch** (`refs/heads/*`): only
+   fast-forward updates are allowed, which means the destination must be
+   an ancestor of the source commit. The source must be a commit.
+2. If the push destination is a **tag** (`refs/tags/*`): all updates will
+   be rejected. The source can be any object.
+3. If the push destination is not a branch or tag:
+   * If the source is a tree or blob object, any updates will be rejected
+   * If the source is a tag or commit object, any fast-forward update
+     is allowed, even in cases where what's being fast-forwarded is not a
+     commit, but a tag object which happens to point to a new commit which
+     is a fast-forward of the commit the last tag (or commit) it's
+     replacing. Replacing a tag with an entirely different tag is also
+     allowed, if it points to the same commit, as well as pushing a peeled
+     tag, i.e. pushing the commit that existing tag object points to, or a
+     new tag object which an existing commit points to.
+
+You can override these rules by passing `--force` or by adding the
+optional leading `+` to a refspec. The only exceptions are that no
+amount of forcing will make a branch accept a non-commit object,
+and forcing won't make the remote repository accept a push that it's
+configured to deny.
+
+Hooks and configuration can also override or amend these rules,
+see e.g. `receive.denyNonFastForwards` and `receive.denyDeletes`
+in linkgit:git-config[1] and `pre-receive` and `update` in
+linkgit:githooks[5].
+
 NOTE ABOUT FAST-FORWARDS
 ------------------------
 
@@ -695,14 +713,15 @@ Commits A and B would no longer belong to a branch with a symbolic name,
 and so would be unreachable.  As such, these commits would be removed by
 a `git gc` command on the origin repository.
 
-include::transfer-data-leaks.txt[]
+include::transfer-data-leaks.adoc[]
 
+[[CONFIGURATION]]
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/push.txt[]
+include::config/push.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.adoc
index 40e02d92eb..40e02d92eb 100644
--- a/Documentation/git-quiltimport.txt
+++ b/Documentation/git-quiltimport.adoc
diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.adoc
index db0e4279b5..b5e85d37f1 100644
--- a/Documentation/git-range-diff.txt
+++ b/Documentation/git-range-diff.adoc
@@ -96,7 +96,8 @@ diff.
 --remerge-diff::
 	Convenience option, equivalent to `--diff-merges=remerge`.
 
---[no-]notes[=<ref>]::
+--notes[=<ref>]::
+--no-notes::
 	This flag is passed to the `git log` program
 	(see linkgit:git-log[1]) that generates the patches.
 
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.adoc
index 1c48c28996..1c04bba2b7 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.adoc
@@ -100,7 +100,8 @@ OPTIONS
 	directories the index file and index output file are
 	located in.
 
---[no-]recurse-submodules::
+--recurse-submodules::
+--no-recurse-submodules::
 	Using --recurse-submodules will update the content of all active
 	submodules according to the commit recorded in the superproject by
 	calling read-tree recursively, also setting the submodules' HEAD to be
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.adoc
index b18cdbc023..005caf6164 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.adoc
@@ -16,49 +16,12 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-If `<branch>` is specified, `git rebase` will perform an automatic
-`git switch <branch>` before doing anything else.  Otherwise
-it remains on the current branch.
+Transplant a series of commits onto a different starting point.
+You can also use `git rebase` to reorder or combine commits: see INTERACTIVE
+MODE below for how to do that.
 
-If `<upstream>` is not specified, the upstream configured in
-`branch.<name>.remote` and `branch.<name>.merge` options will be used (see
-linkgit:git-config[1] for details) and the `--fork-point` option is
-assumed.  If you are currently not on any branch or if the current
-branch does not have a configured upstream, the rebase will abort.
-
-All changes made by commits in the current branch but that are not
-in `<upstream>` are saved to a temporary area.  This is the same set
-of commits that would be shown by `git log <upstream>..HEAD`; or by
-`git log 'fork_point'..HEAD`, if `--fork-point` is active (see the
-description on `--fork-point` below); or by `git log HEAD`, if the
-`--root` option is specified.
-
-The current branch is reset to `<upstream>` or `<newbase>` if the
-`--onto` option was supplied.  This has the exact same effect as
-`git reset --hard <upstream>` (or `<newbase>`). `ORIG_HEAD` is set
-to point at the tip of the branch before the reset.
-
-[NOTE]
-`ORIG_HEAD` is not guaranteed to still point to the previous branch tip
-at the end of the rebase if other commands that write that pseudo-ref
-(e.g. `git reset`) are used during the rebase. The previous branch tip,
-however, is accessible using the reflog of the current branch
-(i.e. `@{1}`, see linkgit:gitrevisions[7]).
-
-The commits that were previously saved into the temporary area are
-then reapplied to the current branch, one by one, in order. Note that
-any commits in `HEAD` which introduce the same textual changes as a commit
-in `HEAD..<upstream>` are omitted (i.e., a patch already accepted upstream
-with a different commit message or timestamp will be skipped).
-
-It is possible that a merge failure will prevent this process from being
-completely automatic.  You will have to resolve any such merge failure
-and run `git rebase --continue`.  Another option is to bypass the commit
-that caused the merge failure with `git rebase --skip`.  To check out the
-original `<branch>` and remove the `.git/rebase-apply` working files, use
-the command `git rebase --abort` instead.
-
-Assume the following history exists and the current branch is "topic":
+For example, imagine that you have been working on the `topic` branch in this
+history, and you want to "catch up" to the work done on the `master` branch.
 
 ------------
           A---B---C topic
@@ -66,13 +29,11 @@ Assume the following history exists and the current branch is "topic":
     D---E---F---G master
 ------------
 
-From this point, the result of either of the following commands:
-
-
-    git rebase master
-    git rebase master topic
-
-would be:
+You want to transplant the commits you made on `topic` since it diverged from
+`master` (i.e. A, B, and C), on top of the current `master`.  You can do this
+by running `git rebase master` while the `topic` branch is checked out.  If you
+want to rebase `topic` while on another branch, `git rebase master topic` is a
+shortcut for `git checkout topic && git rebase master`.
 
 ------------
                   A'--B'--C' topic
@@ -80,30 +41,56 @@ would be:
     D---E---F---G master
 ------------
 
-*NOTE:* The latter form is just a short-hand of `git checkout topic`
-followed by `git rebase master`. When rebase exits `topic` will
-remain the checked-out branch.
 
-If the upstream branch already contains a change you have made (e.g.,
-because you mailed a patch which was applied upstream), then that commit
-will be skipped and warnings will be issued (if the 'merge' backend is
-used).  For example, running `git rebase master` on the following
-history (in which `A'` and `A` introduce the same set of changes, but
-have different committer information):
+If there is a merge conflict during this process, `git rebase` will stop at the
+first problematic commit and leave conflict markers. If this happens, you can do
+one of these things:
 
-------------
-          A---B---C topic
-         /
-    D---E---A'---F master
-------------
+1. Resolve the conflict. You can use `git diff` to find the markers (<<<<<<)
+   and make edits to resolve the conflict. For each file you edit, you need to
+   tell Git that the conflict has been resolved. You can mark the conflict as
+   resolved with  `git add <filename>`. After resolving all of the conflicts,
+   you can continue the rebasing process with
 
-will result in:
+   git rebase --continue
 
-------------
-                   B'---C' topic
-                  /
-    D---E---A'---F master
-------------
+2. Stop the `git rebase` and return your branch to its original state with
+
+   git rebase --abort
+
+3. Skip the commit that caused the merge conflict with
+
+   git rebase --skip
+
+If you don't specify an `<upstream>` to rebase onto, the upstream configured in
+`branch.<name>.remote` and `branch.<name>.merge` options will be used (see
+linkgit:git-config[1] for details) and the `--fork-point` option is
+assumed.  If you are currently not on any branch or if the current
+branch does not have a configured upstream, the rebase will abort.
+
+Here is a simplified description of what `git rebase <upstream>` does:
+
+1. Make a list of all commits on your current branch since it branched
+   off from `<upstream>` that do not have an equivalent commit in
+   `<upstream>`.
+2. Check out `<upstream>` with the equivalent of
+   `git checkout --detach <upstream>`.
+3. Replay the commits, one by one, in order. This is similar to running
+   `git cherry-pick <commit>` for each commit. See REBASING MERGES for how merges
+   are handled.
+4. Update your branch to point to the final commit with the equivalent
+   of `git checkout -B <branch>`.
+
+[NOTE]
+When starting the rebase, `ORIG_HEAD` is set to point to the commit at the tip
+of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still
+point to that commit at the end of the rebase if other commands that change
+`ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch
+tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`,
+see linkgit:gitrevisions[7].
+
+TRANSPLANTING A TOPIC BRANCH WITH --ONTO
+----------------------------------------
 
 Here is how you would transplant a topic branch based on one
 branch to another, to pretend that you forked the topic branch
@@ -186,28 +173,6 @@ This is useful if F and G were flawed in some way, or should not be
 part of topicA.  Note that the argument to `--onto` and the `<upstream>`
 parameter can be any valid commit-ish.
 
-In case of conflict, `git rebase` will stop at the first problematic commit
-and leave conflict markers in the tree.  You can use `git diff` to locate
-the markers (<<<<<<) and make edits to resolve the conflict.  For each
-file you edit, you need to tell Git that the conflict has been resolved,
-typically this would be done with
-
-
-    git add <filename>
-
-
-After resolving the conflict manually and updating the index with the
-desired resolution, you can continue the rebasing process with
-
-
-    git rebase --continue
-
-
-Alternatively, you can undo the 'git rebase' with
-
-
-    git rebase --abort
-
 MODE OPTIONS
 ------------
 
@@ -253,6 +218,8 @@ As a special case, you may use "A\...B" as a shortcut for the
 merge base of A and B if there is exactly one merge base. You can
 leave out at most one of A and B, in which case it defaults to HEAD.
 
+See TRANSPLANTING A TOPIC BRANCH WITH --ONTO above for examples.
+
 --keep-base::
 	Set the starting point at which to create the new commits to the
 	merge base of `<upstream>` and `<branch>`. Running
@@ -401,7 +368,7 @@ See also INCOMPATIBLE OPTIONS below.
 +
 See also INCOMPATIBLE OPTIONS below.
 
-include::rerere-options.txt[]
+include::rerere-options.adoc[]
 
 -S[<keyid>]::
 --gpg-sign[=<keyid>]::
@@ -599,11 +566,11 @@ See also INCOMPATIBLE OPTIONS below.
 --no-autosquash::
 	Automatically squash commits with specially formatted messages into
 	previous commits being rebased.  If a commit message starts with
-	"squash! ", "fixup! " or "amend! ", the remainder of the subject line
+	"squash! ", "fixup! " or "amend! ", the remainder of the title
 	is taken as a commit specifier, which matches a previous commit if it
-	matches the subject line or the hash of that commit.  If no commit
+	matches the title or the hash of that commit.  If no commit
 	matches fully, matches of the specifier with the start of commit
-	subjects are considered.
+	titles are considered.
 +
 In the rebase todo list, the actions of squash, fixup and amend commits are
 changed from `pick` to `squash`, `fixup` or `fixup -C`, respectively, and they
@@ -613,7 +580,7 @@ be used to review and edit the todo list before proceeding.
 The recommended way to create commits with squash markers is by using the
 `--squash`, `--fixup`, `--fixup=amend:` or `--fixup=reword:` options of
 linkgit:git-commit[1], which take the target commit as an argument and
-automatically fill in the subject line of the new commit from that.
+automatically fill in the title of the new commit from that.
 +
 Setting configuration variable `rebase.autoSquash` to true enables
 auto-squashing by default for interactive rebase.  The `--no-autosquash`
@@ -687,7 +654,7 @@ In addition, the following pairs of options are incompatible:
  * --fork-point and --root
 
 BEHAVIORAL DIFFERENCES
------------------------
+----------------------
 
 `git rebase` has two primary backends: 'apply' and 'merge'.  (The 'apply'
 backend used to be known as the 'am' backend, but the name led to
@@ -825,7 +792,7 @@ completeness:
 * State directories: The two backends keep their state in different
   directories under `.git/`
 
-include::merge-strategies.txt[]
+include::merge-strategies.adoc[]
 
 NOTES
 -----
@@ -1107,10 +1074,12 @@ In that case, the fix is easy because 'git rebase' knows to skip
 changes that are already present in the new upstream (unless
 `--reapply-cherry-picks` is given). So if you say
 (assuming you're on 'topic')
+
 ------------
     $ git rebase subsystem
 ------------
 you will end up with the fixed history
+
 ------------
     o---o---o---o---o---o---o---o  master
 				 \
@@ -1145,6 +1114,7 @@ of the old 'subsystem', for example:
 
 You can then transplant the old `subsystem..topic` to the new tip by
 saying (for the reflog case, and assuming you are on 'topic' already):
+
 ------------
     $ git rebase --onto subsystem subsystem@{1}
 ------------
@@ -1294,10 +1264,10 @@ merge cmake
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/rebase.txt[]
-include::config/sequencer.txt[]
+include::config/rebase.adoc[]
+include::config/sequencer.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.adoc
index 20aca92073..0956086d61 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.adoc
@@ -46,6 +46,18 @@ OPTIONS
 	`$GIT_URL/info/refs?service=git-receive-pack` requests. See
 	`--http-backend-info-refs` in linkgit:git-upload-pack[1].
 
+--skip-connectivity-check::
+	Bypasses the connectivity checks that validate the existence of all
+	objects in the transitive closure of reachable objects. This option is
+	intended for server operators that want to implement their own object
+	connectivity validation outside of Git. This is useful in such cases
+	where the server-side knows additional information about how Git is
+	being used and thus can rely on certain guarantees to more efficiently
+	compute object connectivity that Git itself cannot make. Usage of this
+	option without a reliable external mechanism to ensure full reachable
+	object connectivity risks corrupting the repository and should not be
+	used in the general case.
+
 PRE-RECEIVE HOOK
 ----------------
 Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.adoc
index a929c52982..38af0c977a 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.adoc
@@ -8,15 +8,17 @@ git-reflog - Manage reflog information
 
 SYNOPSIS
 --------
-[verse]
-'git reflog' [show] [<log-options>] [<ref>]
-'git reflog list'
-'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
+[synopsis]
+git reflog [show] [<log-options>] [<ref>]
+git reflog list
+git reflog exists <ref>
+git reflog write <ref> <old-oid> <new-oid> <message>
+git reflog delete [--rewrite] [--updateref]
+	[--dry-run | -n] [--verbose] <ref>@{<specifier>}...
+git reflog drop [--all [--single-worktree] | <refs>...]
+git reflog expire [--expire=<time>] [--expire-unreachable=<time>]
 	[--rewrite] [--updateref] [--stale-fix]
 	[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
-'git reflog delete' [--rewrite] [--updateref]
-	[--dry-run | -n] [--verbose] <ref>@{<specifier>}...
-'git reflog exists' <ref>
 
 DESCRIPTION
 -----------
@@ -42,21 +44,31 @@ actions, and in addition the `HEAD` reflog records branch switching.
 
 The "list" subcommand lists all refs which have a corresponding reflog.
 
+The "exists" subcommand checks whether a ref has a reflog.  It exits
+with zero status if the reflog exists, and non-zero status if it does
+not.
+
+The "write" subcommand writes a single entry to the reflog of a given
+reference. This new entry is appended to the reflog and will thus become
+the most recent entry. The reference name must be fully qualified. Both the old
+and new object IDs must not be abbreviated and must point to existing objects.
+The reflog message gets normalized.
+
+The "delete" subcommand deletes single entries from the reflog, but
+not the reflog itself. Its argument must be an _exact_ entry (e.g. "`git
+reflog delete master@{2}`"). This subcommand is also typically not used
+directly by end users.
+
+The "drop" subcommand completely removes the reflog for the specified
+references. This is in contrast to "expire" and "delete", both of which
+can be used to delete reflog entries, but not the reflog itself.
+
 The "expire" subcommand prunes older reflog entries. Entries older
 than `expire` time, or entries older than `expire-unreachable` time
 and not reachable from the current tip, are removed from the reflog.
 This is typically not used directly by end users -- instead, see
 linkgit:git-gc[1].
 
-The "delete" subcommand deletes single entries from the reflog. Its
-argument must be an _exact_ entry (e.g. "`git reflog delete
-master@{2}`"). This subcommand is also typically not used directly by
-end users.
-
-The "exists" subcommand checks whether a ref has a reflog.  It exits
-with zero status if the reflog exists, and non-zero status if it does
-not.
-
 OPTIONS
 -------
 
@@ -66,18 +78,37 @@ Options for `show`
 `git reflog show` accepts any of the options accepted by `git log`.
 
 
+Options for `delete`
+~~~~~~~~~~~~~~~~~~~~
+
+`git reflog delete` accepts options `--updateref`, `--rewrite`, `-n`,
+`--dry-run`, and `--verbose`, with the same meanings as when they are
+used with `expire`.
+
+Options for `drop`
+~~~~~~~~~~~~~~~~~~
+
+`--all`::
+	Drop the reflogs of all references from all worktrees.
+
+`--single-worktree`::
+	By default when `--all` is specified, reflogs from all working
+	trees are dropped. This option limits the processing to reflogs
+	from the current working tree only.
+
+
 Options for `expire`
 ~~~~~~~~~~~~~~~~~~~~
 
---all::
+`--all`::
 	Process the reflogs of all references.
 
---single-worktree::
+`--single-worktree`::
 	By default when `--all` is specified, reflogs from all working
 	trees are processed. This option limits the processing to reflogs
 	from the current working tree only.
 
---expire=<time>::
+`--expire=<time>`::
 	Prune entries older than the specified time. If this option is
 	not specified, the expiration time is taken from the
 	configuration setting `gc.reflogExpire`, which in turn
@@ -85,7 +116,7 @@ Options for `expire`
 	of their age; `--expire=never` turns off pruning of reachable
 	entries (but see `--expire-unreachable`).
 
---expire-unreachable=<time>::
+`--expire-unreachable=<time>`::
 	Prune entries older than `<time>` that are not reachable from
 	the current tip of the branch. If this option is not
 	specified, the expiration time is taken from the configuration
@@ -95,17 +126,17 @@ Options for `expire`
 	turns off early pruning of unreachable entries (but see
 	`--expire`).
 
---updateref::
+`--updateref`::
 	Update the reference to the value of the top reflog entry (i.e.
 	<ref>@\{0\}) if the previous top entry was pruned.  (This
 	option is ignored for symbolic references.)
 
---rewrite::
+`--rewrite`::
 	If a reflog entry's predecessor is pruned, adjust its "old"
 	SHA-1 to be equal to the "new" SHA-1 field of the entry that
 	now precedes it.
 
---stale-fix::
+`--stale-fix`::
 	Prune any reflog entries that point to "broken commits". A
 	broken commit is a commit that is not reachable from any of
 	the reference tips and that refers, directly or indirectly, to
@@ -116,23 +147,15 @@ has the same cost as 'git prune'.  It is primarily intended to fix
 corruption caused by garbage collecting using older versions of Git,
 which didn't protect objects referred to by reflogs.
 
--n::
---dry-run::
+`-n`::
+`--dry-run`::
 	Do not actually prune any entries; just show what would have
 	been pruned.
 
---verbose::
+`--verbose`::
 	Print extra information on screen.
 
 
-Options for `delete`
-~~~~~~~~~~~~~~~~~~~~
-
-`git reflog delete` accepts options `--updateref`, `--rewrite`, `-n`,
-`--dry-run`, and `--verbose`, with the same meanings as when they are
-used with `expire`.
-
-
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
new file mode 100644
index 0000000000..fa33680cc7
--- /dev/null
+++ b/Documentation/git-refs.adoc
@@ -0,0 +1,110 @@
+git-refs(1)
+===========
+
+NAME
+----
+git-refs - Low-level access to refs
+
+
+SYNOPSIS
+--------
+[synopsis]
+git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
+git refs verify [--strict] [--verbose]
+git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
+		   [(--sort=<key>)...] [--format=<format>]
+		   [--include-root-refs] [--points-at=<object>]
+		   [--merged[=<object>]] [--no-merged[=<object>]]
+		   [--contains[=<object>]] [--no-contains[=<object>]]
+		   [(--exclude=<pattern>)...] [--start-after=<marker>]
+		   [ --stdin | (<pattern>...)]
+git refs exists <ref>
+git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]
+
+DESCRIPTION
+-----------
+
+This command provides low-level access to refs.
+
+COMMANDS
+--------
+
+`migrate`::
+	Migrate ref store between different formats.
+
+`verify`::
+	Verify reference database consistency.
+
+list::
+	List references in the repository with support for filtering,
+	formatting, and sorting. This subcommand is an alias for
+	linkgit:git-for-each-ref[1] and offers identical functionality.
+
+exists::
+	Check whether the given reference exists. Returns an exit code of 0 if
+	it does, 2 if it is missing, and 1 in case looking up the reference
+	failed with an error other than the reference being missing. This does
+	not verify whether the reference resolves to an actual object.
+
+optimize::
+	Optimizes references to improve repository performance and reduce disk
+	usage. This subcommand is an alias for linkgit:git-pack-refs[1] and
+	offers identical functionality.
+
+OPTIONS
+-------
+
+The following options are specific to `git refs migrate`:
+
+`--ref-format=<format>`::
+	The ref format to migrate the ref store to. Can be one of:
++
+include::ref-storage-format.adoc[]
+
+`--dry-run`::
+	Perform the migration, but do not modify the repository. The migrated
+	refs will be written into a separate directory that can be inspected
+	separately. The name of the directory will be reported on stdout. This
+	can be used to double check that the migration works as expected before
+	performing the actual migration.
+
+`--reflog`::
+`--no-reflog`::
+	Choose between migrating the reflog data to the new backend,
+	and discarding them.  The default is "--reflog", to migrate.
+
+The following options are specific to `git refs verify`:
+
+`--strict`::
+	Enable stricter error checking. This will cause warnings to be
+	reported as errors. See linkgit:git-fsck[1].
+
+`--verbose`::
+	When verifying the reference database consistency, be chatty.
+
+The following options are specific to 'git refs list':
+
+include::for-each-ref-options.adoc[]
+
+The following options are specific to 'git refs optimize':
+
+include::pack-refs-options.adoc[]
+
+KNOWN LIMITATIONS
+-----------------
+
+The ref format migration has several known limitations in its current form:
+
+* It is not possible to migrate repositories that have worktrees.
+
+* There is no way to block concurrent writes to the repository during an
+  ongoing migration. Concurrent writes can lead to an inconsistent migrated
+  state. Users are expected to block writes on a higher level. If your
+  repository is registered for scheduled maintenance, it is recommended to
+  unregister it first with git-maintenance(1).
+
+These limitations may eventually be lifted.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-refs.txt b/Documentation/git-refs.txt
deleted file mode 100644
index 9829984b0a..0000000000
--- a/Documentation/git-refs.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-git-refs(1)
-===========
-
-NAME
-----
-git-refs - Low-level access to refs
-
-
-SYNOPSIS
---------
-[verse]
-'git refs migrate' --ref-format=<format> [--dry-run]
-'git refs verify' [--strict] [--verbose]
-
-DESCRIPTION
------------
-
-This command provides low-level access to refs.
-
-COMMANDS
---------
-
-migrate::
-	Migrate ref store between different formats.
-
-verify::
-	Verify reference database consistency.
-
-OPTIONS
--------
-
-The following options are specific to 'git refs migrate':
-
---ref-format=<format>::
-	The ref format to migrate the ref store to. Can be one of:
-+
-include::ref-storage-format.txt[]
-
---dry-run::
-	Perform the migration, but do not modify the repository. The migrated
-	refs will be written into a separate directory that can be inspected
-	separately. The name of the directory will be reported on stdout. This
-	can be used to double check that the migration works as expected before
-	performing the actual migration.
-
-The following options are specific to 'git refs verify':
-
---strict::
-	Enable stricter error checking. This will cause warnings to be
-	reported as errors. See linkgit:git-fsck[1].
-
---verbose::
-	When verifying the reference database consistency, be chatty.
-
-KNOWN LIMITATIONS
------------------
-
-The ref format migration has several known limitations in its current form:
-
-* It is not possible to migrate repositories that have worktrees.
-
-* There is no way to block concurrent writes to the repository during an
-  ongoing migration. Concurrent writes can lead to an inconsistent migrated
-  state. Users are expected to block writes on a higher level. If your
-  repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
-
-These limitations may eventually be lifted.
-
-GIT
----
-Part of the linkgit:git[1] suite
diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.adoc
index b33ee3c9e8..b33ee3c9e8 100644
--- a/Documentation/git-remote-ext.txt
+++ b/Documentation/git-remote-ext.adoc
diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.adoc
index 1dd2648a79..1dd2648a79 100644
--- a/Documentation/git-remote-fd.txt
+++ b/Documentation/git-remote-fd.adoc
diff --git a/Documentation/git-remote-helpers.txto b/Documentation/git-remote-helpers.adoco
index 6f353ebfd3..6f353ebfd3 100644
--- a/Documentation/git-remote-helpers.txto
+++ b/Documentation/git-remote-helpers.adoco
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.adoc
index 932a5c3ea4..932a5c3ea4 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.adoc
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.adoc
index c902512a9e..d12c4985f6 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.adoc
@@ -9,7 +9,9 @@ git-repack - Pack unpacked objects in a repository
 SYNOPSIS
 --------
 [verse]
-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]
+'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m]
+	[--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>]
+	[--write-midx] [--name-hash-version=<n>] [--path-walk]
 
 DESCRIPTION
 -----------
@@ -75,15 +77,18 @@ to the new separate pack will be written.
 	Only useful with `--cruft -d`.
 
 --max-cruft-size=<n>::
-	Repack cruft objects into packs as large as `<n>` bytes before
-	creating new packs. As long as there are enough cruft packs
-	smaller than `<n>`, repacking will cause a new cruft pack to
-	be created containing objects from any combined cruft packs,
-	along with any new unreachable objects. Cruft packs larger than
-	`<n>` will not be modified. When the new cruft pack is larger
-	than `<n>` bytes, it will be split into multiple packs, all of
-	which are guaranteed to be at most `<n>` bytes in size. Only
-	useful with `--cruft -d`.
+	Overrides `--max-pack-size` for cruft packs. Inherits the value of
+	`--max-pack-size` (if any) by default. See the documentation for
+	`--max-pack-size` for more details.
+
+--combine-cruft-below-size=<n>::
+	When generating cruft packs without pruning, only repack
+	existing cruft packs whose size is strictly less than `<n>`,
+	where `<n>` represents a number of bytes, which can optionally
+	be suffixed with "k", "m", or "g". Cruft packs whose size is
+	greater than or equal to `<n>` are left as-is and not repacked.
+	Useful when you want to avoid repacking large cruft pack(s) in
+	repositories that have many and/or large unreachable objects.
 
 --expire-to=<dir>::
 	Write a cruft pack containing pruned objects (if any) to the
@@ -249,6 +254,14 @@ linkgit:git-multi-pack-index[1]).
 	Write a multi-pack index (see linkgit:git-multi-pack-index[1])
 	containing the non-redundant packs.
 
+--name-hash-version=<n>::
+	Provide this argument to the underlying `git pack-objects` process.
+	See linkgit:git-pack-objects[1] for full details.
+
+--path-walk::
+	Pass the `--path-walk` option to the underlying `git pack-objects`
+	process. See linkgit:git-pack-objects[1] for full details.
+
 CONFIGURATION
 -------------
 
diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.adoc
index 0a65460adb..0a65460adb 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.adoc
diff --git a/Documentation/git-replay.txt b/Documentation/git-replay.adoc
index 8f3300c683..0b12bf8aa4 100644
--- a/Documentation/git-replay.txt
+++ b/Documentation/git-replay.adoc
@@ -49,7 +49,7 @@ the new commits (in other words, this mimics a cherry-pick operation).
 	to. See "Specifying Ranges" in linkgit:git-rev-parse[1] and the
 	"Commit Limiting" options below.
 
-include::rev-list-options.txt[]
+include::rev-list-options.adoc[]
 
 OUTPUT
 ------
diff --git a/Documentation/git-repo.adoc b/Documentation/git-repo.adoc
new file mode 100644
index 0000000000..ce43cb19c8
--- /dev/null
+++ b/Documentation/git-repo.adoc
@@ -0,0 +1,119 @@
+git-repo(1)
+===========
+
+NAME
+----
+git-repo - Retrieve information about the repository
+
+SYNOPSIS
+--------
+[synopsis]
+git repo info [--format=(keyvalue|nul)] [-z] [<key>...]
+git repo structure [--format=(table|keyvalue|nul)]
+
+DESCRIPTION
+-----------
+Retrieve information about the repository.
+
+THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
+
+COMMANDS
+--------
+`info [--format=(keyvalue|nul)] [-z] [<key>...]`::
+	Retrieve metadata-related information about the current repository. Only
+	the requested data will be returned based on their keys (see "INFO KEYS"
+	section below).
++
+The values are returned in the same order in which their respective keys were
+requested.
++
+The output format can be chosen through the flag `--format`. Two formats are
+supported:
++
+`keyvalue`:::
+	output key-value pairs one per line using the `=` character as
+	the delimiter between the key and the value. Values containing "unusual"
+	characters are quoted as explained for the configuration variable
+	`core.quotePath` (see linkgit:git-config[1]). This is the default.
+
+`nul`:::
+	similar to `keyvalue`, but using a newline character as the delimiter
+	between the key and the value and using a NUL character after each value.
+	This format is better suited for being parsed by another applications than
+	`keyvalue`. Unlike in the `keyvalue` format, the values are never quoted.
++
+`-z` is an alias for `--format=nul`.
+
+`structure [--format=(table|keyvalue|nul)]`::
+	Retrieve statistics about the current repository structure. The
+	following kinds of information are reported:
++
+* Reference counts categorized by type
+* Reachable object counts categorized by type
+
++
+The output format can be chosen through the flag `--format`. Three formats are
+supported:
++
+`table`:::
+	Outputs repository stats in a human-friendly table. This format may
+	change and is not intended for machine parsing. This is the default
+	format.
+
+`keyvalue`:::
+	Each line of output contains a key-value pair for a repository stat.
+	The '=' character is used to delimit between the key and the value.
+	Values containing "unusual" characters are quoted as explained for the
+	configuration variable `core.quotePath` (see linkgit:git-config[1]).
+
+`nul`:::
+	Similar to `keyvalue`, but uses a NUL character to delimit between
+	key-value pairs instead of a newline. Also uses a newline character as
+	the delimiter between the key and value instead of '='. Unlike the
+	`keyvalue` format, values containing "unusual" characters are never
+	quoted.
+
+INFO KEYS
+---------
+In order to obtain a set of values from `git repo info`, you should provide
+the keys that identify them. Here's a list of the available keys and the
+values that they return:
+
+`layout.bare`::
+	`true` if this is a bare repository, otherwise `false`.
+
+`layout.shallow`::
+	`true` if this is a shallow repository, otherwise `false`.
+
+`object.format`::
+	The object format (hash algorithm) used in the repository.
+
+`references.format`::
+	The reference storage format. The valid values are:
++
+include::ref-storage-format.adoc[]
+
+EXAMPLES
+--------
+
+* Retrieves the reference format of the current repository:
++
+------------
+git repo info references.format
+------------
++
+
+* Retrieves whether the current repository is bare and whether it is shallow
+using the `nul` format:
++
+------------
+git repo info --format=nul layout.bare layout.shallow
+------------
+
+SEE ALSO
+--------
+linkgit:git-rev-parse[1]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.adoc
index 15dcbb6d91..15dcbb6d91 100644
--- a/Documentation/git-request-pull.txt
+++ b/Documentation/git-request-pull.adoc
diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.adoc
index 992b469270..992b469270 100644
--- a/Documentation/git-rerere.txt
+++ b/Documentation/git-rerere.adoc
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.adoc
index 79ad5643ee..3b9ba9aee9 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.adoc
@@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state
 
 SYNOPSIS
 --------
-[verse]
-'git reset' [-q] [<tree-ish>] [--] <pathspec>...
-'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
-'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
-'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
+[synopsis]
+git reset [-q] [<tree-ish>] [--] <pathspec>...
+git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]
+git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]
+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
 
 DESCRIPTION
 -----------
-In the first three forms, copy entries from `<tree-ish>` to the index.
-In the last form, set the current branch head (`HEAD`) to `<commit>`,
+In the first three forms, copy entries from _<tree-ish>_ to the index.
+In the last form, set the current branch head (`HEAD`) to _<commit>_,
 optionally modifying index and working tree to match.
-The `<tree-ish>`/`<commit>` defaults to `HEAD` in all forms.
+The _<tree-ish>_/_<commit>_ defaults to `HEAD` in all forms.
 
-'git reset' [-q] [<tree-ish>] [--] <pathspec>...::
-'git reset' [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]::
+`git reset [-q] [<tree-ish>] [--] <pathspec>...`::
+`git reset [-q] [--pathspec-from-file=<file> [--pathspec-file-nul]] [<tree-ish>]`::
 	These forms reset the index entries for all paths that match the
-	`<pathspec>` to their state at `<tree-ish>`.  (It does not affect
+	_<pathspec>_ to their state at _<tree-ish>_.  (It does not affect
 	the working tree or the current branch.)
 +
 This means that `git reset <pathspec>` is the opposite of `git add
@@ -37,30 +37,30 @@ and specifying a commit with `--source`, you
 can copy the contents of a path out of a commit to the index and to the
 working tree in one go.
 
-'git reset' (--patch | -p) [<tree-ish>] [--] [<pathspec>...]::
+`git reset (--patch | -p) [<tree-ish>] [--] [<pathspec>...]`::
 	Interactively select hunks in the difference between the index
-	and `<tree-ish>` (defaults to `HEAD`).  The chosen hunks are applied
+	and _<tree-ish>_ (defaults to `HEAD`).  The chosen hunks are applied
 	in reverse to the index.
 +
 This means that `git reset -p` is the opposite of `git add -p`, i.e.
-you can use it to selectively reset hunks. See the ``Interactive Mode''
+you can use it to selectively reset hunks. See the "Interactive Mode"
 section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
 
-'git reset' [<mode>] [<commit>]::
-	This form resets the current branch head to `<commit>` and
-	possibly updates the index (resetting it to the tree of `<commit>`) and
-	the working tree depending on `<mode>`. Before the operation, `ORIG_HEAD`
-	is set to the tip of the current branch. If `<mode>` is omitted,
-	defaults to `--mixed`. The `<mode>` must be one of the following:
+`git reset [<mode>] [<commit>]`::
+	This form resets the current branch head to _<commit>_ and
+	possibly updates the index (resetting it to the tree of _<commit>_) and
+	the working tree depending on _<mode>_. Before the operation, `ORIG_HEAD`
+	is set to the tip of the current branch. If _<mode>_ is omitted,
+	defaults to `--mixed`. The _<mode>_ must be one of the following:
 +
 --
---soft::
+`--soft`::
 	Does not touch the index file or the working tree at all (but
-	resets the head to `<commit>`, just like all modes do). This leaves
+	resets the head to _<commit>_, just like all modes do). This leaves
 	all your changed files "Changes to be committed", as `git status`
 	would put it.
 
---mixed::
+`--mixed`::
 	Resets the index but not the working tree (i.e., the changed files
 	are preserved but not marked for commit) and reports what has not
 	been updated. This is the default action.
@@ -68,33 +68,34 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
 If `-N` is specified, removed paths are marked as intent-to-add (see
 linkgit:git-add[1]).
 
---hard::
+`--hard`::
 	Resets the index and working tree. Any changes to tracked files in the
-	working tree since `<commit>` are discarded.  Any untracked files or
+	working tree since _<commit>_ are discarded.  Any untracked files or
 	directories in the way of writing any tracked files are simply deleted.
 
---merge::
+`--merge`::
 	Resets the index and updates the files in the working tree that are
-	different between `<commit>` and `HEAD`, but keeps those which are
+	different between _<commit>_ and `HEAD`, but keeps those which are
 	different between the index and working tree (i.e. which have changes
 	which have not been added).
-	If a file that is different between `<commit>` and the index has
+	If a file that is different between _<commit>_ and the index has
 	unstaged changes, reset is aborted.
 +
 In other words, `--merge` does something like a `git read-tree -u -m <commit>`,
 but carries forward unmerged index entries.
 
---keep::
+`--keep`::
 	Resets index entries and updates files in the working tree that are
-	different between `<commit>` and `HEAD`.
-	If a file that is different between `<commit>` and `HEAD` has local
+	different between _<commit>_ and `HEAD`.
+	If a file that is different between _<commit>_ and `HEAD` has local
 	changes, reset is aborted.
 
---[no-]recurse-submodules::
-	When the working tree is updated, using --recurse-submodules will
+`--recurse-submodules`::
+`--no-recurse-submodules`::
+	When the working tree is updated, using `--recurse-submodules` will
 	also recursively reset the working tree of all active submodules
 	according to the commit recorded in the superproject, also setting
-	the submodules' HEAD to be detached at that commit.
+	the submodules' `HEAD` to be detached at that commit.
 --
 
 See "Reset, restore and revert" in linkgit:git[1] for the differences
@@ -104,31 +105,33 @@ between the three commands.
 OPTIONS
 -------
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Be quiet, only report errors.
 
---refresh::
---no-refresh::
+`--refresh`::
+`--no-refresh`::
 	Refresh the index after a mixed reset. Enabled by default.
 
---pathspec-from-file=<file>::
-	Pathspec is passed in `<file>` instead of commandline args. If
-	`<file>` is exactly `-` then standard input is used. Pathspec
-	elements are separated by LF or CR/LF. Pathspec elements can be
+`--pathspec-from-file=<file>`::
+	Pathspec is passed in _<file>_ instead of commandline args. If
+	_<file>_ is exactly `-` then standard input is used. Pathspec
+	elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
 	quoted as explained for the configuration variable `core.quotePath`
 	(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
 	global `--literal-pathspecs`.
 
---pathspec-file-nul::
+`--pathspec-file-nul`::
 	Only meaningful with `--pathspec-from-file`. Pathspec elements are
-	separated with NUL character and all other characters are taken
+	separated with _NUL_ character and all other characters are taken
 	literally (including newlines and quotes).
 
-\--::
+include::diff-context-options.adoc[]
+
+`--`::
 	Do not interpret any more arguments as options.
 
-<pathspec>...::
+`<pathspec>...`::
 	Limits the paths affected by the operation.
 +
 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
@@ -348,7 +351,7 @@ $ git commit ...                            <8>
 ------------
 +
 <1> First, reset the history back one commit so that we remove the original
-    commit, but leave the working tree with all the changes. The -N ensures
+    commit, but leave the working tree with all the changes. The `-N` ensures
     that any new files added with `HEAD` are still marked so that `git add -p`
     will find them.
 <2> Next, we interactively select diff hunks to add using the `git add -p`
@@ -458,7 +461,7 @@ working index HEAD target         working index HEAD
 			  --keep   B       C     C
 ....
 
-`reset --merge` is meant to be used when resetting out of a conflicted
+`git reset --merge` is meant to be used when resetting out of a conflicted
 merge. Any mergy operation guarantees that the working tree file that is
 involved in the merge does not have a local change with respect to the index
 before it starts, and that it writes the result out to the working tree. So if
@@ -467,7 +470,7 @@ between the index and the working tree, then it means that we are not
 resetting out from a state that a mergy operation left after failing
 with a conflict. That is why we disallow `--merge` option in this case.
 
-`reset --keep` is meant to be used when removing some of the last
+`git reset --keep` is meant to be used when removing some of the last
 commits in the current branch while keeping changes in the working
 tree. If there could be conflicts between the changes in the commit we
 want to remove and the changes in the working tree we want to keep,
diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.adoc
index 975825b44a..961eef0137 100644
--- a/Documentation/git-restore.txt
+++ b/Documentation/git-restore.adoc
@@ -7,10 +7,10 @@ git-restore - Restore working tree files
 
 SYNOPSIS
 --------
-[verse]
-'git restore' [<options>] [--source=<tree>] [--staged] [--worktree] [--] <pathspec>...
-'git restore' [<options>] [--source=<tree>] [--staged] [--worktree] --pathspec-from-file=<file> [--pathspec-file-nul]
-'git restore' (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [--] [<pathspec>...]
+[synopsis]
+git restore [<options>] [--source=<tree>] [--staged] [--worktree] [--] <pathspec>...
+git restore [<options>] [--source=<tree>] [--staged] [--worktree] --pathspec-from-file=<file> [--pathspec-file-nul]
+git restore (-p|--patch) [<options>] [--source=<tree>] [--staged] [--worktree] [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
@@ -28,12 +28,10 @@ otherwise from the index. Use `--source` to restore from a different commit.
 See "Reset, restore and revert" in linkgit:git[1] for the differences
 between the three commands.
 
-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
-
 OPTIONS
 -------
--s <tree>::
---source=<tree>::
+`-s <tree>`::
+`--source=<tree>`::
 	Restore the working tree files with the content from the given
 	tree. It is common to specify the source tree by naming a
 	commit, branch or tag associated with it.
@@ -41,79 +39,78 @@ OPTIONS
 If not specified, the contents are restored from `HEAD` if `--staged` is
 given, otherwise from the index.
 +
-As a special case, you may use `"A...B"` as a shortcut for the
-merge base of `A` and `B` if there is exactly one merge base. You can
-leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
+As a special case, you may use `"<rev-A>...<rev-B>"` as a shortcut for the
+merge base of _<rev-A>_ and _<rev-B>_ if there is exactly one merge base. You can
+leave out at most one of _<rev-A>__ and _<rev-B>_, in which case it defaults to `HEAD`.
 
--p::
---patch::
+`-p`::
+`--patch`::
 	Interactively select hunks in the difference between the
-	restore source and the restore location. See the ``Interactive
-	Mode'' section of linkgit:git-add[1] to learn how to operate
+	restore source and the restore location. See the "Interactive
+	Mode" section of linkgit:git-add[1] to learn how to operate
 	the `--patch` mode.
-+
-Note that `--patch` can accept no pathspec and will prompt to restore
-all modified paths.
 
--W::
---worktree::
--S::
---staged::
+include::diff-context-options.adoc[]
+
+`-W`::
+`--worktree`::
+`-S`::
+`--staged`::
 	Specify the restore location. If neither option is specified,
 	by default the working tree is restored. Specifying `--staged`
 	will only restore the index. Specifying both restores both.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Quiet, suppress feedback messages. Implies `--no-progress`.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Progress status is reported on the standard error stream
 	by default when it is attached to a terminal, unless `--quiet`
 	is specified. This flag enables progress reporting even if not
 	attached to a terminal, regardless of `--quiet`.
 
---ours::
---theirs::
+`--ours`::
+`--theirs`::
 	When restoring files in the working tree from the index, use
-	stage #2 ('ours') or #3 ('theirs') for unmerged paths.
+	stage #2 (`ours`) or #3 (`theirs`) for unmerged paths.
 	This option cannot be used when checking out paths from a
 	tree-ish (i.e. with the `--source` option).
 +
-Note that during `git rebase` and `git pull --rebase`, 'ours' and
-'theirs' may appear swapped. See the explanation of the same options
+Note that during `git rebase` and `git pull --rebase`, `ours` and
+`theirs` may appear swapped. See the explanation of the same options
 in linkgit:git-checkout[1] for details.
 
--m::
---merge::
+`-m`::
+`--merge`::
 	When restoring files on the working tree from the index,
 	recreate the conflicted merge in the unmerged paths.
 	This option cannot be used when checking out paths from a
 	tree-ish (i.e. with the `--source` option).
 
---conflict=<style>::
+`--conflict=<style>`::
 	The same as `--merge` option above, but changes the way the
 	conflicting hunks are presented, overriding the
 	`merge.conflictStyle` configuration variable.  Possible values
-	are "merge" (default), "diff3", and "zdiff3".
+	are `merge` (default), `diff3`, and `zdiff3`.
 
---ignore-unmerged::
+`--ignore-unmerged`::
 	When restoring files on the working tree from the index, do
 	not abort the operation if there are unmerged entries and
 	neither `--ours`, `--theirs`, `--merge` or `--conflict` is
 	specified. Unmerged paths on the working tree are left alone.
 
---ignore-skip-worktree-bits::
+`--ignore-skip-worktree-bits`::
 	In sparse checkout mode, the default is to only update entries
-	matched by `<pathspec>` and sparse patterns in
-	$GIT_DIR/info/sparse-checkout. This option ignores the sparse
+	matched by _<pathspec>_ and sparse patterns in
+	`$GIT_DIR/info/sparse-checkout`. This option ignores the sparse
 	patterns and unconditionally restores any files in
-	`<pathspec>`.
+	_<pathspec>_.
 
---recurse-submodules::
---no-recurse-submodules::
-	If `<pathspec>` names an active submodule and the restore location
+`--recurse-submodules`::
+`--no-recurse-submodules`::
+	If _<pathspec>_ names an active submodule and the restore location
 	includes the working tree, the submodule will only be updated if
 	this option is given, in which case its working tree will be
 	restored to the commit recorded in the superproject, and any local
@@ -122,30 +119,30 @@ in linkgit:git-checkout[1] for details.
 	not be updated. Just like linkgit:git-checkout[1], this will detach
 	`HEAD` of the submodule.
 
---overlay::
---no-overlay::
-	In overlay mode, the command never removes files when
-	restoring. In no-overlay mode, tracked files that do not
-	appear in the `--source` tree are removed, to make them match
-	`<tree>` exactly. The default is no-overlay mode.
-
---pathspec-from-file=<file>::
-	Pathspec is passed in `<file>` instead of commandline args. If
-	`<file>` is exactly `-` then standard input is used. Pathspec
-	elements are separated by LF or CR/LF. Pathspec elements can be
+`--overlay`::
+`--no-overlay`::
+	In overlay mode, never remove files when restoring. In no-overlay mode,
+	remove tracked files that do not appear in the _<tree>_ of
+	`--source=<tree>`, to make them match _<tree>_ exactly. The default
+	is no-overlay mode.
+
+`--pathspec-from-file=<file>`::
+	Pathspec is passed in _<file>_ instead of commandline args. If
+	_<file>_ is exactly `-` then standard input is used. Pathspec
+	elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
 	quoted as explained for the configuration variable `core.quotePath`
 	(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
 	global `--literal-pathspecs`.
 
---pathspec-file-nul::
+`--pathspec-file-nul`::
 	Only meaningful with `--pathspec-from-file`. Pathspec elements are
-	separated with NUL character and all other characters are taken
+	separated with _NUL_ character and all other characters are taken
 	literally (including newlines and quotes).
 
-\--::
+`--`::
 	Do not interpret any more arguments as options.
 
-<pathspec>...::
+`<pathspec>...`::
 	Limits the paths affected by the operation.
 +
 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
@@ -154,7 +151,7 @@ EXAMPLES
 --------
 
 The following sequence switches to the `master` branch, reverts the
-`Makefile` to two revisions back, deletes hello.c by mistake, and gets
+`Makefile` to two revisions back, deletes `hello.c` by mistake, and gets
 it back from the index.
 
 ------------
@@ -165,7 +162,7 @@ $ git restore hello.c                     <2>
 ------------
 
 <1> take a file out of another commit
-<2> restore hello.c from the index
+<2> restore `hello.c` from the index
 
 If you want to restore _all_ C source files to match the version in
 the index, you can say
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.adoc
index 2e05c4b510..f582491dd4 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.adoc
@@ -15,7 +15,7 @@ DESCRIPTION
 -----------
 
 :git-rev-list: 1
-include::rev-list-description.txt[]
+include::rev-list-description.adoc[]
 
 'rev-list' is an essential Git command, since it
 provides the ability to build and traverse commit ancestry graphs. For
@@ -27,9 +27,9 @@ OPTIONS
 -------
 
 :git-rev-list: 1
-include::rev-list-options.txt[]
+include::rev-list-options.adoc[]
 
-include::pretty-formats.txt[]
+include::pretty-formats.adoc[]
 
 EXAMPLES
 --------
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.adoc
index dc12d38534..5398691f3f 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.adoc
@@ -174,13 +174,13 @@ for another option.
 
 	Allow oids to be input from any object format that the current
 	repository supports.
-
-	Specifying "sha1" translates if necessary and returns a sha1 oid.
-
-	Specifying "sha256" translates if necessary and returns a sha256 oid.
-
-	Specifying "storage" translates if necessary and returns an oid in
-	encoded in the storage hash algorithm.
++
+Specifying "sha1" translates if necessary and returns a sha1 oid.
++
+Specifying "sha256" translates if necessary and returns a sha256 oid.
++
+Specifying "storage" translates if necessary and returns an oid in
+encoded in the storage hash algorithm.
 
 Options for Objects
 ~~~~~~~~~~~~~~~~~~~
@@ -324,11 +324,12 @@ The following options are unaffected by `--path-format`:
 	path of the current directory relative to the top-level
 	directory.
 
---show-object-format[=(storage|input|output)]::
-	Show the object format (hash algorithm) used for the repository
-	for storage inside the `.git` directory, input, or output. For
-	input, multiple algorithms may be printed, space-separated.
-	If not specified, the default is "storage".
+--show-object-format[=(storage|input|output|compat)]::
+	Show the object format (hash algorithm) used for the repository for storage
+	inside the `.git` directory, input, output, or compatibility. For input,
+	multiple algorithms may be printed, space-separated. If `compat` is
+	requested and no compatibility algorithm is enabled, prints an empty line. If
+	not specified, the default is "storage".
 
 --show-ref-format::
 	Show the reference storage format used for the repository.
@@ -351,7 +352,7 @@ Other Options
 	Flags and parameters to be parsed.
 
 
-include::revisions.txt[]
+include::revisions.adoc[]
 
 PARSEOPT
 --------
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.adoc
index 568925db53..ffba365e63 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.adoc
@@ -112,7 +112,7 @@ effect to your index in a row.
 	Pass the merge strategy-specific option through to the
 	merge strategy.  See linkgit:git-merge[1] for details.
 
-include::rerere-options.txt[]
+include::rerere-options.adoc[]
 
 --reference::
 	Instead of starting the body of the log message with "This
@@ -125,7 +125,7 @@ include::rerere-options.txt[]
 
 SEQUENCER SUBCOMMANDS
 ---------------------
-include::sequencer.txt[]
+include::sequencer.adoc[]
 
 EXAMPLES
 --------
@@ -155,9 +155,9 @@ Please consider rewording these to be shorter and more unique.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/revert.txt[]
+include::config/revert.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.adoc
index 363a26934f..b5ead86796 100644
--- a/Documentation/git-rm.txt
+++ b/Documentation/git-rm.adoc
@@ -7,10 +7,10 @@ git-rm - Remove files from the working tree and from the index
 
 SYNOPSIS
 --------
-[verse]
-'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]
-	  [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]
-	  [--] [<pathspec>...]
+[synopsis]
+git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]
+       [--quiet] [--pathspec-from-file=<file> [--pathspec-file-nul]]
+       [--] [<pathspec>...]
 
 DESCRIPTION
 -----------
@@ -30,7 +30,7 @@ sparse-checkouts are in use (see linkgit:git-sparse-checkout[1]),
 
 OPTIONS
 -------
-<pathspec>...::
+`<pathspec>...`::
 	Files to remove.  A leading directory name (e.g. `dir` to remove
 	`dir/file1` and `dir/file2`) can be given to remove all files in
 	the directory, and recursively all sub-directories, but this
@@ -43,57 +43,57 @@ directories `d` and `d2`, there is a difference between using
 `git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all
 of directory `d2`.
 +
-For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
+For more details, see the _<pathspec>_ entry in linkgit:gitglossary[7].
 
--f::
---force::
+`-f`::
+`--force`::
 	Override the up-to-date check.
 
--n::
---dry-run::
+`-n`::
+`--dry-run`::
 	Don't actually remove any file(s).  Instead, just show
 	if they exist in the index and would otherwise be removed
 	by the command.
 
--r::
+`-r`::
         Allow recursive removal when a leading directory name is
         given.
 
-\--::
+`--`::
 	This option can be used to separate command-line options from
 	the list of files, (useful when filenames might be mistaken
 	for command-line options).
 
---cached::
+`--cached`::
 	Use this option to unstage and remove paths only from the index.
 	Working tree files, whether modified or not, will be
 	left alone.
 
---ignore-unmatch::
+`--ignore-unmatch`::
 	Exit with a zero status even if no files matched.
 
---sparse::
+`--sparse`::
 	Allow updating index entries outside of the sparse-checkout cone.
 	Normally, `git rm` refuses to update index entries whose paths do
 	not fit within the sparse-checkout cone. See
 	linkgit:git-sparse-checkout[1] for more.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	`git rm` normally outputs one line (in the form of an `rm` command)
 	for each file removed. This option suppresses that output.
 
---pathspec-from-file=<file>::
-	Pathspec is passed in `<file>` instead of commandline args. If
-	`<file>` is exactly `-` then standard input is used. Pathspec
-	elements are separated by LF or CR/LF. Pathspec elements can be
+`--pathspec-from-file=<file>`::
+	Pathspec is passed in _<file>_ instead of  args. If
+	_<file>_ is exactly `-` then standard input is used. Pathspec
+	elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
 	quoted as explained for the configuration variable `core.quotePath`
 	(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
 	global `--literal-pathspecs`.
 
---pathspec-file-nul::
+`--pathspec-file-nul`::
 	Only meaningful with `--pathspec-from-file`. Pathspec elements are
-	separated with NUL character and all other characters are taken
+	separated with _NUL_ character and all other characters are taken
 	literally (including newlines and quotes).
 
 
@@ -153,15 +153,15 @@ SUBMODULES
 ----------
 Only submodules using a gitfile (which means they were cloned
 with a Git version 1.7.8 or newer) will be removed from the work
-tree, as their repository lives inside the .git directory of the
+tree, as their repository lives inside the `.git` directory of the
 superproject. If a submodule (or one of those nested inside it)
-still uses a .git directory, `git rm` will move the submodules
+still uses a `.git` directory, `git rm` moves the submodules
 git directory into the superprojects git directory to protect
-the submodule's history. If it exists the submodule.<name> section
+the submodule's history. If it exists the `submodule.<name>` section
 in the linkgit:gitmodules[5] file will also be removed and that file
-will be staged (unless --cached or -n are used).
+will be staged (unless `--cached` or `-n` are used).
 
-A submodule is considered up to date when the HEAD is the same as
+A submodule is considered up to date when the `HEAD` is the same as
 recorded in the index, no tracked files are modified and no untracked
 files that aren't ignored are present in the submodule's work tree.
 Ignored files are deemed expendable and won't stop a submodule's work
diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
new file mode 100644
index 0000000000..263b977353
--- /dev/null
+++ b/Documentation/git-send-email.adoc
@@ -0,0 +1,702 @@
+git-send-email(1)
+=================
+
+NAME
+----
+git-send-email - Send a collection of patches as emails
+
+
+SYNOPSIS
+--------
+[verse]
+'git send-email' [<options>] (<file>|<directory>)...
+'git send-email' [<options>] <format-patch-options>
+'git send-email' --dump-aliases
+'git send-email' --translate-aliases
+
+
+DESCRIPTION
+-----------
+Takes the patches given on the command line and emails them out.
+Patches can be specified as files, directories (which will send all
+files in the directory), or directly as a revision list.  In the
+last case, any format accepted by linkgit:git-format-patch[1] can
+be passed to `git send-email`, as well as options understood by
+linkgit:git-format-patch[1].
+
+The header of the email is configurable via command-line options.  If not
+specified on the command line, the user will be prompted with a ReadLine
+enabled interface to provide the necessary information.
+
+There are two formats accepted for patch files:
+
+1. mbox format files
++
+This is what linkgit:git-format-patch[1] generates.  Most headers and MIME
+formatting are ignored.
+
+2. The original format used by Greg Kroah-Hartman's `send_lots_of_email.pl`
+   script
++
+This format expects the first line of the file to contain the `Cc:` value
+and the `Subject:` of the message as the second line.
+
+
+OPTIONS
+-------
+
+Composing
+~~~~~~~~~
+
+--annotate::
+	Review and edit each patch you're about to send. Default is the value
+	of `sendemail.annotate`. See the CONFIGURATION section for
+	`sendemail.multiEdit`.
+
+--bcc=<address>,...::
+	Specify a `Bcc:` value for each email. Default is the value of
+	`sendemail.bcc`.
++
+This option may be specified multiple times.
+
+--cc=<address>,...::
+	Specify a starting `Cc:` value for each email.
+	Default is the value of `sendemail.cc`.
++
+This option may be specified multiple times.
+
+--compose::
+	Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1])
+	to edit an introductory message for the patch series.
++
+When `--compose` is used, `git send-email` will use the `From`, `To`, `Cc`,
+`Bcc`, `Subject`, `Reply-To`, and `In-Reply-To` headers specified in the
+message. If the body of the message (what you type after the headers and a
+blank line) only contains blank (or `Git:` prefixed) lines, the summary won't be
+sent, but the headers mentioned above will be used unless they are
+removed.
++
+Missing `From` or `In-Reply-To` headers will be prompted for.
++
+See the CONFIGURATION section for `sendemail.multiEdit`.
+
+--from=<address>::
+	Specify the sender of the emails.  If not specified on the command line,
+	the value of the `sendemail.from` configuration option is used.  If
+	neither the command-line option nor `sendemail.from` are set, then the
+	user will be prompted for the value.  The default for the prompt will be
+	the value of `GIT_AUTHOR_IDENT`, or `GIT_COMMITTER_IDENT` if that is not
+	set, as returned by `git var -l`.
+
+--reply-to=<address>::
+	Specify the address where replies from recipients should go to.
+	Use this if replies to messages should go to another address than what
+	is specified with the `--from` parameter.
+
+--in-reply-to=<identifier>::
+	Make the first mail (or all the mails with `--no-thread`) appear as a
+	reply to the given Message-ID, which avoids breaking threads to
+	provide a new patch series.
+	The second and subsequent emails will be sent as replies according to
+	the `--[no-]chain-reply-to` setting.
++
+So for example when `--thread` and `--no-chain-reply-to` are specified, the
+second and subsequent patches will be replies to the first one like in the
+illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:
++
+  [PATCH 0/2] Here is what I did...
+    [PATCH 1/2] Clean up and tests
+    [PATCH 2/2] Implementation
+    [PATCH v2 0/3] Here is a reroll
+      [PATCH v2 1/3] Clean up
+      [PATCH v2 2/3] New tests
+      [PATCH v2 3/3] Implementation
++
+Only necessary if `--compose` is also set.  If `--compose`
+is not set, this will be prompted for.
+
+--outlook-id-fix::
+--no-outlook-id-fix::
+	Microsoft Outlook SMTP servers discard the Message-ID sent via email and
+	assign a new random Message-ID, thus breaking threads.
++
+With `--outlook-id-fix`, `git send-email` uses a mechanism specific to
+Outlook servers to learn the Message-ID the server assigned to fix the
+threading. Use it only when you know that the server reports the
+rewritten Message-ID the same way as Outlook servers do.
++
+Without this option specified, the fix is done by default when talking
+to 'smtp.office365.com' or 'smtp-mail.outlook.com'. Use
+`--no-outlook-id-fix` to disable even when talking to these two servers.
+
+--subject=<string>::
+	Specify the initial subject of the email thread.
+	Only necessary if `--compose` is also set.  If `--compose`
+	is not set, this will be prompted for.
+
+--to=<address>,...::
+	Specify the primary recipient of the emails generated. Generally, this
+	will be the upstream maintainer of the project involved. Default is the
+	value of the `sendemail.to` configuration value; if that is unspecified,
+	and `--to-cmd` is not specified, this will be prompted for.
++
+This option may be specified multiple times.
+
+--8bit-encoding=<encoding>::
+	When encountering a non-ASCII message or subject that does not
+	declare its encoding, add headers/quoting to indicate it is
+	encoded in <encoding>.  Default is the value of the
+	`sendemail.assume8bitEncoding`; if that is unspecified, this
+	will be prompted for if any non-ASCII files are encountered.
++
+Note that no attempts whatsoever are made to validate the encoding.
+
+--compose-encoding=<encoding>::
+	Specify encoding of compose message. Default is the value of the
+	`sendemail.composeEncoding`; if that is unspecified, UTF-8 is assumed.
+
+--transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)::
+	Specify the transfer encoding to be used to send the message over SMTP.
+	`7bit` will fail upon encountering a non-ASCII message. `quoted-printable`
+	can be useful when the repository contains files that contain carriage
+	returns, but makes the raw patch email file (as saved from an MUA) much
+	harder to inspect manually. `base64` is even more fool proof, but also
+	even more opaque. `auto` will use `8bit` when possible, and
+	`quoted-printable` otherwise.
++
+Default is the value of the `sendemail.transferEncoding` configuration
+value; if that is unspecified, default to `auto`.
+
+--xmailer::
+--no-xmailer::
+	Add (or prevent adding) the `X-Mailer:` header.  By default,
+	the header is added, but it can be turned off by setting the
+	`sendemail.xmailer` configuration variable to `false`.
+
+Sending
+~~~~~~~
+
+--envelope-sender=<address>::
+	Specify the envelope sender used to send the emails.
+	This is useful if your default address is not the address that is
+	subscribed to a list. In order to use the `From` address, set the
+	value to `auto`. If you use the `sendmail` binary, you must have
+	suitable privileges for the `-f` parameter.  Default is the value of the
+	`sendemail.envelopeSender` configuration variable; if that is
+	unspecified, choosing the envelope sender is left to your MTA.
+
+--sendmail-cmd=<command>::
+	Specify a command to run to send the email. The command should
+	be sendmail-like; specifically, it must support the `-i` option.
+	The command will be executed in the shell if necessary.  Default
+	is the value of `sendemail.sendmailCmd`.  If unspecified, and if
+	`--smtp-server` is also unspecified, `git send-email` will search
+	for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH`.
+
+--smtp-encryption=<encryption>::
+	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
+	HELO/EHLO command to the SMTP server.  Some servers require the
+	FQDN to match your IP address.  If not set, `git send-email` attempts
+	to determine your FQDN automatically.  Default is the value of
+	`sendemail.smtpDomain`.
+
+--smtp-auth=<mechanisms>::
+	Whitespace-separated list of allowed SMTP-AUTH mechanisms. This setting
+	forces using only the listed mechanisms. Example:
++
+------
+$ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ...
+------
++
+If at least one of the specified mechanisms matches the ones advertised by the
+SMTP server and if it is supported by the utilized SASL library, the mechanism
+is used for authentication. If neither `sendemail.smtpAuth` nor `--smtp-auth`
+is specified, all mechanisms supported by the SASL library can be used. The
+special value `none` maybe specified to completely disable authentication
+independently of `--smtp-user`.
+
+--smtp-pass[=<password>]::
+	Password for SMTP-AUTH. The argument is optional: If no
+	argument is specified, then the empty string is used as
+	the password. Default is the value of `sendemail.smtpPass`,
+	however `--smtp-pass` always overrides this value.
++
+Furthermore, passwords need not be specified in configuration files
+or on the command line. If a username has been specified (with
+`--smtp-user` or a `sendemail.smtpUser`), but no password has been
+specified (with `--smtp-pass` or `sendemail.smtpPass`), then
+a password is obtained using linkgit:git-credential[1].
+
+--no-smtp-auth::
+	Disable SMTP authentication. Short hand for `--smtp-auth=none`.
+
+--smtp-server=<host>::
+	If set, specifies the outgoing SMTP server to use (e.g.
+	`smtp.example.com` or a raw IP address).  If unspecified, and if
+	`--sendmail-cmd` is also unspecified, the default is to search
+	for `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a
+	program is available, falling back to `localhost` otherwise.
++
+For backward compatibility, this option can also specify a full pathname
+of a sendmail-like program instead; the program must support the `-i`
+option.  This method does not support passing arguments or using plain
+command names.  For those use cases, consider using `--sendmail-cmd`
+instead.
+
+--smtp-server-port=<port>::
+	Specifies a port different from the default port (SMTP
+	servers typically listen to smtp port 25, but may also listen to
+	submission port 587, or the common SSL smtp port 465);
+	symbolic port names (e.g. `submission` instead of 587)
+	are also accepted. The port can also be set with the
+	`sendemail.smtpServerPort` configuration variable.
+
+--smtp-server-option=<option>::
+	If set, specifies the outgoing SMTP server option to use.
+	Default value can be specified by the `sendemail.smtpServerOption`
+	configuration option.
++
+The `--smtp-server-option` option must be repeated for each option you want
+to pass to the server. Likewise, different lines in the configuration files
+must be used for each option.
+
+--smtp-ssl::
+	Legacy alias for `--smtp-encryption ssl`.
+
+--smtp-ssl-cert-path::
+	Path to a store of trusted CA certificates for SMTP SSL/TLS
+	certificate validation (either a directory that has been processed
+	by `c_rehash`, or a single file containing one or more PEM format
+	certificates concatenated together: see the description of the
+	`-CAfile` _<file>_ and the `-CApath` _<dir>_ options of
+	https://docs.openssl.org/master/man1/openssl-verify/
+	[OpenSSL's verify(1) manual page] for more information on these).
+	Set it to an empty string to disable certificate verification.
+	Defaults to the value of the `sendemail.smtpSSLCertPath` configuration
+	variable, if set, or the backing SSL library's compiled-in default
+	otherwise (which should be the best choice on most platforms).
+
+--smtp-user=<user>::
+	Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`;
+	if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`),
+	then authentication is not attempted.
+
+--smtp-debug=(0|1)::
+	Enable (1) or disable (0) debug output. If enabled, SMTP
+	commands and replies will be printed. Useful to debug TLS
+	connection and authentication problems.
+
+--imap-sent-folder=<folder>::
+	Some email providers (e.g. iCloud) do not send a copy of the emails sent
+	using SMTP to the `Sent` folder or similar in your mailbox. Use this option
+	to use `git imap-send` to send a copy of the emails to the folder specified
+	using this option. You can run `git imap-send --list` to get a list of
+	valid folder names, including the correct name of the `Sent` folder in
+	your mailbox. You can also use this option to send emails to a dedicated
+	IMAP folder of your choice.
++
+This feature requires setting up `git imap-send`. See linkgit:git-imap-send[1]
+for instructions.
+
+--use-imap-only::
+--no-use-imap-only::
+	If this is set, all emails will only be copied to the IMAP folder specified
+	with `--imap-sent-folder` or `sendemail.imapSentFolder` and will not be sent
+	to the recipients. Useful if you just want to create a draft of the emails
+	and use another email client to send them.
+	If disabled with `--no-use-imap-only`, the emails will be sent like usual.
+	Disabled by default, but the `sendemail.useImapOnly` configuration
+	variable can be used to enable it.
+
++
+This feature requires setting up `git imap-send`. See linkgit:git-imap-send[1]
+for instructions.
+
+--batch-size=<num>::
+	Some email servers (e.g. 'smtp.163.com') limit the number of emails to be
+	sent per session (connection) and this will lead to a failure when
+	sending many messages.  With this option, send-email will disconnect after
+	sending _<num>_ messages and wait for a few seconds
+	(see `--relogin-delay`) and reconnect, to work around such a limit.
+	You may want to use some form of credential helper to avoid having to
+	retype your password every time this happens.  Defaults to the
+	`sendemail.smtpBatchSize` configuration variable.
+
+--relogin-delay=<int>::
+	Waiting _<int>_ seconds before reconnecting to SMTP server. Used together
+	with `--batch-size` option.  Defaults to the `sendemail.smtpReloginDelay`
+	configuration variable.
+
+Automating
+~~~~~~~~~~
+
+--no-to::
+--no-cc::
+--no-bcc::
+	Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously
+	set via config.
+
+--no-identity::
+	Clears the previously read value of `sendemail.identity` set
+	via config, if any.
+
+--to-cmd=<command>::
+	Specify a command to execute once per patch file which
+	should generate patch file specific `To:` entries.
+	Output of this command must be single email address per line.
+	Default is the value of `sendemail.toCmd` configuration value.
+
+--cc-cmd=<command>::
+	Specify a command to execute once per patch file which
+	should generate patch file specific `Cc:` entries.
+	Output of this command must be single email address per line.
+	Default is the value of `sendemail.ccCmd` configuration value.
+
+--header-cmd=<command>::
+	Specify a command that is executed once per outgoing message
+	and output RFC 2822 style header lines to be inserted into
+	them. When the `sendemail.headerCmd` configuration variable is
+	set, its value is always used. When `--header-cmd` is provided
+	at the command line, its value takes precedence over the
+	`sendemail.headerCmd` configuration variable.
+
+--no-header-cmd::
+	Disable any header command in use.
+
+--chain-reply-to::
+--no-chain-reply-to::
+	If this is set, each email will be sent as a reply to the previous
+	email sent.  If disabled with `--no-chain-reply-to`, all emails after
+	the first will be sent as replies to the first email sent.  When using
+	this, it is recommended that the first file given be an overview of the
+	entire patch series. Disabled by default, but the `sendemail.chainReplyTo`
+	configuration variable can be used to enable it.
+
+--identity=<identity>::
+	A configuration identity. When given, causes values in the
+	`sendemail.<identity>` subsection to take precedence over
+	values in the `sendemail` section. The default identity is
+	the value of `sendemail.identity`.
+
+--signed-off-by-cc::
+--no-signed-off-by-cc::
+	If this is set, add emails found in the `Signed-off-by` trailer or `Cc:`
+	lines to the cc list. Default is the value of `sendemail.signedOffByCc`
+	configuration value; if that is unspecified, default to
+	`--signed-off-by-cc`.
+
+--cc-cover::
+--no-cc-cover::
+	If this is set, emails found in `Cc:` headers in the first patch of
+	the series (typically the cover letter) are added to the cc list
+	for each email set. Default is the value of `sendemail.ccCover`
+	configuration value; if that is unspecified, default to `--no-cc-cover`.
+
+--to-cover::
+--no-to-cover::
+	If this is set, emails found in `To:` headers in the first patch of
+	the series (typically the cover letter) are added to the to list
+	for each email set. Default is the value of `sendemail.toCover`
+	configuration value; if that is unspecified, default to `--no-to-cover`.
+
+--suppress-cc=<category>::
+	Specify an additional category of recipients to suppress the
+	auto-cc of:
++
+--
+- `author` will avoid including the patch author.
+- `self` will avoid including the sender.
+- `cc` will avoid including anyone mentioned in Cc lines in the patch header
+  except for self (use `self` for that).
+- `bodycc` will avoid including anyone mentioned in Cc lines in the
+  patch body (commit message) except for self (use `self` for that).
+- `sob` will avoid including anyone mentioned in the Signed-off-by trailers except
+  for self (use `self` for that).
+- `misc-by` will avoid including anyone mentioned in Acked-by,
+  Reviewed-by, Tested-by and other "-by" lines in the patch body,
+  except Signed-off-by (use `sob` for that).
+- `cccmd` will avoid running the --cc-cmd.
+- `body` is equivalent to `sob` + `bodycc` + `misc-by`.
+- `all` will suppress all auto cc values.
+--
++
+Default is the value of `sendemail.suppressCc` configuration value; if
+that is unspecified, default to `self` if `--suppress-from` is
+specified, as well as `body` if `--no-signed-off-cc` is specified.
+
+--suppress-from::
+--no-suppress-from::
+	If this is set, do not add the `From:` address to the `Cc:` list.
+	Default is the value of `sendemail.suppressFrom` configuration
+	value; if that is unspecified, default to `--no-suppress-from`.
+
+--thread::
+--no-thread::
+	If this is set, the `In-Reply-To` and `References` headers will be
+	added to each email sent.  Whether each mail refers to the
+	previous email (`deep` threading per `git format-patch`
+	wording) or to the first email (`shallow` threading) is
+	governed by `--[no-]chain-reply-to`.
++
+If disabled with `--no-thread`, those headers will not be added
+(unless specified with `--in-reply-to`).  Default is the value of the
+`sendemail.thread` configuration value; if that is unspecified,
+default to `--thread`.
++
+It is up to the user to ensure that no In-Reply-To header already
+exists when `git send-email` is asked to add it (especially note that
+`git format-patch` can be configured to do the threading itself).
+Failure to do so may not produce the expected result in the
+recipient's MUA.
+
+--mailmap::
+--no-mailmap::
+	Use the mailmap file (see linkgit:gitmailmap[5]) to map all
+	addresses to their canonical real name and email address. Additional
+	mailmap data specific to `git send-email` may be provided using the
+	`sendemail.mailmap.file` or `sendemail.mailmap.blob` configuration
+	values. Defaults to `sendemail.mailmap`.
+
+Administering
+~~~~~~~~~~~~~
+
+--confirm=<mode>::
+	Confirm just before sending:
++
+--
+- `always` will always confirm before sending.
+- `never` will never confirm before sending.
+- `cc` will confirm before sending when send-email has automatically
+  added addresses from the patch to the Cc list.
+- `compose` will confirm before sending the first message when using --compose.
+- `auto` is equivalent to `cc` + `compose`.
+--
++
+Default is the value of `sendemail.confirm` configuration value; if that
+is unspecified, default to `auto` unless any of the suppress options
+have been specified, in which case default to `compose`.
+
+--dry-run::
+	Do everything except actually send the emails.
+
+--format-patch::
+--no-format-patch::
+	When an argument may be understood either as a reference or as a file name,
+	choose to understand it as a format-patch argument (`--format-patch`)
+	or as a file name (`--no-format-patch`). By default, when such a conflict
+	occurs, `git send-email` will fail.
+
+--quiet::
+	Make `git send-email` less verbose.  One line per email should be
+	all that is output.
+
+--validate::
+--no-validate::
+	Perform sanity checks on patches.
+	Currently, validation means the following:
++
+--
+		*	Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
+		*	Warn of patches that contain lines longer than
+			998 characters unless a suitable transfer encoding
+			(`auto`, `base64`, or `quoted-printable`) is used;
+			this is due to SMTP limits as described by
+			https://www.ietf.org/rfc/rfc5322.txt.
+--
++
+Default is the value of `sendemail.validate`; if this is not set,
+default to `--validate`.
+
+--force::
+	Send emails even if safety checks would prevent it.
+
+
+Information
+~~~~~~~~~~~
+
+--dump-aliases::
+	Instead of the normal operation, dump the shorthand alias names from
+	the configured alias file(s), one per line in alphabetical order. Note
+	that this only includes the alias name and not its expanded email addresses.
+	See `sendemail.aliasesFile` for more information about aliases.
+
+--translate-aliases::
+	Instead of the normal operation, read from standard input and
+	interpret each line as an email alias. Translate it according to the
+	configured alias file(s). Output each translated name and email
+	address to standard output, one per line. See `sendemail.aliasFile`
+	for more information about aliases.
+
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.adoc[]
+
+include::config/sendemail.adoc[]
+
+EXAMPLES OF SMTP SERVERS
+------------------------
+Use Gmail as the SMTP Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To use `git send-email` to send your patches through the Gmail SMTP server,
+edit `~/.gitconfig` to specify your account settings:
+
+----
+[sendemail]
+	smtpEncryption = ssl
+	smtpServer = smtp.gmail.com
+	smtpUser = yourname@gmail.com
+	smtpServerPort = 465
+----
+
+Gmail does not allow using your regular password for `git send-email`.
+If you have multi-factor authentication set up on your Gmail account, you can
+generate an app-specific password for use with `git send-email`. Visit
+https://security.google.com/settings/security/apppasswords to create it.
+
+Alternatively, instead of using an app-specific password, you can use
+OAuth2.0 authentication with Gmail. OAuth2.0 is more secure than
+app-specific passwords, and works regardless of whether you have multi-factor
+authentication set up. `OAUTHBEARER` and `XOAUTH2` are common mechanisms used
+for this type of authentication. Gmail supports both of them. As an example,
+if you want to use `OAUTHBEARER`, edit your `~/.gitconfig` file and add
+`smtpAuth = OAUTHBEARER` to your account settings:
+
+----
+[sendemail]
+	smtpEncryption = ssl
+	smtpServer = smtp.gmail.com
+	smtpUser = yourname@gmail.com
+	smtpServerPort = 465
+	smtpAuth = OAUTHBEARER
+----
+
+Another alternative is using a tool developed by Google known as
+https://github.com/google/gmail-oauth2-tools/tree/master/go/sendgmail[sendgmail]
+to send emails using `git send-email`.
+
+Use Microsoft Outlook as the SMTP Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unlike Gmail, Microsoft Outlook no longer supports app-specific passwords.
+Therefore, OAuth2.0 authentication must be used for Outlook. Also, it only
+supports `XOAUTH2` authentication mechanism.
+
+Edit `~/.gitconfig` to specify your account settings for Outlook and use its
+SMTP server with `git send-email`:
+
+----
+[sendemail]
+	smtpEncryption = tls
+	smtpServer = smtp.office365.com
+	smtpUser = yourname@outlook.com
+	smtpServerPort = 587
+	smtpAuth = XOAUTH2
+----
+
+SENDING PATCHES
+---------------
+Once your commits are ready to be sent to the mailing list, run the
+following commands:
+
+	$ git format-patch --cover-letter -M origin/master -o outgoing/
+	$ edit outgoing/0000-*
+	$ git send-email outgoing/*
+
+The first time you run it, you will be prompted for your credentials.  Enter the
+app-specific or your regular password as appropriate.
+
+If you have a credential helper configured (see linkgit:git-credential[1]), the
+password will be saved in the credential store so you won't have to type it the
+next time.
+
+If you are using OAuth2.0 authentication, you need to use an access token in
+place of a password when prompted. Various OAuth2.0 token generators are
+available online. Community maintained credential helpers are also available:
+
+	- https://github.com/AdityaGarg8/git-credential-email[git-credential-gmail]
+	  (cross platform, dedicated helper for authenticating Gmail accounts)
+
+	- https://github.com/AdityaGarg8/git-credential-email[git-credential-outlook]
+	  (cross platform, dedicated helper for authenticating Microsoft Outlook accounts)
+
+	- https://github.com/AdityaGarg8/git-credential-email[git-credential-yahoo]
+	  (cross platform, dedicated helper for authenticating Yahoo accounts)
+
+	- https://github.com/AdityaGarg8/git-credential-email[git-credential-aol]
+	  (cross platform, dedicated helper for authenticating AOL accounts)
+
+You can also see linkgit:gitcredentials[7] for more OAuth based authentication
+helpers.
+
+Proton Mail does not provide an SMTP server to send emails. If you are a paid
+customer of Proton Mail, you can use
+https://proton.me/mail/bridge[Proton Mail Bridge]
+officially provided by Proton Mail to create a local SMTP server for sending
+emails. For both free and paid users, community maintained projects like
+https://github.com/AdityaGarg8/git-credential-email[git-protonmail] can be
+used.
+
+Note: the following core Perl modules that may be installed with your
+distribution of Perl are required:
+
+https://metacpan.org/pod/MIME::Base64[MIME::Base64],
+https://metacpan.org/pod/MIME::QuotedPrint[MIME::QuotedPrint],
+https://metacpan.org/pod/Net::Domain[Net::Domain] and
+https://metacpan.org/pod/Net::SMTP[Net::SMTP].
+
+These additional Perl modules are also required:
+
+https://metacpan.org/pod/Authen::SASL[Authen::SASL] and
+https://metacpan.org/pod/Mail::Address[Mail::Address].
+
+Exploiting the `sendmailCmd` option of `git send-email`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Apart from sending emails via an SMTP server, `git send-email` can also send
+emails through any application that supports sendmail-like commands. You can
+read documentation of `--sendmail-cmd=<command>` above for more information.
+This ability can be very useful if you want to use another application as an
+SMTP client for `git send-email`, or if your email provider uses proprietary
+APIs instead of SMTP to send emails.
+
+As an example, lets see how to configure https://marlam.de/msmtp/[msmtp], a
+popular SMTP client found in many Linux distributions. Edit `~/.gitconfig`
+to instruct `git-send-email` to use it for sending emails.
+
+----
+[sendemail]
+	sendmailCmd = /usr/bin/msmtp # Change this to the path where msmtp is installed
+----
+
+Links of a few such community maintained helpers are:
+
+	- https://marlam.de/msmtp/[msmtp]
+	  (popular SMTP client with many features, available for Linux and macOS)
+
+	- https://github.com/AdityaGarg8/git-credential-email[git-protonmail]
+	  (cross platform client that can send emails using the ProtonMail API)
+
+	- https://github.com/AdityaGarg8/git-credential-email[git-msgraph]
+	  (cross platform client that can send emails using the Microsoft Graph API)
+
+SEE ALSO
+--------
+linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
deleted file mode 100644
index bc3ef45acb..0000000000
--- a/Documentation/git-send-email.txt
+++ /dev/null
@@ -1,543 +0,0 @@
-git-send-email(1)
-=================
-
-NAME
-----
-git-send-email - Send a collection of patches as emails
-
-
-SYNOPSIS
---------
-[verse]
-'git send-email' [<options>] (<file>|<directory>)...
-'git send-email' [<options>] <format-patch-options>
-'git send-email' --dump-aliases
-'git send-email' --translate-aliases
-
-
-DESCRIPTION
------------
-Takes the patches given on the command line and emails them out.
-Patches can be specified as files, directories (which will send all
-files in the directory), or directly as a revision list.  In the
-last case, any format accepted by linkgit:git-format-patch[1] can
-be passed to git send-email, as well as options understood by
-linkgit:git-format-patch[1].
-
-The header of the email is configurable via command-line options.  If not
-specified on the command line, the user will be prompted with a ReadLine
-enabled interface to provide the necessary information.
-
-There are two formats accepted for patch files:
-
-1. mbox format files
-+
-This is what linkgit:git-format-patch[1] generates.  Most headers and MIME
-formatting are ignored.
-
-2. The original format used by Greg Kroah-Hartman's 'send_lots_of_email.pl'
-   script
-+
-This format expects the first line of the file to contain the "Cc:" value
-and the "Subject:" of the message as the second line.
-
-
-OPTIONS
--------
-
-Composing
-~~~~~~~~~
-
---annotate::
-	Review and edit each patch you're about to send. Default is the value
-	of `sendemail.annotate`. See the CONFIGURATION section for
-	`sendemail.multiEdit`.
-
---bcc=<address>,...::
-	Specify a "Bcc:" value for each email. Default is the value of
-	`sendemail.bcc`.
-+
-This option may be specified multiple times.
-
---cc=<address>,...::
-	Specify a starting "Cc:" value for each email.
-	Default is the value of `sendemail.cc`.
-+
-This option may be specified multiple times.
-
---compose::
-	Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1])
-	to edit an introductory message for the patch series.
-+
-When `--compose` is used, git send-email will use the From, To, Cc, Bcc,
-Subject, Reply-To, and In-Reply-To headers specified in the message. If
-the body of the message (what you type after the headers and a blank
-line) only contains blank (or Git: prefixed) lines, the summary won't be
-sent, but the headers mentioned above will be used unless they are
-removed.
-+
-Missing From or In-Reply-To headers will be prompted for.
-+
-See the CONFIGURATION section for `sendemail.multiEdit`.
-
---from=<address>::
-	Specify the sender of the emails.  If not specified on the command line,
-	the value of the `sendemail.from` configuration option is used.  If
-	neither the command-line option nor `sendemail.from` are set, then the
-	user will be prompted for the value.  The default for the prompt will be
-	the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not
-	set, as returned by "git var -l".
-
---reply-to=<address>::
-	Specify the address where replies from recipients should go to.
-	Use this if replies to messages should go to another address than what
-	is specified with the --from parameter.
-
---in-reply-to=<identifier>::
-	Make the first mail (or all the mails with `--no-thread`) appear as a
-	reply to the given Message-ID, which avoids breaking threads to
-	provide a new patch series.
-	The second and subsequent emails will be sent as replies according to
-	the `--[no-]chain-reply-to` setting.
-+
-So for example when `--thread` and `--no-chain-reply-to` are specified, the
-second and subsequent patches will be replies to the first one like in the
-illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:
-+
-  [PATCH 0/2] Here is what I did...
-    [PATCH 1/2] Clean up and tests
-    [PATCH 2/2] Implementation
-    [PATCH v2 0/3] Here is a reroll
-      [PATCH v2 1/3] Clean up
-      [PATCH v2 2/3] New tests
-      [PATCH v2 3/3] Implementation
-+
-Only necessary if --compose is also set.  If --compose
-is not set, this will be prompted for.
-
---subject=<string>::
-	Specify the initial subject of the email thread.
-	Only necessary if --compose is also set.  If --compose
-	is not set, this will be prompted for.
-
---to=<address>,...::
-	Specify the primary recipient of the emails generated. Generally, this
-	will be the upstream maintainer of the project involved. Default is the
-	value of the `sendemail.to` configuration value; if that is unspecified,
-	and --to-cmd is not specified, this will be prompted for.
-+
-This option may be specified multiple times.
-
---8bit-encoding=<encoding>::
-	When encountering a non-ASCII message or subject that does not
-	declare its encoding, add headers/quoting to indicate it is
-	encoded in <encoding>.  Default is the value of the
-	'sendemail.assume8bitEncoding'; if that is unspecified, this
-	will be prompted for if any non-ASCII files are encountered.
-+
-Note that no attempts whatsoever are made to validate the encoding.
-
---compose-encoding=<encoding>::
-	Specify encoding of compose message. Default is the value of the
-	'sendemail.composeEncoding'; if that is unspecified, UTF-8 is assumed.
-
---transfer-encoding=(7bit|8bit|quoted-printable|base64|auto)::
-	Specify the transfer encoding to be used to send the message over SMTP.
-	7bit will fail upon encountering a non-ASCII message.  quoted-printable
-	can be useful when the repository contains files that contain carriage
-	returns, but makes the raw patch email file (as saved from a MUA) much
-	harder to inspect manually.  base64 is even more fool proof, but also
-	even more opaque.  auto will use 8bit when possible, and quoted-printable
-	otherwise.
-+
-Default is the value of the `sendemail.transferEncoding` configuration
-value; if that is unspecified, default to `auto`.
-
---xmailer::
---no-xmailer::
-	Add (or prevent adding) the "X-Mailer:" header.  By default,
-	the header is added, but it can be turned off by setting the
-	`sendemail.xmailer` configuration variable to `false`.
-
-Sending
-~~~~~~~
-
---envelope-sender=<address>::
-	Specify the envelope sender used to send the emails.
-	This is useful if your default address is not the address that is
-	subscribed to a list. In order to use the 'From' address, set the
-	value to "auto". If you use the sendmail binary, you must have
-	suitable privileges for the -f parameter.  Default is the value of the
-	`sendemail.envelopeSender` configuration variable; if that is
-	unspecified, choosing the envelope sender is left to your MTA.
-
---sendmail-cmd=<command>::
-	Specify a command to run to send the email. The command should
-	be sendmail-like; specifically, it must support the `-i` option.
-	The command will be executed in the shell if necessary.  Default
-	is the value of `sendemail.sendmailCmd`.  If unspecified, and if
-	--smtp-server is also unspecified, git-send-email will search
-	for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.
-
---smtp-encryption=<encryption>::
-	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
-	HELO/EHLO command to the SMTP server.  Some servers require the
-	FQDN to match your IP address.  If not set, git send-email attempts
-	to determine your FQDN automatically.  Default is the value of
-	`sendemail.smtpDomain`.
-
---smtp-auth=<mechanisms>::
-	Whitespace-separated list of allowed SMTP-AUTH mechanisms. This setting
-	forces using only the listed mechanisms. Example:
-+
-------
-$ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ...
-------
-+
-If at least one of the specified mechanisms matches the ones advertised by the
-SMTP server and if it is supported by the utilized SASL library, the mechanism
-is used for authentication. If neither 'sendemail.smtpAuth' nor `--smtp-auth`
-is specified, all mechanisms supported by the SASL library can be used. The
-special value 'none' maybe specified to completely disable authentication
-independently of `--smtp-user`
-
---smtp-pass[=<password>]::
-	Password for SMTP-AUTH. The argument is optional: If no
-	argument is specified, then the empty string is used as
-	the password. Default is the value of `sendemail.smtpPass`,
-	however `--smtp-pass` always overrides this value.
-+
-Furthermore, passwords need not be specified in configuration files
-or on the command line. If a username has been specified (with
-`--smtp-user` or a `sendemail.smtpUser`), but no password has been
-specified (with `--smtp-pass` or `sendemail.smtpPass`), then
-a password is obtained using 'git-credential'.
-
---no-smtp-auth::
-	Disable SMTP authentication. Short hand for `--smtp-auth=none`
-
---smtp-server=<host>::
-	If set, specifies the outgoing SMTP server to use (e.g.
-	`smtp.example.com` or a raw IP address).  If unspecified, and if
-	`--sendmail-cmd` is also unspecified, the default is to search
-	for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH if such a
-	program is available, falling back to `localhost` otherwise.
-+
-For backward compatibility, this option can also specify a full pathname
-of a sendmail-like program instead; the program must support the `-i`
-option.  This method does not support passing arguments or using plain
-command names.  For those use cases, consider using `--sendmail-cmd`
-instead.
-
---smtp-server-port=<port>::
-	Specifies a port different from the default port (SMTP
-	servers typically listen to smtp port 25, but may also listen to
-	submission port 587, or the common SSL smtp port 465);
-	symbolic port names (e.g. "submission" instead of 587)
-	are also accepted. The port can also be set with the
-	`sendemail.smtpServerPort` configuration variable.
-
---smtp-server-option=<option>::
-	If set, specifies the outgoing SMTP server option to use.
-	Default value can be specified by the `sendemail.smtpServerOption`
-	configuration option.
-+
-The --smtp-server-option option must be repeated for each option you want
-to pass to the server. Likewise, different lines in the configuration files
-must be used for each option.
-
---smtp-ssl::
-	Legacy alias for '--smtp-encryption ssl'.
-
---smtp-ssl-cert-path::
-	Path to a store of trusted CA certificates for SMTP SSL/TLS
-	certificate validation (either a directory that has been processed
-	by 'c_rehash', or a single file containing one or more PEM format
-	certificates concatenated together: see verify(1) -CAfile and
-	-CApath for more information on these). Set it to an empty string
-	to disable certificate verification. Defaults to the value of the
-	`sendemail.smtpSSLCertPath` configuration variable, if set, or the
-	backing SSL library's compiled-in default otherwise (which should
-	be the best choice on most platforms).
-
---smtp-user=<user>::
-	Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`;
-	if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`),
-	then authentication is not attempted.
-
---smtp-debug=(0|1)::
-	Enable (1) or disable (0) debug output. If enabled, SMTP
-	commands and replies will be printed. Useful to debug TLS
-	connection and authentication problems.
-
---batch-size=<num>::
-	Some email servers (e.g. smtp.163.com) limit the number emails to be
-	sent per session (connection) and this will lead to a failure when
-	sending many messages.  With this option, send-email will disconnect after
-	sending $<num> messages and wait for a few seconds (see --relogin-delay)
-	and reconnect, to work around such a limit.  You may want to
-	use some form of credential helper to avoid having to retype
-	your password every time this happens.  Defaults to the
-	`sendemail.smtpBatchSize` configuration variable.
-
---relogin-delay=<int>::
-	Waiting $<int> seconds before reconnecting to SMTP server. Used together
-	with --batch-size option.  Defaults to the `sendemail.smtpReloginDelay`
-	configuration variable.
-
-Automating
-~~~~~~~~~~
-
---no-to::
---no-cc::
---no-bcc::
-	Clears any list of "To:", "Cc:", "Bcc:" addresses previously
-	set via config.
-
---no-identity::
-	Clears the previously read value of `sendemail.identity` set
-	via config, if any.
-
---to-cmd=<command>::
-	Specify a command to execute once per patch file which
-	should generate patch file specific "To:" entries.
-	Output of this command must be single email address per line.
-	Default is the value of 'sendemail.toCmd' configuration value.
-
---cc-cmd=<command>::
-	Specify a command to execute once per patch file which
-	should generate patch file specific "Cc:" entries.
-	Output of this command must be single email address per line.
-	Default is the value of `sendemail.ccCmd` configuration value.
-
---header-cmd=<command>::
-	Specify a command that is executed once per outgoing message
-	and output RFC 2822 style header lines to be inserted into
-	them. When the `sendemail.headerCmd` configuration variable is
-	set, its value is always used. When --header-cmd is provided
-	at the command line, its value takes precedence over the
-	`sendemail.headerCmd` configuration variable.
-
---no-header-cmd::
-	Disable any header command in use.
-
---[no-]chain-reply-to::
-	If this is set, each email will be sent as a reply to the previous
-	email sent.  If disabled with "--no-chain-reply-to", all emails after
-	the first will be sent as replies to the first email sent.  When using
-	this, it is recommended that the first file given be an overview of the
-	entire patch series. Disabled by default, but the `sendemail.chainReplyTo`
-	configuration variable can be used to enable it.
-
---identity=<identity>::
-	A configuration identity. When given, causes values in the
-	'sendemail.<identity>' subsection to take precedence over
-	values in the 'sendemail' section. The default identity is
-	the value of `sendemail.identity`.
-
---[no-]signed-off-by-cc::
-	If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the
-	cc list. Default is the value of `sendemail.signedOffByCc` configuration
-	value; if that is unspecified, default to --signed-off-by-cc.
-
---[no-]cc-cover::
-	If this is set, emails found in Cc: headers in the first patch of
-	the series (typically the cover letter) are added to the cc list
-	for each email set. Default is the value of 'sendemail.ccCover'
-	configuration value; if that is unspecified, default to --no-cc-cover.
-
---[no-]to-cover::
-	If this is set, emails found in To: headers in the first patch of
-	the series (typically the cover letter) are added to the to list
-	for each email set. Default is the value of 'sendemail.toCover'
-	configuration value; if that is unspecified, default to --no-to-cover.
-
---suppress-cc=<category>::
-	Specify an additional category of recipients to suppress the
-	auto-cc of:
-+
---
-- 'author' will avoid including the patch author.
-- 'self' will avoid including the sender.
-- 'cc' will avoid including anyone mentioned in Cc lines in the patch header
-  except for self (use 'self' for that).
-- 'bodycc' will avoid including anyone mentioned in Cc lines in the
-  patch body (commit message) except for self (use 'self' for that).
-- 'sob' will avoid including anyone mentioned in the Signed-off-by trailers except
-  for self (use 'self' for that).
-- 'misc-by' will avoid including anyone mentioned in Acked-by,
-  Reviewed-by, Tested-by and other "-by" lines in the patch body,
-  except Signed-off-by (use 'sob' for that).
-- 'cccmd' will avoid running the --cc-cmd.
-- 'body' is equivalent to 'sob' + 'bodycc' + 'misc-by'.
-- 'all' will suppress all auto cc values.
---
-+
-Default is the value of `sendemail.suppressCc` configuration value; if
-that is unspecified, default to 'self' if --suppress-from is
-specified, as well as 'body' if --no-signed-off-cc is specified.
-
---[no-]suppress-from::
-	If this is set, do not add the From: address to the cc: list.
-	Default is the value of `sendemail.suppressFrom` configuration
-	value; if that is unspecified, default to --no-suppress-from.
-
---[no-]thread::
-	If this is set, the In-Reply-To and References headers will be
-	added to each email sent.  Whether each mail refers to the
-	previous email (`deep` threading per 'git format-patch'
-	wording) or to the first email (`shallow` threading) is
-	governed by "--[no-]chain-reply-to".
-+
-If disabled with "--no-thread", those headers will not be added
-(unless specified with --in-reply-to).  Default is the value of the
-`sendemail.thread` configuration value; if that is unspecified,
-default to --thread.
-+
-It is up to the user to ensure that no In-Reply-To header already
-exists when 'git send-email' is asked to add it (especially note that
-'git format-patch' can be configured to do the threading itself).
-Failure to do so may not produce the expected result in the
-recipient's MUA.
-
---[no-]mailmap::
-	Use the mailmap file (see linkgit:gitmailmap[5]) to map all
-	addresses to their canonical real name and email address. Additional
-	mailmap data specific to git-send-email may be provided using the
-	`sendemail.mailmap.file` or `sendemail.mailmap.blob` configuration
-	values. Defaults to `sendemail.mailmap`.
-
-Administering
-~~~~~~~~~~~~~
-
---confirm=<mode>::
-	Confirm just before sending:
-+
---
-- 'always' will always confirm before sending
-- 'never' will never confirm before sending
-- 'cc' will confirm before sending when send-email has automatically
-  added addresses from the patch to the Cc list
-- 'compose' will confirm before sending the first message when using --compose.
-- 'auto' is equivalent to 'cc' + 'compose'
---
-+
-Default is the value of `sendemail.confirm` configuration value; if that
-is unspecified, default to 'auto' unless any of the suppress options
-have been specified, in which case default to 'compose'.
-
---dry-run::
-	Do everything except actually send the emails.
-
---[no-]format-patch::
-	When an argument may be understood either as a reference or as a file name,
-	choose to understand it as a format-patch argument (`--format-patch`)
-	or as a file name (`--no-format-patch`). By default, when such a conflict
-	occurs, git send-email will fail.
-
---quiet::
-	Make git-send-email less verbose.  One line per email should be
-	all that is output.
-
---[no-]validate::
-	Perform sanity checks on patches.
-	Currently, validation means the following:
-+
---
-		*	Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).
-		*	Warn of patches that contain lines longer than
-			998 characters unless a suitable transfer encoding
-			('auto', 'base64', or 'quoted-printable') is used;
-			this is due to SMTP limits as described by
-			https://www.ietf.org/rfc/rfc5322.txt.
---
-+
-Default is the value of `sendemail.validate`; if this is not set,
-default to `--validate`.
-
---force::
-	Send emails even if safety checks would prevent it.
-
-
-Information
-~~~~~~~~~~~
-
---dump-aliases::
-	Instead of the normal operation, dump the shorthand alias names from
-	the configured alias file(s), one per line in alphabetical order. Note
-	that this only includes the alias name and not its expanded email addresses.
-	See 'sendemail.aliasesFile' for more information about aliases.
-
---translate-aliases::
-	Instead of the normal operation, read from standard input and
-	interpret each line as an email alias. Translate it according to the
-	configured alias file(s). Output each translated name and email
-	address to standard output, one per line. See 'sendemail.aliasFile'
-	for more information about aliases.
-
-CONFIGURATION
--------------
-
-include::includes/cmd-config-section-all.txt[]
-
-include::config/sendemail.txt[]
-
-EXAMPLES
---------
-Use gmail as the smtp server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To use 'git send-email' to send your patches through the GMail SMTP server,
-edit ~/.gitconfig to specify your account settings:
-
-----
-[sendemail]
-	smtpEncryption = tls
-	smtpServer = smtp.gmail.com
-	smtpUser = yourname@gmail.com
-	smtpServerPort = 587
-----
-
-If you have multi-factor authentication set up on your Gmail account, you can
-generate an app-specific password for use with 'git send-email'. Visit
-https://security.google.com/settings/security/apppasswords to create it.
-
-Once your commits are ready to be sent to the mailing list, run the
-following commands:
-
-	$ git format-patch --cover-letter -M origin/master -o outgoing/
-	$ edit outgoing/0000-*
-	$ git send-email outgoing/*
-
-The first time you run it, you will be prompted for your credentials.  Enter the
-app-specific or your regular password as appropriate.  If you have credential
-helper configured (see linkgit:git-credential[1]), the password will be saved in
-the credential store so you won't have to type it the next time.
-
-Note: the following core Perl modules that may be installed with your
-distribution of Perl are required:
-MIME::Base64, MIME::QuotedPrint, Net::Domain and Net::SMTP.
-These additional Perl modules are also required:
-Authen::SASL and Mail::Address.
-
-
-SEE ALSO
---------
-linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
-
-GIT
----
-Part of the linkgit:git[1] suite
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.adoc
index b9e73f2e77..811193f16c 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.adoc
@@ -71,7 +71,8 @@ be in a separate packet, and the list must end with a flush packet.
 	fails to update then the entire push will fail without changing any
 	refs.
 
---[no-]signed::
+--signed::
+--no-signed::
 --signed=(true|false|if-asked)::
 	GPG-sign the push request to update refs on the receiving
 	side, to allow it to be checked by the hooks and/or be
diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.adoc
index 2ffaf9392e..2ffaf9392e 100644
--- a/Documentation/git-sh-i18n--envsubst.txt
+++ b/Documentation/git-sh-i18n--envsubst.adoc
diff --git a/Documentation/git-sh-i18n.txt b/Documentation/git-sh-i18n.adoc
index 60cf49cb2a..60cf49cb2a 100644
--- a/Documentation/git-sh-i18n.txt
+++ b/Documentation/git-sh-i18n.adoc
diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.adoc
index bdaf6e5fc4..bdaf6e5fc4 100644
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.adoc
diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.adoc
index 11361f33e9..11361f33e9 100644
--- a/Documentation/git-shell.txt
+++ b/Documentation/git-shell.adoc
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.adoc
index 7d0277d033..aa92800c69 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.adoc
@@ -44,8 +44,8 @@ OPTIONS
 	describe each commit.  '<format>' can be any string accepted
 	by the `--format` option of 'git log', such as '* [%h] %s'.
 	(See the "PRETTY FORMATS" section of linkgit:git-log[1].)
-
-	Each pretty-printed commit will be rewrapped before it is shown.
++
+Each pretty-printed commit will be rewrapped before it is shown.
 
 --date=<format>::
 	Show dates formatted according to the given date string. (See
@@ -114,7 +114,7 @@ Paths may need to be prefixed with `--` to separate them from
 options or the revision range, when confusion arises.
 
 :git-shortlog: 1
-include::rev-list-options.txt[]
+include::rev-list-options.adoc[]
 
 MAPPING AUTHORS
 ---------------
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.adoc
index bc31d8b6d3..7e86d54a24 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.adoc
@@ -202,9 +202,9 @@ topologically related to each other.
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/showbranch.txt[]
+include::config/showbranch.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.adoc
index e49318a5a0..00b3a908cd 100644
--- a/Documentation/git-show-index.txt
+++ b/Documentation/git-show-index.adoc
@@ -9,7 +9,7 @@ git-show-index - Show packed archive index
 SYNOPSIS
 --------
 [verse]
-'git show-index' [--object-format=<hash-algorithm>]
+'git show-index' [--object-format=<hash-algorithm>] < <pack-idx-file>
 
 
 DESCRIPTION
@@ -45,7 +45,7 @@ OPTIONS
 	algorithm for the current repository (set by `extensions.objectFormat`), or
 	'sha1' if no value is set or outside a repository..
 +
-include::object-format-disclaimer.txt[]
+include::object-format-disclaimer.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.adoc
index 616d919655..616d919655 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.adoc
diff --git a/Documentation/git-show.txt b/Documentation/git-show.adoc
index 5eb67439af..51044c814f 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.adoc
@@ -39,10 +39,10 @@ OPTIONS
 	For a more complete list of ways to spell object names, see
 	"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
 
-include::pretty-options.txt[]
+include::pretty-options.adoc[]
 
 
-include::pretty-formats.txt[]
+include::pretty-formats.adoc[]
 
 
 DIFF FORMATTING
@@ -52,9 +52,9 @@ diff output.
 
 :git-log: 1
 :diff-merges-default: `dense-combined`
-include::diff-options.txt[]
+include::diff-options.adoc[]
 
-include::diff-generate-patch.txt[]
+include::diff-generate-patch.adoc[]
 
 
 EXAMPLES
@@ -83,7 +83,7 @@ EXAMPLES
 DISCUSSION
 ----------
 
-include::i18n.txt[]
+include::i18n.adoc[]
 
 GIT
 ---
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.adoc
index 529a8edd9c..0d1618f161 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.adoc
@@ -9,7 +9,7 @@ git-sparse-checkout - Reduce your working tree to a subset of tracked files
 SYNOPSIS
 --------
 [verse]
-'git sparse-checkout' (init | list | set | add | reapply | disable | check-rules) [<options>]
+'git sparse-checkout' (init | list | set | add | reapply | disable | check-rules | clean) [<options>]
 
 
 DESCRIPTION
@@ -111,6 +111,37 @@ flags, with the same meaning as the flags from the `set` command, in order
 to change which sparsity mode you are using without needing to also respecify
 all sparsity paths.
 
+'clean'::
+	Opportunistically remove files outside of the sparse-checkout
+	definition. This command requires cone mode to use recursive
+	directory matches to determine which files should be removed. A
+	file is considered for removal if it is contained within a tracked
+	directory that is outside of the sparse-checkout definition.
++
+Some special cases, such as merge conflicts or modified files outside of
+the sparse-checkout definition could lead to keeping files that would
+otherwise be removed. Resolve conflicts, stage modifications, and use
+`git sparse-checkout reapply` in conjunction with `git sparse-checkout
+clean` to resolve these cases.
++
+This command can be used to be sure the sparse index works efficiently,
+though it does not require enabling the sparse index feature via the
+`index.sparse=true` configuration.
++
+To prevent accidental deletion of worktree files, the `clean` subcommand
+will not delete any files without the `-f` or `--force` option, unless
+the `clean.requireForce` config option is set to `false`.
++
+The `--dry-run` option will list the directories that would be removed
+without deleting them. Running in this mode can be helpful to predict the
+behavior of the clean comand or to determine which kinds of files are left
+in the sparse directories.
++
+The `--verbose` option will list every file within the directories that
+are considered for removal. This option is helpful to determine if those
+files are actually important or perhaps to explain why the directory is
+still present despite the current sparse-checkout.
+
 'disable'::
 	Disable the `core.sparseCheckout` config setting, and restore the
 	working directory to include all files.
@@ -264,34 +295,50 @@ patterns in non-cone mode has a number of shortcomings:
     inconsistent.
 
   * It has edge cases where the "right" behavior is unclear.  Two examples:
-
-    First, two users are in a subdirectory, and the first runs
-       git sparse-checkout set '/toplevel-dir/*.c'
-    while the second runs
-       git sparse-checkout set relative-dir
-    Should those arguments be transliterated into
-       current/subdirectory/toplevel-dir/*.c
-    and
-       current/subdirectory/relative-dir
-    before inserting into the sparse-checkout file?  The user who typed
-    the first command is probably aware that arguments to set/add are
-    supposed to be patterns in non-cone mode, and probably would not be
-    happy with such a transliteration.  However, many gitignore-style
-    patterns are just paths, which might be what the user who typed the
-    second command was thinking, and they'd be upset if their argument
-    wasn't transliterated.
-
-    Second, what should bash-completion complete on for set/add commands
-    for non-cone users?  If it suggests paths, is it exacerbating the
-    problem above?  Also, if it suggests paths, what if the user has a
-    file or directory that begins with either a '!' or '#' or has a '*',
-    '\', '?', '[', or ']' in its name?  And if it suggests paths, will
-    it complete "/pro" to "/proc" (in the root filesystem) rather than to
-    "/progress.txt" in the current directory?  (Note that users are
-    likely to want to start paths with a leading '/' in non-cone mode,
-    for the same reason that .gitignore files often have one.)
-    Completing on files or directories might give nasty surprises in
-    all these cases.
++
+First, two users are in a subdirectory, and the first runs
++
+----
+git sparse-checkout set '/toplevel-dir/*.c'
+----
++
+while the second runs
++
+----
+git sparse-checkout set relative-dir
+----
++
+Should those arguments be transliterated into
++
+----
+current/subdirectory/toplevel-dir/*.c
+----
++
+and
++
+----
+current/subdirectory/relative-dir
+----
++
+before inserting into the sparse-checkout file?  The user who typed
+the first command is probably aware that arguments to set/add are
+supposed to be patterns in non-cone mode, and probably would not be
+happy with such a transliteration.  However, many gitignore-style
+patterns are just paths, which might be what the user who typed the
+second command was thinking, and they'd be upset if their argument
+wasn't transliterated.
++
+Second, what should bash-completion complete on for set/add commands
+for non-cone users?  If it suggests paths, is it exacerbating the
+problem above?  Also, if it suggests paths, what if the user has a
+file or directory that begins with either a '!' or '#' or has a '*',
+'\', '?', '[', or ']' in its name?  And if it suggests paths, will
+it complete "/pro" to "/proc" (in the root filesystem) rather than to
+"/progress.txt" in the current directory?  (Note that users are
+likely to want to start paths with a leading '/' in non-cone mode,
+for the same reason that .gitignore files often have one.)
+Completing on files or directories might give nasty surprises in
+all these cases.
 
   * The excessive flexibility made other extensions essentially
     impractical.  `--sparse-index` is likely impossible in non-cone
diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.adoc
index 2f6aaa75b9..2f6aaa75b9 100644
--- a/Documentation/git-stage.txt
+++ b/Documentation/git-stage.adoc
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.adoc
index 06fb7f1d18..235d57ddd8 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.adoc
@@ -7,22 +7,24 @@ git-stash - Stash the changes in a dirty working directory away
 
 SYNOPSIS
 --------
-[verse]
-'git stash' list [<log-options>]
-'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
-'git stash' drop [-q | --quiet] [<stash>]
-'git stash' pop [--index] [-q | --quiet] [<stash>]
-'git stash' apply [--index] [-q | --quiet] [<stash>]
-'git stash' branch <branchname> [<stash>]
-'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+[synopsis]
+git stash list [<log-options>]
+git stash show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
+git stash drop [-q | --quiet] [<stash>]
+git stash pop [--index] [-q | --quiet] [<stash>]
+git stash apply [--index] [-q | --quiet] [<stash>]
+git stash branch <branchname> [<stash>]
+git stash [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
 	     [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
 	     [--pathspec-from-file=<file> [--pathspec-file-nul]]
 	     [--] [<pathspec>...]]
-'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
-	     [-u | --include-untracked] [-a | --all] [<message>]
-'git stash' clear
-'git stash' create [<message>]
-'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
+git stash save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
+           [-u | --include-untracked] [-a | --all] [<message>]
+git stash clear
+git stash create [<message>]
+git stash store [(-m | --message) <message>] [-q | --quiet] <commit>
+git stash export (--print | --to-ref <ref>) [<stash>...]
+git stash import <commit>
 
 DESCRIPTION
 -----------
@@ -36,7 +38,7 @@ The modifications stashed away by this command can be listed with
 `git stash list`, inspected with `git stash show`, and restored
 (potentially on top of a different commit) with `git stash apply`.
 Calling `git stash` without any arguments is equivalent to `git stash push`.
-A stash is by default listed as "WIP on 'branchname' ...", but
+A stash is by default listed as "WIP on '<branchname>' ...", but
 you can give a more descriptive message on the command line when
 you create one.
 
@@ -45,16 +47,16 @@ stashes are found in the reflog of this reference and can be named using
 the usual reflog syntax (e.g. `stash@{0}` is the most recently
 created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}`
 is also possible). Stashes may also be referenced by specifying just the
-stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
+stash index (e.g. the integer `<n>` is equivalent to `stash@{<n>}`).
 
 COMMANDS
 --------
 
-push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
+`push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [ -a | --all] [-q | --quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]`::
 
 	Save your local modifications to a new 'stash entry' and roll them
-	back to HEAD (in the working tree and in the index).
-	The <message> part is optional and gives
+	back to `HEAD` (in the working tree and in the index).
+	The _<message>_ part is optional and gives
 	the description along with the stashed state.
 +
 For quickly making a snapshot, you can omit "push".  In this mode,
@@ -63,14 +65,14 @@ subcommand from making an unwanted stash entry.  The two exceptions to this
 are `stash -p` which acts as alias for `stash push -p` and pathspec elements,
 which are allowed after a double hyphen `--` for disambiguation.
 
-save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
+`save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-u | --include-untracked] [-a | --all] [-q | --quiet] [<message>]`::
 
 	This option is deprecated in favour of 'git stash push'.  It
 	differs from "stash push" in that it cannot take pathspec.
 	Instead, all non-option arguments are concatenated to form the stash
 	message.
 
-list [<log-options>]::
+`list [<log-options>]`::
 
 	List the stash entries that you currently have.  Each 'stash entry' is
 	listed with its name (e.g. `stash@{0}` is the latest entry, `stash@{1}` is
@@ -86,7 +88,7 @@ stash@{1}: On master: 9cc0589... Add git-stash
 The command takes options applicable to the 'git log'
 command to control what is shown and how. See linkgit:git-log[1].
 
-show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]::
+`show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]`::
 
 	Show the changes recorded in the stash entry as a diff between the
 	stashed contents and the commit back when the stash entry was first
@@ -94,12 +96,12 @@ show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]::
 	By default, the command shows the diffstat, but it will accept any
 	format known to 'git diff' (e.g., `git stash show -p stash@{1}`
 	to view the second most recent entry in patch form).
-	If no `<diff-option>` is provided, the default behavior will be given
+	If no _<diff-option>_ is provided, the default behavior will be given
 	by the `stash.showStat`, and `stash.showPatch` config variables. You
 	can also use `stash.showIncludeUntracked` to set whether
 	`--include-untracked` is enabled by default.
 
-pop [--index] [-q|--quiet] [<stash>]::
+`pop [--index] [-q | --quiet] [<stash>]`::
 
 	Remove a single stashed state from the stash list and apply it
 	on top of the current working tree state, i.e., do the inverse
@@ -110,19 +112,19 @@ Applying the state can fail with conflicts; in this case, it is not
 removed from the stash list. You need to resolve the conflicts by hand
 and call `git stash drop` manually afterwards.
 
-apply [--index] [-q|--quiet] [<stash>]::
+`apply [--index] [-q | --quiet] [<stash>]`::
 
 	Like `pop`, but do not remove the state from the stash list. Unlike `pop`,
 	`<stash>` may be any commit that looks like a commit created by
 	`stash push` or `stash create`.
 
-branch <branchname> [<stash>]::
+`branch <branchname> [<stash>]`::
 
-	Creates and checks out a new branch named `<branchname>` starting from
-	the commit at which the `<stash>` was originally created, applies the
-	changes recorded in `<stash>` to the new working tree and index.
-	If that succeeds, and `<stash>` is a reference of the form
-	`stash@{<revision>}`, it then drops the `<stash>`.
+	Creates and checks out a new branch named _<branchname>_ starting from
+	the commit at which the _<stash>_ was originally created, applies the
+	changes recorded in _<stash>_ to the new working tree and index.
+	If that succeeds, and _<stash>_ is a reference of the form
+	`stash@{<revision>}`, it then drops the _<stash>_.
 +
 This is useful if the branch on which you ran `git stash push` has
 changed enough that `git stash apply` fails due to conflicts. Since
@@ -130,42 +132,51 @@ the stash entry is applied on top of the commit that was HEAD at the
 time `git stash` was run, it restores the originally stashed state
 with no conflicts.
 
-clear::
+`clear`::
 	Remove all the stash entries. Note that those entries will then
 	be subject to pruning, and may be impossible to recover (see
-	'Examples' below for a possible strategy).
-
-drop [-q|--quiet] [<stash>]::
+	'EXAMPLES' below for a possible strategy).
 
+`drop [-q | --quiet] [<stash>]`::
 	Remove a single stash entry from the list of stash entries.
 
-create::
-
+`create`::
 	Create a stash entry (which is a regular commit object) and
 	return its object name, without storing it anywhere in the ref
 	namespace.
 	This is intended to be useful for scripts.  It is probably not
 	the command you want to use; see "push" above.
 
-store::
+`store`::
 
 	Store a given stash created via 'git stash create' (which is a
 	dangling merge commit) in the stash ref, updating the stash
 	reflog.  This is intended to be useful for scripts.  It is
 	probably not the command you want to use; see "push" above.
 
+`export ( --print | --to-ref <ref> ) [<stash>...]`::
+
+	Export the specified stashes, or all of them if none are specified, to
+	a chain of commits which can be transferred using the normal fetch and
+	push mechanisms, then imported using the `import` subcommand.
+
+`import <commit>`::
+	Import the specified stashes from the specified commit, which must have been
+	created by `export`, and add them to the list of stashes.  To replace the
+	existing stashes, use `clear` first.
+
 OPTIONS
 -------
--a::
---all::
+`-a`::
+`--all`::
 	This option is only valid for `push` and `save` commands.
 +
 All ignored and untracked files are also stashed and then cleaned
 up with `git clean`.
 
--u::
---include-untracked::
---no-include-untracked::
+`-u`::
+`--include-untracked`::
+`--no-include-untracked`::
 	When used with the `push` and `save` commands,
 	all untracked files are also stashed and then cleaned up with
 	`git clean`.
@@ -173,12 +184,12 @@ up with `git clean`.
 When used with the `show` command, show the untracked files in the stash
 entry as part of the diff.
 
---only-untracked::
+`--only-untracked`::
 	This option is only valid for the `show` command.
 +
 Show only the untracked files in the stash entry as part of the diff.
 
---index::
+`--index`::
 	This option is only valid for `pop` and `apply` commands.
 +
 Tries to reinstate not only the working tree's changes, but also
@@ -186,15 +197,15 @@ the index's ones. However, this can fail, when you have conflicts
 (which are stored in the index, where you therefore can no longer
 apply the changes as they were originally).
 
--k::
---keep-index::
---no-keep-index::
+`-k`::
+`--keep-index`::
+`--no-keep-index`::
 	This option is only valid for `push` and `save` commands.
 +
 All changes already added to the index are left intact.
 
--p::
---patch::
+`-p`::
+`--patch`::
 	This option is only valid for `push` and `save` commands.
 +
 Interactively select hunks from the diff between HEAD and the
@@ -208,8 +219,10 @@ to learn how to operate the `--patch` mode.
 The `--patch` option implies `--keep-index`.  You can use
 `--no-keep-index` to override this.
 
--S::
---staged::
+include::diff-context-options.adoc[]
+
+`-S`::
+`--staged`::
 	This option is only valid for `push` and `save` commands.
 +
 Stash only the changes that are currently staged. This is similar to
@@ -218,36 +231,49 @@ of current branch.
 +
 The `--patch` option has priority over this one.
 
---pathspec-from-file=<file>::
+`--pathspec-from-file=<file>`::
 	This option is only valid for `push` command.
 +
-Pathspec is passed in `<file>` instead of commandline args. If
-`<file>` is exactly `-` then standard input is used. Pathspec
+Pathspec is passed in _<file>_ instead of commandline args. If
+_<file>_ is exactly `-` then standard input is used. Pathspec
 elements are separated by LF or CR/LF. Pathspec elements can be
 quoted as explained for the configuration variable `core.quotePath`
 (see linkgit:git-config[1]). See also `--pathspec-file-nul` and
 global `--literal-pathspecs`.
 
---pathspec-file-nul::
+`--pathspec-file-nul`::
 	This option is only valid for `push` command.
 +
 Only meaningful with `--pathspec-from-file`. Pathspec elements are
 separated with NUL character and all other characters are taken
 literally (including newlines and quotes).
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	This option is only valid for `apply`, `drop`, `pop`, `push`,
 	`save`, `store` commands.
 +
 Quiet, suppress feedback messages.
 
-\--::
+`--print`::
+	This option is only valid for the `export` command.
++
+Create the chain of commits representing the exported stashes without
+storing it anywhere in the ref namespace and print the object ID to
+standard output.  This is designed for scripts.
+
+`--to-ref`::
+	This option is only valid for the `export` command.
++
+Create the chain of commits representing the exported stashes and store
+it to the specified ref.
+
+`--`::
 	This option is only valid for `push` command.
 +
 Separates pathspec from options for disambiguation purposes.
 
-<pathspec>...::
+`<pathspec>...`::
 	This option is only valid for `push` command.
 +
 The new stash entry records the modified states only for the files
@@ -257,11 +283,11 @@ too, leaving files that do not match the pathspec intact.
 +
 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
 
-<stash>::
+_<stash>_::
 	This option is only valid for `apply`, `branch`, `drop`, `pop`,
-	`show` commands.
+	`show`, and `export` commands.
 +
-A reference of the form `stash@{<revision>}`. When no `<stash>` is
+A reference of the form `stash@{<revision>}`. When no _<stash>_ is
 given, the latest stash is assumed (that is, `stash@{0}`).
 
 DISCUSSION
@@ -388,9 +414,10 @@ xargs git log --merges --no-walk --grep=WIP
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/stash.txt[]
+:git-stash: 1
+include::config/stash.adoc[]
 
 
 SEE ALSO
diff --git a/Documentation/git-status.txt b/Documentation/git-status.adoc
index 9a376886a5..9a376886a5 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.adoc
diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.adoc
index a293327581..37287f211f 100644
--- a/Documentation/git-stripspace.txt
+++ b/Documentation/git-stripspace.adoc
@@ -37,7 +37,8 @@ OPTIONS
 -------
 -s::
 --strip-comments::
-	Skip and remove all lines starting with a comment character (default '#').
+	Skip and remove all lines starting with a comment character
+	(`core.commentChar`, default `#`).
 
 -c::
 --comment-lines::
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.adoc
index 87d8e0f0c5..95beaee561 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.adoc
@@ -307,6 +307,13 @@ OPTIONS
 --force::
 	This option is only valid for add, deinit and update commands.
 	When running add, allow adding an otherwise ignored submodule path.
+	This option is also used to bypass a check that the submodule's name
+	is not already in use. By default, 'git submodule add' will fail if
+	the proposed name (which is derived from the path) is already registered
+	for another submodule in the repository. Using '--force' allows the command
+	to proceed by automatically generating a unique name by appending a number
+	to the conflicting name (e.g., if a submodule named 'child' exists, it will
+	try 'child1', and so on).
 	When running deinit the submodule working trees will be removed even
 	if they contain local changes.
 	When running update (only effective with the checkout procedure),
@@ -435,7 +442,8 @@ options carefully.
 	clone with a history truncated to the specified number of revisions.
 	See linkgit:git-clone[1]
 
---[no-]recommend-shallow::
+--recommend-shallow::
+--no-recommend-shallow::
 	This option is only valid for the update command.
 	The initial clone of a submodule will use the recommended
 	`submodule.<name>.shallow` as provided by the `.gitmodules` file
@@ -447,7 +455,8 @@ options carefully.
 	Clone new submodules in parallel with as many jobs.
 	Defaults to the `submodule.fetchJobs` option.
 
---[no-]single-branch::
+--single-branch::
+--no-single-branch::
 	This option is only valid for the update command.
 	Clone only one branch during update: HEAD or one specified by --branch.
 
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.adoc
index bcf7d84a87..c26c12bab3 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.adoc
@@ -1012,9 +1012,11 @@ branch.
 
 If you do merge, note the following rule: 'git svn dcommit' will
 attempt to commit on top of the SVN commit named in
+
 ------------------------------------------------------------------------
 git log --grep=^git-svn-id: --first-parent -1
 ------------------------------------------------------------------------
+
 You 'must' therefore ensure that the most recent commit of the branch
 you want to dcommit to is the 'first' parent of the merge.  Chaos will
 ensue otherwise, especially if the first parent is an older commit on
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.adoc
index f38e4c8afa..87707e9265 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.adoc
@@ -7,11 +7,11 @@ git-switch - Switch branches
 
 SYNOPSIS
 --------
-[verse]
-'git switch' [<options>] [--no-guess] <branch>
-'git switch' [<options>] --detach [<start-point>]
-'git switch' [<options>] (-c|-C) <new-branch> [<start-point>]
-'git switch' [<options>] --orphan <new-branch>
+[synopsis]
+git switch [<options>] [--no-guess] <branch>
+git switch [<options>] --detach [<start-point>]
+git switch [<options>] (-c|-C) <new-branch> [<start-point>]
+git switch [<options>] --orphan <new-branch>
 
 DESCRIPTION
 -----------
@@ -29,37 +29,35 @@ Switching branches does not require a clean index and working tree
 however if the operation leads to loss of local changes, unless told
 otherwise with `--discard-changes` or `--merge`.
 
-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
-
 OPTIONS
 -------
-<branch>::
+_<branch>_::
 	Branch to switch to.
 
-<new-branch>::
+_<new-branch>_::
 	Name for the new branch.
 
-<start-point>::
+_<start-point>_::
 	The starting point for the new branch. Specifying a
-	`<start-point>` allows you to create a branch based on some
-	other point in history than where HEAD currently points. (Or,
+	_<start-point>_ allows you to create a branch based on some
+	other point in history than where `HEAD` currently points. (Or,
 	in the case of `--detach`, allows you to inspect and detach
 	from some other point.)
 +
-You can use the `@{-N}` syntax to refer to the N-th last
-branch/commit switched to using "git switch" or "git checkout"
+You can use the `@{-<N>}` syntax to refer to the _<N>_-th last
+branch/commit switched to using `git switch` or `git checkout`
 operation. You may also specify `-` which is synonymous to `@{-1}`.
 This is often used to switch quickly between two branches, or to undo
 a branch switch by mistake.
 +
-As a special case, you may use `A...B` as a shortcut for the merge
-base of `A` and `B` if there is exactly one merge base. You can leave
-out at most one of `A` and `B`, in which case it defaults to `HEAD`.
-
--c <new-branch>::
---create <new-branch>::
-	Create a new branch named `<new-branch>` starting at
-	`<start-point>` before switching to the branch. This is the
+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the merge
+base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can leave
+out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
+
+`-c <new-branch>`::
+`--create <new-branch>`::
+	Create a new branch named _<new-branch>_ starting at
+	_<start-point>_ before switching to the branch. This is the
 	transactional equivalent of
 +
 ------------
@@ -67,32 +65,32 @@ $ git branch <new-branch>
 $ git switch <new-branch>
 ------------
 +
-that is to say, the branch is not reset/created unless "git switch" is
+that is to say, the branch is not reset/created unless `git switch` is
 successful (e.g., when the branch is in use in another worktree, not
 just the current branch stays the same, but the branch is not reset to
 the start-point, either).
 
--C <new-branch>::
---force-create <new-branch>::
-	Similar to `--create` except that if `<new-branch>` already
-	exists, it will be reset to `<start-point>`. This is a
+`-C <new-branch>`::
+`--force-create <new-branch>`::
+	Similar to `--create` except that if _<new-branch>_ already
+	exists, it will be reset to _<start-point>_. This is a
 	convenient shortcut for:
 +
 ------------
-$ git branch -f <new-branch>
-$ git switch <new-branch>
+$ git branch -f _<new-branch>_
+$ git switch _<new-branch>_
 ------------
 
--d::
---detach::
+`-d`::
+`--detach`::
 	Switch to a commit for inspection and discardable
 	experiments. See the "DETACHED HEAD" section in
 	linkgit:git-checkout[1] for details.
 
---guess::
---no-guess::
-	If `<branch>` is not found but there does exist a tracking
-	branch in exactly one remote (call it `<remote>`) with a
+`--guess`::
+`--no-guess`::
+	If _<branch>_ is not found but there does exist a tracking
+	branch in exactly one remote (call it _<remote>_) with a
 	matching name, treat as equivalent to
 +
 ------------
@@ -101,9 +99,9 @@ $ git switch -c <branch> --track <remote>/<branch>
 +
 If the branch exists in multiple remotes and one of them is named by
 the `checkout.defaultRemote` configuration variable, we'll use that
-one for the purposes of disambiguation, even if the `<branch>` isn't
+one for the purposes of disambiguation, even if the _<branch>_ isn't
 unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin`
-to always checkout remote branches from there if `<branch>` is
+to always checkout remote branches from there if _<branch>_ is
 ambiguous but exists on the 'origin' remote. See also
 `checkout.defaultRemote` in linkgit:git-config[1].
 +
@@ -112,19 +110,19 @@ ambiguous but exists on the 'origin' remote. See also
 The default behavior can be set via the `checkout.guess` configuration
 variable.
 
--f::
---force::
+`-f`::
+`--force`::
 	An alias for `--discard-changes`.
 
---discard-changes::
+`--discard-changes`::
 	Proceed even if the index or the working tree differs from
 	`HEAD`. Both the index and working tree are restored to match
 	the switching target. If `--recurse-submodules` is specified,
 	submodule content is also restored to match the switching
 	target. This is used to throw away local changes.
 
--m::
---merge::
+`-m`::
+`--merge`::
 	If you have local modifications to one or more files that are
 	different between the current branch and the branch to which
 	you are switching, the command refuses to switch branches in
@@ -138,25 +136,25 @@ paths are left unmerged, and you need to resolve the conflicts
 and mark the resolved paths with `git add` (or `git rm` if the merge
 should result in deletion of the path).
 
---conflict=<style>::
+`--conflict=<style>`::
 	The same as `--merge` option above, but changes the way the
 	conflicting hunks are presented, overriding the
 	`merge.conflictStyle` configuration variable.  Possible values are
-	"merge" (default), "diff3", and "zdiff3".
+	`merge` (default), `diff3`, and `zdiff3`.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Quiet, suppress feedback messages.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Progress status is reported on the standard error stream
 	by default when it is attached to a terminal, unless `--quiet`
 	is specified. This flag enables progress reporting even if not
 	attached to a terminal, regardless of `--quiet`.
 
--t::
---track [direct|inherit]::
+`-t`::
+`--track[ (direct|inherit)]`::
 	When creating a new branch, set up "upstream" configuration.
 	`-c` is implied. See `--track` in linkgit:git-branch[1] for
 	details.
@@ -171,22 +169,22 @@ given name has no slash, or the above guessing results in an empty
 name, the guessing is aborted.  You can explicitly give a name with
 `-c` in such a case.
 
---no-track::
+`--no-track`::
 	Do not set up "upstream" configuration, even if the
 	`branch.autoSetupMerge` configuration variable is true.
 
---orphan <new-branch>::
-	Create a new unborn branch, named `<new-branch>`. All
+`--orphan <new-branch>`::
+	Create a new unborn branch, named _<new-branch>_. All
 	tracked files are removed.
 
---ignore-other-worktrees::
+`--ignore-other-worktrees`::
 	`git switch` refuses when the wanted ref is already
 	checked out by another worktree. This option makes it check
 	the ref out anyway. In other words, the ref can be held by
 	more than one worktree.
 
---recurse-submodules::
---no-recurse-submodules::
+`--recurse-submodules`::
+`--no-recurse-submodules`::
 	Using `--recurse-submodules` will update the content of all
 	active submodules according to the commit recorded in the
 	superproject. If nothing (or `--no-recurse-submodules`) is
@@ -239,7 +237,7 @@ $ git switch -
 ------------
 
 You can grow a new branch from any commit. For example, switch to
-"HEAD~3" and create branch "fixup":
+"`HEAD~3`" and create branch "`fixup`":
 
 ------------
 $ git switch -c fixup HEAD~3
@@ -251,8 +249,8 @@ name:
 
 ------------
 $ git switch new-topic
-Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin'
-Switched to a new branch 'new-topic'
+Branch `new-topic` set up to track remote branch `new-topic` from `origin`
+Switched to a new branch `new-topic`
 ------------
 
 To check out commit `HEAD~3` for temporary inspection or experiment
@@ -273,9 +271,9 @@ $ git switch -c good-surprises
 CONFIGURATION
 -------------
 
-include::includes/cmd-config-section-all.txt[]
+include::includes/cmd-config-section-all.adoc[]
 
-include::config/checkout.txt[]
+include::config/checkout.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.adoc
index 33ca381fde..33ca381fde 100644
--- a/Documentation/git-symbolic-ref.txt
+++ b/Documentation/git-symbolic-ref.adoc
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.adoc
index 4494729f5e..cea3202fdb 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.adoc
@@ -3,26 +3,26 @@ git-tag(1)
 
 NAME
 ----
-git-tag - Create, list, delete or verify a tag object signed with GPG
+git-tag - Create, list, delete or verify tags
 
 
 SYNOPSIS
 --------
-[verse]
-'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
+[synopsis]
+git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
 	[(--trailer <token>[(=|:)<value>])...]
 	<tagname> [<commit> | <object>]
-'git tag' -d <tagname>...
-'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
+git tag -d <tagname>...
+git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
 	[--points-at <object>] [--column[=<options>] | --no-column]
 	[--create-reflog] [--sort=<key>] [--format=<format>]
 	[--merged <commit>] [--no-merged <commit>] [<pattern>...]
-'git tag' -v [--format=<format>] <tagname>...
+git tag -v [--format=<format>] <tagname>...
 
 DESCRIPTION
 -----------
 
-Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
+Add a tag reference in `refs/tags/`, unless `-d`/`-l`/`-v` is given
 to delete, list or verify tags.
 
 Unless `-f` is given, the named tag must not yet exist.
@@ -38,15 +38,17 @@ and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied.
 Otherwise, a tag reference that points directly at the given object
 (i.e., a lightweight tag) is created.
 
-A GnuPG signed tag object will be created when `-s` or `-u
-<key-id>` is used.  When `-u <key-id>` is not used, the
-committer identity for the current user is used to find the
-GnuPG key for signing. 	The configuration variable `gpg.program`
-is used to specify custom GnuPG binary.
+A cryptographically signed tag object will be created when `-s` or
+`-u <key-id>` is used. The signing backend (GPG, X.509, SSH, etc.) is
+controlled by the `gpg.format` configuration variable, defaulting to
+OpenPGP. When `-u <key-id>` is not used, the committer identity for
+the current user is used to find the key for signing. The
+configuration variable `gpg.program` is used to specify a custom
+signing binary.
 
 Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated"
 tags; they contain a creation date, the tagger name and e-mail, a
-tagging message, and an optional GnuPG signature. Whereas a
+tagging message, and an optional cryptographic signature. Whereas a
 "lightweight" tag is simply a name for an object (usually a commit
 object).
 
@@ -58,129 +60,134 @@ lightweight tags by default.
 
 OPTIONS
 -------
--a::
---annotate::
+`-a`::
+`--annotate`::
 	Make an unsigned, annotated tag object
 
--s::
---sign::
-	Make a GPG-signed tag, using the default e-mail address's key.
-	The default behavior of tag GPG-signing is controlled by `tag.gpgSign`
-	configuration variable if it exists, or disabled otherwise.
-	See linkgit:git-config[1].
+`-s`::
+`--sign`::
+	Make a cryptographically signed tag, using the default signing
+	key. The signing backend used depends on the `gpg.format`
+	configuration variable. The default key is determined by the
+	backend. For GPG, it's based on the committer's email address,
+	while for SSH it may be a specific key file or agent
+	identity. See linkgit:git-config[1].
 
---no-sign::
+`--no-sign`::
 	Override `tag.gpgSign` configuration variable that is
 	set to force each and every tag to be signed.
 
--u <key-id>::
---local-user=<key-id>::
-	Make a GPG-signed tag, using the given key.
+`-u <key-id>`::
+`--local-user=<key-id>`::
+	Make a cryptographically signed tag using the given key. The
+	format of the <key-id> and the backend used depend on the
+	`gpg.format` configuration variable. See
+	linkgit:git-config[1].
 
--f::
---force::
+`-f`::
+`--force`::
 	Replace an existing tag with the given name (instead of failing)
 
--d::
---delete::
+`-d`::
+`--delete`::
 	Delete existing tags with the given names.
 
--v::
---verify::
-	Verify the GPG signature of the given tag names.
+`-v`::
+`--verify`::
+	Verify the cryptographic signature of the given tags.
 
--n<num>::
-	<num> specifies how many lines from the annotation, if any,
-	are printed when using -l. Implies `--list`.
+`-n<num>`::
+	_<num>_ specifies how many lines from the annotation, if any,
+	are printed when using `-l`. Implies `--list`.
 +
 The default is not to print any annotation lines.
 If no number is given to `-n`, only the first line is printed.
 If the tag is not annotated, the commit message is displayed instead.
 
--l::
---list::
+`-l`::
+`--list`::
 	List tags. With optional `<pattern>...`, e.g. `git tag --list
 	'v-*'`, list only the tags that match the pattern(s).
 +
-Running "git tag" without arguments also lists all tags. The pattern
-is a shell wildcard (i.e., matched using fnmatch(3)). Multiple
+Running `git tag` without arguments also lists all tags. The pattern
+is a shell wildcard (i.e., matched using `fnmatch`(3)). Multiple
 patterns may be given; if any of them matches, the tag is shown.
 +
 This option is implicitly supplied if any other list-like option such
 as `--contains` is provided. See the documentation for each of those
 options for details.
 
---sort=<key>::
+`--sort=<key>`::
 	Sort based on the key given.  Prefix `-` to sort in
-	descending order of the value. You may use the --sort=<key> option
-	multiple times, in which case the last key becomes the primary
-	key. Also supports "version:refname" or "v:refname" (tag
-	names are treated as versions). The "version:refname" sort
-	order can also be affected by the "versionsort.suffix"
+	descending order of the value. You may use the `--sort=<key>` option
+	multiple times, in which case the last _<key>_ becomes the primary
+	key. Also supports "`version:refname`" or "`v:refname`" (tag
+	names are treated as versions). The "`version:refname`" sort
+	order can also be affected by the "`versionsort.suffix`"
 	configuration variable.
 	The keys supported are the same as those in `git for-each-ref`.
 	Sort order defaults to the value configured for the `tag.sort`
 	variable if it exists, or lexicographic order otherwise. See
 	linkgit:git-config[1].
 
---color[=<when>]::
+`--color[=<when>]`::
 	Respect any colors specified in the `--format` option. The
-	`<when>` field must be one of `always`, `never`, or `auto` (if
-	`<when>` is absent, behave as if `always` was given).
+	_<when>_ field must be one of `always`, `never`, or `auto` (if
+	_<when>_ is absent, behave as if `always` was given).
 
--i::
---ignore-case::
+`-i`::
+`--ignore-case`::
 	Sorting and filtering tags are case insensitive.
 
---omit-empty::
+`--omit-empty`::
 	Do not print a newline after formatted refs where the format expands
 	to the empty string.
 
---column[=<options>]::
---no-column::
+`--column[=<options>]`::
+`--no-column`::
 	Display tag listing in columns. See configuration variable
 	`column.tag` for option syntax. `--column` and `--no-column`
-	without options are equivalent to 'always' and 'never' respectively.
+	without options are equivalent to `always` and `never` respectively.
 +
 This option is only applicable when listing tags without annotation lines.
 
---contains [<commit>]::
-	Only list tags which contain the specified commit (HEAD if not
+`--contains [<commit>]`::
+	Only list tags which contain _<commit>_ (`HEAD` if not
 	specified). Implies `--list`.
 
---no-contains [<commit>]::
-	Only list tags which don't contain the specified commit (HEAD if
+`--no-contains [<commit>]`::
+	Only list tags which don't contain _<commit>_ (`HEAD` if
 	not specified). Implies `--list`.
 
---merged [<commit>]::
-	Only list tags whose commits are reachable from the specified
-	commit (`HEAD` if not specified).
+`--merged [<commit>]`::
+	Only list tags whose commits are reachable from
+	_<commit>_ (`HEAD` if not specified).
 
---no-merged [<commit>]::
-	Only list tags whose commits are not reachable from the specified
-	commit (`HEAD` if not specified).
+`--no-merged [<commit>]`::
+	Only list tags whose commits are not reachable from
+	_<commit>_ (`HEAD` if not specified).
 
---points-at <object>::
-	Only list tags of the given object (HEAD if not
+`--points-at [<object>]`::
+	Only list tags of _<object>_ (`HEAD` if not
 	specified). Implies `--list`.
 
--m <msg>::
---message=<msg>::
-	Use the given tag message (instead of prompting).
+`-m <msg>`::
+`--message=<msg>`::
+	Use _<msg>_ (instead of prompting).
 	If multiple `-m` options are given, their values are
 	concatenated as separate paragraphs.
 	Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
 	is given.
 
--F <file>::
---file=<file>::
-	Take the tag message from the given file.  Use '-' to
+`-F <file>`::
+`--file=<file>`::
+	Take the tag message from _<file>_.  Use `-` to
 	read the message from the standard input.
 	Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
 	is given.
 
---trailer <token>[(=|:)<value>]::
-	Specify a (<token>, <value>) pair that should be applied as a
+`--trailer <token>[(=|:)<value>]`::
+	Specify a (_<token>_, _<value>_) pair that should be applied as a
 	trailer. (e.g. `git tag --trailer "Custom-Key: value"`
 	will add a "Custom-Key" trailer to the tag message.)
 	The `trailer.*` configuration variables
@@ -190,58 +197,68 @@ This option is only applicable when listing tags without annotation lines.
 	The trailers can be extracted in `git tag --list`, using
 	`--format="%(trailers)"` placeholder.
 
--e::
---edit::
-	The message taken from file with `-F` and command line with
-	`-m` are usually used as the tag message unmodified.
-	This option lets you further edit the message taken from these sources.
+`-e`::
+`--edit`::
+	Let further edit the message taken from file with `-F` and command line with
+	`-m`.
 
---cleanup=<mode>::
-	This option sets how the tag message is cleaned up.
-	The  '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'.  The
-	'strip' mode is default. The 'verbatim' mode does not change message at
-	all, 'whitespace' removes just leading/trailing whitespace lines and
-	'strip' removes both whitespace and commentary.
+`--cleanup=<mode>`::
+	Set how the tag message is cleaned up.
+	The  _<mode>_ can be one of `verbatim`, `whitespace` and `strip`.  The
+	`strip` mode is default. The `verbatim` mode does not change message at
+	all, `whitespace` removes just leading/trailing whitespace lines and
+	`strip` removes both whitespace and commentary.
 
---create-reflog::
+`--create-reflog`::
 	Create a reflog for the tag. To globally enable reflogs for tags, see
 	`core.logAllRefUpdates` in linkgit:git-config[1].
 	The negated form `--no-create-reflog` only overrides an earlier
 	`--create-reflog`, but currently does not negate the setting of
 	`core.logAllRefUpdates`.
 
---format=<format>::
+`--format=<format>`::
 	A string that interpolates `%(fieldname)` from a tag ref being shown
 	and the object it points at.  The format is the same as
 	that of linkgit:git-for-each-ref[1].  When unspecified,
 	defaults to `%(refname:strip=2)`.
 
-<tagname>::
+_<tagname>_::
 	The name of the tag to create, delete, or describe.
 	The new tag name must pass all checks defined by
 	linkgit:git-check-ref-format[1].  Some of these checks
 	may restrict the characters allowed in a tag name.
 
-<commit>::
-<object>::
+_<commit>_::
+_<object>_::
 	The object that the new tag will refer to, usually a commit.
-	Defaults to HEAD.
+	Defaults to `HEAD`.
 
 CONFIGURATION
 -------------
-By default, 'git tag' in sign-with-default mode (-s) will use your
+By default, `git tag` in sign-with-default mode (`-s`) will use your
 committer identity (of the form `Your Name <your@email.address>`) to
 find a key.  If you want to use a different default key, you can specify
 it in the repository configuration as follows:
 
 -------------------------------------
 [user]
-    signingKey = <gpg-key-id>
+    signingKey = <key-id>
 -------------------------------------
 
+The signing backend can be chosen via the `gpg.format` configuration
+variable, which defaults to `openpgp`. See linkgit:git-config[1]
+for a list of other supported formats.
+
+The path to the program used for each signing backend can be specified
+with the `gpg.<format>.program` configuration variable. For the
+`openpgp` backend, `gpg.program` can be used as a synonym for
+`gpg.openpgp.program`. See linkgit:git-config[1] for details.
+
 `pager.tag` is only respected when listing tags, i.e., when `-l` is
 used or implied. The default is to use a pager.
-See linkgit:git-config[1].
+
+See linkgit:git-config[1] for more details and other configuration
+variables.
 
 DISCUSSION
 ----------
@@ -252,7 +269,7 @@ On Re-tagging
 What should you do when you tag a wrong commit and you would
 want to re-tag?
 
-If you never pushed anything out, just re-tag it. Use "-f" to
+If you never pushed anything out, just re-tag it. Use `-f` to
 replace the old one. And you're done.
 
 But if you have pushed things out (or others could just read
@@ -268,12 +285,12 @@ the old tag. In that case you can do one of two things:
 
 . The insane thing.
   You really want to call the new version "X" too, 'even though'
-  others have already seen the old one. So just use 'git tag -f'
+  others have already seen the old one. So just use `git tag -f`
   again, as if you hadn't already published the old one.
 
 However, Git does *not* (and it should not) change tags behind
 users back. So if somebody already got the old tag, doing a
-'git pull' on your tree shouldn't just make them overwrite the old
+`git pull` on your tree shouldn't just make them overwrite the old
 one.
 
 If somebody got a release tag from you, you cannot just change
@@ -325,7 +342,7 @@ private anchor point tags from the other person.
 
 Often, "please pull" messages on the mailing list just provide
 two pieces of information: a repo URL and a branch name; this
-is designed to be easily cut&pasted at the end of a 'git fetch'
+is designed to be easily cut&pasted at the end of a `git fetch`
 command line:
 
 ------------
@@ -391,7 +408,7 @@ For example:
 $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
 ------------
 
-include::date-formats.txt[]
+include::date-formats.adoc[]
 
 FILES
 -----
@@ -403,10 +420,18 @@ FILES
 	user in an editor session will be available in this file, but
 	may be overwritten by the next invocation of `git tag`.
 
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.adoc[]
+
+:git-tag: 1
+include::config/tag.adoc[]
+
 NOTES
 -----
 
-include::ref-reachability-filters.txt[]
+include::ref-reachability-filters.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/git-tools.txt b/Documentation/git-tools.adoc
index d0fec4cddd..d0fec4cddd 100644
--- a/Documentation/git-tools.txt
+++ b/Documentation/git-tools.adoc
diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.adoc
index e9f148a00d..e9f148a00d 100644
--- a/Documentation/git-unpack-file.txt
+++ b/Documentation/git-unpack-file.adoc
diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.adoc
index b3de50d710..b3de50d710 100644
--- a/Documentation/git-unpack-objects.txt
+++ b/Documentation/git-unpack-objects.adoc
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.adoc
index 7128aed540..9bea9fab9a 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.adoc
@@ -86,7 +86,8 @@ OPTIONS
 --chmod=(+|-)x::
         Set the execute permissions on the updated files.
 
---[no-]assume-unchanged::
+--assume-unchanged::
+--no-assume-unchanged::
 	When this flag is specified, the object names recorded
 	for the paths are not updated.  Instead, this option
 	sets/unsets the "assume unchanged" bit for the
@@ -108,18 +109,21 @@ you will need to handle the situation manually.
 	Like `--refresh`, but checks stat information unconditionally,
 	without regard to the "assume unchanged" setting.
 
---[no-]skip-worktree::
+--skip-worktree::
+--no-skip-worktree::
 	When one of these flags is specified, the object names recorded
 	for the paths are not updated. Instead, these options
 	set and unset the "skip-worktree" bit for the paths. See
 	section "Skip-worktree bit" below for more information.
 
 
---[no-]ignore-skip-worktree-entries::
+--ignore-skip-worktree-entries::
+--no-ignore-skip-worktree-entries::
 	Do not remove skip-worktree (AKA "index-only") entries even when
 	the `--remove` option was specified.
 
---[no-]fsmonitor-valid::
+--fsmonitor-valid::
+--no-fsmonitor-valid::
 	When one of these flags is specified, the object names recorded
 	for the paths are not updated. Instead, these options
 	set and unset the "fsmonitor valid" bit for the paths. See
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.adoc
index 9e6935d38d..9310ce9768 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.adoc
@@ -7,8 +7,10 @@ git-update-ref - Update the object name stored in a ref safely
 
 SYNOPSIS
 --------
-[verse]
-'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z])
+[synopsis]
+git update-ref [-m <reason>] [--no-deref] -d <ref> [<old-oid>]
+git update-ref [-m <reason>] [--no-deref] [--create-reflog] <ref> <new-oid> [<old-oid>]
+git update-ref [-m <reason>] [--no-deref] --stdin [-z] [--batch-updates]
 
 DESCRIPTION
 -----------
@@ -57,6 +59,14 @@ performs all modifications together.  Specify commands of the form:
 With `--create-reflog`, update-ref will create a reflog for each ref
 even if one would not ordinarily be created.
 
+With `--batch-updates`, update-ref executes the updates in a batch but allows
+individual updates to fail due to invalid or incorrect user input, applying only
+the successful updates. However, system-related errors—such as I/O failures or
+memory issues—will result in a full failure of all batched updates. Any failed
+updates will be reported in the following format:
+
+	rejected SP (<old-oid> | <old-target>) SP (<new-oid> | <new-target>) SP <rejection-reason> LF
+
 Quote fields containing whitespace as if they were strings in C source
 code; i.e., surrounded by double-quotes and with backslash escapes.
 Use 40 "0" characters or the empty string to specify a zero value.  To
diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.adoc
index 6bc9b50d89..6bc9b50d89 100644
--- a/Documentation/git-update-server-info.txt
+++ b/Documentation/git-update-server-info.adoc
diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.adoc
index e8eb10baad..e8eb10baad 100644
--- a/Documentation/git-upload-archive.txt
+++ b/Documentation/git-upload-archive.adoc
diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.adoc
index 516d1639d9..9167a321d0 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.adoc
@@ -25,7 +25,8 @@ repository.  For push operations, see 'git send-pack'.
 OPTIONS
 -------
 
---[no-]strict::
+--strict::
+--no-strict::
 	Do not try <directory>/.git/ if <directory> is not a Git directory.
 
 --timeout=<n>::
diff --git a/Documentation/git-var.txt b/Documentation/git-var.adoc
index 0680568dfd..b606c2d649 100644
--- a/Documentation/git-var.txt
+++ b/Documentation/git-var.adoc
@@ -8,8 +8,8 @@ git-var - Show a Git logical variable
 
 SYNOPSIS
 --------
-[verse]
-'git var' (-l | <variable>)
+[synopsis]
+git var (-l | <variable>)
 
 DESCRIPTION
 -----------
@@ -18,7 +18,7 @@ no value.
 
 OPTIONS
 -------
--l::
+`-l`::
 	Display the logical variables. In addition, all the
 	variables of the Git configuration file .git/config are listed
 	as well. (However, the configuration variables listing functionality
@@ -32,58 +32,56 @@ EXAMPLES
 
 VARIABLES
 ---------
-GIT_AUTHOR_IDENT::
+`GIT_AUTHOR_IDENT`::
     The author of a piece of code.
 
-GIT_COMMITTER_IDENT::
+`GIT_COMMITTER_IDENT`::
     The person who put a piece of code into Git.
 
-GIT_EDITOR::
+`GIT_EDITOR`::
     Text editor for use by Git commands.  The value is meant to be
     interpreted by the shell when it is used.  Examples: `~/bin/vi`,
     `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe"
-    --nofork`.  The order of preference is the `$GIT_EDITOR`
-    environment variable, then `core.editor` configuration, then
-    `$VISUAL`, then `$EDITOR`, and then the default chosen at compile
+    --nofork`.  The order of preference is `$GIT_EDITOR`, then
+    `core.editor` configuration value, then `$VISUAL`, then
+    `$EDITOR`, and then the default chosen at compile
     time, which is usually 'vi'.
 ifdef::git-default-editor[]
     The build you are using chose '{git-default-editor}' as the default.
 endif::git-default-editor[]
 
-GIT_SEQUENCE_EDITOR::
+`GIT_SEQUENCE_EDITOR`::
     Text editor used to edit the 'todo' file while running `git rebase
     -i`. Like `GIT_EDITOR`, the value is meant to be interpreted by
-    the shell when it is used. The order of preference is the
-    `$GIT_SEQUENCE_EDITOR` environment variable, then
-    `sequence.editor` configuration, and then the value of `git var
-    GIT_EDITOR`.
+    the shell when it is used. The order of preference is
+    `$GIT_SEQUENCE_EDITOR`, then `sequence.editor` configuration value,
+    and then the value of `git var GIT_EDITOR`.
 
-GIT_PAGER::
+`GIT_PAGER`::
     Text viewer for use by Git commands (e.g., 'less').  The value
     is meant to be interpreted by the shell.  The order of preference
-    is the `$GIT_PAGER` environment variable, then `core.pager`
-    configuration, then `$PAGER`, and then the default chosen at
-    compile time (usually 'less').
+    is `$GIT_PAGER`, then the value of `core.pager` configuration, then
+    `$PAGER`, and then the default chosen at compile time (usually `less`).
 ifdef::git-default-pager[]
     The build you are using chose '{git-default-pager}' as the default.
 endif::git-default-pager[]
 
-GIT_DEFAULT_BRANCH::
+`GIT_DEFAULT_BRANCH`::
     The name of the first branch created in newly initialized repositories.
 
-GIT_SHELL_PATH::
+`GIT_SHELL_PATH`::
     The path of the binary providing the POSIX shell for commands which use the shell.
 
-GIT_ATTR_SYSTEM::
+`GIT_ATTR_SYSTEM`::
     The path to the system linkgit:gitattributes[5] file, if one is enabled.
 
-GIT_ATTR_GLOBAL::
+`GIT_ATTR_GLOBAL`::
     The path to the global (per-user) linkgit:gitattributes[5] file.
 
-GIT_CONFIG_SYSTEM::
+`GIT_CONFIG_SYSTEM`::
     The path to the system configuration file, if one is enabled.
 
-GIT_CONFIG_GLOBAL::
+`GIT_CONFIG_GLOBAL`::
     The path to the global (per-user) configuration files, if any.
 
 Most path values contain only one value. However, some can contain multiple
diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.adoc
index aee4c40eac..ff5b8b97ef 100644
--- a/Documentation/git-verify-commit.txt
+++ b/Documentation/git-verify-commit.adoc
@@ -7,26 +7,24 @@ git-verify-commit - Check the GPG signature of commits
 
 SYNOPSIS
 --------
-[verse]
-'git verify-commit' [-v | --verbose] [--raw] <commit>...
+[synopsis]
+git verify-commit [-v | --verbose] [--raw] <commit>...
 
 DESCRIPTION
 -----------
-Validates the GPG signature created by 'git commit -S'.
+Validates the GPG signature created by `git commit -S`
+on the commit objects given on the command line.
 
 OPTIONS
 -------
---raw::
+`--raw`::
 	Print the raw gpg status output to standard error instead of the normal
 	human-readable output.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Print the contents of the commit object before validating it.
 
-<commit>...::
-	SHA-1 identifiers of Git commit objects.
-
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.adoc
index d7e886918a..b0462d8db3 100644
--- a/Documentation/git-verify-pack.txt
+++ b/Documentation/git-verify-pack.adoc
@@ -8,43 +8,39 @@ git-verify-pack - Validate packed Git archive files
 
 SYNOPSIS
 --------
-[verse]
-'git verify-pack' [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
+[synopsis]
+git verify-pack [-v | --verbose] [-s | --stat-only] [--] <pack>.idx...
 
 
 DESCRIPTION
 -----------
-Reads given idx file for packed Git archive created with the
-'git pack-objects' command and verifies the idx file and the
-corresponding pack file.
+Read each idx file for packed Git archive given on the command line,
+and verify the idx file and the corresponding pack file.
 
 OPTIONS
 -------
-<pack>.idx ...::
-	The idx files to verify.
-
--v::
---verbose::
+`-v`::
+`--verbose`::
 	After verifying the pack, show the list of objects contained
 	in the pack and a histogram of delta chain length.
 
--s::
---stat-only::
+`-s`::
+`--stat-only`::
 	Do not verify the pack contents; only show the histogram of delta
 	chain length.  With `--verbose`, the list of objects is also shown.
 
-\--::
+`--`::
 	Do not interpret any more arguments as options.
 
 OUTPUT FORMAT
 -------------
-When specifying the -v option the format used is:
+When specifying the `-v` option the format used is:
 
-	SHA-1 type size size-in-packfile offset-in-packfile
+	object-name type size size-in-packfile offset-in-packfile
 
 for objects that are not deltified in the pack, and
 
-	SHA-1 type size size-in-packfile offset-in-packfile depth base-SHA-1
+	object-name type size size-in-packfile offset-in-packfile depth base-object-name
 
 for objects that are deltified.
 
diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.adoc
index 81d50ecc4c..b3721a86f4 100644
--- a/Documentation/git-verify-tag.txt
+++ b/Documentation/git-verify-tag.adoc
@@ -7,26 +7,24 @@ git-verify-tag - Check the GPG signature of tags
 
 SYNOPSIS
 --------
-[verse]
-'git verify-tag' [-v | --verbose] [--format=<format>] [--raw] <tag>...
+[synopsis]
+git verify-tag [-v | --verbose] [--format=<format>] [--raw] <tag>...
 
 DESCRIPTION
 -----------
-Validates the gpg signature created by 'git tag'.
+Validates the gpg signature created by `git tag` in the tag
+objects listed on the command line.
 
 OPTIONS
 -------
---raw::
+`--raw`::
 	Print the raw gpg status output to standard error instead of the normal
 	human-readable output.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Print the contents of the tag object before validating it.
 
-<tag>...::
-	SHA-1 identifiers of Git tag objects.
-
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-version.txt b/Documentation/git-version.adoc
index 80fa7754a6..9462043a14 100644
--- a/Documentation/git-version.txt
+++ b/Documentation/git-version.adoc
@@ -22,6 +22,14 @@ OPTIONS
 --build-options::
 	Include additional information about how git was built for diagnostic
 	purposes.
++
+The libraries used to implement the SHA-1 and SHA-256 algorithms are displayed
+in the form `SHA-1: <option>` and `SHA-256: <option>`. Note that the SHA-1
+options `SHA1_APPLE`, `SHA1_OPENSSL`, and `SHA1_BLK` do not use a collision
+detection algorithm and thus may be vulnerable to known SHA-1 collision
+attacks. When a faster SHA-1 implementation without collision detection is used
+for only non-cryptographic purposes, the algorithm is displayed in the form
+`non-collision-detecting-SHA-1: <option>`.
 
 GIT
 ---
diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.adoc
index f2f996cbe1..f2f996cbe1 100644
--- a/Documentation/git-web--browse.txt
+++ b/Documentation/git-web--browse.adoc
diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.adoc
index 8e55e0bb1e..436e219b7d 100644
--- a/Documentation/git-whatchanged.txt
+++ b/Documentation/git-whatchanged.adoc
@@ -8,8 +8,14 @@ git-whatchanged - Show logs with differences each commit introduces
 
 SYNOPSIS
 --------
-[verse]
-'git whatchanged' <option>...
+[synopsis]
+git whatchanged <option>...
+
+WARNING
+-------
+`git whatchanged` has been deprecated and is scheduled for removal in
+a future version of Git, as it is merely `git log` with different
+defaults.
 
 DESCRIPTION
 -----------
@@ -18,7 +24,11 @@ Shows commit logs and diff output each commit introduces.
 
 New users are encouraged to use linkgit:git-log[1] instead.  The
 `whatchanged` command is essentially the same as linkgit:git-log[1]
-but defaults to showing the raw format diff output and skipping merges.
+but defaults to showing the raw format diff output and skipping merges:
+
+----
+git log --raw --no-merges
+----
 
 The command is primarily kept for historical reasons; fingers of
 many people who learned Git long before `git log` was invented by
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.adoc
index 8340b7f028..f272f79783 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.adoc
@@ -8,16 +8,16 @@ git-worktree - Manage multiple working trees
 
 SYNOPSIS
 --------
-[verse]
-'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]]
-		   [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
-'git worktree list' [-v | --porcelain [-z]]
-'git worktree lock' [--reason <string>] <worktree>
-'git worktree move' <worktree> <new-path>
-'git worktree prune' [-n] [-v] [--expire <expire>]
-'git worktree remove' [-f] <worktree>
-'git worktree repair' [<path>...]
-'git worktree unlock' <worktree>
+[synopsis]
+git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
+		 [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
+git worktree list [-v | --porcelain [-z]]
+git worktree lock [--reason <string>] <worktree>
+git worktree move <worktree> <new-path>
+git worktree prune [-n] [-v] [--expire <expire>]
+git worktree remove [-f] <worktree>
+git worktree repair [<path>...]
+git worktree unlock <worktree>
 
 DESCRIPTION
 -----------
@@ -37,7 +37,7 @@ zero or more linked worktrees. When you are done with a linked worktree,
 remove it with `git worktree remove`.
 
 In its simplest form, `git worktree add <path>` automatically creates a
-new branch whose name is the final component of `<path>`, which is
+new branch whose name is the final component of _<path>_, which is
 convenient if you plan to work on a new topic. For instance, `git
 worktree add ../hotfix` creates new branch `hotfix` and checks it out at
 path `../hotfix`. To instead work on an existing branch in a new worktree,
@@ -63,16 +63,16 @@ locked.
 
 COMMANDS
 --------
-add <path> [<commit-ish>]::
+`add <path> [<commit-ish>]`::
 
-Create a worktree at `<path>` and checkout `<commit-ish>` into it. The new worktree
+Create a worktree at _<path>_ and checkout _<commit-ish>_ into it. The new worktree
 is linked to the current repository, sharing everything except per-worktree
-files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may
+files such as `HEAD`, `index`, etc. As a convenience, _<commit-ish>_ may
 be a bare "`-`", which is synonymous with `@{-1}`.
 +
-If `<commit-ish>` is a branch name (call it `<branch>`) and is not found,
+If _<commit-ish>_ is a branch name (call it _<branch>_) and is not found,
 and neither `-b` nor `-B` nor `--detach` are used, but there does
-exist a tracking branch in exactly one remote (call it `<remote>`)
+exist a tracking branch in exactly one remote (call it _<remote>_)
 with a matching name, treat as equivalent to:
 +
 ------------
@@ -81,32 +81,32 @@ $ git worktree add --track -b <branch> <path> <remote>/<branch>
 +
 If the branch exists in multiple remotes and one of them is named by
 the `checkout.defaultRemote` configuration variable, we'll use that
-one for the purposes of disambiguation, even if the `<branch>` isn't
+one for the purposes of disambiguation, even if the _<branch>_ isn't
 unique across all remotes. Set it to
 e.g. `checkout.defaultRemote=origin` to always checkout remote
-branches from there if `<branch>` is ambiguous but exists on the
+branches from there if _<branch>_ is ambiguous but exists on the
 `origin` remote. See also `checkout.defaultRemote` in
 linkgit:git-config[1].
 +
-If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
+If _<commit-ish>_ is omitted and neither `-b` nor `-B` nor `--detach` used,
 then, as a convenience, the new worktree is associated with a branch (call
-it `<branch>`) named after `$(basename <path>)`.  If `<branch>` doesn't
+it _<branch>_) named after `$(basename <path>)`.  If _<branch>_ doesn't
 exist, a new branch based on `HEAD` is automatically created as if
-`-b <branch>` was given.  If `<branch>` does exist, it will be checked out
+`-b <branch>` was given.  If _<branch>_ does exist, it will be checked out
 in the new worktree, if it's not checked out anywhere else, otherwise the
 command will refuse to create the worktree (unless `--force` is used).
 +
-If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is
+If _<commit-ish>_ is omitted, neither `--detach`, or `--orphan` is
 used, and there are no valid local branches (or remote branches if
 `--guess-remote` is specified) then, as a convenience, the new worktree is
-associated with a new unborn branch named `<branch>` (after
+associated with a new unborn branch named _<branch>_ (after
 `$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was
 passed to the command. In the event the repository has a remote and
 `--guess-remote` is used, but no remote or local branches exist, then the
 command fails with a warning reminding the user to fetch from their remote
 first (or override by using `-f/--force`).
 
-list::
+`list`::
 
 List details of each worktree.  The main worktree is listed first,
 followed by each of the linked worktrees.  The output details include
@@ -115,32 +115,32 @@ branch currently checked out (or "detached HEAD" if none), "locked" if
 the worktree is locked, "prunable" if the worktree can be pruned by the
 `prune` command.
 
-lock::
+`lock`::
 
 If a worktree is on a portable device or network share which is not always
 mounted, lock it to prevent its administrative files from being pruned
 automatically. This also prevents it from being moved or deleted.
 Optionally, specify a reason for the lock with `--reason`.
 
-move::
+`move`::
 
 Move a worktree to a new location. Note that the main worktree or linked
 worktrees containing submodules cannot be moved with this command. (The
 `git worktree repair` command, however, can reestablish the connection
 with linked worktrees if you move the main worktree manually.)
 
-prune::
+`prune`::
 
 Prune worktree information in `$GIT_DIR/worktrees`.
 
-remove::
+`remove`::
 
 Remove a worktree. Only clean worktrees (no untracked files and no
 modification in tracked files) can be removed. Unclean worktrees or ones
 with submodules can be removed with `--force`. The main worktree cannot be
 removed.
 
-repair [<path>...]::
+`repair [<path>...]`::
 
 Repair worktree administrative files, if possible, if they have become
 corrupted or outdated due to external factors.
@@ -154,69 +154,72 @@ Similarly, if the working tree for a linked worktree is moved without
 using `git worktree move`, the main worktree (or bare repository) will be
 unable to locate it. Running `repair` within the recently-moved worktree
 will reestablish the connection. If multiple linked worktrees are moved,
-running `repair` from any worktree with each tree's new `<path>` as an
+running `repair` from any worktree with each tree's new _<path>_ as an
 argument, will reestablish the connection to all the specified paths.
 +
 If both the main worktree and linked worktrees have been moved or copied manually,
-then running `repair` in the main worktree and specifying the new `<path>`
+then running `repair` in the main worktree and specifying the new _<path>_
 of each linked worktree will reestablish all connections in both
 directions.
 
-unlock::
+`unlock`::
 
 Unlock a worktree, allowing it to be pruned, moved or deleted.
 
 OPTIONS
 -------
 
--f::
---force::
+`-f`::
+`--force`::
 	By default, `add` refuses to create a new worktree when
-	`<commit-ish>` is a branch name and is already checked out by
-	another worktree, or if `<path>` is already assigned to some
-	worktree but is missing (for instance, if `<path>` was deleted
+	_<commit-ish>_ is a branch name and is already checked out by
+	another worktree, or if _<path>_ is already assigned to some
+	worktree but is missing (for instance, if _<path>_ was deleted
 	manually). This option overrides these safeguards. To add a missing but
 	locked worktree path, specify `--force` twice.
 +
 `move` refuses to move a locked worktree unless `--force` is specified
 twice. If the destination is already assigned to some other worktree but is
-missing (for instance, if `<new-path>` was deleted manually), then `--force`
+missing (for instance, if _<new-path>_ was deleted manually), then `--force`
 allows the move to proceed; use `--force` twice if the destination is locked.
 +
 `remove` refuses to remove an unclean worktree unless `--force` is used.
 To remove a locked worktree, specify `--force` twice.
 
--b <new-branch>::
--B <new-branch>::
-	With `add`, create a new branch named `<new-branch>` starting at
-	`<commit-ish>`, and check out `<new-branch>` into the new worktree.
-	If `<commit-ish>` is omitted, it defaults to `HEAD`.
+`-b <new-branch>`::
+`-B <new-branch>`::
+	With `add`, create a new branch named _<new-branch>_ starting at
+	_<commit-ish>_, and check out _<new-branch>_ into the new worktree.
+	If _<commit-ish>_ is omitted, it defaults to `HEAD`.
 	By default, `-b` refuses to create a new branch if it already
-	exists. `-B` overrides this safeguard, resetting `<new-branch>` to
-	`<commit-ish>`.
+	exists. `-B` overrides this safeguard, resetting _<new-branch>_ to
+	_<commit-ish>_.
 
--d::
---detach::
+`-d`::
+`--detach`::
 	With `add`, detach `HEAD` in the new worktree. See "DETACHED HEAD"
 	in linkgit:git-checkout[1].
 
---[no-]checkout::
-	By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can
+`--checkout`::
+`--no-checkout`::
+	By default, `add` checks out _<commit-ish>_, however, `--no-checkout` can
 	be used to suppress checkout in order to make customizations,
 	such as configuring sparse-checkout. See "Sparse checkout"
 	in linkgit:git-read-tree[1].
 
---[no-]guess-remote::
-	With `worktree add <path>`, without `<commit-ish>`, instead
+`--guess-remote`::
+`--no-guess-remote`::
+	With `worktree add <path>`, without _<commit-ish>_, instead
 	of creating a new branch from `HEAD`, if there exists a tracking
-	branch in exactly one remote matching the basename of `<path>`,
+	branch in exactly one remote matching the basename of _<path>_,
 	base the new branch on the remote-tracking branch, and mark
 	the remote-tracking branch as "upstream" from the new branch.
 +
 This can also be set up as the default behaviour by using the
 `worktree.guessRemote` config option.
 
---[no-]relative-paths::
+`--relative-paths`::
+`--no-relative-paths`::
 	Link worktrees using relative paths or absolute paths (default).
 	Overrides the `worktree.useRelativePaths` config option, see
 	linkgit:git-config[1].
@@ -224,59 +227,60 @@ This can also be set up as the default behaviour by using the
 With `repair`, the linking files will be updated if there's an absolute/relative
 mismatch, even if the links are correct.
 
---[no-]track::
-	When creating a new branch, if `<commit-ish>` is a branch,
+`--track`::
+`--no-track`::
+	When creating a new branch, if _<commit-ish>_ is a branch,
 	mark it as "upstream" from the new branch.  This is the
-	default if `<commit-ish>` is a remote-tracking branch.  See
+	default if _<commit-ish>_ is a remote-tracking branch.  See
 	`--track` in linkgit:git-branch[1] for details.
 
---lock::
+`--lock`::
 	Keep the worktree locked after creation. This is the
 	equivalent of `git worktree lock` after `git worktree add`,
 	but without a race condition.
 
--n::
---dry-run::
+`-n`::
+`--dry-run`::
 	With `prune`, do not remove anything; just report what it would
 	remove.
 
---orphan::
+`--orphan`::
 	With `add`, make the new worktree and index empty, associating
-	the worktree with a new unborn branch named `<new-branch>`.
+	the worktree with a new unborn branch named _<new-branch>_.
 
---porcelain::
+`--porcelain`::
 	With `list`, output in an easy-to-parse format for scripts.
 	This format will remain stable across Git versions and regardless of user
 	configuration.  It is recommended to combine this with `-z`.
 	See below for details.
 
--z::
-	Terminate each line with a NUL rather than a newline when
+`-z`::
+	Terminate each line with a _NUL_ rather than a newline when
 	`--porcelain` is specified with `list`. This makes it possible
 	to parse the output when a worktree path contains a newline
 	character.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	With `add`, suppress feedback messages.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	With `prune`, report all removals.
 +
 With `list`, output additional information about worktrees (see below).
 
---expire <time>::
-	With `prune`, only expire unused worktrees older than `<time>`.
+`--expire <time>`::
+	With `prune`, only expire unused worktrees older than _<time>_.
 +
 With `list`, annotate missing worktrees as prunable if they are older than
-`<time>`.
+_<time>_.
 
---reason <string>::
+`--reason <string>`::
 	With `lock` or with `add --lock`, an explanation why the worktree
 	is locked.
 
-<worktree>::
+_<worktree>_::
 	Worktrees can be identified by path, either relative or absolute.
 +
 If the last path components in the worktree's path is unique among
@@ -518,6 +522,13 @@ $ popd
 $ git worktree remove ../temp
 ------------
 
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.adoc[]
+
+include::config/worktree.adoc[]
+
 BUGS
 ----
 Multiple checkout in general is still experimental, and the support
diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.adoc
index f22041a9dc..4c7100ea1e 100644
--- a/Documentation/git-write-tree.txt
+++ b/Documentation/git-write-tree.adoc
@@ -8,8 +8,8 @@ git-write-tree - Create a tree object from the current index
 
 SYNOPSIS
 --------
-[verse]
-'git write-tree' [--missing-ok] [--prefix=<prefix>/]
+[synopsis]
+git write-tree [--missing-ok] [--prefix=<prefix>/]
 
 DESCRIPTION
 -----------
@@ -18,23 +18,23 @@ tree object is printed to standard output.
 
 The index must be in a fully merged state.
 
-Conceptually, 'git write-tree' sync()s the current index contents
+Conceptually, `git write-tree` sync()s the current index contents
 into a set of tree files.
 In order to have that match what is actually in your directory right
-now, you need to have done a 'git update-index' phase before you did the
-'git write-tree'.
+now, you need to have done a `git update-index` phase before you did the
+`git write-tree`.
 
 
 OPTIONS
 -------
---missing-ok::
-	Normally 'git write-tree' ensures that the objects referenced by the
+`--missing-ok`::
+	Normally `git write-tree` ensures that the objects referenced by the
 	directory exist in the object database.  This option disables this
 	check.
 
---prefix=<prefix>/::
+`--prefix=<prefix>/`::
 	Writes a tree object that represents a subdirectory
-	`<prefix>`.  This can be used to write the tree object
+	_<prefix>_.  This can be used to write the tree object
 	for a subproject that is in the named subdirectory.
 
 GIT
diff --git a/Documentation/git.txt b/Documentation/git.adoc
index e89a91dd0d..ce099e78b8 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.adoc
@@ -219,7 +219,8 @@ If you just want to run git as if it was started in `<path>` then use
 	List commands by group. This is an internal/experimental
 	option and may change or be removed in the future. Supported
 	groups are: builtins, parseopt (builtin commands that use
-	parse-options), main (all commands in libexec directory),
+	parse-options), deprecated (deprecated builtins),
+	main (all commands in libexec directory),
 	others (all other commands in `$PATH` that have git- prefix),
 	list-<category> (see categories in command-list.txt),
 	nohelpers (exclude helper commands), alias and config
@@ -245,17 +246,17 @@ ancillary user utilities.
 Main porcelain commands
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-include::{build_dir}/cmds-mainporcelain.txt[]
+include::{build_dir}/cmds-mainporcelain.adoc[]
 
 Ancillary Commands
 ~~~~~~~~~~~~~~~~~~
 Manipulators:
 
-include::{build_dir}/cmds-ancillarymanipulators.txt[]
+include::{build_dir}/cmds-ancillarymanipulators.adoc[]
 
 Interrogators:
 
-include::{build_dir}/cmds-ancillaryinterrogators.txt[]
+include::{build_dir}/cmds-ancillaryinterrogators.adoc[]
 
 
 Interacting with Others
@@ -264,7 +265,7 @@ Interacting with Others
 These commands are to interact with foreign SCM and with other
 people via patch over e-mail.
 
-include::{build_dir}/cmds-foreignscminterface.txt[]
+include::{build_dir}/cmds-foreignscminterface.adoc[]
 
 Reset, restore and revert
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -313,13 +314,13 @@ repositories.
 Manipulation commands
 ~~~~~~~~~~~~~~~~~~~~~
 
-include::{build_dir}/cmds-plumbingmanipulators.txt[]
+include::{build_dir}/cmds-plumbingmanipulators.adoc[]
 
 
 Interrogation commands
 ~~~~~~~~~~~~~~~~~~~~~~
 
-include::{build_dir}/cmds-plumbinginterrogators.txt[]
+include::{build_dir}/cmds-plumbinginterrogators.adoc[]
 
 In general, the interrogate commands do not touch the files in
 the working tree.
@@ -328,12 +329,12 @@ the working tree.
 Syncing repositories
 ~~~~~~~~~~~~~~~~~~~~
 
-include::{build_dir}/cmds-synchingrepositories.txt[]
+include::{build_dir}/cmds-synchingrepositories.adoc[]
 
 The following are helper commands used by the above; end users
 typically do not use them directly.
 
-include::{build_dir}/cmds-synchelpers.txt[]
+include::{build_dir}/cmds-synchelpers.adoc[]
 
 
 Internal helper commands
@@ -342,14 +343,14 @@ Internal helper commands
 These are internal helper commands used by other commands; end
 users typically do not use them directly.
 
-include::{build_dir}/cmds-purehelpers.txt[]
+include::{build_dir}/cmds-purehelpers.adoc[]
 
 Guides
 ------
 
 The following documentation pages are guides about Git concepts.
 
-include::{build_dir}/cmds-guide.txt[]
+include::{build_dir}/cmds-guide.adoc[]
 
 Repository, command and file interfaces
 ---------------------------------------
@@ -358,7 +359,7 @@ This documentation discusses repository and command interfaces which
 users are expected to interact with directly. See `--user-formats` in
 linkgit:git-help[1] for more details on the criteria.
 
-include::{build_dir}/cmds-userinterfaces.txt[]
+include::{build_dir}/cmds-userinterfaces.adoc[]
 
 File formats, protocols and other developer interfaces
 ------------------------------------------------------
@@ -367,7 +368,7 @@ This documentation discusses file formats, over-the-wire protocols and
 other git developer interfaces. See `--developer-interfaces` in
 linkgit:git-help[1].
 
-include::{build_dir}/cmds-developerinterfaces.txt[]
+include::{build_dir}/cmds-developerinterfaces.adoc[]
 
 Configuration Mechanism
 -----------------------
@@ -472,8 +473,9 @@ Environment Variables
 ---------------------
 Various Git commands pay attention to environment variables and change
 their behavior.  The environment variables marked as "Boolean" take
-their values the same way as Boolean valued configuration variables, e.g.
-"true", "yes", "on" and positive numbers are taken as "yes".
+their values the same way as Boolean valued configuration variables, i.e.,
+"true", "yes", "on" and positive numbers are taken as "yes", while "false",
+"no", "off", and "0" are taken as "no".
 
 Here are the variables:
 
@@ -683,7 +685,7 @@ other
 
 `GIT_PROGRESS_DELAY`::
 	A number controlling how many seconds to delay before showing
-	optional progress indicators. Defaults to 2.
+	optional progress indicators. Defaults to 1.
 
 `GIT_EDITOR`::
 	This environment variable overrides `$EDITOR` and `$VISUAL`.
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.adoc
index e6150595af..f20041a323 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.adoc
@@ -513,7 +513,7 @@ If the filter command (a string value) is defined via
 `filter.<driver>.process` then Git can process all blobs with a
 single filter invocation for the entire life of a single Git
 command. This is achieved by using the long-running process protocol
-(described in technical/long-running-process-protocol.txt).
+(described in Documentation/technical/long-running-process-protocol.adoc).
 
 When Git encounters the first file that needs to be cleaned or smudged,
 it starts the filter and performs the handshake. In the handshake, the
@@ -531,13 +531,14 @@ must not send any response before it received the content and the
 final flush packet. Also note that the "value" of a "key=value" pair
 can contain the "=" character whereas the key would never contain
 that character.
-------------------------
+
+-----------------------
 packet:          git> command=smudge
 packet:          git> pathname=path/testfile.dat
 packet:          git> 0000
 packet:          git> CONTENT
 packet:          git> 0000
-------------------------
+-----------------------
 
 The filter is expected to respond with a list of "key=value" pairs
 terminated with a flush packet. If the filter does not experience
@@ -559,6 +560,7 @@ packet:          git< 0000  # empty list, keep "status=success" unchanged!
 
 If the result content is empty then the filter is expected to respond
 with a "success" status and a flush packet to signal the empty content.
+
 ------------------------
 packet:          git< status=success
 packet:          git< 0000
@@ -568,14 +570,16 @@ packet:          git< 0000  # empty list, keep "status=success" unchanged!
 
 In case the filter cannot or does not want to process the content,
 it is expected to respond with an "error" status.
-------------------------
+
+-----------------------
 packet:          git< status=error
 packet:          git< 0000
-------------------------
+-----------------------
 
 If the filter experiences an error during processing, then it can
 send the status "error" after the content was (partially or
 completely) sent.
+
 ------------------------
 packet:          git< status=success
 packet:          git< 0000
@@ -589,10 +593,11 @@ In case the filter cannot or does not want to process the content
 as well as any future content for the lifetime of the Git process,
 then it is expected to respond with an "abort" status at any point
 in the protocol.
-------------------------
+
+-----------------------
 packet:          git< status=abort
 packet:          git< 0000
-------------------------
+-----------------------
 
 Git neither stops nor restarts the filter process in case the
 "error"/"abort" status is set. However, Git sets its exit code
@@ -613,7 +618,8 @@ flag "can-delay" after the filter command and pathname. This flag
 denotes that the filter can delay filtering the current blob (e.g. to
 compensate network latencies) by responding with no content but with
 the status "delayed" and a flush packet.
-------------------------
+
+-----------------------
 packet:          git> command=smudge
 packet:          git> pathname=path/testfile.dat
 packet:          git> can-delay=1
@@ -622,7 +628,7 @@ packet:          git> CONTENT
 packet:          git> 0000
 packet:          git< status=delayed
 packet:          git< 0000
-------------------------
+-----------------------
 
 If the filter supports the "delay" capability then it must support the
 "list_available_blobs" command. If Git sends this command, then the
@@ -647,10 +653,12 @@ packet:          git< status=success
 packet:          git< 0000
 ------------------------
 
+
 After Git received the pathnames, it will request the corresponding
 blobs again. These requests contain a pathname and an empty content
 section. The filter is expected to respond with the smudged content
 in the usual way as explained above.
+
 ------------------------
 packet:          git> command=smudge
 packet:          git> pathname=path/testfile.dat
@@ -701,8 +709,8 @@ where the attribute is not in place would normally cause merge
 conflicts.
 
 To prevent these unnecessary merge conflicts, Git can be told to run a
-virtual check-out and check-in of all three stages of a file when
-resolving a three-way merge by setting the `merge.renormalize`
+virtual check-out and check-in of all three stages of each file that
+needs a three-way content merge, by setting the `merge.renormalize`
 configuration variable.  This prevents changes caused by check-in
 conversion from causing spurious merge conflicts when a converted file
 is merged with an unconverted file.
@@ -1166,7 +1174,7 @@ internal merge and the final merge.
 The merge driver can learn the pathname in which the merged result
 will be stored via placeholder `%P`. The conflict labels to be used
 for the common ancestor, local head and other head can be passed by
-using '%S', '%X' and '%Y` respectively.
+using `%S`, `%X` and `%Y` respectively.
 
 `conflict-marker-size`
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -1177,11 +1185,11 @@ integer has a meaningful effect.
 
 For example, this line in `.gitattributes` can be used to tell the merge
 machinery to leave much longer (instead of the usual 7-character-long)
-conflict markers when merging the file `Documentation/git-merge.txt`
+conflict markers when merging the file `Documentation/git-merge.adoc`
 results in a conflict.
 
 ------------------------
-Documentation/git-merge.txt	conflict-marker-size=32
+Documentation/git-merge.adoc	conflict-marker-size=32
 ------------------------
 
 
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.adoc
index fcd86d2eee..ef2a0a399d 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.adoc
@@ -161,6 +161,23 @@ can use `--no-track` to override that behaviour. The same goes for `--color`
 and `--no-color`.
 
 
+Options trump configuration and environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When there is a configuration variable or an environment variable
+that tweak the behaviour of an aspect of a Git command, and also a
+command line option that tweaks the same, the command line option
+overrides what the configuration and/or environment variable say.
+
+For example, the `user.name` configuration variable is used to
+specify the human-readable name used by the `git commit` command to
+record the author and the committer name in a newly created commit.
+The `GIT_AUTHOR_NAME` environment variable, if set, takes precedence
+when deciding what author name to record.  The `--author=<author>`
+command line option of the `git commit` command, when given, takes
+precedence over these two sources of information.
+
+
 Aggregating short options
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 Commands that support the enhanced option parser allow you to aggregate short
@@ -192,6 +209,7 @@ $ git foo -o Arg
 
 However, this is *NOT* allowed for switches with an optional value, where the
 'stuck' form must be used:
+
 ----------------------------
 $ git describe --abbrev HEAD     # correct
 $ git describe --abbrev=10 HEAD  # correct
@@ -199,6 +217,19 @@ $ git describe --abbrev 10 HEAD  # NOT WHAT YOU MEANT
 ----------------------------
 
 
+Magic filename options
+~~~~~~~~~~~~~~~~~~~~~~
+Options that take a filename allow a prefix `:(optional)`. For example:
+
+----------------------------
+git commit -F :(optional)COMMIT_EDITMSG
+# if COMMIT_EDITMSG does not exist, equivalent to
+git commit
+----------------------------
+
+Like with configuration values, if the named file is missing Git behaves as if
+the option was not given at all. See "Values" in linkgit:git-config[1].
+
 NOTES ON FREQUENTLY CONFUSED OPTIONS
 ------------------------------------
 
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.adoc
index 2122aeb976..2122aeb976 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.adoc
diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.adoc
index 35a7452c8f..60c2cc4ade 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.adoc
@@ -66,18 +66,7 @@ storage provided by the OS or other programs. Alternatively, a
 credential-generating helper might generate credentials for certain servers via
 some API.
 
-To use a helper, you must first select one to use. Git currently
-includes the following helpers:
-
-cache::
-
-	Cache credentials in memory for a short period of time. See
-	linkgit:git-credential-cache[1] for details.
-
-store::
-
-	Store credentials indefinitely on disk. See
-	linkgit:git-credential-store[1] for details.
+To use a helper, you must first select one to use (see below for a list).
 
 You may also have third-party helpers installed; search for
 `credential-*` in the output of `git help -a`, and consult the
@@ -106,6 +95,28 @@ $ git config --global credential.helper foo
 
 === Available helpers
 
+Git currently includes the following helpers:
+
+cache::
+
+    Cache credentials in memory for a short period of time. See
+    linkgit:git-credential-cache[1] for details.
+
+store::
+
+    Store credentials indefinitely on disk. See
+    linkgit:git-credential-store[1] for details.
+
+Popular helpers with secure persistent storage include:
+
+    - git-credential-libsecret (Linux)
+
+    - git-credential-osxkeychain (macOS)
+
+    - git-credential-wincred (Windows)
+
+    - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows)
+
 The community maintains a comprehensive list of Git credential helpers at
 https://git-scm.com/doc/credential-helpers.
 
@@ -116,6 +127,12 @@ OAuth credential helper. Initial authentication opens a browser window to the
 host. Subsequent authentication happens in the background. Many popular Git
 hosts support OAuth.
 
+Popular helpers with OAuth support include:
+
+    - https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager] (cross platform, included in Git for Windows)
+
+    - https://github.com/hickford/git-credential-oauth[git-credential-oauth] (cross platform, included in many Linux distributions)
+
 CREDENTIAL CONTEXTS
 -------------------
 
@@ -133,9 +150,8 @@ pattern in the config file. For example, if you have this in your config file:
 	username = foo
 --------------------------------------
 
-then we will match: both protocols are the same, both hosts are the same, and
-the "pattern" URL does not care about the path component at all. However, this
-context would not match:
+then we will match: both protocols are the same and both hosts are the same.
+However, this context would not match:
 
 --------------------------------------
 [credential "https://kernel.org"]
@@ -149,11 +165,11 @@ match: Git compares the protocols exactly.  However, you may use wildcards in
 the domain name and other pattern matching techniques as with the `http.<URL>.*`
 options.
 
-If the "pattern" URL does include a path component, then this too must match
-exactly: the context `https://example.com/bar/baz.git` will match a config
-entry for `https://example.com/bar/baz.git` (in addition to matching the config
-entry for `https://example.com`) but will not match a config entry for
-`https://example.com/bar`.
+If the "pattern" URL does include a path component, then this must match
+as a prefix path: the context `https://example.com/bar` will match a config
+entry for `https://example.com/bar/baz.git` but will not match a config entry for
+`https://example.com/other/repo.git` or `https://example.com/barry/repo.git`
+(even though it is a string prefix).
 
 
 CONFIGURATION OPTIONS
diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.adoc
index 1cd1283d0f..1cd1283d0f 100644
--- a/Documentation/gitcvs-migration.txt
+++ b/Documentation/gitcvs-migration.adoc
diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.adoc
index 642c51227b..642c51227b 100644
--- a/Documentation/gitdiffcore.txt
+++ b/Documentation/gitdiffcore.adoc
diff --git a/Documentation/giteveryday.txt b/Documentation/giteveryday.adoc
index 6cfdd0e07b..6cfdd0e07b 100644
--- a/Documentation/giteveryday.txt
+++ b/Documentation/giteveryday.adoc
diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.adoc
index f2917d142c..f2917d142c 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.adoc
diff --git a/Documentation/gitformat-bundle.txt b/Documentation/gitformat-bundle.adoc
index 1b75cf71ce..1b75cf71ce 100644
--- a/Documentation/gitformat-bundle.txt
+++ b/Documentation/gitformat-bundle.adoc
diff --git a/Documentation/gitformat-chunk.txt b/Documentation/gitformat-chunk.adoc
index 3315df6201..3315df6201 100644
--- a/Documentation/gitformat-chunk.txt
+++ b/Documentation/gitformat-chunk.adoc
diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.adoc
index 14d1631234..14d1631234 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.adoc
diff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.adoc
index 145cace1fe..145cace1fe 100644
--- a/Documentation/gitformat-index.txt
+++ b/Documentation/gitformat-index.adoc
diff --git a/Documentation/gitformat-loose.adoc b/Documentation/gitformat-loose.adoc
new file mode 100644
index 0000000000..947993663e
--- /dev/null
+++ b/Documentation/gitformat-loose.adoc
@@ -0,0 +1,53 @@
+gitformat-loose(5)
+==================
+
+NAME
+----
+gitformat-loose - Git loose object format
+
+
+SYNOPSIS
+--------
+[verse]
+$GIT_DIR/objects/[0-9a-f][0-9a-f]/*
+
+DESCRIPTION
+-----------
+
+Loose objects are how Git stores individual objects, where every object is
+written as a separate file.
+
+Over the lifetime of a repository, objects are usually written as loose objects
+initially.  Eventually, these loose objects will be compacted into packfiles
+via repository maintenance to improve disk space usage and speed up the lookup
+of these objects.
+
+== Loose objects
+
+Each loose object contains a prefix, followed immediately by the data of the
+object.  The prefix contains `<type> <size>\0`.  `<type>` is one of `blob`,
+`tree`, `commit`, or `tag` and `size` is the size of the data (without the
+prefix) as a decimal integer expressed in ASCII.
+
+The entire contents, prefix and data concatenated, is then compressed with zlib
+and the compressed data is stored in the file.  The object ID of the object is
+the SHA-1 or SHA-256 (as appropriate) hash of the uncompressed data.
+
+The file for the loose object is stored under the `objects` directory, with the
+first two hex characters of the object ID being the directory and the remaining
+characters being the file name.  This is done to shard the data and avoid too
+many files being in one directory, since some file systems perform poorly with
+many items in a directory.
+
+As an example, the empty tree contains the data (when uncompressed) `tree 0\0`
+and, in a SHA-256 repository, would have the object ID
+`6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321` and would be
+stored under
+`$GIT_DIR/objects/6e/f19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321`.
+
+Similarly, a blob containing the contents `abc` would have the uncompressed
+data of `blob 3\0abc`.
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.adoc
index d6ae229be5..1b4db4aa61 100644
--- a/Documentation/gitformat-pack.txt
+++ b/Documentation/gitformat-pack.adoc
@@ -32,6 +32,10 @@ In a repository using the traditional SHA-1, pack checksums, index checksums,
 and object IDs (object names) mentioned below are all computed using SHA-1.
 Similarly, in SHA-256 repositories, these values are computed using SHA-256.
 
+CRC32 checksums are always computed over the entire packed object, including
+the header (n-byte type and length); the base object name or offset, if any;
+and the entire compressed object.  The CRC32 algorithm used is that of zlib.
+
 == pack-*.pack files have the following format:
 
    - A header appears at the beginning and consists of the following:
@@ -80,6 +84,16 @@ Valid object types are:
 
 Type 5 is reserved for future expansion. Type 0 is invalid.
 
+=== Object encoding
+
+Unlike loose objects, packed objects do not have a prefix containing the type,
+size, and a NUL byte. These are not necessary because they can be determined by
+the n-byte type and length that prefixes the data and so they are omitted from
+the compressed and deltified data.
+
+The computation of the object ID still uses this prefix by reconstructing it
+from the type and length as needed.
+
 === Size encoding
 
 This document uses the following "size encoding" of non-negative
@@ -92,6 +106,11 @@ values are more significant.
 This size encoding should not be confused with the "offset encoding",
 which is also used in this document.
 
+When encoding the size of an undeltified object in a pack, the size is that of
+the uncompressed raw object. For deltified objects, it is the size of the
+uncompressed delta.  The base object name or offset is not included in the size
+computation.
+
 === Deltified representation
 
 Conceptually there are only four object types: commit, tree, tag and
diff --git a/Documentation/gitformat-signature.txt b/Documentation/gitformat-signature.adoc
index d4d3a31f03..d4d3a31f03 100644
--- a/Documentation/gitformat-signature.txt
+++ b/Documentation/gitformat-signature.adoc
diff --git a/Documentation/gitglossary.txt b/Documentation/gitglossary.adoc
index 571f640f5c..0e85be4847 100644
--- a/Documentation/gitglossary.txt
+++ b/Documentation/gitglossary.adoc
@@ -12,7 +12,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-include::glossary-content.txt[]
+include::glossary-content.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/githooks.txt b/Documentation/githooks.adoc
index 0397dec64d..0397dec64d 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.adoc
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.adoc
index 5e0964ef41..5e0964ef41 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.adoc
diff --git a/Documentation/gitk.txt b/Documentation/gitk.adoc
index 35b3996029..5b34dcd077 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.adoc
@@ -98,7 +98,7 @@ linkgit:git-rev-list[1] for a complete list.
 	(See "History simplification" in linkgit:git-log[1] for a more
 	detailed explanation.)
 
-include::line-range-options.txt[]
+include::line-range-options.adoc[]
 
 <revision range>::
 
@@ -163,16 +163,16 @@ used by default. If '$XDG_CONFIG_HOME' is not set it defaults to
 
 History
 -------
-Gitk was the first graphical repository browser. It's written in
-tcl/tk.
+Gitk was the first graphical repository browser, written by
+Paul Mackerras in Tcl/Tk.
 
 'gitk' is actually maintained as an independent project, but stable
 versions are distributed as part of the Git suite for the convenience
 of end users.
 
-gitk-git/ comes from Paul Mackerras's gitk project:
+`gitk-git/` comes from Johannes Sixt's gitk project:
 
-	git://ozlabs.org/~paulus/gitk
+	https://github.com/j6t/gitk
 
 SEE ALSO
 --------
diff --git a/Documentation/gitmailmap.txt b/Documentation/gitmailmap.adoc
index 06f4af93fe..06f4af93fe 100644
--- a/Documentation/gitmailmap.txt
+++ b/Documentation/gitmailmap.adoc
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.adoc
index d9bec8b187..d9bec8b187 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.adoc
diff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.adoc
index 1c8d2ecc35..06f4d37efa 100644
--- a/Documentation/gitnamespaces.txt
+++ b/Documentation/gitnamespaces.adoc
@@ -61,7 +61,7 @@ For a simple local test, you can use linkgit:git-remote-ext[1]:
 git clone ext::'git --namespace=foo %s /tmp/prefixed.git'
 ----------
 
-include::transfer-data-leaks.txt[]
+include::transfer-data-leaks.adoc[]
 
 GIT
 ---
diff --git a/Documentation/gitpacking.txt b/Documentation/gitpacking.adoc
index 321154d4e6..a56596e2d1 100644
--- a/Documentation/gitpacking.txt
+++ b/Documentation/gitpacking.adoc
@@ -136,7 +136,7 @@ chunks of "stableSize" in order of age.
 
 The exact configuration for pseudo-merges is as follows:
 
-include::config/bitmap-pseudo-merge.txt[]
+include::config/bitmap-pseudo-merge.adoc[]
 
 === Examples
 
diff --git a/Documentation/gitprotocol-capabilities.txt b/Documentation/gitprotocol-capabilities.adoc
index 2cf7735be4..2cf7735be4 100644
--- a/Documentation/gitprotocol-capabilities.txt
+++ b/Documentation/gitprotocol-capabilities.adoc
diff --git a/Documentation/gitprotocol-common.txt b/Documentation/gitprotocol-common.adoc
index cdc9d6e707..b4a5316ca4 100644
--- a/Documentation/gitprotocol-common.txt
+++ b/Documentation/gitprotocol-common.adoc
@@ -21,11 +21,13 @@ ABNF Notation
 
 ABNF notation as described by RFC 5234 is used within the protocol documents,
 except the following replacement core rules are used:
+
 ----
   HEXDIG    =  DIGIT / "a" / "b" / "c" / "d" / "e" / "f"
 ----
 
 We also define the following common rules:
+
 ----
   NUL       =  %x00
   zero-id   =  40*"0"
diff --git a/Documentation/gitprotocol-http.txt b/Documentation/gitprotocol-http.adoc
index ec40a550cc..d024010414 100644
--- a/Documentation/gitprotocol-http.txt
+++ b/Documentation/gitprotocol-http.adoc
@@ -318,7 +318,7 @@ Extra Parameter.
 
 
 Smart Service git-upload-pack
-------------------------------
+-----------------------------
 This service reads from the repository pointed to by `$GIT_URL`.
 
 Clients MUST first perform ref discovery with
diff --git a/Documentation/gitprotocol-pack.txt b/Documentation/gitprotocol-pack.adoc
index 837b691c89..837b691c89 100644
--- a/Documentation/gitprotocol-pack.txt
+++ b/Documentation/gitprotocol-pack.adoc
diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.adoc
index 1652fef3ae..c7db103299 100644
--- a/Documentation/gitprotocol-v2.txt
+++ b/Documentation/gitprotocol-v2.adoc
@@ -54,7 +54,7 @@ In general a client can request to speak protocol v2 by sending
 `version=2` through the respective side-channel for the transport being
 used which inevitably sets `GIT_PROTOCOL`.  More information can be
 found in linkgit:gitprotocol-pack[5] and linkgit:gitprotocol-http[5], as well as the
-`GIT_PROTOCOL` definition in `git.txt`. In all cases the
+`GIT_PROTOCOL` definition in linkgit:git[1]. In all cases the
 response from the server is the capability advertisement.
 
 Git Transport
@@ -99,7 +99,7 @@ Uses the `--http-backend-info-refs` option to
 linkgit:git-upload-pack[1].
 
 The server may need to be configured to pass this header's contents via
-the `GIT_PROTOCOL` variable. See the discussion in `git-http-backend.txt`.
+the `GIT_PROTOCOL` variable. See the discussion in linkgit:git-http-backend[1].
 
 Capability Advertisement
 ------------------------
@@ -184,9 +184,13 @@ form `agent=X`) to notify the client that the server is running version
 the `agent` capability with a value `Y` (in the form `agent=Y`) in its
 request to the server (but it MUST NOT do so if the server did not
 advertise the agent capability). The `X` and `Y` strings may contain any
-printable ASCII characters except space (i.e., the byte range 32 < x <
-127), and are typically of the form "package/version" (e.g.,
-"git/1.8.3.1"). The agent strings are purely informative for statistics
+printable ASCII characters except space (i.e., the byte range 33 <= x <=
+126), and are typically of the form "package/version-os" (e.g.,
+"git/1.8.3.1-Linux") where `os` is the operating system name (e.g.,
+"Linux"). `X` and `Y` can be configured using the GIT_USER_AGENT
+environment variable and it takes priority. The `os` is
+retrieved using the 'sysname' field of the `uname(2)` system call
+or its equivalent. The agent strings are purely informative for statistics
 and debugging purposes, and MUST NOT be used to programmatically assume
 the presence or absence of particular features.
 
@@ -781,6 +785,92 @@ retrieving the header from a bundle at the indicated URI, and thus
 save themselves and the server(s) the request(s) needed to inspect the
 headers of that bundle or bundles.
 
+promisor-remote=<pr-info>
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The server may advertise some promisor remotes it is using or knows
+about to a client which may want to use them as its promisor remotes,
+instead of this repository. In this case <pr-info> should be of the
+form:
+
+	pr-info = pr-fields | pr-info ";" pr-fields
+
+	pr-fields = pr-field | pr-fields "," pr-field
+
+	pr-field = field-name "=" field-value
+
+where all the `field-name` and `field-value` in a given `pr-fields`
+are field names and values related to a single promisor remote. A
+given `field-name` MUST NOT appear more than once in given
+`pr-fields`.
+
+The server MUST advertise at least the "name" and "url" field names
+along with the associated field values, which are the name of a valid
+remote and its URL, in each `pr-fields`. The "name" and "url" fields
+MUST appear first in each pr-fields, in that order.
+
+After these mandatory fields, the server MAY advertise the following
+optional fields in any order:
+
+`partialCloneFilter`:: The filter specification used by the remote.
+Clients can use this to determine if the remote's filtering strategy
+is compatible with their needs (e.g., checking if both use "blob:none").
+It corresponds to the "remote.<name>.partialCloneFilter" config setting.
+
+`token`:: An authentication token that clients can use when
+connecting to the remote. It corresponds to the "remote.<name>.token"
+config setting.
+
+No other fields are defined by the protocol at this time. Field names
+are case-sensitive and MUST be transmitted exactly as specified
+above. Clients MUST ignore fields they don't recognize to allow for
+future protocol extensions.
+
+For now, the client can only use information transmitted through these
+fields to decide if it accepts the advertised promisor remote. In the
+future that information might be used for other purposes though.
+
+Field values MUST be urlencoded.
+
+If the client decides to use one or more promisor remotes the server
+advertised, it can reply with "promisor-remote=<pr-names>" where
+<pr-names> should be of the form:
+
+	pr-names = pr-name | pr-names ";" pr-name
+
+where `pr-name` is the urlencoded name of a promisor remote the server
+advertised and the client accepts.
+
+Note that, everywhere in this document, the ';' and ',' characters
+MUST be encoded if they appear in `pr-name` or `field-value`.
+
+If the server doesn't know any promisor remote that could be good for
+a client to use, or prefers a client not to use any promisor remote it
+uses or knows about, it shouldn't advertise the "promisor-remote"
+capability at all.
+
+In this case, or if the client doesn't want to use any promisor remote
+the server advertised, the client shouldn't advertise the
+"promisor-remote" capability at all in its reply.
+
+On the server side, the "promisor.advertise" and "promisor.sendFields"
+configuration options can be used to control what it advertises. On
+the client side, the "promisor.acceptFromServer" configuration option
+can be used to control what it accepts. See the documentation of these
+configuration options for more information.
+
+Note that in the future it would be nice if the "promisor-remote"
+protocol capability could be used by the server, when responding to
+`git fetch` or `git clone`, to advertise better-connected remotes that
+the client can use as promisor remotes, instead of this repository, so
+that the client can lazily fetch objects from these other
+better-connected remotes. This would require the server to omit in its
+response the objects available on the better-connected remotes that
+the client has accepted. This hasn't been implemented yet though. So
+for now this "promisor-remote" capability is useful only when the
+server advertises some promisor remotes it already uses to borrow
+objects from.
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.adoc
index d0be008e5e..39cdece16e 100644
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.adoc
@@ -498,7 +498,7 @@ set by Git if the remote helper has the 'option' capability.
 	ask for the tag specifically.  Some helpers may be able to
 	use this option to avoid a second network connection.
 
-'option dry-run' {'true'|'false'}:
+'option dry-run' {'true'|'false'}::
 	If true, pretend the operation completed successfully,
 	but don't actually change any repository data.  For most
 	helpers this only applies to the 'push', if supported.
diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.adoc
index fa8b51daf0..7421ef956d 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.adoc
@@ -152,8 +152,9 @@ config.worktree::
 	working directory in multiple working directory setup (see
 	linkgit:git-worktree[1]).
 
+ifndef::with-breaking-changes[]
 branches::
-	A slightly deprecated way to store shorthands to be used
+	A deprecated way to store shorthands to be used
 	to specify a URL to 'git fetch', 'git pull' and 'git push'.
 	A file can be stored as `branches/<name>` and then
 	'name' can be given to these commands in place of
@@ -162,7 +163,9 @@ branches::
 	and not likely to be found in modern repositories. This
 	directory is ignored if $GIT_COMMON_DIR is set and
 	"$GIT_COMMON_DIR/branches" will be used instead.
-
++
+Git will stop reading remotes from this directory in Git 3.0.
+endif::with-breaking-changes[]
 
 hooks::
 	Hooks are customization scripts used by various Git
@@ -230,6 +233,7 @@ info/sparse-checkout::
 	This file stores sparse checkout patterns.
 	See also: linkgit:git-read-tree[1].
 
+ifndef::with-breaking-changes[]
 remotes::
 	Stores shorthands for URL and default refnames for use
 	when interacting with remote repositories via 'git fetch',
@@ -238,6 +242,9 @@ remotes::
 	and not likely to be found in modern repositories. This
 	directory is ignored if $GIT_COMMON_DIR is set and
 	"$GIT_COMMON_DIR/remotes" will be used instead.
++
+Git will stop reading remotes from this directory in Git 3.0.
+endif::with-breaking-changes[]
 
 logs::
 	Records of changes made to refs are stored in this directory.
@@ -292,7 +299,7 @@ worktrees/<id>/locked::
 worktrees/<id>/config.worktree::
 	Working directory specific configuration file.
 
-include::technical/repository-version.txt[]
+include::technical/repository-version.adoc[]
 
 SEE ALSO
 --------
diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.adoc
index d407b7dee1..7146117de5 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.adoc
@@ -24,7 +24,7 @@ linkgit:git-push[1]) can also take revision parameters which denote
 other objects than commits, e.g. blobs ("files") or trees
 ("directories of files").
 
-include::revisions.txt[]
+include::revisions.adoc[]
 
 
 SEE ALSO
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.adoc
index f7b5a25a0c..2082296199 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.adoc
@@ -8,6 +8,7 @@ gitsubmodules - Mounting one repository inside another
 SYNOPSIS
 --------
  .gitmodules, $GIT_DIR/config
+
 ------------------
 git submodule
 git <command> --recurse-submodules
@@ -240,7 +241,7 @@ Workflow for a third party library
 
 
 Workflow for an artificially split repo
---------------------------------------
+---------------------------------------
 
   # Enable recursion for relevant commands, such that
   # regular commands recurse into submodules by default
diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.adoc
index 8bdb7d0bd3..8bdb7d0bd3 100644
--- a/Documentation/gittutorial-2.txt
+++ b/Documentation/gittutorial-2.adoc
diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.adoc
index f89ad30cf6..f89ad30cf6 100644
--- a/Documentation/gittutorial.txt
+++ b/Documentation/gittutorial.adoc
diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.adoc
index 5e2b491ec2..4261f9e235 100644
--- a/Documentation/gitweb.txt
+++ b/Documentation/gitweb.adoc
@@ -103,6 +103,7 @@ You can generate the projects list index file using the project_index action
 "Generating projects list using gitweb" section below.
 
 Example contents:
+
 -----------------------------------------------------------------------
 foo.git       Joe+R+Hacker+<joe@example.com>
 foo/bar.git   O+W+Ner+<owner@example.org>
@@ -124,6 +125,7 @@ Generating projects list using gitweb
 
 We assume that GITWEB_CONFIG has its default Makefile value, namely
 'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file:
+
 ----------------------------------------------------------------------------
 read_config_file("gitweb_config.perl");
 $projects_list = $projectroot;
@@ -518,12 +520,14 @@ rules.
 If you use the rewrite rules from the example you *might* also need
 something like the following in your gitweb configuration file
 (`/etc/gitweb.conf` following example):
+
 ----------------------------------------------------------------------------
 @stylesheets = ("/some/absolute/path/gitweb.css");
 $my_uri    = "/";
 $home_link = "/";
 $per_request_config = 1;
 ----------------------------------------------------------------------------
+
 Nowadays though gitweb should create HTML base tag when needed (to set base
 URI for relative links), so it should work automatically.
 
@@ -535,6 +539,7 @@ Apache virtual host and gitweb configuration files in the following way.
 
 The virtual host configuration (in Apache configuration file) should look
 like this:
+
 --------------------------------------------------------------------------
 <VirtualHost *:80>
     ServerName    git.example.org
@@ -575,9 +580,11 @@ like this:
 Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT`
 environment variable from a web server, so you need to put the following
 line in gitweb configuration file (`/etc/gitweb.conf` in above example):
+
 --------------------------------------------------------------------------
 $projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
 --------------------------------------------------------------------------
+
 *Note* that this requires to be set for each request, so either
 `$per_request_config` must be false, or the above must be put in code
 referenced by `$per_request_config`;
@@ -604,9 +611,11 @@ the third and the fourth.
 PATH_INFO usage
 ~~~~~~~~~~~~~~~
 If you enable PATH_INFO usage in gitweb by putting
+
 ----------------------------------------------------------------------------
 $feature{'pathinfo'}{'default'} = [1];
 ----------------------------------------------------------------------------
+
 in your gitweb configuration file, it is possible to set up your server so
 that it consumes and produces URLs in the form
 
@@ -636,6 +645,7 @@ complementary static files (stylesheet, favicon, JavaScript):
 	</Directory>
 </VirtualHost>
 ----------------------------------------------------------------------------
+
 The rewrite rule guarantees that existing static files will be properly
 served, whereas any other URL will be passed to gitweb as PATH_INFO
 parameter.
@@ -647,6 +657,7 @@ for fetching" section).  A possible workaround for the latter is the
 following: in your project root dir (e.g. `/pub/git`) have the projects
 named *without* a .git extension (e.g. `/pub/git/project` instead of
 `/pub/git/project.git`) and configure Apache as follows:
+
 ----------------------------------------------------------------------------
 <VirtualHost *:80>
 	ServerAlias git.example.com
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.adoc
index 85983587fc..64bebb811c 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.adoc
@@ -178,7 +178,7 @@ $export_ok::
 	Show repository only if this file exists (in repository).  Only
 	effective if this variable evaluates to true.  Can be set when
 	building gitweb by setting `GITWEB_EXPORT_OK`.  This path is
-	relative to `GIT_DIR`.  git-daemon[1] uses 'git-daemon-export-ok',
+	relative to `GIT_DIR`.  linkgit:git-daemon[1] uses 'git-daemon-export-ok',
 	unless started with `--export-all`.  By default this variable is
 	not set, which means that this feature is turned off.
 
@@ -603,6 +603,7 @@ Many gitweb features can be enabled (or disabled) and configured using the
 
 Each `%feature` hash element is a hash reference and has the following
 structure:
+
 ----------------------------------------------------------------------
 "<feature-name>" => {
 	"sub" => <feature-sub-(subroutine)>,
@@ -613,6 +614,7 @@ structure:
 Some features cannot be overridden per project.  For those
 features the structure of appropriate `%feature` hash element has a simpler
 form:
+
 ----------------------------------------------------------------------
 "<feature-name>" => {
 	"override" => 0,
diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.adoc
index 59305265c5..59305265c5 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.adoc
diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.adoc
index 575c18f776..e423e4765b 100644
--- a/Documentation/glossary-content.txt
+++ b/Documentation/glossary-content.adoc
@@ -418,9 +418,8 @@ full pathname may have special meaning:
 
  - A leading "`**`" followed by a slash means match in all
    directories. For example, "`**/foo`" matches file or directory
-   "`foo`" anywhere, the same as pattern "`foo`". "`**/foo/bar`"
-   matches file or directory "`bar`" anywhere that is directly
-   under directory "`foo`".
+   "`foo`" anywhere. "`**/foo/bar`" matches file or directory "`bar`"
+   anywhere that is directly under directory "`foo`".
 
  - A trailing "`/**`" matches everything inside. For example,
    "`abc/**`" matches all files inside directory "abc", relative
diff --git a/Documentation/howto/coordinate-embargoed-releases.txt b/Documentation/howto/coordinate-embargoed-releases.adoc
index b9cb95e82f..b9cb95e82f 100644
--- a/Documentation/howto/coordinate-embargoed-releases.txt
+++ b/Documentation/howto/coordinate-embargoed-releases.adoc
diff --git a/Documentation/howto/howto-index.sh b/Documentation/howto/howto-index.sh
index eecd123a93..ace49830a8 100755
--- a/Documentation/howto/howto-index.sh
+++ b/Documentation/howto/howto-index.sh
@@ -9,9 +9,9 @@ people describing how they use Git in their workflow.
 
 EOF
 
-for txt
+for adoc
 do
-	title=$(expr "$txt" : '.*/\(.*\)\.txt$')
+	title=$(expr "$adoc" : '.*/\(.*\)\.adoc$')
 	from=$(sed -ne '
 	/^$/q
 	/^From:[ 	]/{
@@ -21,7 +21,7 @@ do
 		s/^/by /
 		p
 	}
-	' "$txt")
+	' "$adoc")
 
 	abstract=$(sed -ne '
 	/^Abstract:[ 	]/{
@@ -39,13 +39,13 @@ do
 		x
 		p
 		q
-	}' "$txt")
+	}' "$adoc")
 
-	if grep 'Content-type: text/asciidoc' >/dev/null $txt
+	if grep 'Content-type: text/asciidoc' >/dev/null $adoc
 	then
-		file=$(expr "$txt" : '\(.*\)\.txt$').html
+		file=$(expr "$adoc" : '\(.*\)\.adoc$').html
 	else
-		file="$txt"
+		file="$adoc"
 	fi
 
 	echo "* link:howto/$(basename "$file")[$title] $from
diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.adoc
index e98f03275e..e98f03275e 100644
--- a/Documentation/howto/keep-canonical-history-correct.txt
+++ b/Documentation/howto/keep-canonical-history-correct.adoc
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.adoc
index 45e2599c5d..45e2599c5d 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.adoc
diff --git a/Documentation/howto/meson.build b/Documentation/howto/meson.build
index c023c10416..ece20244af 100644
--- a/Documentation/howto/meson.build
+++ b/Documentation/howto/meson.build
@@ -1,20 +1,20 @@
 howto_sources = [
-  'coordinate-embargoed-releases.txt',
-  'keep-canonical-history-correct.txt',
-  'maintain-git.txt',
-  'new-command.txt',
-  'rebase-from-internal-branch.txt',
-  'rebuild-from-update-hook.txt',
-  'recover-corrupted-blob-object.txt',
-  'recover-corrupted-object-harder.txt',
-  'revert-a-faulty-merge.txt',
-  'revert-branch-rebase.txt',
-  'separating-topic-branches.txt',
-  'setup-git-server-over-http.txt',
-  'update-hook-example.txt',
-  'use-git-daemon.txt',
-  'using-merge-subtree.txt',
-  'using-signed-tag-in-pull-request.txt',
+  'coordinate-embargoed-releases.adoc',
+  'keep-canonical-history-correct.adoc',
+  'maintain-git.adoc',
+  'new-command.adoc',
+  'rebase-from-internal-branch.adoc',
+  'rebuild-from-update-hook.adoc',
+  'recover-corrupted-blob-object.adoc',
+  'recover-corrupted-object-harder.adoc',
+  'revert-a-faulty-merge.adoc',
+  'revert-branch-rebase.adoc',
+  'separating-topic-branches.adoc',
+  'setup-git-server-over-http.adoc',
+  'update-hook-example.adoc',
+  'use-git-daemon.adoc',
+  'using-merge-subtree.adoc',
+  'using-signed-tag-in-pull-request.adoc',
 ]
 
 howto_index = custom_target(
@@ -26,10 +26,10 @@ howto_index = custom_target(
   env: script_environment,
   capture: true,
   input: howto_sources,
-  output: 'howto-index.txt',
+  output: 'howto-index.adoc',
 )
 
-custom_target(
+doc_targets += custom_target(
   command: asciidoc_html_options,
   input: howto_index,
   output: 'howto-index.html',
@@ -41,7 +41,7 @@ custom_target(
 foreach howto : howto_sources
   howto_stripped = custom_target(
     command: [
-      find_program('sed'),
+      sed,
       '-e',
       '1,/^$/d',
       '@INPUT@',
@@ -51,7 +51,7 @@ foreach howto : howto_sources
     capture: true,
   )
 
-  custom_target(
+  doc_targets += custom_target(
     command: asciidoc_html_options,
     input: howto_stripped,
     output: fs.stem(howto_stripped.full_path()) + '.html',
diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.adoc
index 880c51112b..ac73c98be7 100644
--- a/Documentation/howto/new-command.txt
+++ b/Documentation/howto/new-command.adoc
@@ -48,7 +48,7 @@ binary); this organization makes it easy for people reading the code
 to find things.
 
 See the CodingGuidelines document for other guidance on what we consider
-good practice in C and shell, and api-builtin.txt for the support
+good practice in C and shell, and builtin.h for the support
 functions available to built-in commands written in C.
 
 What every extension command needs
diff --git a/Documentation/howto/rebase-from-internal-branch.txt b/Documentation/howto/rebase-from-internal-branch.adoc
index f2e10a7ec8..f2e10a7ec8 100644
--- a/Documentation/howto/rebase-from-internal-branch.txt
+++ b/Documentation/howto/rebase-from-internal-branch.adoc
diff --git a/Documentation/howto/rebuild-from-update-hook.txt b/Documentation/howto/rebuild-from-update-hook.adoc
index db219f5c07..db219f5c07 100644
--- a/Documentation/howto/rebuild-from-update-hook.txt
+++ b/Documentation/howto/rebuild-from-update-hook.adoc
diff --git a/Documentation/howto/recover-corrupted-blob-object.txt b/Documentation/howto/recover-corrupted-blob-object.adoc
index 1b3b188d3c..1b3b188d3c 100644
--- a/Documentation/howto/recover-corrupted-blob-object.txt
+++ b/Documentation/howto/recover-corrupted-blob-object.adoc
diff --git a/Documentation/howto/recover-corrupted-object-harder.txt b/Documentation/howto/recover-corrupted-object-harder.adoc
index 5efb4fe81f..86a1ba75cf 100644
--- a/Documentation/howto/recover-corrupted-object-harder.txt
+++ b/Documentation/howto/recover-corrupted-object-harder.adoc
@@ -125,7 +125,7 @@ static int try_zlib(unsigned char *buf, int len)
 {
 	/* make this absurdly large so we don't have to loop */
 	static unsigned char out[1024*1024];
-	z_stream z;
+	struct z_stream_s z;
 	int ret;
 
 	memset(&z, 0, sizeof(z));
@@ -278,7 +278,7 @@ int main(int argc, char **argv)
 	static unsigned char buf[25 * 1024 * 1024];
 	static unsigned char out[25 * 1024 * 1024];
 	int len;
-	z_stream z;
+	struct z_stream_s z;
 	int ret;
 
 	len = read(0, buf, sizeof(buf));
diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.adoc
index 19f59cc888..19f59cc888 100644
--- a/Documentation/howto/revert-a-faulty-merge.txt
+++ b/Documentation/howto/revert-a-faulty-merge.adoc
diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.adoc
index a3e5595a56..a3e5595a56 100644
--- a/Documentation/howto/revert-branch-rebase.txt
+++ b/Documentation/howto/revert-branch-rebase.adoc
diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.adoc
index 81be0d6115..81be0d6115 100644
--- a/Documentation/howto/separating-topic-branches.txt
+++ b/Documentation/howto/separating-topic-branches.adoc
diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.adoc
index bfe6f9b500..bfe6f9b500 100644
--- a/Documentation/howto/setup-git-server-over-http.txt
+++ b/Documentation/howto/setup-git-server-over-http.adoc
diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.adoc
index 4e727deedd..4e727deedd 100644
--- a/Documentation/howto/update-hook-example.txt
+++ b/Documentation/howto/update-hook-example.adoc
diff --git a/Documentation/howto/use-git-daemon.txt b/Documentation/howto/use-git-daemon.adoc
index 2cad9b3ca5..2cad9b3ca5 100644
--- a/Documentation/howto/use-git-daemon.txt
+++ b/Documentation/howto/use-git-daemon.adoc
diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.adoc
index 3bd581ac35..3bd581ac35 100644
--- a/Documentation/howto/using-merge-subtree.txt
+++ b/Documentation/howto/using-merge-subtree.adoc
diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.adoc
index bbf040eda8..bbf040eda8 100644
--- a/Documentation/howto/using-signed-tag-in-pull-request.txt
+++ b/Documentation/howto/using-signed-tag-in-pull-request.adoc
diff --git a/Documentation/i18n.txt b/Documentation/i18n.adoc
index 3a866af4a4..baff780a7e 100644
--- a/Documentation/i18n.txt
+++ b/Documentation/i18n.adoc
@@ -34,7 +34,7 @@ project find it more convenient to use legacy encodings, Git
 does not forbid it.  However, there are a few things to keep in
 mind.
 
-. 'git commit' and 'git commit-tree' issue
+. `git commit` and `git commit-tree` issue
   a warning if the commit log message given to it does not look
   like a valid UTF-8 string, unless you explicitly say your
   project uses a legacy encoding.  The way to say this is to
@@ -50,7 +50,7 @@ of `i18n.commitEncoding` in their `encoding` header.  This is to
 help other people who look at them later.  Lack of this header
 implies that the commit log message is encoded in UTF-8.
 
-. 'git log', 'git show', 'git blame' and friends look at the
+. `git log`, `git show`, `git blame` and friends look at the
   `encoding` header of a commit object, and try to re-code the
   log message into UTF-8 unless otherwise specified.  You can
   specify the desired output encoding with
diff --git a/Documentation/includes/cmd-config-section-all.txt b/Documentation/includes/cmd-config-section-all.adoc
index 296a239f2a..296a239f2a 100644
--- a/Documentation/includes/cmd-config-section-all.txt
+++ b/Documentation/includes/cmd-config-section-all.adoc
diff --git a/Documentation/includes/cmd-config-section-rest.txt b/Documentation/includes/cmd-config-section-rest.adoc
index b1e7682c1d..b1e7682c1d 100644
--- a/Documentation/includes/cmd-config-section-rest.txt
+++ b/Documentation/includes/cmd-config-section-rest.adoc
diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh
index ed8b4ff3e5..b237b311c3 100755
--- a/Documentation/install-webdoc.sh
+++ b/Documentation/install-webdoc.sh
@@ -3,10 +3,10 @@
 T="$1"
 
 for h in \
-	*.txt *.html \
-	howto/*.txt howto/*.html \
-	technical/*.txt technical/*.html \
-	RelNotes/*.txt *.css
+	*.adoc *.html \
+	howto/*.adoc howto/*.html \
+	technical/*.adoc technical/*.html \
+	RelNotes/*.adoc *.css
 do
 	if test ! -f "$h"
 	then
@@ -24,13 +24,13 @@ do
 done
 strip_leading=$(echo "$T/" | sed -e 's|.|.|g')
 for th in \
-	"$T"/*.html "$T"/*.txt \
-	"$T"/howto/*.txt "$T"/howto/*.html \
-	"$T"/technical/*.txt "$T"/technical/*.html
+	"$T"/*.html "$T"/*.adoc \
+	"$T"/howto/*.adoc "$T"/howto/*.html \
+	"$T"/technical/*.adoc "$T"/technical/*.html
 do
 	h=$(expr "$th" : "$strip_leading"'\(.*\)')
 	case "$h" in
-	RelNotes-*.txt | index.html) continue ;;
+	RelNotes-*.adoc | index.html) continue ;;
 	esac
 	test -f "$h" && continue
 	echo >&2 "# rm -f $th"
diff --git a/Documentation/line-range-format.adoc b/Documentation/line-range-format.adoc
new file mode 100644
index 0000000000..3cc2a14544
--- /dev/null
+++ b/Documentation/line-range-format.adoc
@@ -0,0 +1,32 @@
+_<start>_ and _<end>_ can take one of these forms:
+
+- _<number>_
++
+If _<start>_ or _<end>_ is a number, it specifies an
+absolute line number (lines count from 1).
++
+
+- `/<regex>/`
++
+This form will use the first line matching the given
+POSIX _<regex>_. If _<start>_ is a regex, it will search from the end of
+the previous `-L` range, if any, otherwise from the start of file.
+If _<start>_ is `^/<regex>/`, it will search from the start of file.
+If _<end>_ is a regex, it will search starting at the line given by
+_<start>_.
++
+
+- `+<offset>` or `-<offset>`
++
+This is only valid for _<end>_ and will specify a number
+of lines before or after the line given by _<start>_.
+
++
+If `:<funcname>` is given in place of _<start>_ and _<end>_, it is a
+regular expression that denotes the range from the first funcname line
+that matches _<funcname>_, up to the next funcname line. `:<funcname>`
+searches from the end of the previous `-L` range, if any, otherwise
+from the start of file. `^:<funcname>` searches from the start of
+file. The function names are determined in the same way as `git diff`
+works out patch hunk headers (see 'Defining a custom hunk-header'
+in linkgit:gitattributes[5]).
diff --git a/Documentation/line-range-format.txt b/Documentation/line-range-format.txt
deleted file mode 100644
index 9b51e9fb66..0000000000
--- a/Documentation/line-range-format.txt
+++ /dev/null
@@ -1,32 +0,0 @@
-'<start>' and '<end>' can take one of these forms:
-
-- number
-+
-If '<start>' or '<end>' is a number, it specifies an
-absolute line number (lines count from 1).
-+
-
-- `/regex/`
-+
-This form will use the first line matching the given
-POSIX regex. If '<start>' is a regex, it will search from the end of
-the previous `-L` range, if any, otherwise from the start of file.
-If '<start>' is `^/regex/`, it will search from the start of file.
-If '<end>' is a regex, it will search
-starting at the line given by '<start>'.
-+
-
-- +offset or -offset
-+
-This is only valid for '<end>' and will specify a number
-of lines before or after the line given by '<start>'.
-
-+
-If `:<funcname>` is given in place of '<start>' and '<end>', it is a
-regular expression that denotes the range from the first funcname line
-that matches '<funcname>', up to the next funcname line. `:<funcname>`
-searches from the end of the previous `-L` range, if any, otherwise
-from the start of file. `^:<funcname>` searches from the start of
-file. The function names are determined in the same way as `git diff`
-works out patch hunk headers (see 'Defining a custom hunk-header'
-in linkgit:gitattributes[5]).
diff --git a/Documentation/line-range-options.txt b/Documentation/line-range-options.adoc
index 8e295a62b8..c44ba05320 100644
--- a/Documentation/line-range-options.txt
+++ b/Documentation/line-range-options.adoc
@@ -1,15 +1,15 @@
--L<start>,<end>:<file>::
--L:<funcname>:<file>::
+`-L<start>,<end>:<file>`::
+`-L:<funcname>:<file>`::
 
-	Trace the evolution of the line range given by '<start>,<end>',
-	or by the function name regex '<funcname>', within the '<file>'. You may
+	Trace the evolution of the line range given by `<start>,<end>`,
+	or by the function name regex _<funcname>_, within the _<file>_. You may
 	not give any pathspec limiters.  This is currently limited to
 	a walk starting from a single revision, i.e., you may only
 	give zero or one positive revision arguments, and
-	'<start>' and '<end>' (or '<funcname>') must exist in the starting revision.
+	_<start>_ and _<end>_ (or _<funcname>_) must exist in the starting revision.
 	You can specify this option more than once. Implies `--patch`.
 	Patch output can be suppressed using `--no-patch`, but other diff formats
 	(namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
 	`--name-only`, `--name-status`, `--check`) are not currently implemented.
 +
-include::line-range-format.txt[]
+include::line-range-format.adoc[]
diff --git a/Documentation/lint-delimited-sections.perl b/Documentation/lint-delimited-sections.perl
new file mode 100755
index 0000000000..140b852e5d
--- /dev/null
+++ b/Documentation/lint-delimited-sections.perl
@@ -0,0 +1,48 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+my $exit_code = 0;
+sub report {
+	my ($msg) = @_;
+	print STDERR "$ARGV:$.: $msg\n";
+	$exit_code = 1;
+}
+
+my $line_length = 0;
+my $in_section = 0;
+my $section_header = "";
+
+
+while (my $line = <>) {
+	if (($line =~ /^\+?$/) ||
+	    ($line =~ /^\[.*\]$/) ||
+	    ($line =~ /^ifdef::/)) {
+		$line_length = 0;
+	} elsif ($line =~ /^[^-.]/) {
+		$line_length = length($line);
+	} elsif (($line =~ /^-{3,}$/) || ($line =~ /^\.{3,}$/)) {
+		if ($in_section) {
+			if ($line eq $section_header) {
+				$in_section = 0;
+			}
+		next;
+		}
+		if ($line_length == 0) {
+			$in_section = 1;
+			$section_header = $line;
+			next;
+		}
+		if (($line_length != 0) && (length($line) != $line_length)) {
+			report("section delimiter not preceded by an empty line");
+		}
+		$line_length = 0;
+	}
+}
+
+if ($in_section) {
+	report("section not finished");
+}
+
+exit $exit_code;
diff --git a/Documentation/lint-documentation-style.perl b/Documentation/lint-documentation-style.perl
new file mode 100755
index 0000000000..d7ab732293
--- /dev/null
+++ b/Documentation/lint-documentation-style.perl
@@ -0,0 +1,33 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+my $exit_code = 0;
+sub report {
+	my ($line, $msg) = @_;
+	chomp $line;
+	print STDERR "$ARGV:$.: '$line' $msg\n";
+	$exit_code = 1;
+}
+
+my $synopsis_style = 0;
+
+while (my $line = <>) {
+	if ($line =~ /^[ \t]*`?[-a-z0-9.]+`?(, `?[-a-z0-9.]+`?)+(::|;;)$/) {
+
+		report($line, "multiple parameters in a definition list item");
+	}
+	if ($line =~ /^`?--\[no-\][a-z0-9-]+.*(::|;;)$/) {
+		report($line, "definition list item with a `--[no-]` parameter");
+	}
+	if ($line =~ /^\[synopsis\]$/) {
+		$synopsis_style = 1;
+	}
+	if (($line =~ /^(-[-a-z].*|<[-a-z0-9]+>(\.{3})?)(::|;;)$/) && ($synopsis_style)) {
+			report($line, "synopsis style and definition list item not backquoted");
+	}
+}
+
+
+exit $exit_code;
diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
index 1c61dd9512..f183a18df2 100755
--- a/Documentation/lint-gitlink.perl
+++ b/Documentation/lint-gitlink.perl
@@ -5,7 +5,7 @@ use warnings;
 
 # Parse arguments, a simple state machine for input like:
 #
-# <file-to-check.txt> <valid-files-to-link-to> --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]
+# <file-to-check.adoc> <valid-files-to-link-to> --section=1 git.adoc git-add.adoc [...] --to-lint git-add.adoc a-file.adoc [...]
 my %TXT;
 my %SECTION;
 my $section;
@@ -17,7 +17,7 @@ for my $arg (@ARGV) {
 		next;
 	}
 
-	my ($name) = $arg =~ /^(.*?)\.txt$/s;
+	my ($name) = $arg =~ /^(.*?)\.adoc$/s;
 	unless (defined $section) {
 		$TXT{$name} = $arg;
 		next;
@@ -41,6 +41,13 @@ die "BUG: No list of valid linkgit:* files given" unless @ARGV;
 @ARGV = $to_check;
 while (<>) {
 	my $line = $_;
+	while ($line =~ m/(.{,8})((git[-a-z]+|scalar)\[(\d)*\])/g) {
+	    my $pos = pos $line;
+	    my ($macro, $target, $page, $section) = ($1, $2, $3, $4);
+		if ( $macro ne "linkgit:" && $macro !~ "ifn?def::" && $macro ne "endif::" ) {
+			report($pos, $line, $target, "linkgit: macro expected");
+		}
+	}
 	while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) {
 		my $pos = pos $line;
 		my ($target, $page, $section) = ($1, $2, $3);
diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh
index 92cfc0a15a..a0ea572382 100755
--- a/Documentation/lint-manpages.sh
+++ b/Documentation/lint-manpages.sh
@@ -31,7 +31,7 @@ check_missing_docs () (
 		git-?*--?* ) continue ;;
 		esac
 
-		if ! test -f "$v.txt"
+		if ! test -f "$v.adoc"
 		then
 			echo "no doc: $v"
 			ret=1
@@ -63,9 +63,9 @@ check_extraneous_docs () {
 		    -e 's/[ 	].*//' \
 		    -e 's/^/listed /' ../command-list.txt
 		make print-man1 |
-		grep '\.txt$' |
+		grep '\.adoc$' |
 		sed -e 's|^|documented |' \
-		    -e 's/\.txt//'
+		    -e 's/\.adoc//'
 	) | (
 		all_commands="$(printf "%s " "$ALL_COMMANDS" "$BUILT_INS" "$EXCLUDED_PROGRAMS" | tr '\n' ' ')"
 		ret=0
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.adoc
index 3eaefc4e94..9d433265b2 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.adoc
@@ -1,23 +1,23 @@
---commit::
---no-commit::
+`--commit`::
+`--no-commit`::
 	Perform the merge and commit the result. This option can
-	be used to override --no-commit.
+	be used to override `--no-commit`.
 ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 +
-With --no-commit perform the merge and stop just before creating
+With `--no-commit` perform the merge and stop just before creating
 a merge commit, to give the user a chance to inspect and further
 tweak the merge result before committing.
 +
 Note that fast-forward updates do not create a merge commit and
-therefore there is no way to stop those merges with --no-commit.
+therefore there is no way to stop those merges with `--no-commit`.
 Thus, if you want to ensure your branch is not changed or updated
-by the merge command, use --no-ff with --no-commit.
+by the merge command, use `--no-ff` with `--no-commit`.
 
---edit::
--e::
---no-edit::
+`--edit`::
+`-e`::
+`--no-edit`::
 	Invoke an editor before committing successful mechanical merge to
 	further edit the auto-generated merge message, so that the user
 	can explain and justify the merge. The `--no-edit` option can be
@@ -35,17 +35,17 @@ they run `git merge`. To make it easier to adjust such scripts to the
 updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be
 set to `no` at the beginning of them.
 
---cleanup=<mode>::
+`--cleanup=<mode>`::
 	This option determines how the merge message will be cleaned up before
 	committing. See linkgit:git-commit[1] for more details. In addition, if
-	the '<mode>' is given a value of `scissors`, scissors will be appended
+	the _<mode>_ is given a value of `scissors`, scissors will be appended
 	to `MERGE_MSG` before being passed on to the commit machinery in the
 	case of a merge conflict.
 
 ifdef::git-merge[]
---ff::
---no-ff::
---ff-only::
+`--ff`::
+`--no-ff`::
+`--ff-only`::
 	Specifies how a merge is handled when the merged-in history is
 	already a descendant of the current history.  `--ff` is the
 	default unless merging an annotated (and possibly signed) tag
@@ -53,13 +53,13 @@ ifdef::git-merge[]
 	hierarchy, in which case `--no-ff` is assumed.
 endif::git-merge[]
 ifdef::git-pull[]
---ff-only::
+`--ff-only`::
 	Only update to the new history if there is no divergent local
 	history.  This is the default when no method for reconciling
 	divergent histories is provided (via the --rebase=* flags).
 
---ff::
---no-ff::
+`--ff`::
+`--no-ff`::
 	When merging rather than rebasing, specifies how a merge is
 	handled when the merged-in history is already a descendant of
 	the current history.  If merging is requested, `--ff` is the
@@ -81,40 +81,43 @@ With `--ff-only`, resolve the merge as a fast-forward when possible.
 When not possible, refuse to merge and exit with a non-zero status.
 endif::git-merge[]
 
--S[<keyid>]::
---gpg-sign[=<keyid>]::
---no-gpg-sign::
-	GPG-sign the resulting merge commit. The `keyid` argument is
+`-S[<key-id>]`::
+`--gpg-sign[=<key-id>]`::
+`--no-gpg-sign`::
+	GPG-sign the resulting merge commit. The _<key-id>_ argument is
 	optional and defaults to the committer identity; if specified,
 	it must be stuck to the option without a space. `--no-gpg-sign`
 	is useful to countermand both `commit.gpgSign` configuration variable,
 	and earlier `--gpg-sign`.
 
---log[=<n>]::
---no-log::
+`--log[=<n>]`::
+`--no-log`::
 	In addition to branch names, populate the log message with
-	one-line descriptions from at most <n> actual commits that are being
+	one-line descriptions from at most _<n>_ actual commits that are being
 	merged. See also linkgit:git-fmt-merge-msg[1].
 ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 +
-With --no-log do not list one-line descriptions from the
+With `--no-log` do not list one-line descriptions from the
 actual commits being merged.
 
-include::signoff-option.txt[]
+include::signoff-option.adoc[]
 
---stat::
--n::
---no-stat::
+`--stat`::
+`-n`::
+`--no-stat`::
 	Show a diffstat at the end of the merge. The diffstat is also
 	controlled by the configuration option merge.stat.
 +
-With -n or --no-stat do not show a diffstat at the end of the
+With `-n` or `--no-stat` do not show a diffstat at the end of the
 merge.
 
---squash::
---no-squash::
+`--compact-summary`::
+	Show a compact-summary at the end of the merge.
+
+`--squash`::
+`--no-squash`::
 	Produce the working tree and index state as if a real merge
 	happened (except for the merge information), but do not actually
 	make a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD`
@@ -123,16 +126,17 @@ merge.
 	the current branch whose effect is the same as merging another
 	branch (or more in case of an octopus).
 +
-With --no-squash perform the merge and commit the result. This
-option can be used to override --squash.
+With `--no-squash` perform the merge and commit the result. This
+option can be used to override `--squash`.
 +
-With --squash, --commit is not allowed, and will fail.
+With `--squash`, `--commit` is not allowed, and will fail.
 ifdef::git-pull[]
 +
 Only useful when merging.
 endif::git-pull[]
 
---[no-]verify::
+`--verify`::
+`--no-verify`::
 	By default, the pre-merge and commit-msg hooks are run.
 	When `--no-verify` is given, these are bypassed.
 	See also linkgit:githooks[5].
@@ -140,21 +144,21 @@ ifdef::git-pull[]
 	Only useful when merging.
 endif::git-pull[]
 
--s <strategy>::
---strategy=<strategy>::
+`-s <strategy>`::
+`--strategy=<strategy>`::
 	Use the given merge strategy; can be supplied more than
 	once to specify them in the order they should be tried.
 	If there is no `-s` option, a built-in list of strategies
 	is used instead (`ort` when merging a single head,
 	`octopus` otherwise).
 
--X <option>::
---strategy-option=<option>::
+`-X <option>`::
+`--strategy-option=<option>`::
 	Pass merge strategy specific option through to the merge
 	strategy.
 
---verify-signatures::
---no-verify-signatures::
+`--verify-signatures`::
+`--no-verify-signatures`::
 	Verify that the tip commit of the side branch being merged is
 	signed with a valid key, i.e. a key that has a valid uid: in the
 	default trust model, this means the signing key has been signed by
@@ -165,22 +169,22 @@ ifdef::git-pull[]
 Only useful when merging.
 endif::git-pull[]
 
---summary::
---no-summary::
-	Synonyms to --stat and --no-stat; these are deprecated and will be
+`--summary`::
+`--no-summary`::
+	Synonyms to `--stat` and `--no-stat`; these are deprecated and will be
 	removed in the future.
 
 ifndef::git-pull[]
--q::
---quiet::
-	Operate quietly. Implies --no-progress.
+`-q`::
+`--quiet`::
+	Operate quietly. Implies `--no-progress`.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Be verbose.
 
---progress::
---no-progress::
+`--progress`::
+`--no-progress`::
 	Turn progress on/off explicitly. If neither is specified,
 	progress is shown if standard error is connected to a terminal.
 	Note that not all merge strategies may support progress
@@ -188,8 +192,8 @@ ifndef::git-pull[]
 
 endif::git-pull[]
 
---autostash::
---no-autostash::
+`--autostash`::
+`--no-autostash`::
 	Automatically create a temporary stash entry before the operation
 	begins, record it in the ref `MERGE_AUTOSTASH`
 	and apply it after the operation ends.  This means
@@ -197,13 +201,13 @@ endif::git-pull[]
 	with care: the final stash application after a successful
 	merge might result in non-trivial conflicts.
 
---allow-unrelated-histories::
+`--allow-unrelated-histories`::
 	By default, `git merge` command refuses to merge histories
 	that do not share a common ancestor.  This option can be
 	used to override this safety when merging histories of two
 	projects that started their lives independently. As that is
 	a very rare occasion, no configuration variable to enable
-	this by default exists and will not be added.
+	this by default exists or will be added.
 ifdef::git-pull[]
 +
 Only useful when merging.
diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.adoc
index 5fc54ec060..2ba43f84e7 100644
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.adoc
@@ -6,7 +6,7 @@ backend 'merge strategies' to be chosen with `-s` option.  Some strategies
 can also take their own options, which can be passed by giving `-X<option>`
 arguments to `git merge` and/or `git pull`.
 
-ort::
+`ort`::
 	This is the default merge strategy when pulling or merging one
 	branch.  This strategy can only resolve two heads using a
 	3-way merge algorithm.  When there is more than one common
@@ -22,26 +22,33 @@ ort::
 	was written as a replacement for the previous default
 	algorithm, `recursive`.
 +
-The 'ort' strategy can take the following options:
+In the case where the path is a submodule, if the submodule commit used on
+one side of the merge is a descendant of the submodule commit used on the
+other side of the merge, Git attempts to fast-forward to the
+descendant. Otherwise, Git will treat this case as a conflict, suggesting
+as a resolution a submodule commit that is descendant of the conflicting
+ones, if one exists.
++
+The `ort` strategy can take the following options:
 
-ours;;
+`ours`;;
 	This option forces conflicting hunks to be auto-resolved cleanly by
 	favoring 'our' version.  Changes from the other tree that do not
 	conflict with our side are reflected in the merge result.
 	For a binary file, the entire contents are taken from our side.
 +
-This should not be confused with the 'ours' merge strategy, which does not
+This should not be confused with the `ours` merge strategy, which does not
 even look at what the other tree contains at all.  It discards everything
 the other tree did, declaring 'our' history contains all that happened in it.
 
-theirs;;
-	This is the opposite of 'ours'; note that, unlike 'ours', there is
-	no 'theirs' merge strategy to confuse this merge option with.
+`theirs`;;
+	This is the opposite of `ours`; note that, unlike `ours`, there is
+	no `theirs` merge strategy to confuse this merge option with.
 
-ignore-space-change;;
-ignore-all-space;;
-ignore-space-at-eol;;
-ignore-cr-at-eol;;
+`ignore-space-change`;;
+`ignore-all-space`;;
+`ignore-space-at-eol`;;
+`ignore-cr-at-eol`;;
 	Treats lines with the indicated type of whitespace change as
 	unchanged for the sake of a three-way merge.  Whitespace
 	changes mixed with other changes to a line are not ignored.
@@ -54,97 +61,89 @@ ignore-cr-at-eol;;
   version includes a substantial change, 'their' version is used;
 * Otherwise, the merge proceeds in the usual way.
 
-renormalize;;
+`renormalize`;;
 	This runs a virtual check-out and check-in of all three stages
-	of a file when resolving a three-way merge.  This option is
+	of any file which needs a three-way merge.  This option is
 	meant to be used when merging branches with different clean
 	filters or end-of-line normalization rules.  See "Merging
 	branches with differing checkin/checkout attributes" in
 	linkgit:gitattributes[5] for details.
 
-no-renormalize;;
+`no-renormalize`;;
 	Disables the `renormalize` option.  This overrides the
 	`merge.renormalize` configuration variable.
 
-find-renames[=<n>];;
+`find-renames[=<n>]`;;
 	Turn on rename detection, optionally setting the similarity
 	threshold.  This is the default. This overrides the
-	'merge.renames' configuration variable.
+	`merge.renames` configuration variable.
 	See also linkgit:git-diff[1] `--find-renames`.
 
-rename-threshold=<n>;;
+`rename-threshold=<n>`;;
 	Deprecated synonym for `find-renames=<n>`.
 
-subtree[=<path>];;
-	This option is a more advanced form of 'subtree' strategy, where
-	the strategy makes a guess on how two trees must be shifted to
-	match with each other when merging.  Instead, the specified path
-	is prefixed (or stripped from the beginning) to make the shape of
-	two trees to match.
+`no-renames`;;
+	Turn off rename detection. This overrides the `merge.renames`
+	configuration variable.
+	See also linkgit:git-diff[1] `--no-renames`.
 
-recursive::
-	This can only resolve two heads using a 3-way merge
-	algorithm.  When there is more than one common
-	ancestor that can be used for 3-way merge, it creates a
-	merged tree of the common ancestors and uses that as
-	the reference tree for the 3-way merge.  This has been
-	reported to result in fewer merge conflicts without
-	causing mismerges by tests done on actual merge commits
-	taken from Linux 2.6 kernel development history.
-	Additionally this can detect and handle merges involving
-	renames.  It does not make use of detected copies.  This was
-	the default strategy for resolving two heads from Git v0.99.9k
-	until v2.33.0.
-+
-The 'recursive' strategy takes the same options as 'ort'.  However,
-there are three additional options that 'ort' ignores (not documented
-above) that are potentially useful with the 'recursive' strategy:
+`histogram`;;
+	Deprecated synonym for `diff-algorithm=histogram`.
 
-patience;;
+`patience`;;
 	Deprecated synonym for `diff-algorithm=patience`.
 
-diff-algorithm=[patience|minimal|histogram|myers];;
+`diff-algorithm=(histogram|minimal|myers|patience)`;;
 	Use a different diff algorithm while merging, which can help
 	avoid mismerges that occur due to unimportant matching lines
 	(such as braces from distinct functions).  See also
 	linkgit:git-diff[1] `--diff-algorithm`.  Note that `ort`
-	specifically uses `diff-algorithm=histogram`, while `recursive`
-	defaults to the `diff.algorithm` config setting.
+	defaults to `diff-algorithm=histogram`, while regular diffs
+	currently default to the `diff.algorithm` config setting.
 
-no-renames;;
-	Turn off rename detection. This overrides the `merge.renames`
-	configuration variable.
-	See also linkgit:git-diff[1] `--no-renames`.
+`subtree[=<path>]`;;
+	This option is a more advanced form of 'subtree' strategy, where
+	the strategy makes a guess on how two trees must be shifted to
+	match with each other when merging.  Instead, the specified path
+	is prefixed (or stripped from the beginning) to make the shape of
+	two trees to match.
+
+`recursive`::
+	This is now a synonym for `ort`.  It was an alternative
+	implementation until v2.49.0, but was redirected to mean `ort`
+	in v2.50.0.  The previous recursive strategy was the default
+	strategy for resolving two heads from Git v0.99.9k until
+	v2.33.0.
 
-resolve::
+`resolve`::
 	This can only resolve two heads (i.e. the current branch
 	and another branch you pulled from) using a 3-way merge
 	algorithm.  It tries to carefully detect criss-cross
 	merge ambiguities.  It does not handle renames.
 
-octopus::
+`octopus`::
 	This resolves cases with more than two heads, but refuses to do
 	a complex merge that needs manual resolution.  It is
 	primarily meant to be used for bundling topic branch
 	heads together.  This is the default merge strategy when
 	pulling or merging more than one branch.
 
-ours::
+`ours`::
 	This resolves any number of heads, but the resulting tree of the
 	merge is always that of the current branch head, effectively
 	ignoring all changes from all other branches.  It is meant to
 	be used to supersede old development history of side
-	branches.  Note that this is different from the -Xours option to
-	the 'recursive' merge strategy.
+	branches.  Note that this is different from the `-Xours` option to
+	the `ort` merge strategy.
 
-subtree::
+`subtree`::
 	This is a modified `ort` strategy. When merging trees A and
 	B, if B corresponds to a subtree of A, B is first adjusted to
 	match the tree structure of A, instead of reading the trees at
 	the same level. This adjustment is also done to the common
 	ancestor tree.
 
-With the strategies that use 3-way merge (including the default, 'ort'),
+With the strategies that use 3-way merge (including the default, `ort`),
 if a change is made on both branches, but later reverted on one of the
 branches, that change will be present in the merged result; some people find
 this behavior confusing.  It occurs because only the heads and the merge base
diff --git a/Documentation/mergetools/vimdiff.txt b/Documentation/mergetools/vimdiff.adoc
index befa86d692..b4ab83a510 100644
--- a/Documentation/mergetools/vimdiff.txt
+++ b/Documentation/mergetools/vimdiff.adoc
@@ -3,6 +3,7 @@ Description
 
 When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4
 windows layout distributed in the following way:
+
 ....
 ------------------------------------------
 |             |           |              |
@@ -56,6 +57,7 @@ needed in this case. The next layout definition is equivalent:
 +
 --
 If, for some reason, we are not interested in the `BASE` buffer.
+
 ....
 ------------------------------------------
 |             |           |              |
@@ -72,6 +74,7 @@ If, for some reason, we are not interested in the `BASE` buffer.
 Only the `MERGED` buffer will be shown. Note, however, that all the other
 ones are still loaded in vim, and you can access them with the "buffers"
 command.
+
 ....
 ------------------------------------------
 |                                        |
@@ -86,8 +89,9 @@ command.
 +
 --
 When `MERGED` is not present in the layout, you must "mark" one of the
-buffers with an asterisk. That will become the buffer you need to edit and
+buffers with an arobase (`@`). That will become the buffer you need to edit and
 save after resolving the conflicts.
+
 ....
 ------------------------------------------
 |                   |                    |
@@ -106,6 +110,7 @@ save after resolving the conflicts.
 Three tabs will open: the first one is a copy of the default layout, while
 the other two only show the differences between (`BASE` and `LOCAL`) and
 (`BASE` and `REMOTE`) respectively.
+
 ....
 ------------------------------------------
 | <TAB #1> |  TAB #2  |  TAB #3  |       |
@@ -119,6 +124,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and
 |                                        |
 ------------------------------------------
 ....
+
 ....
 ------------------------------------------
 |  TAB #1  | <TAB #2> |  TAB #3  |       |
@@ -132,6 +138,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and
 |                   |                    |
 ------------------------------------------
 ....
+
 ....
 ------------------------------------------
 |  TAB #1  |  TAB #2  | <TAB #3> |       |
@@ -151,6 +158,7 @@ the other two only show the differences between (`BASE` and `LOCAL`) and
 --
 Same as the previous example, but adds a fourth tab with the same
 information as the first tab, with a different layout.
+
 ....
 ---------------------------------------------
 |  TAB #1  |  TAB #2  |  TAB #3  | <TAB #4> |
@@ -183,13 +191,13 @@ latter will be used as fallback if the variant-specific one is not set).
 In addition, for backwards compatibility with previous Git versions, you can
 also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex:
 `vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout.
-In other words, using `--tool=[g,n,]vimdiffx` is the same as using
-`--tool=[g,n,]vimdiff` and setting configuration variable
-`mergetool.[g,n,]vimdiff.layout` to...
+In other words, using `--tool=[g|n]vimdiff<x>` is the same as using
+`--tool=[g|n]vimdiff` and setting configuration variable
+`mergetool.[g|n]vimdiff.layout` to...
 
-  * `x=1`: `"@LOCAL, REMOTE"`
-  * `x=2`: `"LOCAL, MERGED, REMOTE"`
-  * `x=3`: `"MERGED"`
+  * `<x>=1`: `"@LOCAL, REMOTE"`
+  * `<x>=2`: `"LOCAL, MERGED, REMOTE"`
+  * `<x>=3`: `"MERGED"`
 
-Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL,
-MERGED and REMOTE).
+Example: using `--tool=gvimdiff2` will open `gvim` with three columns (`LOCAL`,
+`MERGED` and `REMOTE`).
diff --git a/Documentation/meson.build b/Documentation/meson.build
index 2a26fa8a5f..9d24f2da54 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -1,214 +1,226 @@
 manpages = {
   # Category 1.
-  'git-add.txt' : 1,
-  'git-am.txt' : 1,
-  'git-annotate.txt' : 1,
-  'git-apply.txt' : 1,
-  'git-archimport.txt' : 1,
-  'git-archive.txt' : 1,
-  'git-bisect.txt' : 1,
-  'git-blame.txt' : 1,
-  'git-branch.txt' : 1,
-  'git-bugreport.txt' : 1,
-  'git-bundle.txt' : 1,
-  'git-cat-file.txt' : 1,
-  'git-check-attr.txt' : 1,
-  'git-check-ignore.txt' : 1,
-  'git-check-mailmap.txt' : 1,
-  'git-checkout-index.txt' : 1,
-  'git-checkout.txt' : 1,
-  'git-check-ref-format.txt' : 1,
-  'git-cherry-pick.txt' : 1,
-  'git-cherry.txt' : 1,
-  'git-citool.txt' : 1,
-  'git-clean.txt' : 1,
-  'git-clone.txt' : 1,
-  'git-column.txt' : 1,
-  'git-commit-graph.txt' : 1,
-  'git-commit-tree.txt' : 1,
-  'git-commit.txt' : 1,
-  'git-config.txt' : 1,
-  'git-count-objects.txt' : 1,
-  'git-credential-cache--daemon.txt' : 1,
-  'git-credential-cache.txt' : 1,
-  'git-credential-store.txt' : 1,
-  'git-credential.txt' : 1,
-  'git-cvsexportcommit.txt' : 1,
-  'git-cvsimport.txt' : 1,
-  'git-cvsserver.txt' : 1,
-  'git-daemon.txt' : 1,
-  'git-describe.txt' : 1,
-  'git-diagnose.txt' : 1,
-  'git-diff-files.txt' : 1,
-  'git-diff-index.txt' : 1,
-  'git-difftool.txt' : 1,
-  'git-diff-tree.txt' : 1,
-  'git-diff.txt' : 1,
-  'git-fast-export.txt' : 1,
-  'git-fast-import.txt' : 1,
-  'git-fetch-pack.txt' : 1,
-  'git-fetch.txt' : 1,
-  'git-filter-branch.txt' : 1,
-  'git-fmt-merge-msg.txt' : 1,
-  'git-for-each-ref.txt' : 1,
-  'git-for-each-repo.txt' : 1,
-  'git-format-patch.txt' : 1,
-  'git-fsck-objects.txt' : 1,
-  'git-fsck.txt' : 1,
-  'git-fsmonitor--daemon.txt' : 1,
-  'git-gc.txt' : 1,
-  'git-get-tar-commit-id.txt' : 1,
-  'git-grep.txt' : 1,
-  'git-gui.txt' : 1,
-  'git-hash-object.txt' : 1,
-  'git-help.txt' : 1,
-  'git-hook.txt' : 1,
-  'git-http-backend.txt' : 1,
-  'git-http-fetch.txt' : 1,
-  'git-http-push.txt' : 1,
-  'git-imap-send.txt' : 1,
-  'git-index-pack.txt' : 1,
-  'git-init-db.txt' : 1,
-  'git-init.txt' : 1,
-  'git-instaweb.txt' : 1,
-  'git-interpret-trailers.txt' : 1,
-  'git-log.txt' : 1,
-  'git-ls-files.txt' : 1,
-  'git-ls-remote.txt' : 1,
-  'git-ls-tree.txt' : 1,
-  'git-mailinfo.txt' : 1,
-  'git-mailsplit.txt' : 1,
-  'git-maintenance.txt' : 1,
-  'git-merge-base.txt' : 1,
-  'git-merge-file.txt' : 1,
-  'git-merge-index.txt' : 1,
-  'git-merge-one-file.txt' : 1,
-  'git-mergetool--lib.txt' : 1,
-  'git-mergetool.txt' : 1,
-  'git-merge-tree.txt' : 1,
-  'git-merge.txt' : 1,
-  'git-mktag.txt' : 1,
-  'git-mktree.txt' : 1,
-  'git-multi-pack-index.txt' : 1,
-  'git-mv.txt' : 1,
-  'git-name-rev.txt' : 1,
-  'git-notes.txt' : 1,
-  'git-p4.txt' : 1,
-  'git-pack-objects.txt' : 1,
-  'git-pack-redundant.txt' : 1,
-  'git-pack-refs.txt' : 1,
-  'git-patch-id.txt' : 1,
-  'git-prune-packed.txt' : 1,
-  'git-prune.txt' : 1,
-  'git-pull.txt' : 1,
-  'git-push.txt' : 1,
-  'git-quiltimport.txt' : 1,
-  'git-range-diff.txt' : 1,
-  'git-read-tree.txt' : 1,
-  'git-rebase.txt' : 1,
-  'git-receive-pack.txt' : 1,
-  'git-reflog.txt' : 1,
-  'git-refs.txt' : 1,
-  'git-remote-ext.txt' : 1,
-  'git-remote-fd.txt' : 1,
-  'git-remote.txt' : 1,
-  'git-repack.txt' : 1,
-  'git-replace.txt' : 1,
-  'git-replay.txt' : 1,
-  'git-request-pull.txt' : 1,
-  'git-rerere.txt' : 1,
-  'git-reset.txt' : 1,
-  'git-restore.txt' : 1,
-  'git-revert.txt' : 1,
-  'git-rev-list.txt' : 1,
-  'git-rev-parse.txt' : 1,
-  'git-rm.txt' : 1,
-  'git-send-email.txt' : 1,
-  'git-send-pack.txt' : 1,
-  'git-shell.txt' : 1,
-  'git-sh-i18n--envsubst.txt' : 1,
-  'git-sh-i18n.txt' : 1,
-  'git-shortlog.txt' : 1,
-  'git-show-branch.txt' : 1,
-  'git-show-index.txt' : 1,
-  'git-show-ref.txt' : 1,
-  'git-show.txt' : 1,
-  'git-sh-setup.txt' : 1,
-  'git-sparse-checkout.txt' : 1,
-  'git-stage.txt' : 1,
-  'git-stash.txt' : 1,
-  'git-status.txt' : 1,
-  'git-stripspace.txt' : 1,
-  'git-submodule.txt' : 1,
-  'git-svn.txt' : 1,
-  'git-switch.txt' : 1,
-  'git-symbolic-ref.txt' : 1,
-  'git-tag.txt' : 1,
-  'git-unpack-file.txt' : 1,
-  'git-unpack-objects.txt' : 1,
-  'git-update-index.txt' : 1,
-  'git-update-ref.txt' : 1,
-  'git-update-server-info.txt' : 1,
-  'git-upload-archive.txt' : 1,
-  'git-upload-pack.txt' : 1,
-  'git-var.txt' : 1,
-  'git-verify-commit.txt' : 1,
-  'git-verify-pack.txt' : 1,
-  'git-verify-tag.txt' : 1,
-  'git-version.txt' : 1,
-  'git-web--browse.txt' : 1,
-  'git-whatchanged.txt' : 1,
-  'git-worktree.txt' : 1,
-  'git-write-tree.txt' : 1,
-  'git.txt' : 1,
-  'gitk.txt' : 1,
-  'gitweb.txt' : 1,
-  'scalar.txt' : 1,
+  'git-add.adoc' : 1,
+  'git-am.adoc' : 1,
+  'git-annotate.adoc' : 1,
+  'git-apply.adoc' : 1,
+  'git-archimport.adoc' : 1,
+  'git-archive.adoc' : 1,
+  'git-backfill.adoc' : 1,
+  'git-bisect.adoc' : 1,
+  'git-blame.adoc' : 1,
+  'git-branch.adoc' : 1,
+  'git-bugreport.adoc' : 1,
+  'git-bundle.adoc' : 1,
+  'git-cat-file.adoc' : 1,
+  'git-check-attr.adoc' : 1,
+  'git-check-ignore.adoc' : 1,
+  'git-check-mailmap.adoc' : 1,
+  'git-checkout-index.adoc' : 1,
+  'git-checkout.adoc' : 1,
+  'git-check-ref-format.adoc' : 1,
+  'git-cherry-pick.adoc' : 1,
+  'git-cherry.adoc' : 1,
+  'git-citool.adoc' : 1,
+  'git-clean.adoc' : 1,
+  'git-clone.adoc' : 1,
+  'git-column.adoc' : 1,
+  'git-commit-graph.adoc' : 1,
+  'git-commit-tree.adoc' : 1,
+  'git-commit.adoc' : 1,
+  'git-config.adoc' : 1,
+  'git-count-objects.adoc' : 1,
+  'git-credential-cache--daemon.adoc' : 1,
+  'git-credential-cache.adoc' : 1,
+  'git-credential-store.adoc' : 1,
+  'git-credential.adoc' : 1,
+  'git-cvsexportcommit.adoc' : 1,
+  'git-cvsimport.adoc' : 1,
+  'git-cvsserver.adoc' : 1,
+  'git-daemon.adoc' : 1,
+  'git-describe.adoc' : 1,
+  'git-diagnose.adoc' : 1,
+  'git-diff-files.adoc' : 1,
+  'git-diff-index.adoc' : 1,
+  'git-diff-pairs.adoc' : 1,
+  'git-difftool.adoc' : 1,
+  'git-diff-tree.adoc' : 1,
+  'git-diff.adoc' : 1,
+  'git-fast-export.adoc' : 1,
+  'git-fast-import.adoc' : 1,
+  'git-fetch-pack.adoc' : 1,
+  'git-fetch.adoc' : 1,
+  'git-filter-branch.adoc' : 1,
+  'git-fmt-merge-msg.adoc' : 1,
+  'git-for-each-ref.adoc' : 1,
+  'git-for-each-repo.adoc' : 1,
+  'git-format-patch.adoc' : 1,
+  'git-fsck-objects.adoc' : 1,
+  'git-fsck.adoc' : 1,
+  'git-fsmonitor--daemon.adoc' : 1,
+  'git-gc.adoc' : 1,
+  'git-get-tar-commit-id.adoc' : 1,
+  'git-grep.adoc' : 1,
+  'git-gui.adoc' : 1,
+  'git-hash-object.adoc' : 1,
+  'git-help.adoc' : 1,
+  'git-hook.adoc' : 1,
+  'git-http-backend.adoc' : 1,
+  'git-http-fetch.adoc' : 1,
+  'git-http-push.adoc' : 1,
+  'git-imap-send.adoc' : 1,
+  'git-index-pack.adoc' : 1,
+  'git-init-db.adoc' : 1,
+  'git-init.adoc' : 1,
+  'git-instaweb.adoc' : 1,
+  'git-interpret-trailers.adoc' : 1,
+  'git-last-modified.adoc' : 1,
+  'git-log.adoc' : 1,
+  'git-ls-files.adoc' : 1,
+  'git-ls-remote.adoc' : 1,
+  'git-ls-tree.adoc' : 1,
+  'git-mailinfo.adoc' : 1,
+  'git-mailsplit.adoc' : 1,
+  'git-maintenance.adoc' : 1,
+  'git-merge-base.adoc' : 1,
+  'git-merge-file.adoc' : 1,
+  'git-merge-index.adoc' : 1,
+  'git-merge-one-file.adoc' : 1,
+  'git-mergetool--lib.adoc' : 1,
+  'git-mergetool.adoc' : 1,
+  'git-merge-tree.adoc' : 1,
+  'git-merge.adoc' : 1,
+  'git-mktag.adoc' : 1,
+  'git-mktree.adoc' : 1,
+  'git-multi-pack-index.adoc' : 1,
+  'git-mv.adoc' : 1,
+  'git-name-rev.adoc' : 1,
+  'git-notes.adoc' : 1,
+  'git-p4.adoc' : 1,
+  'git-pack-objects.adoc' : 1,
+  'git-pack-refs.adoc' : 1,
+  'git-patch-id.adoc' : 1,
+  'git-prune-packed.adoc' : 1,
+  'git-prune.adoc' : 1,
+  'git-pull.adoc' : 1,
+  'git-push.adoc' : 1,
+  'git-quiltimport.adoc' : 1,
+  'git-range-diff.adoc' : 1,
+  'git-read-tree.adoc' : 1,
+  'git-rebase.adoc' : 1,
+  'git-receive-pack.adoc' : 1,
+  'git-reflog.adoc' : 1,
+  'git-refs.adoc' : 1,
+  'git-remote-ext.adoc' : 1,
+  'git-remote-fd.adoc' : 1,
+  'git-remote.adoc' : 1,
+  'git-repack.adoc' : 1,
+  'git-replace.adoc' : 1,
+  'git-replay.adoc' : 1,
+  'git-repo.adoc' : 1,
+  'git-request-pull.adoc' : 1,
+  'git-rerere.adoc' : 1,
+  'git-reset.adoc' : 1,
+  'git-restore.adoc' : 1,
+  'git-revert.adoc' : 1,
+  'git-rev-list.adoc' : 1,
+  'git-rev-parse.adoc' : 1,
+  'git-rm.adoc' : 1,
+  'git-send-email.adoc' : 1,
+  'git-send-pack.adoc' : 1,
+  'git-shell.adoc' : 1,
+  'git-sh-i18n--envsubst.adoc' : 1,
+  'git-sh-i18n.adoc' : 1,
+  'git-shortlog.adoc' : 1,
+  'git-show-branch.adoc' : 1,
+  'git-show-index.adoc' : 1,
+  'git-show-ref.adoc' : 1,
+  'git-show.adoc' : 1,
+  'git-sh-setup.adoc' : 1,
+  'git-sparse-checkout.adoc' : 1,
+  'git-stage.adoc' : 1,
+  'git-stash.adoc' : 1,
+  'git-status.adoc' : 1,
+  'git-stripspace.adoc' : 1,
+  'git-submodule.adoc' : 1,
+  'git-svn.adoc' : 1,
+  'git-switch.adoc' : 1,
+  'git-symbolic-ref.adoc' : 1,
+  'git-tag.adoc' : 1,
+  'git-unpack-file.adoc' : 1,
+  'git-unpack-objects.adoc' : 1,
+  'git-update-index.adoc' : 1,
+  'git-update-ref.adoc' : 1,
+  'git-update-server-info.adoc' : 1,
+  'git-upload-archive.adoc' : 1,
+  'git-upload-pack.adoc' : 1,
+  'git-var.adoc' : 1,
+  'git-verify-commit.adoc' : 1,
+  'git-verify-pack.adoc' : 1,
+  'git-verify-tag.adoc' : 1,
+  'git-version.adoc' : 1,
+  'git-web--browse.adoc' : 1,
+  'git-worktree.adoc' : 1,
+  'git-write-tree.adoc' : 1,
+  'git.adoc' : 1,
+  'gitk.adoc' : 1,
+  'gitweb.adoc' : 1,
+  'scalar.adoc' : 1,
 
   # Category 5.
-  'gitattributes.txt' : 5,
-  'gitformat-bundle.txt' : 5,
-  'gitformat-chunk.txt' : 5,
-  'gitformat-commit-graph.txt' : 5,
-  'gitformat-index.txt' : 5,
-  'gitformat-pack.txt' : 5,
-  'gitformat-signature.txt' : 5,
-  'githooks.txt' : 5,
-  'gitignore.txt' : 5,
-  'gitmailmap.txt' : 5,
-  'gitmodules.txt' : 5,
-  'gitprotocol-capabilities.txt' : 5,
-  'gitprotocol-common.txt' : 5,
-  'gitprotocol-http.txt' : 5,
-  'gitprotocol-pack.txt' : 5,
-  'gitprotocol-v2.txt' : 5,
-  'gitrepository-layout.txt' : 5,
-  'gitweb.conf.txt' : 5,
+  'gitattributes.adoc' : 5,
+  'gitformat-bundle.adoc' : 5,
+  'gitformat-chunk.adoc' : 5,
+  'gitformat-commit-graph.adoc' : 5,
+  'gitformat-index.adoc' : 5,
+  'gitformat-loose.adoc' : 5,
+  'gitformat-pack.adoc' : 5,
+  'gitformat-signature.adoc' : 5,
+  'githooks.adoc' : 5,
+  'gitignore.adoc' : 5,
+  'gitmailmap.adoc' : 5,
+  'gitmodules.adoc' : 5,
+  'gitprotocol-capabilities.adoc' : 5,
+  'gitprotocol-common.adoc' : 5,
+  'gitprotocol-http.adoc' : 5,
+  'gitprotocol-pack.adoc' : 5,
+  'gitprotocol-v2.adoc' : 5,
+  'gitrepository-layout.adoc' : 5,
+  'gitweb.conf.adoc' : 5,
 
   # Category 7.
-  'gitcli.txt' : 7,
-  'gitcore-tutorial.txt' : 7,
-  'gitcredentials.txt' : 7,
-  'gitcvs-migration.txt' : 7,
-  'gitdiffcore.txt' : 7,
-  'giteveryday.txt' : 7,
-  'gitfaq.txt' : 7,
-  'gitglossary.txt' : 7,
-  'gitpacking.txt' : 7,
-  'gitnamespaces.txt' : 7,
-  'gitremote-helpers.txt' : 7,
-  'gitrevisions.txt' : 7,
-  'gitsubmodules.txt' : 7,
-  'gittutorial-2.txt' : 7,
-  'gittutorial.txt' : 7,
-  'gitworkflows.txt' : 7,
+  'gitcli.adoc' : 7,
+  'gitcore-tutorial.adoc' : 7,
+  'gitcredentials.adoc' : 7,
+  'gitcvs-migration.adoc' : 7,
+  'gitdiffcore.adoc' : 7,
+  'giteveryday.adoc' : 7,
+  'gitfaq.adoc' : 7,
+  'gitglossary.adoc' : 7,
+  'gitpacking.adoc' : 7,
+  'gitnamespaces.adoc' : 7,
+  'gitremote-helpers.adoc' : 7,
+  'gitrevisions.adoc' : 7,
+  'gitsubmodules.adoc' : 7,
+  'gittutorial-2.adoc' : 7,
+  'gittutorial.adoc' : 7,
+  'gitworkflows.adoc' : 7,
 }
 
+manpages_breaking_changes = {
+  'git-pack-redundant.adoc' : 1,
+  'git-whatchanged.adoc' : 1,
+}
+
+if not get_option('breaking_changes')
+  manpages += manpages_breaking_changes
+endif
+
 docs_backend = get_option('docs_backend')
 if docs_backend == 'auto'
-  if find_program('asciidoc', required: false).found()
+  if find_program('asciidoc', dirs: program_path, native: true, required: false).found()
     docs_backend = 'asciidoc'
-  elif find_program('asciidoctor', required: false).found()
+  elif find_program('asciidoctor', dirs: program_path, native: true, required: false).found()
     docs_backend = 'asciidoctor'
   else
     error('Neither asciidoc nor asciidoctor were found.')
@@ -216,7 +228,7 @@ if docs_backend == 'auto'
 endif
 
 if docs_backend == 'asciidoc'
-  asciidoc = find_program('asciidoc', required: true)
+  asciidoc = find_program('asciidoc', dirs: program_path, native: true)
   asciidoc_html = 'xhtml11'
   asciidoc_docbook = 'docbook'
   xmlto_extra = [ ]
@@ -241,11 +253,21 @@ if docs_backend == 'asciidoc'
     '--attribute=build_dir=' + meson.current_build_dir(),
   ]
 
+  pager_opt = get_option('default_pager')
+  if pager_opt != '' and pager_opt != 'less'
+    asciidoc_common_options += '-agit-default-pager=' + pager_opt
+  endif
+
+  editor_opt = get_option('default_editor')
+  if editor_opt != '' and editor_opt != 'vi'
+    asciidoc_common_options += '-agit-default-editor=' + editor_opt
+  endif
+
   documentation_deps = [
     asciidoc_conf,
   ]
 elif docs_backend == 'asciidoctor'
-  asciidoctor = find_program('asciidoctor', required: true)
+  asciidoctor = find_program('asciidoctor', dirs: program_path, native: true)
   asciidoc_html = 'xhtml5'
   asciidoc_docbook = 'docbook5'
   xmlto_extra = [
@@ -278,37 +300,50 @@ elif docs_backend == 'asciidoctor'
     '--require', 'asciidoctor-extensions',
   ]
 
+  pager_opt = get_option('default_pager')
+  if pager_opt != '' and pager_opt != 'less'
+    asciidoc_common_options += '-agit-default-pager=' + pager_opt
+  endif
+
+  editor_opt = get_option('default_editor')
+  if editor_opt != '' and editor_opt != 'vi'
+    asciidoc_common_options += '-agit-default-editor=' + editor_opt
+  endif
+
   documentation_deps = [
     asciidoctor_extensions,
   ]
 endif
 
-git = find_program('git', required: false)
-xmlto = find_program('xmlto')
+if get_option('breaking_changes')
+   asciidoc_common_options += ['--attribute', 'with-breaking-changes']
+endif
+
+xmlto = find_program('xmlto', dirs: program_path, native: true)
 
 cmd_lists = [
-  'cmds-ancillaryinterrogators.txt',
-  'cmds-ancillarymanipulators.txt',
-  'cmds-mainporcelain.txt',
-  'cmds-plumbinginterrogators.txt',
-  'cmds-plumbingmanipulators.txt',
-  'cmds-synchingrepositories.txt',
-  'cmds-synchelpers.txt',
-  'cmds-guide.txt',
-  'cmds-developerinterfaces.txt',
-  'cmds-userinterfaces.txt',
-  'cmds-purehelpers.txt',
-  'cmds-foreignscminterface.txt',
+  'cmds-ancillaryinterrogators.adoc',
+  'cmds-ancillarymanipulators.adoc',
+  'cmds-mainporcelain.adoc',
+  'cmds-plumbinginterrogators.adoc',
+  'cmds-plumbingmanipulators.adoc',
+  'cmds-synchingrepositories.adoc',
+  'cmds-synchelpers.adoc',
+  'cmds-guide.adoc',
+  'cmds-developerinterfaces.adoc',
+  'cmds-userinterfaces.adoc',
+  'cmds-purehelpers.adoc',
+  'cmds-foreignscminterface.adoc',
 ]
 
 documentation_deps += custom_target(
   command: [
-    perl,
+    shell,
     '@INPUT@',
     meson.project_source_root(),
     meson.current_build_dir(),
   ] + cmd_lists,
-  input: 'cmd-list.perl',
+  input: 'cmd-list.sh',
   output: cmd_lists
 )
 
@@ -325,7 +360,7 @@ foreach mode : [ 'diff', 'merge' ]
       'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools',
     ],
     input: 'generate-mergetool-list.sh',
-    output: 'mergetools-' + mode + '.txt',
+    output: 'mergetools-' + mode + '.adoc',
   )
 endforeach
 
@@ -343,8 +378,7 @@ foreach manpage, category : manpages
       output: fs.stem(manpage) + '.xml',
     )
 
-    manpage_path = fs.stem(manpage) + '.' + category.to_string()
-    manpage_target = custom_target(
+    doc_targets += custom_target(
       command: [
         xmlto,
         '-m', '@INPUT0@',
@@ -360,14 +394,14 @@ foreach manpage, category : manpages
         'manpage-normal.xsl',
         'manpage-bold-literal.xsl',
       ],
-      output: manpage_path,
+      output: fs.stem(manpage) + '.' + category.to_string(),
       install: true,
       install_dir: get_option('mandir') / 'man' + category.to_string(),
     )
   endif
 
   if get_option('docs').contains('html')
-    custom_target(
+    doc_targets += custom_target(
       command: asciidoc_common_options + [
         '--backend=' + asciidoc_html,
         '--doctype=manpage',
@@ -405,7 +439,7 @@ if get_option('docs').contains('html')
     pointing_to: 'git.html',
   )
 
-  xsltproc = find_program('xsltproc')
+  xsltproc = find_program('xsltproc', dirs: program_path, native: true)
 
   user_manual_xml = custom_target(
     command: asciidoc_common_options + [
@@ -414,12 +448,12 @@ if get_option('docs').contains('html')
       '--out-file=@OUTPUT@',
       '@INPUT@',
     ],
-    input: 'user-manual.txt',
+    input: 'user-manual.adoc',
     output: 'user-manual.xml',
     depends: documentation_deps,
   )
 
-  custom_target(
+  doc_targets += custom_target(
     command: [
       xsltproc,
       '--xinclude',
@@ -436,18 +470,19 @@ if get_option('docs').contains('html')
   )
 
   articles = [
-    'DecisionMaking.txt',
-    'MyFirstContribution.txt',
-    'MyFirstObjectWalk.txt',
-    'ReviewingGuidelines.txt',
+    'BreakingChanges.adoc',
+    'DecisionMaking.adoc',
+    'MyFirstContribution.adoc',
+    'MyFirstObjectWalk.adoc',
+    'ReviewingGuidelines.adoc',
     'SubmittingPatches',
-    'ToolsForGit.txt',
-    'git-bisect-lk2009.txt',
-    'git-tools.txt',
+    'ToolsForGit.adoc',
+    'git-bisect-lk2009.adoc',
+    'git-tools.adoc',
   ]
 
   foreach article : articles
-    custom_target(
+    doc_targets += custom_target(
       command: asciidoc_common_options + [
         '--backend=' + asciidoc_html,
         '--out-file=@OUTPUT@',
@@ -475,8 +510,10 @@ endif
 # Sanity check that we are not missing any tests present in 't/'. This check
 # only runs once at configure time and is thus best-effort, only. Furthermore,
 # it only verifies man pages for the sake of simplicity.
-configured_manpages = manpages.keys() + [ 'git-bisect-lk2009.txt', 'git-tools.txt' ]
-actual_manpages = run_command(shell, '-c', 'ls git*.txt scalar.txt',
+configured_manpages = manpages.keys()
+configured_manpages += manpages_breaking_changes.keys()
+configured_manpages += [ 'git-bisect-lk2009.adoc', 'git-tools.adoc' ]
+actual_manpages = run_command(shell, '-c', 'ls git*.adoc scalar.adoc',
   check: true,
   env: script_environment,
 ).stdout().strip().split('\n')
diff --git a/Documentation/object-format-disclaimer.txt b/Documentation/object-format-disclaimer.adoc
index e561e6668c..e561e6668c 100644
--- a/Documentation/object-format-disclaimer.txt
+++ b/Documentation/object-format-disclaimer.adoc
diff --git a/Documentation/git-pack-refs.txt b/Documentation/pack-refs-options.adoc
index 2dcabaf74c..0b11282941 100644
--- a/Documentation/git-pack-refs.txt
+++ b/Documentation/pack-refs-options.adoc
@@ -1,50 +1,3 @@
-git-pack-refs(1)
-================
-
-NAME
-----
-git-pack-refs - Pack heads and tags for efficient repository access
-
-SYNOPSIS
---------
-[verse]
-'git pack-refs' [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]
-
-DESCRIPTION
------------
-
-Traditionally, tips of branches and tags (collectively known as
-'refs') were stored one file per ref in a (sub)directory
-under `$GIT_DIR/refs`
-directory.  While many branch tips tend to be updated often,
-most tags and some branch tips are never updated.  When a
-repository has hundreds or thousands of tags, this
-one-file-per-ref format both wastes storage and hurts
-performance.
-
-This command is used to solve the storage and performance
-problem by storing the refs in a single file,
-`$GIT_DIR/packed-refs`.  When a ref is missing from the
-traditional `$GIT_DIR/refs` directory hierarchy, it is looked
-up in this
-file and used if found.
-
-Subsequent updates to branches always create new files under
-`$GIT_DIR/refs` directory hierarchy.
-
-A recommended practice to deal with a repository with too many
-refs is to pack its refs with `--all` once, and
-occasionally run `git pack-refs`.  Tags are by
-definition stationary and are not expected to change.  Branch
-heads will be packed with the initial `pack-refs --all`, but
-only the currently active branch heads will become unpacked,
-and the next `pack-refs` (without `--all`) will leave them
-unpacked.
-
-
-OPTIONS
--------
-
 --all::
 
 The command by default packs all tags and refs that are already
@@ -66,7 +19,10 @@ Pack refs as needed depending on the current state of the ref database. The
 behavior depends on the ref format used by the repository and may change in the
 future.
 +
-	- "files": No special handling for `--auto` has been implemented.
+	- "files": Loose references are packed into the `packed-refs` file
+	  based on the ratio of loose references to the size of the
+	  `packed-refs` file. The bigger the `packed-refs` file, the more loose
+	  references need to exist before we repack.
 +
 	- "reftable": Tables are compacted such that they form a geometric
 	  sequence. For two tables N and N+1, where N+1 is newer, this
@@ -88,22 +44,9 @@ Do not pack refs matching the given `glob(7)` pattern. Repetitions of this optio
 accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of
 patterns. If a ref is already packed, including it with `--exclude` will not
 unpack it.
-
++
 When used with `--all`, pack only loose refs which do not match any of
 the provided `--exclude` patterns.
-
++
 When used with `--include`, refs provided to `--include`, minus refs that are
 provided to `--exclude` will be packed.
-
-
-BUGS
-----
-
-Older documentation written before the packed-refs mechanism was
-introduced may still say things like ".git/refs/heads/<branch> file
-exists" when it means "branch <branch> exists".
-
-
-GIT
----
-Part of the linkgit:git[1] suite
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.adoc
index 8ee940b6a4..2121e8e1df 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.adoc
@@ -2,11 +2,11 @@ PRETTY FORMATS
 --------------
 
 If the commit is a merge, and if the pretty-format
-is not 'oneline', 'email' or 'raw', an additional line is
-inserted before the 'Author:' line.  This line begins with
+is not `oneline`, `email` or `raw`, an additional line is
+inserted before the `Author:` line.  This line begins with
 "Merge: " and the hashes of ancestral commits are printed,
 separated by spaces.  Note that the listed commits may not
-necessarily be the list of the *direct* parent commits if you
+necessarily be the list of the 'direct' parent commits if you
 have limited your view of history: for example, if you are
 only interested in changes related to a certain directory or
 file.
@@ -14,24 +14,24 @@ file.
 There are several built-in formats, and you can define
 additional formats by setting a pretty.<name>
 config option to either another format name, or a
-'format:' string, as described below (see
+`format:` string, as described below (see
 linkgit:git-config[1]). Here are the details of the
 built-in formats:
 
-* 'oneline'
+* `oneline`
 
 	  <hash> <title-line>
 +
 This is designed to be as compact as possible.
 
-* 'short'
+* `short`
 
 	  commit <hash>
 	  Author: <author>
 
 	      <title-line>
 
-* 'medium'
+* `medium`
 
 	  commit <hash>
 	  Author: <author>
@@ -41,7 +41,7 @@ This is designed to be as compact as possible.
 
 	      <full-commit-message>
 
-* 'full'
+* `full`
 
 	  commit <hash>
 	  Author: <author>
@@ -51,7 +51,7 @@ This is designed to be as compact as possible.
 
 	      <full-commit-message>
 
-* 'fuller'
+* `fuller`
 
 	  commit <hash>
 	  Author:     <author>
@@ -63,18 +63,18 @@ This is designed to be as compact as possible.
 
 	       <full-commit-message>
 
-* 'reference'
+* `reference`
 
 	  <abbrev-hash> (<title-line>, <short-author-date>)
 +
 This format is used to refer to another commit in a commit message and
-is the same as `--pretty='format:%C(auto)%h (%s, %ad)'`.  By default,
+is the same as ++--pretty=\'format:%C(auto)%h (%s, %ad)'++.  By default,
 the date is formatted with `--date=short` unless another `--date` option
 is explicitly specified.  As with any `format:` with format
 placeholders, its output is not affected by other options like
 `--decorate` and `--walk-reflogs`.
 
-* 'email'
+* `email`
 
 	  From <hash> <date>
 	  From: <author>
@@ -83,30 +83,30 @@ placeholders, its output is not affected by other options like
 
 	  <full-commit-message>
 
-* 'mboxrd'
+* `mboxrd`
 +
-Like 'email', but lines in the commit message starting with "From "
+Like `email`, but lines in the commit message starting with "From "
 (preceded by zero or more ">") are quoted with ">" so they aren't
 confused as starting a new commit.
 
-* 'raw'
+* `raw`
 +
-The 'raw' format shows the entire commit exactly as
+The `raw` format shows the entire commit exactly as
 stored in the commit object.  Notably, the hashes are
-displayed in full, regardless of whether --abbrev or
---no-abbrev are used, and 'parents' information show the
+displayed in full, regardless of whether `--abbrev` or
+`--no-abbrev` are used, and 'parents' information show the
 true parent commits, without taking grafts or history
 simplification into account. Note that this format affects the way
 commits are displayed, but not the way the diff is shown e.g. with
 `git log --raw`. To get full object names in a raw diff format,
 use `--no-abbrev`.
 
-* 'format:<format-string>'
+* `format:<format-string>`
 +
-The 'format:<format-string>' format allows you to specify which information
+The `format:<format-string>` format allows you to specify which information
 you want to show. It works a little bit like printf format,
-with the notable exception that you get a newline with '%n'
-instead of '\n'.
+with the notable exception that you get a newline with `%n`
+instead of `\n`.
 +
 E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"'
 would show something like this:
@@ -120,158 +120,163 @@ The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
 The placeholders are:
 
 - Placeholders that expand to a single literal character:
-'%n':: newline
-'%%':: a raw '%'
-'%x00':: '%x' followed by two hexadecimal digits is replaced with a
+++%n++:: newline
+++%%++:: a raw ++%++
+++%x00++:: ++%x++ followed by two hexadecimal digits is replaced with a
 	 byte with the hexadecimal digits' value (we will call this
 	 "literal formatting code" in the rest of this document).
 
 - Placeholders that affect formatting of later placeholders:
-'%Cred':: switch color to red
-'%Cgreen':: switch color to green
-'%Cblue':: switch color to blue
-'%Creset':: reset color
-'%C(...)':: color specification, as described under Values in the
+++%Cred++:: switch color to red
+++%Cgreen++:: switch color to green
+++%Cblue++:: switch color to blue
+++%Creset++:: reset color
+++%C(++_<spec>_++)++:: color specification, as described under Values in the
 	    "CONFIGURATION FILE" section of linkgit:git-config[1].  By
 	    default, colors are shown only when enabled for log output
 	    (by `color.diff`, `color.ui`, or `--color`, and respecting
 	    the `auto` settings of the former if we are going to a
-	    terminal). `%C(auto,...)` is accepted as a historical
-	    synonym for the default (e.g., `%C(auto,red)`). Specifying
-	    `%C(always,...)` will show the colors even when color is
+	    terminal). ++%C(auto,++_<spec>_++)++ is accepted as a historical
+	    synonym for the default (e.g., ++%C(auto,red)++). Specifying
+	    ++%C(always,++_<spec>_++)++ will show the colors even when color is
 	    not otherwise enabled (though consider just using
-	    `--color=always` to enable color for the whole output,
+	    `--color=always` to enable color for the  whole output,
 	    including this format and anything else git might color).
-	    `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
+	    `auto` alone (i.e. ++%C(auto)++) will turn on auto coloring
 	    on the next placeholders until the color is switched
 	    again.
-'%m':: left (`<`), right (`>`) or boundary (`-`) mark
-'%w([<w>[,<i1>[,<i2>]]])':: switch line wrapping, like the -w option of
+++%m++:: left (`<`), right (`>`) or boundary (`-`) mark
+++%w(++`[<w>[,<i1>[,<i2>]]]`++)++:: switch line wrapping, like the `-w` option of
 			    linkgit:git-shortlog[1].
-'%<( <N> [,trunc|ltrunc|mtrunc])':: make the next placeholder take at
+++%<(++`<n>[,(trunc|ltrunc|mtrunc)]`++)++:: make the next placeholder take at
 				  least N column widths, padding spaces on
 				  the right if necessary.  Optionally
-				  truncate (with ellipsis '..') at the left (ltrunc) `..ft`,
+				  truncate (with ellipsis `..`) at the left (ltrunc) `..ft`,
 				  the middle (mtrunc) `mi..le`, or the end
 				  (trunc) `rig..`, if the output is longer than
-				  N columns.
+				  _<n>_ columns.
 				  Note 1: that truncating
-				  only works correctly with N >= 2.
-				  Note 2: spaces around the N and M (see below)
+				  only works correctly with _<n>_ >= 2.
+				  Note 2: spaces around the _<n>_ and _<m>_ (see below)
 				  values are optional.
 				  Note 3: Emojis and other wide characters
 				  will take two display columns, which may
 				  over-run column boundaries.
 				  Note 4: decomposed character combining marks
 				  may be misplaced at padding boundaries.
-'%<|( <M> )':: make the next placeholder take at least until Mth
+++%<|(++_<m>_ ++)++:: make the next placeholder take at least until _<m>_ th
 	     display column, padding spaces on the right if necessary.
-	     Use negative M values for column positions measured
+	     Use negative _<m>_ values for column positions measured
 	     from the right hand edge of the terminal window.
-'%>( <N> )', '%>|( <M> )':: similar to '%<( <N> )', '%<|( <M> )' respectively,
+++%>(++_<n>_++)++::
+++%>|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++ respectively,
 			but padding spaces on the left
-'%>>( <N> )', '%>>|( <M> )':: similar to '%>( <N> )', '%>|( <M> )'
+++%>>(++_<n>_++)++::
+++%>>|(++_<m>_++)++:: similar to ++%>(++_<n>_++)++, ++%>|(++_<m>_++)++
 			  respectively, except that if the next
 			  placeholder takes more spaces than given and
 			  there are spaces on its left, use those
 			  spaces
-'%><( <N> )', '%><|( <M> )':: similar to '%<( <N> )', '%<|( <M> )'
+++%><(++_<n>_++)++::
+++%><|(++_<m>_++)++:: similar to ++%<(++_<n>_++)++, ++%<|(++_<m>_++)++
 			  respectively, but padding both sides
 			  (i.e. the text is centered)
 
 - Placeholders that expand to information extracted from the commit:
-'%H':: commit hash
-'%h':: abbreviated commit hash
-'%T':: tree hash
-'%t':: abbreviated tree hash
-'%P':: parent hashes
-'%p':: abbreviated parent hashes
-'%an':: author name
-'%aN':: author name (respecting .mailmap, see linkgit:git-shortlog[1]
++%H+:: commit hash
++%h+:: abbreviated commit hash
++%T+:: tree hash
++%t+:: abbreviated tree hash
++%P+:: parent hashes
++%p+:: abbreviated parent hashes
++%an+:: author name
++%aN+:: author name (respecting .mailmap, see linkgit:git-shortlog[1]
 	or linkgit:git-blame[1])
-'%ae':: author email
-'%aE':: author email (respecting .mailmap, see linkgit:git-shortlog[1]
++%ae+:: author email
++%aE+:: author email (respecting .mailmap, see linkgit:git-shortlog[1]
 	or linkgit:git-blame[1])
-'%al':: author email local-part (the part before the '@' sign)
-'%aL':: author local-part (see '%al') respecting .mailmap, see
++%al+:: author email local-part (the part before the `@` sign)
++%aL+:: author local-part (see +%al+) respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
-'%ad':: author date (format respects --date= option)
-'%aD':: author date, RFC2822 style
-'%ar':: author date, relative
-'%at':: author date, UNIX timestamp
-'%ai':: author date, ISO 8601-like format
-'%aI':: author date, strict ISO 8601 format
-'%as':: author date, short format (`YYYY-MM-DD`)
-'%ah':: author date, human style (like the `--date=human` option of
++%ad+:: author date (format respects --date= option)
++%aD+:: author date, RFC2822 style
++%ar+:: author date, relative
++%at+:: author date, UNIX timestamp
++%ai+:: author date, ISO 8601-like format
++%aI+:: author date, strict ISO 8601 format
++%as+:: author date, short format (`YYYY-MM-DD`)
++%ah+:: author date, human style (like the `--date=human` option of
 	linkgit:git-rev-list[1])
-'%cn':: committer name
-'%cN':: committer name (respecting .mailmap, see
++%cn+:: committer name
++%cN+:: committer name (respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
-'%ce':: committer email
-'%cE':: committer email (respecting .mailmap, see
++%ce+:: committer email
++%cE+:: committer email (respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
-'%cl':: committer email local-part (the part before the '@' sign)
-'%cL':: committer local-part (see '%cl') respecting .mailmap, see
++%cl+:: committer email local-part (the part before the `@` sign)
++%cL+:: committer local-part (see +%cl+) respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
-'%cd':: committer date (format respects --date= option)
-'%cD':: committer date, RFC2822 style
-'%cr':: committer date, relative
-'%ct':: committer date, UNIX timestamp
-'%ci':: committer date, ISO 8601-like format
-'%cI':: committer date, strict ISO 8601 format
-'%cs':: committer date, short format (`YYYY-MM-DD`)
-'%ch':: committer date, human style (like the `--date=human` option of
++%cd+:: committer date (format respects --date= option)
++%cD+:: committer date, RFC2822 style
++%cr+:: committer date, relative
++%ct+:: committer date, UNIX timestamp
++%ci+:: committer date, ISO 8601-like format
++%cI+:: committer date, strict ISO 8601 format
++%cs+:: committer date, short format (`YYYY-MM-DD`)
++%ch+:: committer date, human style (like the `--date=human` option of
 	linkgit:git-rev-list[1])
-'%d':: ref names, like the --decorate option of linkgit:git-log[1]
-'%D':: ref names without the " (", ")" wrapping.
-'%(decorate[:<options>])'::
++%d+:: ref names, like the --decorate option of linkgit:git-log[1]
++%D+:: ref names without the " (", ")" wrapping.
+++%(decorate++`[:<option>,...]`++)++::
 ref names with custom decorations. The `decorate` string may be followed by a
 colon and zero or more comma-separated options. Option values may contain
 literal formatting codes. These must be used for commas (`%x2C`) and closing
 parentheses (`%x29`), due to their role in the option syntax.
-+
-** 'prefix=<value>': Shown before the list of ref names.  Defaults to "{nbsp}`(`".
-** 'suffix=<value>': Shown after the list of ref names.  Defaults to "`)`".
-** 'separator=<value>': Shown between ref names.  Defaults to "`,`{nbsp}".
-** 'pointer=<value>': Shown between HEAD and the branch it points to, if any.
-		      Defaults to "{nbsp}`->`{nbsp}".
-** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}".
+
+** `prefix=<value>`: Shown before the list of ref names.  Defaults to "{nbsp}++(++".
+** `suffix=<value>`: Shown after the list of ref names.  Defaults to "+)+".
+** `separator=<value>`: Shown between ref names.  Defaults to "+,+{nbsp}".
+** `pointer=<value>`: Shown between HEAD and the branch it points to, if any.
+		      Defaults to "{nbsp}++->++{nbsp}".
+** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
 
 +
+--
 For example, to produce decorations with no wrapping
 or tag annotations, and spaces as separators:
-+
-`%(decorate:prefix=,suffix=,tag=,separator= )`
 
-'%(describe[:<options>])'::
+++%(decorate:prefix=,suffix=,tag=,separator= )++
+--
+
+++%(describe++`[:<option>,...]`++)++::
 human-readable name, like linkgit:git-describe[1]; empty string for
 undescribable commits.  The `describe` string may be followed by a colon and
 zero or more comma-separated options.  Descriptions can be inconsistent when
 tags are added or removed at the same time.
 +
-** 'tags[=<bool-value>]': Instead of only considering annotated tags,
+** `tags[=<bool-value>]`: Instead of only considering annotated tags,
    consider lightweight tags as well.
-** 'abbrev=<number>': Instead of using the default number of hexadecimal digits
+** `abbrev=<number>`: Instead of using the default number of hexadecimal digits
    (which will vary according to the number of objects in the repository with a
    default of 7) of the abbreviated object name, use <number> digits, or as many
    digits as needed to form a unique object name.
-** 'match=<pattern>': Only consider tags matching the given
-   `glob(7)` pattern, excluding the "refs/tags/" prefix.
-** 'exclude=<pattern>': Do not consider tags matching the given
-   `glob(7)` pattern, excluding the "refs/tags/" prefix.
+** `match=<pattern>`: Only consider tags matching the given
+   `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
+** `exclude=<pattern>`: Do not consider tags matching the given
+   `glob(7)` _<pattern>_, excluding the `refs/tags/` prefix.
 
-'%S':: ref name given on the command line by which the commit was reached
++%S+:: ref name given on the command line by which the commit was reached
        (like `git log --source`), only works with `git log`
-'%e':: encoding
-'%s':: subject
-'%f':: sanitized subject line, suitable for a filename
-'%b':: body
-'%B':: raw body (unwrapped subject and body)
++%e+:: encoding
++%s+:: subject
++%f+:: sanitized subject line, suitable for a filename
++%b+:: body
++%B+:: raw body (unwrapped subject and body)
 ifndef::git-rev-list[]
-'%N':: commit notes
++%N+:: commit notes
 endif::git-rev-list[]
-'%GG':: raw verification message from GPG for a signed commit
-'%G?':: show "G" for a good (valid) signature,
++%GG+:: raw verification message from GPG for a signed commit
++%G?+:: show "G" for a good (valid) signature,
 	"B" for a bad signature,
 	"U" for a good signature with unknown validity,
 	"X" for a good signature that has expired,
@@ -279,86 +284,86 @@ endif::git-rev-list[]
 	"R" for a good signature made by a revoked key,
 	"E" if the signature cannot be checked (e.g. missing key)
 	and "N" for no signature
-'%GS':: show the name of the signer for a signed commit
-'%GK':: show the key used to sign a signed commit
-'%GF':: show the fingerprint of the key used to sign a signed commit
-'%GP':: show the fingerprint of the primary key whose subkey was used
++%GS+:: show the name of the signer for a signed commit
++%GK+:: show the key used to sign a signed commit
++%GF+:: show the fingerprint of the key used to sign a signed commit
++%GP+:: show the fingerprint of the primary key whose subkey was used
 	to sign a signed commit
-'%GT':: show the trust level for the key used to sign a signed commit
-'%gD':: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2
++%GT+:: show the trust level for the key used to sign a signed commit
++%gD+:: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2
 	minutes ago}`; the format follows the rules described for the
 	`-g` option. The portion before the `@` is the refname as
 	given on the command line (so `git log -g refs/heads/master`
 	would yield `refs/heads/master@{0}`).
-'%gd':: shortened reflog selector; same as `%gD`, but the refname
++%gd+:: shortened reflog selector; same as `%gD`, but the refname
 	portion is shortened for human readability (so
 	`refs/heads/master` becomes just `master`).
-'%gn':: reflog identity name
-'%gN':: reflog identity name (respecting .mailmap, see
++%gn+:: reflog identity name
++%gN+:: reflog identity name (respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
-'%ge':: reflog identity email
-'%gE':: reflog identity email (respecting .mailmap, see
++%ge+:: reflog identity email
++%gE+:: reflog identity email (respecting .mailmap, see
 	linkgit:git-shortlog[1] or linkgit:git-blame[1])
-'%gs':: reflog subject
-'%(trailers[:<options>])'::
++%gs+:: reflog subject
+++%(trailers++`[:<option>,...]`++)++::
 display the trailers of the body as interpreted by
 linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by
 a colon and zero or more comma-separated options. If any option is provided
 multiple times, the last occurrence wins.
 +
-** 'key=<key>': only show trailers with specified <key>. Matching is done
+** `key=<key>`: only show trailers with specified <key>. Matching is done
    case-insensitively and trailing colon is optional. If option is
    given multiple times trailer lines matching any of the keys are
    shown. This option automatically enables the `only` option so that
    non-trailer lines in the trailer block are hidden. If that is not
    desired it can be disabled with `only=false`.  E.g.,
-   `%(trailers:key=Reviewed-by)` shows trailer lines with key
+   +%(trailers:key=Reviewed-by)+ shows trailer lines with key
    `Reviewed-by`.
-** 'only[=<bool>]': select whether non-trailer lines from the trailer
+** `only[=<bool>]`: select whether non-trailer lines from the trailer
    block should be included.
-** 'separator=<sep>': specify the separator inserted between trailer
+** `separator=<sep>`: specify the separator inserted between trailer
    lines. Defaults to a line feed character. The string <sep> may contain
    the literal formatting codes described above. To use comma as
    separator one must use `%x2C` as it would otherwise be parsed as
-   next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
+   next option. E.g., +%(trailers:key=Ticket,separator=%x2C )+
    shows all trailer lines whose key is "Ticket" separated by a comma
    and a space.
-** 'unfold[=<bool>]': make it behave as if interpret-trailer's `--unfold`
+** `unfold[=<bool>]`: make it behave as if interpret-trailer's `--unfold`
    option was given. E.g.,
-   `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
-** 'keyonly[=<bool>]': only show the key part of the trailer.
-** 'valueonly[=<bool>]': only show the value part of the trailer.
-** 'key_value_separator=<sep>': specify the separator inserted between
+   +%(trailers:only,unfold=true)+ unfolds and shows all trailer lines.
+** `keyonly[=<bool>]`: only show the key part of the trailer.
+** `valueonly[=<bool>]`: only show the value part of the trailer.
+** `key_value_separator=<sep>`: specify the separator inserted between
    the key and value of each trailer. Defaults to ": ". Otherwise it
-   shares the same semantics as 'separator=<sep>' above.
+   shares the same semantics as `separator=<sep>` above.
 
 NOTE: Some placeholders may depend on other options given to the
-revision traversal engine. For example, the `%g*` reflog options will
+revision traversal engine. For example, the +%g*+ reflog options will
 insert an empty string unless we are traversing reflog entries (e.g., by
-`git log -g`). The `%d` and `%D` placeholders will use the "short"
+`git log -g`). The +%d+ and +%D+ placeholders will use the "short"
 decoration format if `--decorate` was not already provided on the command
 line.
 
-The boolean options accept an optional value `[=<bool-value>]`. The values
-`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
-sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
-option is given with no value, it's enabled.
+The boolean options accept an optional value `[=<bool-value>]`. The
+values taken by `--type=bool` linkgit:git-config[1], like `yes` and `off`,
+are all accepted.  Giving a boolean option without `=<value>` is
+equivalent to giving it with `=true`.
 
-If you add a `+` (plus sign) after '%' of a placeholder, a line-feed
+If you add a `+` (plus sign) after +%+ of a placeholder, a line-feed
 is inserted immediately before the expansion if and only if the
 placeholder expands to a non-empty string.
 
-If you add a `-` (minus sign) after '%' of a placeholder, all consecutive
+If you add a `-` (minus sign) after +%+ of a placeholder, all consecutive
 line-feeds immediately preceding the expansion are deleted if and only if the
 placeholder expands to an empty string.
 
-If you add a ` ` (space) after '%' of a placeholder, a space
+If you add a `' '` (space) after +%+ of a placeholder, a space
 is inserted immediately before the expansion if and only if the
 placeholder expands to a non-empty string.
 
-* 'tformat:'
+* `tformat:`
 +
-The 'tformat:' format works exactly like 'format:', except that it
+The `tformat:` format works exactly like `format:`, except that it
 provides "terminator" semantics instead of "separator" semantics. In
 other words, each commit has the message terminator character (usually a
 newline) appended, rather than a separator placed between entries.
@@ -378,7 +383,7 @@ $ git log -2 --pretty=tformat:%h 4da45bef \
 7134973
 ---------------------
 +
-In addition, any unrecognized string that has a `%` in it is interpreted
+In addition, any unrecognized string that has a +%+ in it is interpreted
 as if it has `tformat:` in front of it.  For example, these two are
 equivalent:
 +
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.adoc
index 23888cd612..658e462b25 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.adoc
@@ -1,38 +1,38 @@
---pretty[=<format>]::
---format=<format>::
+`--pretty[=<format>]`::
+`--format=<format>`::
 
 	Pretty-print the contents of the commit logs in a given format,
-	where '<format>' can be one of 'oneline', 'short', 'medium',
-	'full', 'fuller', 'reference', 'email', 'raw', 'format:<string>'
-	and 'tformat:<string>'.  When '<format>' is none of the above,
-	and has '%placeholder' in it, it acts as if
-	'--pretty=tformat:<format>' were given.
+	where '<format>' can be one of `oneline`, `short`, `medium`,
+	`full`, `fuller`, `reference`, `email`, `raw`, `format:<string>`
+	and `tformat:<string>`.  When _<format>_ is none of the above,
+	and has `%<placeholder>` in it, it acts as if
+	`--pretty=tformat:<format>` were given.
 +
 See the "PRETTY FORMATS" section for some additional details for each
-format.  When '=<format>' part is omitted, it defaults to 'medium'.
+format.  When `=<format>` part is omitted, it defaults to `medium`.
 +
-Note: you can specify the default pretty format in the repository
+NOTE: you can specify the default pretty format in the repository
 configuration (see linkgit:git-config[1]).
 
---abbrev-commit::
+`--abbrev-commit`::
 	Instead of showing the full 40-byte hexadecimal commit object
 	name, show a prefix that names the object uniquely.
-	"--abbrev=<n>" (which also modifies diff output, if it is displayed)
+	`--abbrev=<n>` (which also modifies diff output, if it is displayed)
 	option can be used to specify the minimum length of the prefix.
 +
-This should make "--pretty=oneline" a whole lot more readable for
+This should make `--pretty=oneline` a whole lot more readable for
 people using 80-column terminals.
 
---no-abbrev-commit::
+`--no-abbrev-commit`::
 	Show the full 40-byte hexadecimal commit object name. This negates
 	`--abbrev-commit`, either explicit or implied by other options such
-	as "--oneline". It also overrides the `log.abbrevCommit` variable.
+	as `--oneline`. It also overrides the `log.abbrevCommit` variable.
 
---oneline::
-	This is a shorthand for "--pretty=oneline --abbrev-commit"
+`--oneline`::
+	This is a shorthand for `--pretty=oneline --abbrev-commit`
 	used together.
 
---encoding=<encoding>::
+`--encoding=<encoding>`::
 	Commit objects record the character encoding used for the log message
 	in their encoding header; this option can be used to tell the
 	command to re-code the commit log message in the encoding
@@ -44,27 +44,33 @@ people using 80-column terminals.
 	to convert the commit, we will quietly output the original
 	object verbatim.
 
---expand-tabs=<n>::
---expand-tabs::
---no-expand-tabs::
+`--expand-tabs=<n>`::
+`--expand-tabs`::
+`--no-expand-tabs`::
 	Perform a tab expansion (replace each tab with enough spaces
-	to fill to the next display column that is a multiple of '<n>')
+	to fill to the next display column that is a multiple of _<n>_)
 	in the log message before showing it in the output.
 	`--expand-tabs` is a short-hand for `--expand-tabs=8`, and
 	`--no-expand-tabs` is a short-hand for `--expand-tabs=0`,
 	which disables tab expansion.
 +
 By default, tabs are expanded in pretty formats that indent the log
-message by 4 spaces (i.e.  'medium', which is the default, 'full',
-and 'fuller').
+message by 4 spaces (i.e.  `medium`, which is the default, `full`,
+and `fuller`).
 
 ifndef::git-rev-list[]
---notes[=<ref>]::
+`--notes[=<ref>]`::
 	Show the notes (see linkgit:git-notes[1]) that annotate the
-	commit, when showing the commit log message.  This is the default
-	for `git log`, `git show` and `git whatchanged` commands when
-	there is no `--pretty`, `--format`, or `--oneline` option given
-	on the command line.
+	commit, when showing the commit log message.
+ifndef::with-breaking-changes[]
+This is the default for `git log`, `git show` and `git whatchanged`
+commands when there is no `--pretty`, `--format`, or `--oneline` option given
+on the command line.
+endif::with-breaking-changes[]
+ifdef::with-breaking-changes[]
+This is the default for `git log` and `git show` commands when there is no
+`--pretty`, `--format`, or `--oneline` option given on the command line.
+endif::with-breaking-changes[]
 +
 By default, the notes shown are from the notes refs listed in the
 `core.notesRef` and `notes.displayRef` variables (or corresponding
@@ -75,28 +81,29 @@ to display.  The ref can specify the full refname when it begins
 with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise
 `refs/notes/` is prefixed to form the full name of the ref.
 +
-Multiple --notes options can be combined to control which notes are
-being displayed. Examples: "--notes=foo" will show only notes from
-"refs/notes/foo"; "--notes=foo --notes" will show both notes from
+Multiple `--notes` options can be combined to control which notes are
+being displayed. Examples: "`--notes=foo`" will show only notes from
+`refs/notes/foo`; "`--notes=foo --notes`" will show both notes from
 "refs/notes/foo" and from the default notes ref(s).
 
---no-notes::
+`--no-notes`::
 	Do not show notes. This negates the above `--notes` option, by
 	resetting the list of notes refs from which notes are shown.
 	Options are parsed in the order given on the command line, so e.g.
-	"--notes --notes=foo --no-notes --notes=bar" will only show notes
-	from "refs/notes/bar".
+	"`--notes --notes=foo --no-notes --notes=bar`" will only show notes
+	from `refs/notes/bar`.
 
---show-notes-by-default::
+`--show-notes-by-default`::
 	Show the default notes unless options for displaying specific
 	notes are given.
 
---show-notes[=<ref>]::
---[no-]standard-notes::
-	These options are deprecated. Use the above --notes/--no-notes
+`--show-notes[=<ref>]`::
+`--standard-notes`::
+`--no-standard-notes`::
+	These options are deprecated. Use the above `--notes`/`--no-notes`
 	options instead.
 endif::git-rev-list[]
 
---show-signature::
+`--show-signature`::
 	Check the validity of a signed commit object by passing the signature
 	to `gpg --verify` and show the output.
diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.adoc
index d79d2f6065..bb2cf6a462 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.adoc
@@ -11,6 +11,7 @@ ifndef::git-pull[]
 	(See linkgit:git-config[1]).
 endif::git-pull[]
 
+[[fetch-refspec]]
 <refspec>::
 	Specifies which refs to fetch and which local refs to update.
 	When no <refspec>s appear on the command line, the refs to fetch
diff --git a/Documentation/ref-reachability-filters.txt b/Documentation/ref-reachability-filters.adoc
index 9bae46d84c..9bae46d84c 100644
--- a/Documentation/ref-reachability-filters.txt
+++ b/Documentation/ref-reachability-filters.adoc
diff --git a/Documentation/ref-storage-format.txt b/Documentation/ref-storage-format.adoc
index 14fff8a9c6..14fff8a9c6 100644
--- a/Documentation/ref-storage-format.txt
+++ b/Documentation/ref-storage-format.adoc
diff --git a/Documentation/rerere-options.txt b/Documentation/rerere-options.adoc
index c3321ddea2..b0b920144a 100644
--- a/Documentation/rerere-options.txt
+++ b/Documentation/rerere-options.adoc
@@ -1,5 +1,5 @@
---rerere-autoupdate::
---no-rerere-autoupdate::
+`--rerere-autoupdate`::
+`--no-rerere-autoupdate`::
 	After the rerere mechanism reuses a recorded resolution on
 	the current conflict to update the files in the working
 	tree, allow it to also update the index with the result of
diff --git a/Documentation/rev-list-description.txt b/Documentation/rev-list-description.adoc
index a9efa7fa27..82c680e570 100644
--- a/Documentation/rev-list-description.txt
+++ b/Documentation/rev-list-description.adoc
@@ -26,8 +26,8 @@ endif::git-log[]
 means "list all the commits which are reachable from 'foo' or 'bar', but
 not from 'baz'".
 
-A special notation "'<commit1>'..'<commit2>'" can be used as a
-short-hand for "^'<commit1>' '<commit2>'". For example, either of
+A special notation "`<commit1>..<commit2>`" can be used as a
+short-hand for "`^<commit1> <commit2>`". For example, either of
 the following may be used interchangeably:
 
 ifdef::git-rev-list[]
@@ -43,7 +43,7 @@ $ git log HEAD ^origin
 -----------------------------------------------------------------------
 endif::git-log[]
 
-Another special notation is "'<commit1>'...'<commit2>'" which is useful
+Another special notation is "`<commit1>...<commit2>`" which is useful
 for merges.  The resulting set of commits is the symmetric difference
 between the two operands.  The following two commands are equivalent:
 
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.adoc
index 459e5a02f5..d9665d82c8 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.adoc
@@ -6,60 +6,60 @@ special notations explained in the description, additional commit
 limiting may be applied.
 
 Using more options generally further limits the output (e.g.
-`--since=<date1>` limits to commits newer than `<date1>`, and using it
+`--since=<date1>` limits to commits newer than _<date1>_, and using it
 with `--grep=<pattern>` further limits to commits whose log message
-has a line that matches `<pattern>`), unless otherwise noted.
+has a line that matches _<pattern>_), unless otherwise noted.
 
 Note that these are applied before commit
 ordering and formatting options, such as `--reverse`.
 
--<number>::
--n <number>::
---max-count=<number>::
-	Limit the number of commits to output.
+`-<number>`::
+`-n <number>`::
+`--max-count=<number>`::
+	Limit the output to _<number>_ commits.
 
---skip=<number>::
-	Skip 'number' commits before starting to show the commit output.
+`--skip=<number>`::
+	Skip _<number>_ commits before starting to show the commit output.
 
---since=<date>::
---after=<date>::
-	Show commits more recent than a specific date.
+`--since=<date>`::
+`--after=<date>`::
+	Show commits more recent than _<date>_.
 
---since-as-filter=<date>::
-	Show all commits more recent than a specific date. This visits
+`--since-as-filter=<date>`::
+	Show all commits more recent than _<date>_. This visits
 	all commits in the range, rather than stopping at the first commit which
-	is older than a specific date.
+	is older than _<date>_.
 
---until=<date>::
---before=<date>::
-	Show commits older than a specific date.
+`--until=<date>`::
+`--before=<date>`::
+	Show commits older than _<date>_.
 
 ifdef::git-rev-list[]
---max-age=<timestamp>::
---min-age=<timestamp>::
+`--max-age=<timestamp>`::
+`--min-age=<timestamp>`::
 	Limit the commits output to specified time range.
 endif::git-rev-list[]
 
---author=<pattern>::
---committer=<pattern>::
+`--author=<pattern>`::
+`--committer=<pattern>`::
 	Limit the commits output to ones with author/committer
-	header lines that match the specified pattern (regular
-	expression).  With more than one `--author=<pattern>`,
-	commits whose author matches any of the given patterns are
+	header lines that match the _<pattern>_ regular
+	expression.  With more than one `--author=<pattern>`,
+	commits whose author matches any of the _<pattern>_ are
 	chosen (similarly for multiple `--committer=<pattern>`).
 
---grep-reflog=<pattern>::
+`--grep-reflog=<pattern>`::
 	Limit the commits output to ones with reflog entries that
-	match the specified pattern (regular expression). With
+	match the _<pattern>_ regular expression. With
 	more than one `--grep-reflog`, commits whose reflog message
 	matches any of the given patterns are chosen.  It is an
 	error to use this option unless `--walk-reflogs` is in use.
 
---grep=<pattern>::
+`--grep=<pattern>`::
 	Limit the commits output to ones with a log message that
-	matches the specified pattern (regular expression).  With
+	matches the _<pattern>_ regular expression.  With
 	more than one `--grep=<pattern>`, commits whose message
-	matches any of the given patterns are chosen (but see
+	matches any of the _<pattern>_ are chosen (but see
 	`--all-match`).
 ifndef::git-rev-list[]
 +
@@ -67,35 +67,35 @@ When `--notes` is in effect, the message from the notes is
 matched as if it were part of the log message.
 endif::git-rev-list[]
 
---all-match::
+`--all-match`::
 	Limit the commits output to ones that match all given `--grep`,
 	instead of ones that match at least one.
 
---invert-grep::
+`--invert-grep`::
 	Limit the commits output to ones with a log message that do not
-	match the pattern specified with `--grep=<pattern>`.
+	match the _<pattern>_ specified with `--grep=<pattern>`.
 
--i::
---regexp-ignore-case::
+`-i`::
+`--regexp-ignore-case`::
 	Match the regular expression limiting patterns without regard to letter
 	case.
 
---basic-regexp::
+`--basic-regexp`::
 	Consider the limiting patterns to be basic regular expressions;
 	this is the default.
 
--E::
---extended-regexp::
+`-E`::
+`--extended-regexp`::
 	Consider the limiting patterns to be extended regular expressions
 	instead of the default basic regular expressions.
 
--F::
---fixed-strings::
+`-F`::
+`--fixed-strings`::
 	Consider the limiting patterns to be fixed strings (don't interpret
 	pattern as a regular expression).
 
--P::
---perl-regexp::
+`-P`::
+`--perl-regexp`::
 	Consider the limiting patterns to be Perl-compatible regular
 	expressions.
 +
@@ -103,20 +103,20 @@ Support for these types of regular expressions is an optional
 compile-time dependency. If Git wasn't compiled with support for them
 providing this option will cause it to die.
 
---remove-empty::
+`--remove-empty`::
 	Stop when a given path disappears from the tree.
 
---merges::
+`--merges`::
 	Print only merge commits. This is exactly the same as `--min-parents=2`.
 
---no-merges::
+`--no-merges`::
 	Do not print commits with more than one parent. This is
 	exactly the same as `--max-parents=1`.
 
---min-parents=<number>::
---max-parents=<number>::
---no-min-parents::
---no-max-parents::
+`--min-parents=<number>`::
+`--max-parents=<number>`::
+`--no-min-parents`::
+`--no-max-parents`::
 	Show only commits which have at least (or at most) that many parent
 	commits. In particular, `--max-parents=1` is the same as `--no-merges`,
 	`--min-parents=2` is the same as `--merges`.  `--max-parents=0`
@@ -126,7 +126,7 @@ providing this option will cause it to die.
 again.  Equivalent forms are `--min-parents=0` (any commit has 0 or more
 parents) and `--max-parents=-1` (negative numbers denote no upper limit).
 
---first-parent::
+`--first-parent`::
 	When finding commits to include, follow only the first
 	parent commit upon seeing a merge commit.  This option
 	can give a better overview when viewing the evolution of
@@ -141,14 +141,14 @@ This option also changes default diff format for merge commits
 to `first-parent`, see `--diff-merges=first-parent` for details.
 endif::git-log[]
 
---exclude-first-parent-only::
+`--exclude-first-parent-only`::
 	When finding commits to exclude (with a '{caret}'), follow only
 	the first parent commit upon seeing a merge commit.
 	This can be used to find the set of changes in a topic branch
 	from the point where it diverged from the remote branch, given
 	that arbitrary merges can be valid topic branch changes.
 
---not::
+`--not`::
 	Reverses the meaning of the '{caret}' prefix (or lack thereof)
 	for all following revision specifiers, up to the next `--not`.
 	When used on the command line before --stdin, the revisions passed
@@ -156,37 +156,37 @@ endif::git-log[]
 	via standard input, the revisions passed on the command line will
 	not be affected by it.
 
---all::
+`--all`::
 	Pretend as if all the refs in `refs/`, along with `HEAD`, are
-	listed on the command line as '<commit>'.
+	listed on the command line as _<commit>_.
 
---branches[=<pattern>]::
+`--branches[=<pattern>]`::
 	Pretend as if all the refs in `refs/heads` are listed
-	on the command line as '<commit>'. If '<pattern>' is given, limit
-	branches to ones matching given shell glob. If pattern lacks '?',
+	on the command line as _<commit>_. If _<pattern>_ is given, limit
+	branches to ones matching given shell glob. If _<pattern>_ lacks '?',
 	'{asterisk}', or '[', '/{asterisk}' at the end is implied.
 
---tags[=<pattern>]::
+`--tags[=<pattern>]`::
 	Pretend as if all the refs in `refs/tags` are listed
-	on the command line as '<commit>'. If '<pattern>' is given, limit
+	on the command line as _<commit>_. If _<pattern>_ is given, limit
 	tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}',
 	or '[', '/{asterisk}' at the end is implied.
 
---remotes[=<pattern>]::
+`--remotes[=<pattern>]`::
 	Pretend as if all the refs in `refs/remotes` are listed
-	on the command line as '<commit>'. If '<pattern>' is given, limit
+	on the command line as _<commit>_. If _<pattern>_ is given, limit
 	remote-tracking branches to ones matching given shell glob.
 	If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied.
 
---glob=<glob-pattern>::
-	Pretend as if all the refs matching shell glob '<glob-pattern>'
-	are listed on the command line as '<commit>'. Leading 'refs/',
+`--glob=<glob-pattern>`::
+	Pretend as if all the refs matching shell glob _<glob-pattern>_
+	are listed on the command line as _<commit>_. Leading 'refs/',
 	is automatically prepended if missing. If pattern lacks '?', '{asterisk}',
 	or '[', '/{asterisk}' at the end is implied.
 
---exclude=<glob-pattern>::
+`--exclude=<glob-pattern>`::
 
-	Do not include refs matching '<glob-pattern>' that the next `--all`,
+	Do not include refs matching _<glob-pattern>_ that the next `--all`,
 	`--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
 	consider. Repetitions of this option accumulate exclusion patterns
 	up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
@@ -199,7 +199,7 @@ respectively, and they must begin with `refs/` when applied to `--glob`
 or `--all`. If a trailing '/{asterisk}' is intended, it must be given
 explicitly.
 
---exclude-hidden=[fetch|receive|uploadpack]::
+`--exclude-hidden=(fetch|receive|uploadpack)`::
 	Do not include refs that would be hidden by `git-fetch`,
 	`git-receive-pack` or `git-upload-pack` by consulting the appropriate
 	`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
@@ -207,11 +207,11 @@ explicitly.
 	linkgit:git-config[1]). This option affects the next pseudo-ref option
 	`--all` or `--glob` and is cleared after processing them.
 
---reflog::
+`--reflog`::
 	Pretend as if all objects mentioned by reflogs are listed on the
-	command line as `<commit>`.
+	command line as _<commit>_.
 
---alternate-refs::
+`--alternate-refs`::
 	Pretend as if all objects mentioned as ref tips of alternate
 	repositories were listed on the command line. An alternate
 	repository is any repository whose object directory is specified
@@ -219,7 +219,7 @@ explicitly.
 	be modified by `core.alternateRefsCommand`, etc. See
 	linkgit:git-config[1].
 
---single-worktree::
+`--single-worktree`::
 	By default, all working trees will be examined by the
 	following options when there are more than one (see
 	linkgit:git-worktree[1]): `--all`, `--reflog` and
@@ -227,19 +227,19 @@ explicitly.
 	This option forces them to examine the current working tree
 	only.
 
---ignore-missing::
+`--ignore-missing`::
 	Upon seeing an invalid object name in the input, pretend as if
 	the bad input was not given.
 
 ifndef::git-rev-list[]
---bisect::
+`--bisect`::
 	Pretend as if the bad bisection ref `refs/bisect/bad`
 	was listed and as if it was followed by `--not` and the good
 	bisection refs `refs/bisect/good-*` on the command
 	line.
 endif::git-rev-list[]
 
---stdin::
+`--stdin`::
 	In addition to getting arguments from the command line, read
 	them from standard input as well. This accepts commits and
 	pseudo-options like `--all` and `--glob=`. When a `--` separator
@@ -249,15 +249,15 @@ endif::git-rev-list[]
 	influence any subsequent command line arguments.
 
 ifdef::git-rev-list[]
---quiet::
+`--quiet`::
 	Don't print anything to standard output.  This form
 	is primarily meant to allow the caller to
 	test the exit status to see if a range of objects is fully
 	connected (or not).  It is faster than redirecting stdout
 	to `/dev/null` as the output does not have to be formatted.
 
---disk-usage::
---disk-usage=human::
+`--disk-usage`::
+`--disk-usage=human`::
 	Suppress normal output; instead, print the sum of the bytes used
 	for on-disk storage by the selected commits or objects. This is
 	equivalent to piping the output into `git cat-file
@@ -269,11 +269,11 @@ ifdef::git-rev-list[]
 	in human-readable string(e.g. 12.24 Kib, 3.50 Mib).
 endif::git-rev-list[]
 
---cherry-mark::
+`--cherry-mark`::
 	Like `--cherry-pick` (see below) but mark equivalent commits
 	with `=` rather than omitting them, and inequivalent ones with `+`.
 
---cherry-pick::
+`--cherry-pick`::
 	Omit any commit that introduces the same change as
 	another commit on the ``other side'' when the set of
 	commits are limited with symmetric difference.
@@ -286,8 +286,8 @@ cherry-picked from the other branch (for example, ``3rd on b'' may be
 cherry-picked from branch A). With this option, such pairs of commits are
 excluded from the output.
 
---left-only::
---right-only::
+`--left-only`::
+`--right-only`::
 	List only commits on the respective side of a symmetric difference,
 	i.e. only those which would be marked `<` resp. `>` by
 	`--left-right`.
@@ -298,20 +298,20 @@ commits from `B` which are in `A` or are patch-equivalent to a commit in
 More precisely, `--cherry-pick --right-only --no-merges` gives the exact
 list.
 
---cherry::
+`--cherry`::
 	A synonym for `--right-only --cherry-mark --no-merges`; useful to
 	limit the output to the commits on our side and mark those that
 	have been applied to the other side of a forked history with
 	`git log --cherry upstream...mybranch`, similar to
 	`git cherry upstream mybranch`.
 
--g::
---walk-reflogs::
+`-g`::
+`--walk-reflogs`::
 	Instead of walking the commit ancestry chain, walk
 	reflog entries from the most recent one to older ones.
 	When this option is used you cannot specify commits to
-	exclude (that is, '{caret}commit', 'commit1..commit2',
-	and 'commit1\...commit2' notations cannot be used).
+	exclude (that is, `^<commit>`, `<commit1>..<commit2>`,
+	and `<commit1>...<commit2>` notations cannot be used).
 +
 With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
 this causes the output to have two extra lines of information
@@ -340,27 +340,51 @@ See also linkgit:git-reflog[1].
 +
 Under `--pretty=reference`, this information will not be shown at all.
 
---merge::
+`--merge`::
 	Show commits touching conflicted paths in the range `HEAD...<other>`,
 	where `<other>` is the first existing pseudoref in `MERGE_HEAD`,
 	`CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works
 	when the index has unmerged entries. This option can be used to show
 	relevant commits when resolving conflicts from a 3-way merge.
 
---boundary::
+`--boundary`::
 	Output excluded boundary commits. Boundary commits are
 	prefixed with `-`.
 
 ifdef::git-rev-list[]
---use-bitmap-index::
+`--use-bitmap-index`::
 
 	Try to speed up the traversal using the pack bitmap index (if
 	one is available). Note that when traversing with `--objects`,
 	trees and blobs will not have their associated path printed.
 
---progress=<header>::
+`--progress=<header>`::
 	Show progress reports on stderr as objects are considered. The
 	`<header>` text will be printed with each progress update.
+
+`-z`::
+	Instead of being newline-delimited, each outputted object and its
+	accompanying metadata is delimited using NUL bytes. Output is printed
+	in the following form:
++
+-----------------------------------------------------------------------
+<OID> NUL [<token>=<value> NUL]...
+-----------------------------------------------------------------------
++
+Additional object metadata, such as object paths or boundary objects, is
+printed using the `<token>=<value>` form. Token values are printed as-is
+without any encoding/truncation. An OID entry never contains a '=' character
+and thus is used to signal the start of a new object record. Examples:
++
+-----------------------------------------------------------------------
+<OID> NUL
+<OID> NUL path=<path> NUL
+<OID> NUL boundary=yes NUL
+<OID> NUL missing=yes NUL [<token>=<value> NUL]...
+-----------------------------------------------------------------------
++
+This mode is only compatible with the `--objects`, `--boundary`, and
+`--missing` output options.
 endif::git-rev-list[]
 
 History Simplification
@@ -373,62 +397,63 @@ is how to do it, as there are various strategies to simplify the history.
 
 The following options select the commits to be shown:
 
-<paths>::
+`<paths>`::
 	Commits modifying the given <paths> are selected.
 
---simplify-by-decoration::
+`--simplify-by-decoration`::
 	Commits that are referred by some branch or tag are selected.
 
 Note that extra commits can be shown to give a meaningful history.
 
 The following options affect the way the simplification is performed:
 
-Default mode::
+`Default mode`::
 	Simplifies the history to the simplest history explaining the
 	final state of the tree. Simplest because it prunes some side
 	branches if the end result is the same (i.e. merging branches
 	with the same content)
 
---show-pulls::
+`--show-pulls`::
 	Include all commits from the default mode, but also any merge
 	commits that are not TREESAME to the first parent but are
 	TREESAME to a later parent. This mode is helpful for showing
 	the merge commits that "first introduced" a change to a branch.
 
---full-history::
+`--full-history`::
 	Same as the default mode, but does not prune some history.
 
---dense::
+`--dense`::
 	Only the selected commits are shown, plus some to have a
 	meaningful history.
 
---sparse::
+`--sparse`::
 	All commits in the simplified history are shown.
 
---simplify-merges::
+`--simplify-merges`::
 	Additional option to `--full-history` to remove some needless
 	merges from the resulting history, as there are no selected
 	commits contributing to this merge.
 
---ancestry-path[=<commit>]::
-	When given a range of commits to display (e.g. 'commit1..commit2'
-	or 'commit2 {caret}commit1'), and a commit <commit> in that range,
+`--ancestry-path[=<commit>]`::
+	When given a range of commits to display (e.g. `<commit1>..<commit2>`
+	or `<commit2> ^<commit1>`), and a commit _<commit>_ in that range,
 	only display commits in that range
-	that are ancestors of <commit>, descendants of <commit>, or
-	<commit> itself.  If no commit is specified, use 'commit1' (the
-	excluded part of the range) as <commit>.  Can be passed multiple
+	that are ancestors of _<commit>_, descendants of _<commit>_, or
+	_<commit>_ itself.  If no commit is specified, use _<commit1>_ (the
+	excluded part of the range) as _<commit>_.  Can be passed multiple
 	times; if so, a commit is included if it is any of the commits
 	given or if it is an ancestor or descendant of one of them.
 
 A more detailed explanation follows.
 
-Suppose you specified `foo` as the <paths>.  We shall call commits
+Suppose you specified `foo` as the _<paths>_.  We shall call commits
 that modify `foo` !TREESAME, and the rest TREESAME.  (In a diff
 filtered for `foo`, they look different and equal, respectively.)
 
 In the following, we will always refer to the same example history to
 illustrate the differences between simplification settings.  We assume
 that you are filtering for a file `foo` in this commit graph:
+
 -----------------------------------------------------------------------
 	  .-A---M---N---O---P---Q
 	 /     /   /   /   /   /
@@ -436,26 +461,27 @@ that you are filtering for a file `foo` in this commit graph:
 	 \   /   /   /   /   /
 	  `-------------'   X
 -----------------------------------------------------------------------
+
 The horizontal line of history A---Q is taken to be the first parent of
 each merge.  The commits are:
 
 * `I` is the initial commit, in which `foo` exists with contents
-  ``asdf'', and a file `quux` exists with contents ``quux''. Initial
+  `asdf`, and a file `quux` exists with contents `quux`. Initial
   commits are compared to an empty tree, so `I` is !TREESAME.
 
-* In `A`, `foo` contains just ``foo''.
+* In `A`, `foo` contains just `foo`.
 
 * `B` contains the same change as `A`.  Its merge `M` is trivial and
   hence TREESAME to all parents.
 
-* `C` does not change `foo`, but its merge `N` changes it to ``foobar'',
+* `C` does not change `foo`, but its merge `N` changes it to `foobar`,
   so it is not TREESAME to any parent.
 
-* `D` sets `foo` to ``baz''. Its merge `O` combines the strings from
-  `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent.
+* `D` sets `foo` to `baz`. Its merge `O` combines the strings from
+  `N` and `D` to `foobarbaz`; i.e., it is not TREESAME to any parent.
 
-* `E` changes `quux` to ``xyzzy'', and its merge `P` combines the
-  strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`.
+* `E` changes `quux` to `xyzzy`, and its merge `P` combines the
+  strings to `quux xyzzy`. `P` is TREESAME to `O`, but not to `E`.
 
 * `X` is an independent root commit that added a new file `side`, and `Y`
   modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and
@@ -491,7 +517,7 @@ Parent/child relations are only visible with `--parents`, but that does
 not affect the commits selected in default mode, so we have shown the
 parent lines.
 
---full-history without parent rewriting::
+`--full-history` without parent rewriting::
 	This mode differs from the default in one point: always follow
 	all parents of a merge, even if it is TREESAME to one of them.
 	Even if more than one side of the merge has commits that are
@@ -510,7 +536,7 @@ Note that without parent rewriting, it is not really possible to talk
 about the parent/child relationships between the commits, so we show
 them disconnected.
 
---full-history with parent rewriting::
+`--full-history` with parent rewriting::
 	Ordinary commits are only included if they are !TREESAME
 	(though this can be changed, see `--sparse` below).
 +
@@ -534,18 +560,18 @@ rewritten to contain `E`'s parent `I`.  The same happened for `C` and
 In addition to the above settings, you can change whether TREESAME
 affects inclusion:
 
---dense::
+`--dense`::
 	Commits that are walked are included if they are not TREESAME
 	to any parent.
 
---sparse::
+`--sparse`::
 	All commits that are walked are included.
 +
 Note that without `--full-history`, this still simplifies merges: if
 one of the parents is TREESAME, we follow only that one, so the other
 sides of the merge are never walked.
 
---simplify-merges::
+`--simplify-merges`::
 	First, build a history graph in the same way that
 	`--full-history` with parent rewriting does (see above).
 +
@@ -592,9 +618,9 @@ Note the major differences in `N`, `P`, and `Q` over `--full-history`:
 
 There is another simplification mode available:
 
---ancestry-path[=<commit>]::
+`--ancestry-path[=<commit>]`::
 	Limit the displayed commits to those which are an ancestor of
-	<commit>, or which are a descendant of <commit>, or are <commit>
+	_<commit>_, or which are a descendant of _<commit>_, or are _<commit>_
 	itself.
 +
 As an example use case, consider the following commit history:
@@ -610,15 +636,15 @@ As an example use case, consider the following commit history:
 A regular 'D..M' computes the set of commits that are ancestors of `M`,
 but excludes the ones that are ancestors of `D`. This is useful to see
 what happened to the history leading to `M` since `D`, in the sense
-that ``what does `M` have that did not exist in `D`''. The result in this
+that "what does `M` have that did not exist in `D`". The result in this
 example would be all the commits, except `A` and `B` (and `D` itself,
 of course).
 +
 When we want to find out what commits in `M` are contaminated with the
 bug introduced by `D` and need fixing, however, we might want to view
-only the subset of 'D..M' that are actually descendants of `D`, i.e.
+only the subset of `D..M` that are actually descendants of `D`, i.e.
 excluding `C` and `K`. This is exactly what the `--ancestry-path`
-option does. Applied to the 'D..M' range, it results in:
+option does. Applied to the `D..M` range, it results in:
 +
 -----------------------------------------------------------------------
 		E-------F
@@ -629,7 +655,7 @@ option does. Applied to the 'D..M' range, it results in:
 -----------------------------------------------------------------------
 +
 We can also use `--ancestry-path=D` instead of `--ancestry-path` which
-means the same thing when applied to the 'D..M' range but is just more
+means the same thing when applied to the `D..M` range but is just more
 explicit.
 +
 If we instead are interested in a given topic within this range, and all
@@ -640,7 +666,7 @@ commits affected by that topic, we may only want to view the subset of
 -----------------------------------------------------------------------
 		E
 		 \
-		  G---H---I---J
+	      C---G---H---I---J
 			       \
 				L--M
 -----------------------------------------------------------------------
@@ -744,7 +770,7 @@ into the important branch. This commit may have information about why
 the change `X` came to override the changes from `A` and `B` in its
 commit message.
 
---show-pulls::
+`--show-pulls`::
 	In addition to the commits shown in the default history, show
 	each merge commit that is not TREESAME to its first parent but
 	is TREESAME to a later parent.
@@ -793,7 +819,7 @@ ifdef::git-rev-list[]
 Bisection Helpers
 ~~~~~~~~~~~~~~~~~
 
---bisect::
+`--bisect`::
 	Limit output to the one commit object which is roughly halfway between
 	included and excluded commits. Note that the bad bisection ref
 	`refs/bisect/bad` is added to the included commits (if it
@@ -817,7 +843,7 @@ introduces a regression is thus reduced to a binary search: repeatedly
 generate and test new 'midpoint's until the commit chain is of length
 one.
 
---bisect-vars::
+`--bisect-vars`::
 	This calculates the same as `--bisect`, except that refs in
 	`refs/bisect/` are not used, and except that this outputs
 	text ready to be eval'ed by the shell. These lines will assign the
@@ -829,7 +855,7 @@ one.
 	`bisect_bad`, and the number of commits we are bisecting right now to
 	`bisect_all`.
 
---bisect-all::
+`--bisect-all`::
 	This outputs all the commit objects between the included and excluded
 	commits, ordered by their distance to the included and excluded
 	commits. Refs in `refs/bisect/` are not used. The farthest
@@ -852,15 +878,15 @@ Commit Ordering
 
 By default, the commits are shown in reverse chronological order.
 
---date-order::
+`--date-order`::
 	Show no parents before all of its children are shown, but
 	otherwise show commits in the commit timestamp order.
 
---author-date-order::
+`--author-date-order`::
 	Show no parents before all of its children are shown, but
 	otherwise show commits in the author timestamp order.
 
---topo-order::
+`--topo-order`::
 	Show no parents before all of its children are shown, and
 	avoid showing commits on multiple lines of history
 	intermixed.
@@ -884,8 +910,8 @@ With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
 avoid showing the commits from two parallel development track mixed
 together.
 
---reverse::
-	Output the commits chosen to be shown (see Commit Limiting
+`--reverse`::
+	Output the commits chosen to be shown (see 'Commit Limiting'
 	section above) in reverse order. Cannot be combined with
 	`--walk-reflogs`.
 endif::git-shortlog[]
@@ -897,39 +923,39 @@ Object Traversal
 These options are mostly targeted for packing of Git repositories.
 
 ifdef::git-rev-list[]
---objects::
+`--objects`::
 	Print the object IDs of any object referenced by the listed
-	commits.  `--objects foo ^bar` thus means ``send me
+	commits.  `--objects foo ^bar` thus means "send me
 	all object IDs which I need to download if I have the commit
-	object _bar_ but not _foo_''. See also `--object-names` below.
+	object `bar` but not `foo`". See also `--object-names` below.
 
---in-commit-order::
+`--in-commit-order`::
 	Print tree and blob ids in order of the commits. The tree
 	and blob ids are printed after they are first referenced
 	by a commit.
 
---objects-edge::
+`--objects-edge`::
 	Similar to `--objects`, but also print the IDs of excluded
-	commits prefixed with a ``-'' character.  This is used by
+	commits prefixed with a "`-`" character.  This is used by
 	linkgit:git-pack-objects[1] to build a ``thin'' pack, which records
 	objects in deltified form based on objects contained in these
 	excluded commits to reduce network traffic.
 
---objects-edge-aggressive::
+`--objects-edge-aggressive`::
 	Similar to `--objects-edge`, but it tries harder to find excluded
 	commits at the cost of increased time.  This is used instead of
 	`--objects-edge` to build ``thin'' packs for shallow repositories.
 
---indexed-objects::
+`--indexed-objects`::
 	Pretend as if all trees and blobs used by the index are listed
 	on the command line.  Note that you probably want to use
 	`--objects`, too.
 
---unpacked::
+`--unpacked`::
 	Only useful with `--objects`; print the object IDs that are not
 	in packs.
 
---object-names::
+`--object-names`::
 	Only useful with `--objects`; print the names of the object IDs
 	that are found. This is the default behavior. Note that the
 	"name" of each object is ambiguous, and mostly intended as a
@@ -938,52 +964,52 @@ ifdef::git-rev-list[]
 	to remove newlines; and if an object would appear multiple times
 	with different names, only one name is shown.
 
---no-object-names::
+`--no-object-names`::
 	Only useful with `--objects`; does not print the names of the object
 	IDs that are found. This inverts `--object-names`. This flag allows
 	the output to be more easily parsed by commands such as
 	linkgit:git-cat-file[1].
 
---filter=<filter-spec>::
+`--filter=<filter-spec>`::
 	Only useful with one of the `--objects*`; omits objects (usually
-	blobs) from the list of printed objects.  The '<filter-spec>'
+	blobs) from the list of printed objects.  The _<filter-spec>_
 	may be one of the following:
 +
-The form '--filter=blob:none' omits all blobs.
+The form `--filter=blob:none` omits all blobs.
 +
-The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n
-bytes or units.  n may be zero.  The suffixes k, m, and g can be used
-to name units in KiB, MiB, or GiB.  For example, 'blob:limit=1k'
+The form `--filter=blob:limit=<n>[kmg]` omits blobs of size at least _<n>_
+bytes or units.  _<n>_ may be zero.  The suffixes `k`, `m`, and `g` can be used
+to name units in KiB, MiB, or GiB.  For example, `blob:limit=1k`
 is the same as 'blob:limit=1024'.
 +
-The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects
+The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects
 which are not of the requested type.
 +
-The form '--filter=sparse:oid=<blob-ish>' uses a sparse-checkout
-specification contained in the blob (or blob-expression) '<blob-ish>'
+The form `--filter=sparse:oid=<blob-ish>` uses a sparse-checkout
+specification contained in the blob (or blob-expression) _<blob-ish>_
 to omit blobs that would not be required for a sparse checkout on
 the requested refs.
 +
-The form '--filter=tree:<depth>' omits all blobs and trees whose depth
-from the root tree is >= <depth> (minimum depth if an object is located
-at multiple depths in the commits traversed). <depth>=0 will not include
+The form `--filter=tree:<depth>` omits all blobs and trees whose depth
+from the root tree is >= _<depth>_ (minimum depth if an object is located
+at multiple depths in the commits traversed). _<depth>_=0 will not include
 any trees or blobs unless included explicitly in the command-line (or
-standard input when --stdin is used). <depth>=1 will include only the
+standard input when `--stdin` is used). _<depth>_=1 will include only the
 tree and blobs which are referenced directly by a commit reachable from
-<commit> or an explicitly-given object. <depth>=2 is like <depth>=1
+_<commit>_ or an explicitly-given object. _<depth>_=2 is like <depth>=1
 while also including trees and blobs one more level removed from an
 explicitly-given commit or tree.
 +
-Note that the form '--filter=sparse:path=<path>' that wants to read
+Note that the form `--filter=sparse:path=<path>` that wants to read
 from an arbitrary path on the filesystem has been dropped for security
 reasons.
 +
-Multiple '--filter=' flags can be specified to combine filters. Only
+Multiple `--filter=` flags can be specified to combine filters. Only
 objects which are accepted by every filter are included.
 +
-The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be
+The form `--filter=combine:<filter1>+<filter2>+...<filterN>` can also be
 used to combined several filters, but this is harder than just repeating
-the '--filter' flag and is usually not necessary. Filters are joined by
+the `--filter` flag and is usually not necessary. Filters are joined by
 '{plus}' and individual filters are %-encoded (i.e. URL-encoded).
 Besides the '{plus}' and '%' characters, the following characters are
 reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+&#39;&#96;+
@@ -991,44 +1017,63 @@ as well as all characters with ASCII code &lt;= `0x20`, which includes
 space and newline.
 +
 Other arbitrary characters can also be encoded. For instance,
-'combine:tree:3+blob:none' and 'combine:tree%3A3+blob%3Anone' are
+`combine:tree:3+blob:none` and `combine:tree%3A3+blob%3Anone` are
 equivalent.
 
---no-filter::
+`--no-filter`::
 	Turn off any previous `--filter=` argument.
 
---filter-provided-objects::
+`--filter-provided-objects`::
 	Filter the list of explicitly provided objects, which would otherwise
 	always be printed even if they did not match any of the filters. Only
 	useful with `--filter=`.
 
---filter-print-omitted::
+`--filter-print-omitted`::
 	Only useful with `--filter=`; prints a list of the objects omitted
 	by the filter.  Object IDs are prefixed with a ``~'' character.
 
---missing=<missing-action>::
+`--missing=<missing-action>`::
 	A debug option to help with future "partial clone" development.
 	This option specifies how missing objects are handled.
 +
-The form '--missing=error' requests that rev-list stop with an error if
+The form `--missing=error` requests that rev-list stop with an error if
 a missing object is encountered.  This is the default action.
 +
-The form '--missing=allow-any' will allow object traversal to continue
+The form `--missing=allow-any` will allow object traversal to continue
 if a missing object is encountered.  Missing objects will silently be
 omitted from the results.
 +
-The form '--missing=allow-promisor' is like 'allow-any', but will only
+The form `--missing=allow-promisor` is like `allow-any`, but will only
 allow object traversal to continue for EXPECTED promisor missing objects.
 Unexpected missing objects will raise an error.
 +
-The form '--missing=print' is like 'allow-any', but will also print a
+The form `--missing=print` is like `allow-any`, but will also print a
 list of the missing objects.  Object IDs are prefixed with a ``?'' character.
 +
+The form `--missing=print-info` is like `print`, but will also print additional
+information about the missing object inferred from its containing object. The
+information is all printed on the same line with the missing object ID in the
+form: `?<oid> [<token>=<value>]...`. The `<token>=<value>` pairs containing
+additional information are separated from each other by a _SP_. The value is
+encoded in a token specific fashion, but _SP_ or _LF_ contained in value are always
+expected to be represented in such a way that the resulting encoded value does
+not have either of these two problematic bytes. Each `<token>=<value>` may be
+one of the following:
++
+--
+* The `path=<path>` shows the path of the missing object inferred from a
+  containing object. A path containing _SP_ or special characters is enclosed in
+  double-quotes in the C style as needed.
++
+* The `type=<type>` shows the type of the missing object inferred from a
+  containing object.
+--
++
 If some tips passed to the traversal are missing, they will be
 considered as missing too, and the traversal will ignore them. In case
 we cannot get their Object ID though, an error will be raised.
 
---exclude-promisor-objects::
+`--exclude-promisor-objects`::
 	(For internal use only.)  Prefilter object traversal at
 	promisor boundary.  This is used with partial clone.  This is
 	stronger than `--missing=allow-promisor` because it limits the
@@ -1036,7 +1081,7 @@ we cannot get their Object ID though, an error will be raised.
 	objects.
 endif::git-rev-list[]
 
---no-walk[=(sorted|unsorted)]::
+`--no-walk[=(sorted|unsorted)]`::
 	Only show the given commits, but do not traverse their ancestors.
 	This has no effect if a range is specified. If the argument
 	`unsorted` is given, the commits are shown in the order they were
@@ -1045,7 +1090,7 @@ endif::git-rev-list[]
 	by commit time.
 	Cannot be combined with `--graph`.
 
---do-walk::
+`--do-walk`::
 	Overrides a previous `--no-walk`.
 endif::git-shortlog[]
 
@@ -1055,16 +1100,21 @@ Commit Formatting
 
 ifdef::git-rev-list[]
 Using these options, linkgit:git-rev-list[1] will act similar to the
-more specialized family of commit log tools: linkgit:git-log[1],
-linkgit:git-show[1], and linkgit:git-whatchanged[1]
+more specialized family of commit log tools:
+ifndef::with-breaking-changes[]
+linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1].
+endif::with-breaking-changes[]
+ifdef::with-breaking-changes[]
+linkgit:git-log[1] and linkgit:git-show[1].
+endif::with-breaking-changes[]
 endif::git-rev-list[]
 
-include::pretty-options.txt[]
+include::pretty-options.adoc[]
 
---relative-date::
+`--relative-date`::
 	Synonym for `--date=relative`.
 
---date=<format>::
+`--date=<format>`::
 	Only takes effect for dates shown in human-readable format, such
 	as when using `--pretty`. `log.date` config variable sets a default
 	value for the log command's `--date` option. By default, dates
@@ -1114,12 +1164,12 @@ omitted.
 1970).  As with `--raw`, this is always in UTC and therefore `-local`
 has no effect.
 
-`--date=format:...` feeds the format `...` to your system `strftime`,
-except for %s, %z, and %Z, which are handled internally.
+`--date=format:<format>` feeds the _<format>_ to your system `strftime`,
+except for `%s`, `%z`, and `%Z`, which are handled internally.
 Use `--date=format:%c` to show the date in your system locale's
-preferred format.  See the `strftime` manual for a complete list of
+preferred format.  See the `strftime`(3) manual for a complete list of
 format placeholders. When using `-local`, the correct syntax is
-`--date=format-local:...`.
+`--date=format-local:<format>`.
 
 `--date=default` is the default format, and is based on ctime(3)
 output.  It shows a single line with three-letter day of the week,
@@ -1129,33 +1179,33 @@ the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`.
 --
 
 ifdef::git-rev-list[]
---header::
+`--header`::
 	Print the contents of the commit in raw-format; each record is
 	separated with a NUL character.
 
---no-commit-header::
+`--no-commit-header`::
 	Suppress the header line containing "commit" and the object ID printed before
 	the specified format.  This has no effect on the built-in formats; only custom
 	formats are affected.
 
---commit-header::
+`--commit-header`::
 	Overrides a previous `--no-commit-header`.
 endif::git-rev-list[]
 
---parents::
+`--parents`::
 	Print also the parents of the commit (in the form "commit parent...").
 	Also enables parent rewriting, see 'History Simplification' above.
 
---children::
+`--children`::
 	Print also the children of the commit (in the form "commit child...").
 	Also enables parent rewriting, see 'History Simplification' above.
 
 ifdef::git-rev-list[]
---timestamp::
+`--timestamp`::
 	Print the raw commit timestamp.
 endif::git-rev-list[]
 
---left-right::
+`--left-right`::
 	Mark which side of a symmetric difference a commit is reachable from.
 	Commits from the left side are prefixed with `<` and those from
 	the right with `>`.  If combined with `--boundary`, those
@@ -1184,7 +1234,7 @@ you would get an output like this:
 	-xxxxxxx... 1st on a
 -----------------------------------------------------------------------
 
---graph::
+`--graph`::
 	Draw a text-based graphical representation of the commit history
 	on the left hand side of the output.  This may cause extra lines
 	to be printed in between commits, in order for the graph history
@@ -1196,15 +1246,15 @@ This enables parent rewriting, see 'History Simplification' above.
 This implies the `--topo-order` option by default, but the
 `--date-order` option may also be specified.
 
---show-linear-break[=<barrier>]::
-	When --graph is not used, all history branches are flattened
+`--show-linear-break[=<barrier>]`::
+	When `--graph` is not used, all history branches are flattened
 	which can make it hard to see that the two consecutive commits
 	do not belong to a linear branch. This option puts a barrier
-	in between them in that case. If `<barrier>` is specified, it
+	in between them in that case. If _<barrier>_ is specified, it
 	is the string that will be shown instead of the default one.
 
 ifdef::git-rev-list[]
---count::
+`--count`::
 	Print a number stating how many commits would have been
 	listed, and suppress all other output.  When used together
 	with `--left-right`, instead print the counts for left and
diff --git a/Documentation/revisions.txt b/Documentation/revisions.adoc
index 6ea6c7cead..6ea6c7cead 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.adoc
diff --git a/Documentation/scalar.txt b/Documentation/scalar.adoc
index 7e4259c674..f81b2832f8 100644
--- a/Documentation/scalar.txt
+++ b/Documentation/scalar.adoc
@@ -9,12 +9,12 @@ SYNOPSIS
 --------
 [verse]
 scalar clone [--single-branch] [--branch <main-branch>] [--full-clone]
-	[--[no-]src] <url> [<enlistment>]
+	[--[no-]src] [--[no-]tags] [--[no-]maintenance] <url> [<enlistment>]
 scalar list
-scalar register [<enlistment>]
+scalar register [--[no-]maintenance] [<enlistment>]
 scalar unregister [<enlistment>]
 scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]
-scalar reconfigure [ --all | <enlistment> ]
+scalar reconfigure [--maintenance=(enable|disable|keep)] [ --all | <enlistment> ]
 scalar diagnose [<enlistment>]
 scalar delete <enlistment>
 
@@ -71,7 +71,8 @@ HEAD[:<directory>]`.
 	Instead of checking out the branch pointed to by the cloned
 	repository's HEAD, check out the `<name>` branch instead.
 
---[no-]single-branch::
+--single-branch::
+--no-single-branch::
 	Clone only the history leading to the tip of a single branch, either
 	specified by the `--branch` option or the primary branch remote's
 	`HEAD` points at.
@@ -81,22 +82,31 @@ remote-tracking branch for the branch this option was used for the initial
 cloning. If the HEAD at the remote did not point at any branch when
 `--single-branch` clone was made, no remote-tracking branch is created.
 
---[no-]src::
+--src::
+--no-src::
 	By default, `scalar clone` places the cloned repository within a
 	`<entlistment>/src` directory. Use `--no-src` to place the cloned
 	repository directly in the `<enlistment>` directory.
 
---[no-]tags::
+--tags::
+--no-tags::
 	By default, `scalar clone` will fetch the tag objects advertised by
 	the remote and future `git fetch` commands will do the same. Use
 	`--no-tags` to avoid fetching tags in `scalar clone` and to configure
 	the repository to avoid fetching tags in the future. To fetch tags after
 	cloning with `--no-tags`, run `git fetch --tags`.
 
---[no-]full-clone::
+--full-clone::
+--no-full-clone::
 	A sparse-checkout is initialized by default. This behavior can be
 	turned off via `--full-clone`.
 
+--maintenance::
+--no-maintenance::
+	By default, `scalar clone` configures the enlistment to use Git's
+	background maintenance feature. Use the `--no-maintenance` to skip
+	this configuration.
+
 List
 ~~~~
 
@@ -117,6 +127,13 @@ Note: when this subcommand is called in a worktree that is called `src/`, its
 parent directory is considered to be the Scalar enlistment. If the worktree is
 _not_ called `src/`, it itself will be considered to be the Scalar enlistment.
 
+--maintenance::
+--no-maintenance::
+	By default, `scalar register` configures the enlistment to use Git's
+	background maintenance feature. Use the `--no-maintenance` to skip
+	this configuration. This does not disable any maintenance that may
+	already be enabled in other ways.
+
 Unregister
 ~~~~~~~~~~
 
@@ -149,8 +166,18 @@ After a Scalar upgrade, or when the configuration of a Scalar enlistment
 was somehow corrupted or changed by mistake, this subcommand allows to
 reconfigure the enlistment.
 
-With the `--all` option, all enlistments currently registered with Scalar
-will be reconfigured. Use this option after each Scalar upgrade.
+--all::
+	When `--all` is specified, reconfigure all enlistments currently
+	registered with Scalar by the `scalar.repo` config key. Use this
+	option after each upgrade to get the latest features.
+
+--maintenance=(enable|disable|keep)::
+	By default, Scalar configures the enlistment to use Git's
+	background maintenance feature; this is the same as using the
+	`enable` value for this option. Use the	`disable` value to
+	remove each considered enlistment from background maintenance.
+	Use `keep' to leave the background maintenance configuration
+	untouched for these repositories.
 
 Diagnose
 ~~~~~~~~
diff --git a/Documentation/sequencer.txt b/Documentation/sequencer.adoc
index 3bceb56474..3bceb56474 100644
--- a/Documentation/sequencer.txt
+++ b/Documentation/sequencer.adoc
diff --git a/Documentation/signoff-option.txt b/Documentation/signoff-option.adoc
index d98758f3cb..cddfb225d1 100644
--- a/Documentation/signoff-option.txt
+++ b/Documentation/signoff-option.adoc
@@ -1,8 +1,8 @@
 ifdef::git-commit[]
--s::
+`-s`::
 endif::git-commit[]
---signoff::
---no-signoff::
+`--signoff`::
+`--no-signoff`::
 	Add a `Signed-off-by` trailer by the committer at the end of the commit
 	log message.  The meaning of a signoff depends on the project
 	to which you're committing.  For example, it may certify that
@@ -14,5 +14,5 @@ endif::git-commit[]
 	leadership of the project to which you're contributing to
 	understand how the signoffs are used in that project.
 +
-The --no-signoff option can be used to countermand an earlier --signoff
+The `--no-signoff` option can be used to countermand an earlier `--signoff`
 option on the command line.
diff --git a/Documentation/technical/.gitignore b/Documentation/technical/.gitignore
index 8aa891daee..3caef14a93 100644
--- a/Documentation/technical/.gitignore
+++ b/Documentation/technical/.gitignore
@@ -1 +1,2 @@
 api-index.txt
+api-index.adoc
diff --git a/Documentation/technical/api-error-handling.txt b/Documentation/technical/api-error-handling.adoc
index 665c4960b4..665c4960b4 100644
--- a/Documentation/technical/api-error-handling.txt
+++ b/Documentation/technical/api-error-handling.adoc
diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.adoc
index 7780a76b08..7780a76b08 100644
--- a/Documentation/technical/api-index-skel.txt
+++ b/Documentation/technical/api-index-skel.adoc
diff --git a/Documentation/technical/api-index.sh b/Documentation/technical/api-index.sh
index 2964885574..dd206b1ca4 100755
--- a/Documentation/technical/api-index.sh
+++ b/Documentation/technical/api-index.sh
@@ -13,18 +13,18 @@ OUTPUT="$2"
 	cd "$SOURCE_DIR"
 
 	c=////////////////////////////////////////////////////////////////
-	skel=api-index-skel.txt
+	skel=api-index-skel.adoc
 	sed -e '/^\/\/ table of contents begin/q' "$skel"
 	echo "$c"
 
-	ls api-*.txt |
+	ls api-*.adoc |
 	while read filename
 	do
 		case "$filename" in
-		api-index-skel.txt | api-index.txt) continue ;;
+		api-index-skel.adoc | api-index.adoc) continue ;;
 		esac
 		title=$(sed -e 1q "$filename")
-		html=${filename%.txt}.html
+		html=${filename%.adoc}.html
 		echo "* link:$html[$title]"
 	done
 	echo "$c"
diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.adoc
index c2ba01828c..c2ba01828c 100644
--- a/Documentation/technical/api-merge.txt
+++ b/Documentation/technical/api-merge.adoc
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.adoc
index 61fa6ee167..880eb94642 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.adoc
@@ -211,11 +211,13 @@ There are some macros to easily define options:
 	Use of `--no-option` will clear the list of preceding values.
 
 `OPT_INTEGER(short, long, &int_var, description)`::
-	Introduce an option with integer argument.
-	The integer is put into `int_var`.
+	Introduce an option with integer argument. The argument must be a
+	integer and may include a suffix of 'k', 'm' or 'g' to
+	scale the provided value by 1024, 1024^2 or 1024^3 respectively.
+	The scaled value is put into `int_var`.
 
-`OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`::
-	Introduce an option with a size argument. The argument must be a
+`OPT_UNSIGNED(short, long, &unsigned_long_var, description)`::
+	Introduce an option with an unsigned integer argument. The argument must be a
 	non-negative integer and may include a suffix of 'k', 'm' or 'g' to
 	scale the provided value by 1024, 1024^2 or 1024^3 respectively.
 	The scaled value is put into `unsigned_long_var`.
diff --git a/Documentation/technical/api-path-walk.adoc b/Documentation/technical/api-path-walk.adoc
new file mode 100644
index 0000000000..a67de1b143
--- /dev/null
+++ b/Documentation/technical/api-path-walk.adoc
@@ -0,0 +1,84 @@
+Path-Walk API
+=============
+
+The path-walk API is used to walk reachable objects, but to visit objects
+in batches based on a common path they appear in, or by type.
+
+For example, all reachable commits are visited in a group. All tags are
+visited in a group. Then, all root trees are visited. At some point, all
+blobs reachable via a path `my/dir/to/A` are visited. When there are
+multiple paths possible to reach the same object, then only one of those
+paths is used to visit the object.
+
+Basics
+------
+
+To use the path-walk API, include `path-walk.h` and call
+`walk_objects_by_path()` with a customized `path_walk_info` struct. The
+struct is used to set all of the options for how the walk should proceed.
+Let's dig into the different options and their use.
+
+`path_fn` and `path_fn_data`::
+	The most important option is the `path_fn` option, which is a
+	function pointer to the callback that can execute logic on the
+	object IDs for objects grouped by type and path. This function
+	also receives a `data` value that corresponds to the
+	`path_fn_data` member, for providing custom data structures to
+	this callback function.
+
+`revs`::
+	To configure the exact details of the reachable set of objects,
+	use the `revs` member and initialize it using the revision
+	machinery in `revision.h`. Initialize `revs` using calls such as
+	`setup_revisions()` or `parse_revision_opt()`. Do not call
+	`prepare_revision_walk()`, as that will be called within
+	`walk_objects_by_path()`.
++
+It is also important that you do not specify the `--objects` flag for the
+`revs` struct. The revision walk should only be used to walk commits, and
+the objects will be walked in a separate way based on those starting
+commits.
+
+`commits`::
+`blobs`::
+`trees`::
+`tags`::
+	By default, these members are enabled and signal that the path-walk
+	API should call the `path_fn` on objects of these types. Specialized
+	applications could disable some options to make it simpler to walk
+	the objects or to have fewer calls to `path_fn`.
++
+While it is possible to walk only commits in this way, consumers would be
+better off using the revision walk API instead.
+
+`prune_all_uninteresting`::
+	By default, all reachable paths are emitted by the path-walk API.
+	This option allows consumers to declare that they are not
+	interested in paths where all included objects are marked with the
+	`UNINTERESTING` flag. This requires using the `boundary` option in
+	the revision walk so that the walk emits commits marked with the
+	`UNINTERESTING` flag.
+
+`edge_aggressive`::
+	For performance reasons, usually only the boundary commits are
+	explored to find UNINTERESTING objects. However, in the case of
+	shallow clones it can be helpful to mark all trees and blobs
+	reachable from UNINTERESTING tip commits as UNINTERESTING. This
+	matches the behavior of `--objects-edge-aggressive` in the
+	revision API.
+
+`pl`::
+	This pattern list pointer allows focusing the path-walk search to
+	a set of patterns, only emitting paths that match the given
+	patterns. See linkgit:gitignore[5] or
+	linkgit:git-sparse-checkout[1] for details about pattern lists.
+	When the pattern list uses cone-mode patterns, then the path-walk
+	API can prune the set of paths it walks to improve performance.
+
+Examples
+--------
+
+See example usages in:
+	`t/helper/test-path-walk.c`,
+	`builtin/pack-objects.c`,
+	`builtin/backfill.c`
diff --git a/Documentation/technical/api-simple-ipc.txt b/Documentation/technical/api-simple-ipc.adoc
index c4fb152b23..972178b042 100644
--- a/Documentation/technical/api-simple-ipc.txt
+++ b/Documentation/technical/api-simple-ipc.adoc
@@ -36,7 +36,7 @@ Comparison with sub-process model
 ---------------------------------
 
 The Simple-IPC mechanism differs from the existing `sub-process.c`
-model (Documentation/technical/long-running-process-protocol.txt) and
+model (Documentation/technical/long-running-process-protocol.adoc) and
 used by applications like Git-LFS.  In the LFS-style sub-process model,
 the helper is started by the foreground process, communication happens
 via a pair of file descriptors bound to the stdin/stdout of the
diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.adoc
index 5817b18310..cf493dae03 100644
--- a/Documentation/technical/api-trace2.txt
+++ b/Documentation/technical/api-trace2.adoc
@@ -140,7 +140,7 @@ $ cat ~/log.event
 To enable a target, set the corresponding environment variable or
 system or global config value to one of the following:
 
-include::../trace2-target-values.txt[]
+include::../trace2-target-values.adoc[]
 
 When trace files are written to a target directory, they will be named according
 to the last component of the SID (optionally followed by a counter to avoid
diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/technical/bitmap-format.adoc
index bfb0ec7beb..bfb0ec7beb 100644
--- a/Documentation/technical/bitmap-format.txt
+++ b/Documentation/technical/bitmap-format.adoc
diff --git a/Documentation/technical/build-systems.txt b/Documentation/technical/build-systems.adoc
index d9dafb407c..3c5237b9fd 100644
--- a/Documentation/technical/build-systems.txt
+++ b/Documentation/technical/build-systems.adoc
@@ -32,7 +32,10 @@ that generally have somebody running test pipelines against regularly:
   - OpenBSD
 
 The platforms which must be supported by the tool should be aligned with our
-[platform support policy](platform-support.txt).
+platform support policy (see platform-support.adoc).
+// once we lose AsciiDoc compatibility, we can start writing the above as:
+// xref:platform-support.adoc#platform-support-policy[platform support policy]
+// or something like that, but until then....
 
 === Auto-detection of supported features
 
diff --git a/Documentation/technical/bundle-uri.txt b/Documentation/technical/bundle-uri.adoc
index 91d3a13e32..12283fa9ed 100644
--- a/Documentation/technical/bundle-uri.txt
+++ b/Documentation/technical/bundle-uri.adoc
@@ -232,13 +232,13 @@ will interact with bundle URIs according to the following flow:
    are present in the client repository. If some are missing, then the
    client delays unbundling until other bundles have been unbundled,
    making those OIDs present. When all required OIDs are present, the
-   client unbundles that data using a refspec. The default refspec is
-   `+refs/heads/*:refs/bundles/*`, but this can be configured. These refs
-   are stored so that later `git fetch` negotiations can communicate each
-   bundled ref as a `have`, reducing the size of the fetch over the Git
-   protocol. To allow pruning refs from this ref namespace, Git may
-   introduce a numbered namespace (such as `refs/bundles/<i>/*`) such that
-   stale bundle refs can be deleted.
+   client unbundles that data using a refspec. The refspec used is
+   `+refs/*:refs/bundles/*`. These refs are stored so that later
+   `git fetch` negotiations can communicate each bundled ref as a `have`,
+   reducing the size of the fetch over the Git protocol. To allow pruning
+   refs from this ref namespace, Git may introduce a numbered namespace
+   (such as `refs/bundles/<i>/*`) such that stale bundle refs can be
+   deleted.
 
 3. If the file is instead a bundle list, then the client inspects the
    `bundle.mode` to see if the list is of the `all` or `any` form.
diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.adoc
index 2c26e95e51..a259d1567b 100644
--- a/Documentation/technical/commit-graph.txt
+++ b/Documentation/technical/commit-graph.adoc
@@ -39,6 +39,7 @@ A consumer may load the following info for a commit from the graph:
 Values 1-4 satisfy the requirements of parse_commit_gently().
 
 There are two definitions of generation number:
+
 1. Corrected committer dates (generation number v2)
 2. Topological levels (generation number v1)
 
@@ -158,7 +159,8 @@ number of commits in the full history. By creating a "chain" of commit-graphs,
 we enable fast writes of new commit data without rewriting the entire commit
 history -- at least, most of the time.
 
-## File Layout
+File Layout
+~~~~~~~~~~~
 
 A commit-graph chain uses multiple files, and we use a fixed naming convention
 to organize these files. Each commit-graph file has a name
@@ -170,11 +172,11 @@ hashes for the files in order from "lowest" to "highest".
 
 For example, if the `commit-graph-chain` file contains the lines
 
-```
+----
 	{hash0}
 	{hash1}
 	{hash2}
-```
+----
 
 then the commit-graph chain looks like the following diagram:
 
@@ -213,7 +215,8 @@ specifying the hashes of all files in the lower layers. In the above example,
 `graph-{hash1}.graph` contains `{hash0}` while `graph-{hash2}.graph` contains
 `{hash0}` and `{hash1}`.
 
-## Merging commit-graph files
+Merging commit-graph files
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If we only added a new commit-graph file on every write, we would run into a
 linear search problem through many commit-graph files.  Instead, we use a merge
@@ -225,6 +228,7 @@ is determined by the merge strategy that the files should collapse to
 the commits in `graph-{hash1}` should be combined into a new `graph-{hash3}`
 file.
 
+....
 			    +---------------------+
 			    |                     |
 			    |    (new commits)    |
@@ -250,6 +254,7 @@ file.
  |                       |
  |                       |
  +-----------------------+
+....
 
 During this process, the commits to write are combined, sorted and we write the
 contents to a temporary file, all while holding a `commit-graph-chain.lock`
@@ -257,14 +262,15 @@ lock-file.  When the file is flushed, we rename it to `graph-{hash3}`
 according to the computed `{hash3}`. Finally, we write the new chain data to
 `commit-graph-chain.lock`:
 
-```
+----
 	{hash3}
 	{hash0}
-```
+----
 
 We then close the lock-file.
 
-## Merge Strategy
+Merge Strategy
+~~~~~~~~~~~~~~
 
 When writing a set of commits that do not exist in the commit-graph stack of
 height N, we default to creating a new file at level N + 1. We then decide to
@@ -289,7 +295,8 @@ The merge strategy values (2 for the size multiple, 64,000 for the maximum
 number of commits) could be extracted into config settings for full
 flexibility.
 
-## Handling Mixed Generation Number Chains
+Handling Mixed Generation Number Chains
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 With the introduction of generation number v2 and generation data chunk, the
 following scenario is possible:
@@ -318,7 +325,8 @@ have corrected commit dates when written by compatible versions of Git. Thus,
 rewriting split commit-graph as a single file (`--split=replace`) creates a
 single layer with corrected commit dates.
 
-## Deleting graph-{hash} files
+Deleting graph-\{hash\} files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After a new tip file is written, some `graph-{hash}` files may no longer
 be part of a chain. It is important to remove these files from disk, eventually.
@@ -333,7 +341,8 @@ files whose modified times are older than a given expiry window. This window
 defaults to zero, but can be changed using command-line arguments or a config
 setting.
 
-## Chains across multiple object directories
+Chains across multiple object directories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In a repo with alternates, we look for the `commit-graph-chain` file starting
 in the local object directory and then in each alternate. The first file that
diff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.adoc
index 029ee2cedc..029ee2cedc 100644
--- a/Documentation/technical/directory-rename-detection.txt
+++ b/Documentation/technical/directory-rename-detection.adoc
diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.adoc
index 7102c7c8f5..2359d7d106 100644
--- a/Documentation/technical/hash-function-transition.txt
+++ b/Documentation/technical/hash-function-transition.adoc
@@ -227,9 +227,9 @@ network byte order):
     ** 4-byte length in bytes of shortened object names. This is the
       shortest possible length needed to make names in the shortened
       object name table unambiguous.
-    ** 4-byte integer, recording where tables relating to this format
+    ** 8-byte integer, recording where tables relating to this format
       are stored in this index file, as an offset from the beginning.
-  * 4-byte offset to the trailer from the beginning of this file.
+  * 8-byte offset to the trailer from the beginning of this file.
   * Zero or more additional key/value pairs (4-byte key, 4-byte
     value). Only one key is supported: 'PSRC'. See the "Loose objects
     and unreachable objects" section for supported values and how this
@@ -260,12 +260,10 @@ network byte order):
     compressed data to be copied directly from pack to pack during
     repacking without undetected data corruption.
 
-  * A table of 4-byte offset values. For an object in the table of
-    sorted shortened object names, the value at the corresponding
-    index in this table indicates where that object can be found in
-    the pack file. These are usually 31-bit pack file offsets, but
-    large offsets are encoded as an index into the next table with the
-    most significant bit set.
+  * A table of 4-byte offset values. The index of this table in pack order
+    indicates where that object can be found in the pack file. These are
+    usually 31-bit pack file offsets, but large offsets are encoded as
+    an index into the next table with the most significant bit set.
 
   * A table of 8-byte offset entries (empty for pack files less than
     2 GiB). Pack files are organized with heavily used objects toward
@@ -276,10 +274,14 @@ network byte order):
   up to and not including the table of CRC32 values.
 - Zero or more NUL bytes.
 - The trailer consists of the following:
-  * A copy of the 20-byte SHA-256 checksum at the end of the
+  * A copy of the full main hash checksum at the end of the
     corresponding packfile.
 
-  * 20-byte SHA-256 checksum of all of the above.
+  * Full main hash checksum of all of the above.
+
+The "full main hash" is a full-length hash of the main (not compatibility)
+algorithm in the repository.  Thus, if the main algorithm is SHA-256, this is
+a 32-byte SHA-256 hash and for SHA-1, it's a 20-byte SHA-1 hash.
 
 Loose object index
 ~~~~~~~~~~~~~~~~~~
@@ -394,7 +396,7 @@ inflated again in step 3, for a total of two inflations.
 
 Step 4 is probably necessary for good read-time performance. "git
 pack-objects" on the server optimizes the pack file for good data
-locality (see Documentation/technical/pack-heuristics.txt).
+locality (see Documentation/technical/pack-heuristics.adoc).
 
 Details of this process are likely to change. It will take some
 experimenting to get this to perform well.
@@ -427,17 +429,19 @@ ordinary unsigned commit.
 
 Signed Tags
 ~~~~~~~~~~~
-We add a new field "gpgsig-sha256" to the tag object format to allow
-signing tags without relying on SHA-1. Its signed payload is the
-SHA-256 content of the tag with its gpgsig-sha256 field and "-----BEGIN PGP
-SIGNATURE-----" delimited in-body signature removed.
-
-This means tags can be signed
-
-1. using SHA-1 only, as in existing signed tag objects
-2. using both SHA-1 and SHA-256, by using gpgsig-sha256 and an in-body
-   signature.
-3. using only SHA-256, by only using the gpgsig-sha256 field.
+We add new fields "gpgsig" and "gpgsig-sha256" to the tag object format to
+allow signing tags in both formats.  The in-body signature is used for the
+signature in the current hash algorithm and the header is used for the
+signature in the other algorithm.  Thus, a dual-signature tag will contain both
+an in-body signature and a gpgsig-sha256 header for the SHA-1 format of an
+object or both an in-body signature and a gpgsig header for the SHA-256 format
+of and object.
+
+The signed payload of the tag is the content of the tag in the current
+algorithm with both its gpgsig and gpgsig-sha256 fields and
+"-----BEGIN PGP SIGNATURE-----" delimited in-body signature removed.
+
+This means tags can be signed using one or both algorithms.
 
 Mergetag embedding
 ~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/technical/large-object-promisors.adoc b/Documentation/technical/large-object-promisors.adoc
new file mode 100644
index 0000000000..2aa815e023
--- /dev/null
+++ b/Documentation/technical/large-object-promisors.adoc
@@ -0,0 +1,656 @@
+Large Object Promisors
+======================
+
+Since Git has been created, users have been complaining about issues
+with storing large files in Git. Some solutions have been created to
+help, but they haven't helped much with some issues.
+
+Git currently supports multiple promisor remotes, which could help
+with some of these remaining issues, but it's very hard to use them to
+help, because a number of important features are missing.
+
+The goal of the effort described in this document is to add these
+important features.
+
+We will call a "Large Object Promisor", or "LOP" in short, a promisor
+remote which is used to store only large blobs and which is separate
+from the main remote that should store the other Git objects and the
+rest of the repos.
+
+By extension, we will also call "Large Object Promisor", or LOP, the
+effort described in this document to add a set of features to make it
+easier to handle large blobs/files in Git by using LOPs.
+
+This effort aims to especially improve things on the server side, and
+especially for large blobs that are already compressed in a binary
+format.
+
+This effort aims to provide an alternative to Git LFS
+(https://git-lfs.com/) and similar tools like git-annex
+(https://git-annex.branchable.com/) for handling large files, even
+though a complete alternative would very likely require other efforts
+especially on the client side, where it would likely help to implement
+a new object representation for large blobs as discussed in:
+
+https://lore.kernel.org/git/xmqqbkdometi.fsf@gitster.g/
+
+Non goals
+---------
+
+- We will not discuss those client side improvements here, as they
+  would require changes in different parts of Git than this effort.
++
+So we don't pretend to fully replace Git LFS with only this effort,
+but we nevertheless believe that it can significantly improve the
+current situation on the server side, and that other separate
+efforts could also improve the situation on the client side.
+
+- In the same way, we are not going to discuss all the possible ways
+  to implement a LOP or their underlying object storage, or to
+  optimize how LOP works.
++
+Our opinion is that the simplest solution for now is for LOPs to use
+object storage through a remote helper (see section II.2 below for
+more details) to store their objects. So we consider that this is the
+default implementation. If there are improvements on top of this,
+that's great, but our opinion is that such improvements are not
+necessary for LOPs to already be useful. Such improvements are likely
+a different technical topic, and can be taken care of separately
+anyway.
++
+So in particular we are not going to discuss pluggable ODBs or other
+object database backends that could chunk large blobs, dedup the
+chunks and store them efficiently. Sure, that would be a nice
+improvement to store large blobs on the server side, but we believe
+it can just be a separate effort as it's also not technically very
+related to this effort.
++
+We are also not going to discuss data transfer improvements between
+LOPs and clients or servers. Sure, there might be some easy and very
+effective optimizations there (as we know that objects on LOPs are
+very likely incompressible and not deltifying well), but this can be
+dealt with separately in a separate effort.
+
+In other words, the goal of this document is not to talk about all the
+possible ways to optimize how Git could handle large blobs, but to
+describe how a LOP based solution can already work well and alleviate
+a number of current issues in the context of Git clients and servers
+sharing Git objects.
+
+Even if LOPs are used not very efficiently, they can still be useful
+and worth using in some cases, as we will see in more details
+later in this document:
+
+  - they can make it simpler for clients to use promisor remotes and
+    therefore avoid fetching a lot of large blobs they might not need
+    locally,
+
+  - they can make it significantly cheaper or easier for servers to
+    host a significant part of the current repository content, and
+    even more to host content with larger blobs or more large blobs
+    than currently.
+
+I Issues with the current situation
+-----------------------------------
+
+- Some statistics made on GitLab repos have shown that more than 75%
+  of the disk space is used by blobs that are larger than 1MB and
+  often in a binary format.
+
+- So even if users could use Git LFS or similar tools to store a lot
+  of large blobs out of their repos, it's a fact that in practice they
+  don't do it as much as they probably should.
+
+- On the server side ideally, the server should be able to decide for
+  itself how it stores things. It should not depend on users deciding
+  to use tools like Git LFS on some blobs or not.
+
+- It's much more expensive to store large blobs that don't delta
+  compress well on regular fast seeking drives (like SSDs) than on
+  object storage (like Amazon S3 or GCP Buckets). Using fast drives
+  for regular Git repos makes sense though, as serving regular Git
+  content (blobs containing text or code) needs drives where seeking
+  is fast, but the content is relatively small. On the other hand,
+  object storage for Git LFS blobs makes sense as seeking speed is not
+  as important when dealing with large files, while costs are more
+  important. So the fact that users don't use Git LFS or similar tools
+  for a significant number of large blobs has likely some bad
+  consequences on the cost of repo storage for most Git hosting
+  platforms.
+
+- Having large blobs handled in the same way as other blobs and Git
+  objects in Git repos instead of on object storage also has a cost in
+  increased memory and CPU usage, and therefore decreased performance,
+  when creating packfiles. (This is because Git tries to use delta
+  compression or zlib compression which is unlikely to work well on
+  already compressed binary content.) So it's not just a storage cost
+  increase.
+
+- When a large blob has been committed into a repo, it might not be
+  possible to remove this blob from the repo without rewriting
+  history, even if the user then decides to use Git LFS or a similar
+  tool to handle it.
+
+- In fact Git LFS and similar tools are not very flexible in letting
+  users change their minds about the blobs they should handle or not.
+
+- Even when users are using Git LFS or similar tools, they are often
+  complaining that these tools require significant effort to set up,
+  learn and use correctly.
+
+II Main features of the "Large Object Promisors" solution
+---------------------------------------------------------
+
+The main features below should give a rough overview of how the
+solution may work. Details about needed elements can be found in
+following sections.
+
+Even if each feature below is very useful for the full solution, it is
+very likely to be also useful on its own in some cases where the full
+solution is not required. However, we'll focus primarily on the big
+picture here.
+
+Also each feature doesn't need to be implemented entirely in Git
+itself. Some could be scripts, hooks or helpers that are not part of
+the Git repo. It would be helpful if those could be shared and
+improved on collaboratively though. So we want to encourage sharing
+them.
+
+1) Large blobs are stored on LOPs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Large blobs should be stored on special promisor remotes that we will
+call "Large Object Promisors" or LOPs. These LOPs should be additional
+remotes dedicated to contain large blobs especially those in binary
+format. They should be used along with main remotes that contain the
+other objects.
+
+Note 1
+^^^^^^
+
+To clarify, a LOP is a normal promisor remote, except that:
+
+- it should store only large blobs,
+
+- it should be separate from the main remote, so that the main remote
+  can focus on serving other objects and the rest of the repos (see
+  feature 4) below) and can use the LOP as a promisor remote for
+  itself.
+
+Note 2
+^^^^^^
+
+Git already makes it possible for a main remote to also be a promisor
+remote storing both regular objects and large blobs for a client that
+clones from it with a filter on blob size. But here we explicitly want
+to avoid that.
+
+Rationale
+^^^^^^^^^
+
+LOPs aim to be good at handling large blobs while main remotes are
+already good at handling other objects.
+
+Implementation
+^^^^^^^^^^^^^^
+
+Git already has support for multiple promisor remotes, see
+link:partial-clone.html#using-many-promisor-remotes[the partial clone documentation].
+
+Also, Git already has support for partial clone using a filter on the
+size of the blobs (with `git clone --filter=blob:limit=<size>`).  Most
+of the other main features below are based on these existing features
+and are about making them easy and efficient to use for the purpose of
+better handling large blobs.
+
+2) LOPs can use object storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+LOPs can be implemented using object storage, like an Amazon S3 or GCP
+Bucket or MinIO (which is open source under the GNU AGPLv3 license) to
+actually store the large blobs, and can be accessed through a Git
+remote helper (see linkgit:gitremote-helpers[7]) which makes the
+underlying object storage appear like a remote to Git.
+
+Note
+^^^^
+
+A LOP can be a promisor remote accessed using a remote helper by
+both some clients and the main remote.
+
+Rationale
+^^^^^^^^^
+
+This looks like the simplest way to create LOPs that can cheaply
+handle many large blobs.
+
+Implementation
+^^^^^^^^^^^^^^
+
+Remote helpers are quite easy to write as shell scripts, but it might
+be more efficient and maintainable to write them using other languages
+like Go.
+
+Some already exist under open source licenses, for example:
+
+  - https://github.com/awslabs/git-remote-s3
+  - https://gitlab.com/eric.p.ju/git-remote-gs
+
+Other ways to implement LOPs are certainly possible, but the goal of
+this document is not to discuss how to best implement a LOP or its
+underlying object storage (see the "0) Non goals" section above).
+
+3) LOP object storage can be Git LFS storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The underlying object storage that a LOP uses could also serve as
+storage for large files handled by Git LFS.
+
+Rationale
+^^^^^^^^^
+
+This would simplify the server side if it wants to both use a LOP and
+act as a Git LFS server.
+
+4) A main remote can offload to a LOP with a configurable threshold
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On the server side, a main remote should have a way to offload to a
+LOP all its blobs with a size over a configurable threshold.
+
+Rationale
+^^^^^^^^^
+
+This makes it easy to set things up and to clean things up. For
+example, an admin could use this to manually convert a repo not using
+LOPs to a repo using a LOP. On a repo already using a LOP but where
+some users would sometimes push large blobs, a cron job could use this
+to regularly make sure the large blobs are moved to the LOP.
+
+Implementation
+^^^^^^^^^^^^^^
+
+Using something based on `git repack --filter=...` to separate the
+blobs we want to offload from the other Git objects could be a good
+idea. The missing part is to connect to the LOP, check if the blobs we
+want to offload are already there and if not send them.
+
+5) A main remote should try to remain clean from large blobs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A main remote should try to avoid containing a lot of oversize
+blobs. For that purpose, it should offload as needed to a LOP and it
+should have ways to prevent oversize blobs to be fetched, and also
+perhaps pushed, into it.
+
+Rationale
+^^^^^^^^^
+
+A main remote containing many oversize blobs would defeat the purpose
+of LOPs.
+
+Implementation
+^^^^^^^^^^^^^^
+
+The way to offload to a LOP discussed in 4) above can be used to
+regularly offload oversize blobs. About preventing oversize blobs from
+being fetched into the repo see 6) below. About preventing oversize
+blob pushes, a pre-receive hook could be used.
+
+Also there are different scenarios in which large blobs could get
+fetched into the main remote, for example:
+
+- A client that doesn't implement the "promisor-remote" protocol
+  (described in 6) below) clones from the main remote.
+
+- The main remote gets a request for information about a large blob
+  and is not able to get that information without fetching the blob
+  from the LOP.
+
+It might not be possible to completely prevent all these scenarios
+from happening. So the goal here should be to implement features that
+make the fetching of large blobs less likely. For example adding a
+`remote-object-info` command in the `git cat-file --batch` protocol
+and its variants might make it possible for a main repo to respond to
+some requests about large blobs without fetching them.
+
+6) A protocol negotiation should happen when a client clones
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a client clones from a main repo, there should be a protocol
+negotiation so that the server can advertise one or more LOPs and so
+that the client and the server can discuss if the client could
+directly use a LOP the server is advertising. If the client and the
+server can agree on that, then the client would be able to get the
+large blobs directly from the LOP and the server would not need to
+fetch those blobs from the LOP to be able to serve the client.
+
+Note
+^^^^
+
+For fetches instead of clones, a protocol negotiation might not always
+happen, see the "What about fetches?" FAQ entry below for details.
+
+Rationale
+^^^^^^^^^
+
+Security, configurability and efficiency of setting things up.
+
+Implementation
+^^^^^^^^^^^^^^
+
+A "promisor-remote" protocol v2 capability looks like a good way to
+implement this. The way the client and server use this capability
+could be controlled by configuration variables.
+
+Information that the server could send to the client through that
+protocol could be things like: LOP name, LOP URL, filter-spec (for
+example `blob:limit=<size>`) or just size limit that should be used as
+a filter when cloning, token to be used with the LOP, etc.
+
+7) A client can offload to a LOP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a client is using a LOP that is also a LOP of its main remote,
+the client should be able to offload some large blobs it has fetched,
+but might not need anymore, to the LOP.
+
+Note
+^^^^
+
+It might depend on the context if it should be OK or not for clients
+to offload large blobs they have created, instead of fetched, directly
+to the LOP without the main remote checking them in some ways
+(possibly using hooks or other tools).
+
+This should be discussed and refined when we get closer to
+implementing this feature.
+
+Rationale
+^^^^^^^^^
+
+On the client, the easiest way to deal with unneeded large blobs is to
+offload them.
+
+Implementation
+^^^^^^^^^^^^^^
+
+This is very similar to what 4) above is about, except on the client
+side instead of the server side. So a good solution to 4) could likely
+be adapted to work on the client side too.
+
+There might be some security issues here, as there is no negotiation,
+but they might be mitigated if the client can reuse a token it got
+when cloning (see 6) above). Also if the large blobs were fetched from
+a LOP, it is likely, and can easily be confirmed, that the LOP still
+has them, so that they can just be removed from the client.
+
+III Benefits of using LOPs
+--------------------------
+
+Many benefits are related to the issues discussed in "I) Issues with
+the current situation" above:
+
+- No need to rewrite history when deciding which blobs are worth
+  handling separately than other objects, or when moving or removing
+  the threshold.
+
+- If the protocol between client and server is developed and secured
+  enough, then many details might be setup on the server side only and
+  all the clients could then easily get all the configuration
+  information and use it to set themselves up mostly automatically.
+
+- Storage costs benefits on the server side.
+
+- Reduced memory and CPU needs on main remotes on the server side.
+
+- Reduced storage needs on the client side.
+
+IV FAQ
+------
+
+What about using multiple LOPs on the server and client side?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+That could perhaps be useful in some cases, but for now it's more
+likely that in most cases a single LOP will be advertised by the
+server and should be used by the client.
+
+A case where it could be useful for a server to advertise multiple
+LOPs is if a LOP is better for some users while a different LOP is
+better for other users. For example some clients might have a better
+connection to a LOP than others.
+
+In those cases it's the responsibility of the server to have some
+documentation to help clients. It could say for example something like
+"Users in this part of the world might want to pick only LOP A as it
+is likely to be better connected to them, while users in other parts
+of the world should pick only LOP B for the same reason."
+
+When should we trust or not trust the LOPs advertised by the server?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In some contexts, like in corporate setup where the server and all the
+clients are parts of an internal network in a company where admins
+have all the rights on every system, it's OK, and perhaps even a good
+thing, if the clients fully trust the server, as it can help ensure
+that all the clients are on the same page.
+
+There are also contexts in which clients trust a code hosting platform
+serving them some repos, but might not fully trust other users
+managing or contributing to some of these repos. For example, the code
+hosting platform could have hooks in place to check that any object it
+receives doesn't contain malware or otherwise bad content. In this
+case it might be OK for the client to use a main remote and its LOP if
+they are both hosted by the code hosting platform, but not if the LOP
+is hosted elsewhere (where the content is not checked).
+
+In other contexts, a client should just not trust a server.
+
+So there should be different ways to configure how the client should
+behave when a server advertises a LOP to it at clone time.
+
+As the basic elements that a server can advertise about a LOP are a
+LOP name and a LOP URL, the client should base its decision about
+accepting a LOP on these elements.
+
+One simple way to be very strict in the LOP it accepts is for example
+for the client to check that the LOP is already configured on the
+client with the same name and URL as what the server advertises.
+
+In general default and "safe" settings should require that the LOP are
+configured on the client separately from the "promisor-remote"
+protocol and that the client accepts a LOP only when information about
+it from the protocol matches what has been already configured
+separately.
+
+What about LOP names?
+~~~~~~~~~~~~~~~~~~~~~
+
+In some contexts, for example if the clients sometimes fetch from each
+other, it can be a good idea for all the clients to use the same names
+for all the remotes they use, including LOPs.
+
+In other contexts, each client might want to be able to give the name
+it wants to each remote, including each LOP, it interacts with.
+
+So there should be different ways to configure how the client accepts
+or not the LOP name the server advertises.
+
+If a default or "safe" setting is used, then as such a setting should
+require that the LOP be configured separately, then the name would be
+configured separately and there is no risk that the server could
+dictate a name to a client.
+
+Could the main remote be bogged down by old or paranoid clients?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yes, it could happen if there are too many clients that are either
+unwilling to trust the main remote or that just don't implement the
+"promisor-remote" protocol because they are too old or not fully
+compatible with the 'git' client.
+
+When serving such a client, the main remote has no other choice than
+to first fetch from its LOP, to then be able to provide to the client
+everything it requested. So the main remote, even if it has cleanup
+mechanisms (see section II.4 above), would be burdened at least
+temporarily with the large blobs it had to fetch from its LOP.
+
+Not behaving like this would be breaking backward compatibility, and
+could be seen as segregating clients. For example, it might be
+possible to implement a special mode that allows the server to just
+reject clients that don't implement the "promisor-remote" protocol or
+aren't willing to trust the main remote. This mode might be useful in
+a special context like a corporate environment. There is no plan to
+implement such a mode though, and this should be discussed separately
+later anyway.
+
+A better way to proceed is probably for the main remote to show a
+message telling clients that don't implement the protocol or are
+unwilling to accept the advertised LOP(s) that they would get faster
+clone and fetches by upgrading client software or properly setting
+them up to accept LOP(s).
+
+Waiting for clients to upgrade, monitoring these upgrades and limiting
+the use of LOPs to repos that are not very frequently accessed might
+be other good ways to make sure that some benefits are still reaped
+from LOPs. Over time, as more and more clients upgrade and benefit
+from LOPs, using them in more and more frequently accessed repos will
+become worth it.
+
+Corporate environments, where it might be easier to make sure that all
+the clients are up-to-date and properly configured, could hopefully
+benefit more and earlier from using LOPs.
+
+What about fetches?
+~~~~~~~~~~~~~~~~~~~
+
+There are different kinds of fetches. A regular fetch happens when
+some refs have been updated on the server and the client wants the ref
+updates and possibly the new objects added with them. A "backfill" or
+"lazy" fetch, on the contrary, happens when the client needs to use
+some objects it already knows about but doesn't have because they are
+on a promisor remote.
+
+Regular fetch
+^^^^^^^^^^^^^
+
+In a regular fetch, the client will contact the main remote and a
+protocol negotiation will happen between them. It's a good thing that
+a protocol negotiation happens every time, as the configuration on the
+client or the main remote could have changed since the previous
+protocol negotiation. In this case, the new protocol negotiation
+should ensure that the new fetch will happen in a way that satisfies
+the new configuration of both the client and the server.
+
+In most cases though, the configurations on the client and the main
+remote will not have changed between 2 fetches or between the initial
+clone and a subsequent fetch. This means that the result of a new
+protocol negotiation will be the same as the previous result, so the
+new fetch will happen in the same way as the previous clone or fetch,
+using, or not using, the same LOP(s) as last time.
+
+"Backfill" or "lazy" fetch
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When there is a backfill fetch, the client doesn't necessarily contact
+the main remote first. It will try to fetch from its promisor remotes
+in the order they appear in the config file, except that a remote
+configured using the `extensions.partialClone` config variable will be
+tried last. See
+link:partial-clone.html#using-many-promisor-remotes[the partial clone documentation].
+
+This is not new with this effort. In fact this is how multiple remotes
+have already been working for around 5 years.
+
+When using LOPs, having the main remote configured using
+`extensions.partialClone`, so it's tried last, makes sense, as missing
+objects should only be large blobs that are on LOPs.
+
+This means that a protocol negotiation will likely not happen as the
+missing objects will be fetched from the LOPs, and then there will be
+nothing left to fetch from the main remote.
+
+To secure that, it could be a good idea for LOPs to require a token
+from the client when it fetches from them. The client could get the
+token when performing a protocol negotiation with the main remote (see
+section II.6 above).
+
+V Future improvements
+---------------------
+
+It is expected that at the beginning using LOPs will be mostly worth
+it either in a corporate context where the Git version that clients
+use can easily be controlled, or on repos that are infrequently
+accessed. (See the "Could the main remote be bogged down by old or
+paranoid clients?" section in the FAQ above.)
+
+Over time, as more and more clients upgrade to a version that
+implements the "promisor-remote" protocol v2 capability described
+above in section II.6), it will be worth it to use LOPs more widely.
+
+A lot of improvements may also help using LOPs more widely. Some of
+these improvements are part of the scope of this document like the
+following:
+
+  - Implementing a "remote-object-info" command in the
+    `git cat-file --batch` protocol and its variants to allow main
+    remotes to respond to requests about large blobs without fetching
+    them. (Eric Ju has started working on this based on previous work
+    by Calvin Wan.)
+
+  - Creating better cleanup and offload mechanisms for main remotes
+    and clients to prevent accumulation of large blobs.
+
+  - Developing more sophisticated protocol negotiation capabilities
+    between clients and servers for handling LOPs, for example adding
+    a filter-spec (e.g., blob:limit=<size>) or size limit for
+    filtering when cloning, or adding a token for LOP authentication.
+
+  - Improving security measures for LOP access, particularly around
+    token handling and authentication.
+
+  - Developing standardized ways to configure and manage multiple LOPs
+    across different environments. Especially in the case where
+    different LOPs serve the same content to clients in different
+    geographical locations, there is a need for replication or
+    synchronization between LOPs.
+
+Some improvements, including some that have been mentioned in the "0)
+Non Goals" section of this document, are out of the scope of this
+document:
+
+  - Implementing a new object representation for large blobs on the
+    client side.
+
+  - Developing pluggable ODBs or other object database backends that
+    could chunk large blobs, dedup the chunks and store them
+    efficiently.
+
+  - Optimizing data transfer between LOPs and clients/servers,
+    particularly for incompressible and non-deltifying content.
+
+  - Creating improved client side tools for managing large objects
+    more effectively, for example tools for migrating from Git LFS or
+    git-annex, or tools to find which objects could be offloaded and
+    how much disk space could be reclaimed by offloading them.
+
+Some improvements could be seen as part of the scope of this document,
+but might already have their own separate projects from the Git
+project, like:
+
+  - Improving existing remote helpers to access object storage or
+    developing new ones.
+
+  - Improving existing object storage solutions or developing new
+    ones.
+
+Even though all the above improvements may help, this document and the
+LOP effort should try to focus, at least first, on a relatively small
+number of improvements mostly those that are in its current scope.
+
+For example introducing pluggable ODBs and a new object database
+backend is likely a multi-year effort on its own that can happen
+separately in parallel. It has different technical requirements,
+touches other part of the Git code base and should have its own design
+document(s).
diff --git a/Documentation/technical/long-running-process-protocol.txt b/Documentation/technical/long-running-process-protocol.adoc
index 6f33654b42..39bd89d467 100644
--- a/Documentation/technical/long-running-process-protocol.txt
+++ b/Documentation/technical/long-running-process-protocol.adoc
@@ -24,6 +24,7 @@ After the version negotiation Git sends a list of all capabilities that
 it supports and a flush packet. Git expects to read a list of desired
 capabilities, which must be a subset of the supported capabilities list,
 and a flush packet as response:
+
 ------------------------
 packet:          git> git-filter-client
 packet:          git> version=2
diff --git a/Documentation/technical/meson.build b/Documentation/technical/meson.build
index 21dfb8b5c9..be698ef22a 100644
--- a/Documentation/technical/meson.build
+++ b/Documentation/technical/meson.build
@@ -1,37 +1,38 @@
 api_docs = [
-  'api-error-handling.txt',
-  'api-merge.txt',
-  'api-parse-options.txt',
-  'api-simple-ipc.txt',
-  'api-trace2.txt',
+  'api-error-handling.adoc',
+  'api-merge.adoc',
+  'api-parse-options.adoc',
+  'api-simple-ipc.adoc',
+  'api-trace2.adoc',
 ]
 
 articles = [
-  'bitmap-format.txt',
-  'build-systems.txt',
-  'bundle-uri.txt',
-  'commit-graph.txt',
-  'directory-rename-detection.txt',
-  'hash-function-transition.txt',
-  'long-running-process-protocol.txt',
-  'multi-pack-index.txt',
-  'packfile-uri.txt',
-  'pack-heuristics.txt',
-  'parallel-checkout.txt',
-  'partial-clone.txt',
-  'platform-support.txt',
-  'racy-git.txt',
-  'reftable.txt',
-  'remembering-renames.txt',
-  'repository-version.txt',
-  'rerere.txt',
-  'scalar.txt',
-  'send-pack-pipeline.txt',
-  'shallow.txt',
-  'sparse-checkout.txt',
-  'sparse-index.txt',
-  'trivial-merge.txt',
-  'unit-tests.txt',
+  'bitmap-format.adoc',
+  'build-systems.adoc',
+  'bundle-uri.adoc',
+  'commit-graph.adoc',
+  'directory-rename-detection.adoc',
+  'hash-function-transition.adoc',
+  'large-object-promisors.adoc',
+  'long-running-process-protocol.adoc',
+  'multi-pack-index.adoc',
+  'packfile-uri.adoc',
+  'pack-heuristics.adoc',
+  'parallel-checkout.adoc',
+  'partial-clone.adoc',
+  'platform-support.adoc',
+  'racy-git.adoc',
+  'reftable.adoc',
+  'remembering-renames.adoc',
+  'repository-version.adoc',
+  'rerere.adoc',
+  'scalar.adoc',
+  'send-pack-pipeline.adoc',
+  'shallow.adoc',
+  'sparse-checkout.adoc',
+  'sparse-index.adoc',
+  'trivial-merge.adoc',
+  'unit-tests.adoc',
 ]
 
 api_index = custom_target(
@@ -43,10 +44,10 @@ api_index = custom_target(
   ],
   env: script_environment,
   input: api_docs,
-  output: 'api-index.txt',
+  output: 'api-index.adoc',
 )
 
-custom_target(
+doc_targets += custom_target(
   command: asciidoc_html_options,
   input: api_index,
   output: 'api-index.html',
@@ -56,10 +57,11 @@ custom_target(
 )
 
 foreach article : api_docs + articles
-  custom_target(
+  doc_targets += custom_target(
     command: asciidoc_html_options,
     input: article,
     output: fs.stem(article) + '.html',
+    depends: documentation_deps,
     install: true,
     install_dir: get_option('datadir') / 'doc/git-doc/technical',
   )
diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.adoc
index cc063b30be..ffda70aa13 100644
--- a/Documentation/technical/multi-pack-index.txt
+++ b/Documentation/technical/multi-pack-index.adoc
@@ -164,19 +164,81 @@ objects_nr($H2) + objects_nr($H1) + i
 (in the C implementation, this is often computed as `i +
 m->num_objects_in_base`).
 
+=== Pseudo-pack order for incremental MIDXs
+
+The original implementation of multi-pack reachability bitmaps defined
+the pseudo-pack order in linkgit:gitformat-pack[5] (see the section
+titled "multi-pack-index reverse indexes") roughly as follows:
+
+____
+In short, a MIDX's pseudo-pack is the de-duplicated concatenation of
+objects in packs stored by the MIDX, laid out in pack order, and the
+packs arranged in MIDX order (with the preferred pack coming first).
+____
+
+In the incremental MIDX design, we extend this definition to include
+objects from multiple layers of the MIDX chain. The pseudo-pack order
+for incremental MIDXs is determined by concatenating the pseudo-pack
+ordering for each layer of the MIDX chain in order. Formally two objects
+`o1` and `o2` are compared as follows:
+
+1. If `o1` appears in an earlier layer of the MIDX chain than `o2`, then
+  `o1` sorts ahead of `o2`.
+
+2. Otherwise, if `o1` and `o2` appear in the same MIDX layer, and that
+   MIDX layer has no base, then if one of `pack(o1)` and `pack(o2)` is
+   preferred and the other is not, then the preferred one sorts ahead of
+   the non-preferred one. If there is a base layer (i.e. the MIDX layer
+   is not the first layer in the chain), then if `pack(o1)` appears
+   earlier in that MIDX layer's pack order, then `o1` sorts ahead of
+   `o2`. Likewise if `pack(o2)` appears earlier, then the opposite is
+   true.
+
+3. Otherwise, `o1` and `o2` appear in the same pack, and thus in the
+   same MIDX layer. Sort `o1` and `o2` by their offset within their
+   containing packfile.
+
+Note that the preferred pack is a property of the MIDX chain, not the
+individual layers themselves. Fundamentally we could introduce a
+per-layer preferred pack, but this is less relevant now that we can
+perform multi-pack reuse across the set of packs in a MIDX.
+
+=== Reachability bitmaps and incremental MIDXs
+
+Each layer of an incremental MIDX chain may have its objects (and the
+objects from any previous layer in the same MIDX chain) represented in
+its own `*.bitmap` file.
+
+The structure of a `*.bitmap` file belonging to an incremental MIDX
+chain is identical to that of a non-incremental MIDX bitmap, or a
+classic single-pack bitmap. Since objects are added to the end of the
+incremental MIDX's pseudo-pack order (see above), it is possible to
+extend a bitmap when appending to the end of a MIDX chain.
+
+(Note: it is possible likewise to compress a contiguous sequence of MIDX
+incremental layers, and their `*.bitmap` files into a single layer and
+`*.bitmap`, but this is not yet implemented.)
+
+The object positions used are global within the pseudo-pack order, so
+subsequent layers will have, for example, `m->num_objects_in_base`
+number of `0` bits in each of their four type bitmaps. This follows from
+the fact that we only write type bitmap entries for objects present in
+the layer immediately corresponding to the bitmap).
+
+Note also that only the bitmap pertaining to the most recent layer in an
+incremental MIDX chain is used to store reachability information about
+the interesting and uninteresting objects in a reachability query.
+Earlier bitmap layers are only used to look up commit and pseudo-merge
+bitmaps from that layer, as well as the type-level bitmaps for objects
+in that layer.
+
+To simplify the implementation, type-level bitmaps are iterated
+simultaneously, and their results are OR'd together to avoid recursively
+calling internal bitmap functions.
+
 Future Work
 -----------
 
-- The multi-pack-index allows many packfiles, especially in a context
-  where repacking is expensive (such as a very large repo), or
-  unexpected maintenance time is unacceptable (such as a high-demand
-  build machine). However, the multi-pack-index needs to be rewritten
-  in full every time. We can extend the format to be incremental, so
-  writes are fast. By storing a small "tip" multi-pack-index that
-  points to large "base" MIDX files, we can keep writes fast while
-  still reducing the number of binary searches required for object
-  lookups.
-
 - If the multi-pack-index is extended to store a "stable object order"
   (a function Order(hash) = integer that is constant for a given hash,
   even as the multi-pack-index is updated) then MIDX bitmaps could be
diff --git a/Documentation/technical/pack-heuristics.txt b/Documentation/technical/pack-heuristics.adoc
index 95a07db6e8..95a07db6e8 100644
--- a/Documentation/technical/pack-heuristics.txt
+++ b/Documentation/technical/pack-heuristics.adoc
diff --git a/Documentation/technical/packfile-uri.txt b/Documentation/technical/packfile-uri.adoc
index 9d453d4765..9d453d4765 100644
--- a/Documentation/technical/packfile-uri.txt
+++ b/Documentation/technical/packfile-uri.adoc
diff --git a/Documentation/technical/parallel-checkout.txt b/Documentation/technical/parallel-checkout.adoc
index b4a144e5f4..b4a144e5f4 100644
--- a/Documentation/technical/parallel-checkout.txt
+++ b/Documentation/technical/parallel-checkout.adoc
diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.adoc
index bf5ec5c82d..e513e391ea 100644
--- a/Documentation/technical/partial-clone.txt
+++ b/Documentation/technical/partial-clone.adoc
@@ -85,7 +85,7 @@ See "filter" in linkgit:gitprotocol-pack[5].
   server to request filtering during packfile construction.
 +
 There are various filters available to accommodate different situations.
-See "--filter=<filter-spec>" in Documentation/rev-list-options.txt.
+See "--filter=<filter-spec>" in Documentation/rev-list-options.adoc.
 
 - On the server pack-objects applies the requested filter-spec as it
   creates "filtered" packfiles for the client.
diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.adoc
index 0a2fb28d62..0a2fb28d62 100644
--- a/Documentation/technical/platform-support.txt
+++ b/Documentation/technical/platform-support.adoc
diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.adoc
index 59bea66c0f..59bea66c0f 100644
--- a/Documentation/technical/racy-git.txt
+++ b/Documentation/technical/racy-git.adoc
diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.adoc
index dd0b37c4e3..dd0b37c4e3 100644
--- a/Documentation/technical/reftable.txt
+++ b/Documentation/technical/reftable.adoc
diff --git a/Documentation/technical/remembering-renames.txt b/Documentation/technical/remembering-renames.adoc
index 73f41761e2..6155f36c72 100644
--- a/Documentation/technical/remembering-renames.txt
+++ b/Documentation/technical/remembering-renames.adoc
@@ -10,32 +10,32 @@ history as an optimization, assuming all merges are automatic and clean
 
 Outline:
 
-  0. Assumptions
+  1. Assumptions
 
-  1. How rebasing and cherry-picking work
+  2. How rebasing and cherry-picking work
 
-  2. Why the renames on MERGE_SIDE1 in any given pick are *always* a
+  3. Why the renames on MERGE_SIDE1 in any given pick are *always* a
      superset of the renames on MERGE_SIDE1 for the next pick.
 
-  3. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also
+  4. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also
      a rename on MERGE_SIDE1 for the next pick
 
-  4. A detailed description of the counter-examples to #3.
+  5. A detailed description of the counter-examples to #4.
 
-  5. Why the special cases in #4 are still fully reasonable to use to pair
+  6. Why the special cases in #5 are still fully reasonable to use to pair
      up files for three-way content merging in the merge machinery, and why
      they do not affect the correctness of the merge.
 
-  6. Interaction with skipping of "irrelevant" renames
+  7. Interaction with skipping of "irrelevant" renames
 
-  7. Additional items that need to be cached
+  8. Additional items that need to be cached
 
-  8. How directory rename detection interacts with the above and why this
+  9. How directory rename detection interacts with the above and why this
      optimization is still safe even if merge.directoryRenames is set to
      "true".
 
 
-=== 0. Assumptions ===
+== 1. Assumptions ==
 
 There are two assumptions that will hold throughout this document:
 
@@ -44,8 +44,8 @@ There are two assumptions that will hold throughout this document:
 
   * All merges are fully automatic
 
-and a third that will hold in sections 2-5 for simplicity, that I'll later
-address in section 8:
+and a third that will hold in sections 3-6 for simplicity, that I'll later
+address in section 9:
 
   * No directory renames occur
 
@@ -77,9 +77,9 @@ conflicts that the user needs to resolve), the cache of renames is not
 stored on disk, and thus is thrown away as soon as the rebase or cherry
 pick stops for the user to resolve the operation.
 
-The third assumption makes sections 2-5 simpler, and allows people to
+The third assumption makes sections 3-6 simpler, and allows people to
 understand the basics of why this optimization is safe and effective, and
-then I can go back and address the specifics in section 8.  It is probably
+then I can go back and address the specifics in section 9.  It is probably
 also worth noting that if directory renames do occur, then the default of
 merge.directoryRenames being set to "conflict" means that the operation
 will stop for users to resolve the conflicts and the cache will be thrown
@@ -88,22 +88,26 @@ reason we need to address directory renames specifically, is that some
 users will have set merge.directoryRenames to "true" to allow the merges to
 continue to proceed automatically.  The optimization is still safe with
 this config setting, but we have to discuss a few more cases to show why;
-this discussion is deferred until section 8.
+this discussion is deferred until section 9.
 
 
-=== 1. How rebasing and cherry-picking work ===
+== 2. How rebasing and cherry-picking work ==
 
 Consider the following setup (from the git-rebase manpage):
 
+------------
 		     A---B---C topic
 		    /
 	       D---E---F---G main
+------------
 
 After rebasing or cherry-picking topic onto main, this will appear as:
 
+------------
 			     A'--B'--C' topic
 			    /
 	       D---E---F---G main
+------------
 
 The way the commits A', B', and C' are created is through a series of
 merges, where rebase or cherry-pick sequentially uses each of the three
@@ -111,6 +115,7 @@ A-B-C commits in a special merge operation.  Let's label the three commits
 in the merge operation as MERGE_BASE, MERGE_SIDE1, and MERGE_SIDE2.  For
 this picture, the three commits for each of the three merges would be:
 
+....
 To create A':
    MERGE_BASE:   E
    MERGE_SIDE1:  G
@@ -125,6 +130,7 @@ To create C':
    MERGE_BASE:   B
    MERGE_SIDE1:  B'
    MERGE_SIDE2:  C
+....
 
 Sometimes, folks are surprised that these three-way merges are done.  It
 can be useful in understanding these three-way merges to view them in a
@@ -138,8 +144,7 @@ Conceptually the two statements above are the same as a three-way merge of
 B, B', and C, at least the parts before you decide to record a commit.
 
 
-=== 2. Why the renames on MERGE_SIDE1 in any given pick are always a ===
-===    superset of the renames on MERGE_SIDE1 for the next pick.     ===
+== 3. Why the renames on MERGE_SIDE1 in any given pick are always a superset of the renames on MERGE_SIDE1 for the next pick. ==
 
 The merge machinery uses the filenames it is fed from MERGE_BASE,
 MERGE_SIDE1, and MERGE_SIDE2.  It will only move content to a different
@@ -156,6 +161,7 @@ filename under one of three conditions:
 First, let's remember what commits are involved in the first and second
 picks of the cherry-pick or rebase sequence:
 
+....
 To create A':
    MERGE_BASE:   E
    MERGE_SIDE1:  G
@@ -165,6 +171,7 @@ To create B':
    MERGE_BASE:   A
    MERGE_SIDE1:  A'
    MERGE_SIDE2:  B
+....
 
 So, in particular, we need to show that the renames between E and G are a
 superset of those between A and A'.
@@ -181,11 +188,11 @@ are a subset of those between E and G.  Equivalently, all renames between E
 and G are a superset of those between A and A'.
 
 
-=== 3. Why any rename on MERGE_SIDE1 in any given pick is _almost_   ===
-===    always also a rename on MERGE_SIDE1 for the next pick.        ===
+== 4. Why any rename on MERGE_SIDE1 in any given pick is _almost_ always also a rename on MERGE_SIDE1 for the next pick. ==
 
 Let's again look at the first two picks:
 
+....
 To create A':
    MERGE_BASE:   E
    MERGE_SIDE1:  G
@@ -195,17 +202,25 @@ To create B':
    MERGE_BASE:   A
    MERGE_SIDE1:  A'
    MERGE_SIDE2:  B
+....
 
 Now let's look at any given rename from MERGE_SIDE1 of the first pick, i.e.
 any given rename from E to G.  Let's use the filenames 'oldfile' and
 'newfile' for demonstration purposes.  That first pick will function as
 follows; when the rename is detected, the merge machinery will do a
 three-way content merge of the following:
+
+....
     E:oldfile
     G:newfile
     A:oldfile
+....
+
 and produce a new result:
+
+....
     A':newfile
+....
 
 Note above that I've assumed that E->A did not rename oldfile.  If that
 side did rename, then we most likely have a rename/rename(1to2) conflict
@@ -254,19 +269,21 @@ were detected as renames, A:oldfile and A':newfile should also be
 detectable as renames almost always.
 
 
-=== 4. A detailed description of the counter-examples to #3.         ===
+== 5. A detailed description of the counter-examples to #4. ==
 
-We already noted in section 3 that rename/rename(1to1) (i.e. both sides
+We already noted in section 4 that rename/rename(1to1) (i.e. both sides
 renaming a file the same way) was one counter-example.  The more
 interesting bit, though, is why did we need to use the "almost" qualifier
 when stating that A:oldfile and A':newfile are "almost" always detectable
 as renames?
 
-Let's repeat an earlier point that section 3 made:
+Let's repeat an earlier point that section 4 made:
 
+....
   A':newfile was created by applying the changes between E:oldfile and
   G:newfile to A:oldfile.  The changes between E:oldfile and G:newfile were
   <50% of the size of E:oldfile.
+....
 
 If those changes that were <50% of the size of E:oldfile are also <50% of
 the size of A:oldfile, then A:oldfile and A':newfile will be detectable as
@@ -276,18 +293,21 @@ still somehow merge cleanly), then traditional rename detection would not
 detect A:oldfile and A':newfile as renames.
 
 Here's an example where that can happen:
+
   * E:oldfile had 20 lines
   * G:newfile added 10 new lines at the beginning of the file
   * A:oldfile kept the first 3 lines of the file, and deleted all the rest
+
 then
+
+....
   => A':newfile would have 13 lines, 3 of which matches those in A:oldfile.
-E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and
-A':newfile would not be.
+  E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and
+  A':newfile would not be.
+....
 
 
-=== 5. Why the special cases in #4 are still fully reasonable to use to    ===
-===    pair up files for three-way content merging in the merge machinery, ===
-===    and why they do not affect the correctness of the merge.            ===
+== 6. Why the special cases in #5 are still fully reasonable to use to pair up files for three-way content merging in the merge machinery, and why they do not affect the correctness of the merge. ==
 
 In the rename/rename(1to1) case, A:newfile and A':newfile are not renames
 since they use the *same* filename.  However, files with the same filename
@@ -295,14 +315,14 @@ are obviously fine to pair up for three-way content merging (the merge
 machinery has never employed break detection).  The interesting
 counter-example case is thus not the rename/rename(1to1) case, but the case
 where A did not rename oldfile.  That was the case that we spent most of
-the time discussing in sections 3 and 4.  The remainder of this section
+the time discussing in sections 4 and 5.  The remainder of this section
 will be devoted to that case as well.
 
 So, even if A:oldfile and A':newfile aren't detectable as renames, why is
 it still reasonable to pair them up for three-way content merging in the
 merge machinery?  There are multiple reasons:
 
-  * As noted in sections 3 and 4, the diff between A:oldfile and A':newfile
+  * As noted in sections 4 and 5, the diff between A:oldfile and A':newfile
     is *exactly* the same as the diff between E:oldfile and G:newfile.  The
     latter pair were detected as renames, so it seems unlikely to surprise
     users for us to treat A:oldfile and A':newfile as renames.
@@ -394,7 +414,7 @@ cases 1 and 3 seem to provide as good or better behavior with the
 optimization than without.
 
 
-=== 6. Interaction with skipping of "irrelevant" renames ===
+== 7. Interaction with skipping of "irrelevant" renames ==
 
 Previous optimizations involved skipping rename detection for paths
 considered to be "irrelevant".  See for example the following commits:
@@ -421,24 +441,27 @@ detection -- though we can limit it to the paths for which we have not
 already detected renames.
 
 
-=== 7. Additional items that need to be cached ===
+== 8. Additional items that need to be cached ==
 
 It turns out we have to cache more than just renames; we also cache:
 
+....
   A) non-renames (i.e. unpaired deletes)
   B) counts of renames within directories
   C) sources that were marked as RELEVANT_LOCATION, but which were
      downgraded to RELEVANT_NO_MORE
   D) the toplevel trees involved in the merge
+....
 
 These are all stored in struct rename_info, and respectively appear in
+
   * cached_pairs (along side actual renames, just with a value of NULL)
   * dir_rename_counts
   * cached_irrelevant
   * merge_trees
 
-The reason for (A) comes from the irrelevant renames skipping
-optimization discussed in section 6.  The fact that irrelevant renames
+The reason for `(A)` comes from the irrelevant renames skipping
+optimization discussed in section 7.  The fact that irrelevant renames
 are skipped means we only get a subset of the potential renames
 detected and subsequent commits may need to run rename detection on
 the upstream side on a subset of the remaining renames (to get the
@@ -447,23 +470,24 @@ deletes are involved in rename detection too, we don't want to
 repeatedly check that those paths remain unpaired on the upstream side
 with every commit we are transplanting.
 
-The reason for (B) is that diffcore_rename_extended() is what
+The reason for `(B)` is that diffcore_rename_extended() is what
 generates the counts of renames by directory which is needed in
 directory rename detection, and if we don't run
 diffcore_rename_extended() again then we need to have the output from
 it, including dir_rename_counts, from the previous run.
 
-The reason for (C) is that merge-ort's tree traversal will again think
+The reason for `(C)` is that merge-ort's tree traversal will again think
 those paths are relevant (marking them as RELEVANT_LOCATION), but the
 fact that they were downgraded to RELEVANT_NO_MORE means that
 dir_rename_counts already has the information we need for directory
 rename detection.  (A path which becomes RELEVANT_CONTENT in a
 subsequent commit will be removed from cached_irrelevant.)
 
-The reason for (D) is that is how we determine whether the remember
+The reason for `(D)` is that is how we determine whether the remember
 renames optimization can be used.  In particular, remembering that our
 sequence of merges looks like:
 
+....
    Merge 1:
    MERGE_BASE:   E
    MERGE_SIDE1:  G
@@ -475,6 +499,7 @@ sequence of merges looks like:
    MERGE_SIDE1:  A'
    MERGE_SIDE2:  B
    => Creates    B'
+....
 
 It is the fact that the trees A and A' appear both in Merge 1 and in
 Merge 2, with A as a parent of A' that allows this optimization.  So
@@ -482,12 +507,11 @@ we store the trees to compare with what we are asked to merge next
 time.
 
 
-=== 8. How directory rename detection interacts with the above and   ===
-===    why this optimization is still safe even if                   ===
-===    merge.directoryRenames is set to "true".                      ===
+== 9. How directory rename detection interacts with the above and why this optimization is still safe even if merge.directoryRenames is set to "true". ==
 
 As noted in the assumptions section:
 
+....
     """
     ...if directory renames do occur, then the default of
     merge.directoryRenames being set to "conflict" means that the operation
@@ -497,11 +521,13 @@ As noted in the assumptions section:
     is that some users will have set merge.directoryRenames to "true" to
     allow the merges to continue to proceed automatically.
     """
+....
 
 Let's remember that we need to look at how any given pick affects the next
 one.  So let's again use the first two picks from the diagram in section
 one:
 
+....
   First pick does this three-way merge:
     MERGE_BASE:   E
     MERGE_SIDE1:  G
@@ -513,6 +539,7 @@ one:
     MERGE_SIDE1:  A'
     MERGE_SIDE2:  B
     => creates B'
+....
 
 Now, directory rename detection exists so that if one side of history
 renames a directory, and the other side adds a new file to the old
@@ -545,7 +572,7 @@ while considering all of these cases:
     concerned; see the assumptions section).  Two interesting sub-notes
     about these counts:
 
-    * If we need to perform rename-detection again on the given side (e.g.
+   ** If we need to perform rename-detection again on the given side (e.g.
       some paths are relevant for rename detection that weren't before),
       then we clear dir_rename_counts and recompute it, making use of
       cached_pairs.  The reason it is important to do this is optimizations
@@ -556,7 +583,7 @@ while considering all of these cases:
       easiest way to "fix up" dir_rename_counts in such cases is to just
       recompute it.
 
-    * If we prune rename/rename(1to1) entries from the cache, then we also
+   ** If we prune rename/rename(1to1) entries from the cache, then we also
       need to update dir_rename_counts to decrement the counts for the
       involved directory and any relevant parent directories (to undo what
       update_dir_rename_counts() in diffcore-rename.c incremented when the
@@ -578,6 +605,7 @@ in order:
 
 Case 1: MERGE_SIDE1 renames old dir, MERGE_SIDE2 adds new file to old dir
 
+....
   This case looks like this:
 
     MERGE_BASE:   E,   Has olddir/
@@ -595,10 +623,13 @@ Case 1: MERGE_SIDE1 renames old dir, MERGE_SIDE2 adds new file to old dir
     * MERGE_SIDE1 has cached olddir/newfile -> newdir/newfile
   Given the cached rename noted above, the second merge can proceed as
   expected without needing to perform rename detection from A -> A'.
+....
 
 Case 2: MERGE_SIDE1 renames old dir, MERGE_SIDE2 renames  file into old dir
 
+....
   This case looks like this:
+
     MERGE_BASE:   E    oldfile, olddir/
     MERGE_SIDE1:  G    oldfile, olddir/ -> newdir/
     MERGE_SIDE2:  A    oldfile -> olddir/newfile
@@ -617,9 +648,11 @@ Case 2: MERGE_SIDE1 renames old dir, MERGE_SIDE2 renames  file into old dir
 
   Given the cached rename noted above, the second merge can proceed as
   expected without needing to perform rename detection from A -> A'.
+....
 
 Case 3: MERGE_SIDE1 adds new file to   old dir, MERGE_SIDE2 renames old dir
 
+....
   This case looks like this:
 
     MERGE_BASE:   E,   Has olddir/
@@ -635,9 +668,11 @@ Case 3: MERGE_SIDE1 adds new file to   old dir, MERGE_SIDE2 renames old dir
   In this case, with the optimization, note that after the first commit there
   were no renames on MERGE_SIDE1, and any renames on MERGE_SIDE2 are tossed.
   But the second merge didn't need any renames so this is fine.
+....
 
 Case 4: MERGE_SIDE1 renames  file into old dir, MERGE_SIDE2 renames old dir
 
+....
   This case looks like this:
 
     MERGE_BASE:   E,   Has olddir/
@@ -658,6 +693,7 @@ Case 4: MERGE_SIDE1 renames  file into old dir, MERGE_SIDE2 renames old dir
 
   Given the cached rename noted above, the second merge can proceed as
   expected without needing to perform rename detection from A -> A'.
+....
 
 Finally, I'll just note here that interactions with the
 skip-irrelevant-renames optimization means we sometimes don't detect
diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.adoc
index b9bb81a81f..b9bb81a81f 100644
--- a/Documentation/technical/repository-version.txt
+++ b/Documentation/technical/repository-version.adoc
diff --git a/Documentation/technical/rerere.txt b/Documentation/technical/rerere.adoc
index 580f23360a..580f23360a 100644
--- a/Documentation/technical/rerere.txt
+++ b/Documentation/technical/rerere.adoc
diff --git a/Documentation/technical/scalar.txt b/Documentation/technical/scalar.adoc
index 921cb104c3..921cb104c3 100644
--- a/Documentation/technical/scalar.txt
+++ b/Documentation/technical/scalar.adoc
diff --git a/Documentation/technical/send-pack-pipeline.txt b/Documentation/technical/send-pack-pipeline.adoc
index 9b5a0bc186..9b5a0bc186 100644
--- a/Documentation/technical/send-pack-pipeline.txt
+++ b/Documentation/technical/send-pack-pipeline.adoc
diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.adoc
index f3738baa0f..f3738baa0f 100644
--- a/Documentation/technical/shallow.txt
+++ b/Documentation/technical/shallow.adoc
diff --git a/Documentation/technical/sparse-checkout.txt b/Documentation/technical/sparse-checkout.adoc
index d968659354..3fa8e53655 100644
--- a/Documentation/technical/sparse-checkout.txt
+++ b/Documentation/technical/sparse-checkout.adoc
@@ -14,37 +14,41 @@ Table of contents:
   * Reference Emails
 
 
-=== Terminology ===
+== Terminology ==
 
-cone mode: one of two modes for specifying the desired subset of files
+*`cone mode`*::
+	one of two modes for specifying the desired subset of files
 	in a sparse-checkout.  In cone-mode, the user specifies
 	directories (getting both everything under that directory as
 	well as everything in leading directories), while in non-cone
 	mode, the user specifies gitignore-style patterns.  Controlled
 	by the --[no-]cone option to sparse-checkout init|set.
 
-SKIP_WORKTREE: When tracked files do not match the sparse specification and
+*`SKIP_WORKTREE`*::
+	When tracked files do not match the sparse specification and
 	are removed from the working tree, the file in the index is marked
 	with a SKIP_WORKTREE bit.  Note that if a tracked file has the
 	SKIP_WORKTREE bit set but the file is later written by the user to
 	the working tree anyway, the SKIP_WORKTREE bit will be cleared at
 	the beginning of any subsequent Git operation.
-
-	Most sparse checkout users are unaware of this implementation
-	detail, and the term should generally be avoided in user-facing
-	descriptions and command flags.  Unfortunately, prior to the
-	`sparse-checkout` subcommand this low-level detail was exposed,
-	and as of time of writing, is still exposed in various places.
-
-sparse-checkout: a subcommand in git used to reduce the files present in
++
+Most sparse checkout users are unaware of this implementation
+detail, and the term should generally be avoided in user-facing
+descriptions and command flags.  Unfortunately, prior to the
+`sparse-checkout` subcommand this low-level detail was exposed,
+and as of time of writing, is still exposed in various places.
+
+*`sparse-checkout`*::
+	a subcommand in git used to reduce the files present in
 	the working tree to a subset of all tracked files.  Also, the
 	name of the file in the $GIT_DIR/info directory used to track
 	the sparsity patterns corresponding to the user's desired
 	subset.
 
-sparse cone: see cone mode
+*`sparse cone`*:: see cone mode
 
-sparse directory: An entry in the index corresponding to a directory, which
+*`sparse directory`*::
+	An entry in the index corresponding to a directory, which
 	appears in the index instead of all the files under that directory
 	that would normally appear.  See also sparse-index.  Something that
 	can cause confusion is that the "sparse directory" does NOT match
@@ -52,7 +56,8 @@ sparse directory: An entry in the index corresponding to a directory, which
 	working tree.  May be renamed in the future (e.g. to "skipped
 	directory").
 
-sparse index: A special mode for sparse-checkout that also makes the
+*`sparse index`*::
+	A special mode for sparse-checkout that also makes the
 	index sparse by recording a directory entry in lieu of all the
 	files underneath that directory (thus making that a "skipped
 	directory" which unfortunately has also been called a "sparse
@@ -60,17 +65,19 @@ sparse index: A special mode for sparse-checkout that also makes the
 	directories.  Controlled by the --[no-]sparse-index option to
 	init|set|reapply.
 
-sparsity patterns: patterns from $GIT_DIR/info/sparse-checkout used to
+*`sparsity patterns`*::
+	patterns from $GIT_DIR/info/sparse-checkout used to
 	define the set of files of interest.  A warning: It is easy to
 	over-use this term (or the shortened "patterns" term), for two
 	reasons: (1) users in cone mode specify directories rather than
 	patterns (their directories are transformed into patterns, but
 	users may think you are talking about non-cone mode if you use the
-	word "patterns"), and (b) the sparse specification might
+	word "patterns"), and (2) the sparse specification might
 	transiently differ in the working tree or index from the sparsity
 	patterns (see "Sparse specification vs. sparsity patterns").
 
-sparse specification: The set of paths in the user's area of focus.  This
+*`sparse specification`*::
+	The set of paths in the user's area of focus.  This
 	is typically just the tracked files that match the sparsity
 	patterns, but the sparse specification can temporarily differ and
 	include additional files.  (See also "Sparse specification
@@ -87,12 +94,13 @@ sparse specification: The set of paths in the user's area of focus.  This
 	* If working with the index and the working copy, the sparse
 	  specification is the union of the paths from above.
 
-vivifying: When a command restores a tracked file to the working tree (and
+*`vivifying`*::
+	When a command restores a tracked file to the working tree (and
 	hopefully also clears the SKIP_WORKTREE bit in the index for that
 	file), this is referred to as "vivifying" the file.
 
 
-=== Purpose of sparse-checkouts ===
+== Purpose of sparse-checkouts ==
 
 sparse-checkouts exist to allow users to work with a subset of their
 files.
@@ -120,14 +128,12 @@ those usecases, sparse-checkouts can modify different subcommands in over a
 half dozen different ways.  Let's start by considering the high level
 usecases:
 
-  A) Users are _only_ interested in the sparse portion of the repo
-
-  A*) Users are _only_ interested in the sparse portion of the repo
-      that they have downloaded so far
-
-  B) Users want a sparse working tree, but are working in a larger whole
-
-  C) sparse-checkout is a behind-the-scenes implementation detail allowing
+[horizontal]
+A):: Users are _only_ interested in the sparse portion of the repo
+A*):: Users are _only_ interested in the sparse portion of the repo
+     that they have downloaded so far
+B):: Users want a sparse working tree, but are working in a larger whole
+C):: sparse-checkout is a behind-the-scenes implementation detail allowing
      Git to work with a specially crafted in-house virtual file system;
      users are actually working with a "full" working tree that is
      lazily populated, and sparse-checkout helps with the lazy population
@@ -136,7 +142,7 @@ usecases:
 It may be worth explaining each of these in a bit more detail:
 
 
-  (Behavior A) Users are _only_ interested in the sparse portion of the repo
+=== (Behavior A) Users are _only_ interested in the sparse portion of the repo
 
 These folks might know there are other things in the repository, but
 don't care.  They are uninterested in other parts of the repository, and
@@ -163,8 +169,7 @@ side-effects of various other commands (such as the printed diffstat
 after a merge or pull) can lead to worries about local repository size
 growing unnecessarily[10].
 
-  (Behavior A*) Users are _only_ interested in the sparse portion of the repo
-      that they have downloaded so far (a variant on the first usecase)
+=== (Behavior A*) Users are _only_ interested in the sparse portion of the repo that they have downloaded so far (a variant on the first usecase)
 
 This variant is driven by folks who using partial clones together with
 sparse checkouts and do disconnected development (so far sounding like a
@@ -173,15 +178,14 @@ reason for yet another variant is that downloading even just the blobs
 through history within their sparse specification may be too much, so they
 only download some.  They would still like operations to succeed without
 network connectivity, though, so things like `git log -S${SEARCH_TERM} -p`
-or `git grep ${SEARCH_TERM} OLDREV ` would need to be prepared to provide
+or `git grep ${SEARCH_TERM} OLDREV` would need to be prepared to provide
 partial results that depend on what happens to have been downloaded.
 
 This variant could be viewed as Behavior A with the sparse specification
 for history querying operations modified from "sparsity patterns" to
 "sparsity patterns limited to the blobs we have already downloaded".
 
-  (Behavior B) Users want a sparse working tree, but are working in a
-      larger whole
+=== (Behavior B) Users want a sparse working tree, but are working in a larger whole
 
 Stolee described this usecase this way[11]:
 
@@ -229,8 +233,7 @@ those expensive checks when interacting with the working copy, and may
 prefer getting "unrelated" results from their history queries over having
 slow commands.
 
-  (Behavior C) sparse-checkout is an implementational detail supporting a
-	       special VFS.
+=== (Behavior C) sparse-checkout is an implementational detail supporting a special VFS.
 
 This usecase goes slightly against the traditional definition of
 sparse-checkout in that it actually tries to present a full or dense
@@ -255,13 +258,13 @@ will perceive the checkout as dense, and commands should thus behave as if
 all files are present.
 
 
-=== Usecases of primary concern ===
+== Usecases of primary concern ==
 
 Most of the rest of this document will focus on Behavior A and Behavior
 B.  Some notes about the other two cases and why we are not focusing on
 them:
 
-  (Behavior A*)
+=== (Behavior A*)
 
 Supporting this usecase is estimated to be difficult and a lot of work.
 There are no plans to implement it currently, but it may be a potential
@@ -275,7 +278,7 @@ valid for this usecase, with the only exception being that it redefines the
 sparse specification to restrict it to already-downloaded blobs.  The hard
 part is in making commands capable of respecting that modified definition.
 
-  (Behavior C)
+=== (Behavior C)
 
 This usecase violates some of the early sparse-checkout documented
 assumptions (since files marked as SKIP_WORKTREE will be displayed to users
@@ -300,20 +303,20 @@ Behavior C do not assume they are part of the Behavior B camp and propose
 patches that break things for the real Behavior B folks.
 
 
-=== Oversimplified mental models ===
+== Oversimplified mental models ==
 
 An oversimplification of the differences in the above behaviors is:
 
-  Behavior A: Restrict worktree and history operations to sparse specification
-  Behavior B: Restrict worktree operations to sparse specification; have any
-	      history operations work across all files
-  Behavior C: Do not restrict either worktree or history operations to the
-	      sparse specification...with the exception of branch checkouts or
-	      switches which avoid writing files that will match the index so
-	      they can later lazily be populated instead.
+(Behavior A):: Restrict worktree and history operations to sparse specification
+(Behavior B):: Restrict worktree operations to sparse specification; have any
+	     history operations work across all files
+(Behavior C):: Do not restrict either worktree or history operations to the
+	     sparse specification...with the exception of branch checkouts or
+	     switches which avoid writing files that will match the index so
+	     they can later lazily be populated instead.
 
 
-=== Desired behavior ===
+== Desired behavior ==
 
 As noted previously, despite the simple idea of just working with a subset
 of files, there are a range of different behavioral changes that need to be
@@ -326,39 +329,38 @@ understanding these differences can be beneficial.
 
 * Commands behaving the same regardless of high-level use-case
 
-  * commands that only look at files within the sparsity specification
+  ** commands that only look at files within the sparsity specification
 
-      * diff (without --cached or REVISION arguments)
-      * grep (without --cached or REVISION arguments)
-      * diff-files
+      *** diff (without --cached or REVISION arguments)
+      *** grep (without --cached or REVISION arguments)
+      *** diff-files
 
-  * commands that restore files to the working tree that match sparsity
+  ** commands that restore files to the working tree that match sparsity
     patterns, and remove unmodified files that don't match those
     patterns:
 
-      * switch
-      * checkout (the switch-like half)
-      * read-tree
-      * reset --hard
+      *** switch
+      *** checkout (the switch-like half)
+      *** read-tree
+      *** reset --hard
 
-  * commands that write conflicted files to the working tree, but otherwise
+  ** commands that write conflicted files to the working tree, but otherwise
     will omit writing files to the working tree that do not match the
     sparsity patterns:
 
-      * merge
-      * rebase
-      * cherry-pick
-      * revert
+      *** merge
+      *** rebase
+      *** cherry-pick
+      *** revert
 
-      * `am` and `apply --cached` should probably be in this section but
+      *** `am` and `apply --cached` should probably be in this section but
 	are buggy (see the "Known bugs" section below)
 
     The behavior for these commands somewhat depends upon the merge
     strategy being used:
-      * `ort` behaves as described above
-      * `recursive` tries to not vivify files unnecessarily, but does sometimes
-	vivify files without conflicts.
-      * `octopus` and `resolve` will always vivify any file changed in the merge
+
+      *** `ort` behaves as described above
+      *** `octopus` and `resolve` will always vivify any file changed in the merge
 	relative to the first parent, which is rather suboptimal.
 
     It is also important to note that these commands WILL update the index
@@ -374,21 +376,21 @@ understanding these differences can be beneficial.
     specification and the sparsity patterns (much like the commands in the
     previous section).
 
-  * commands that always ignore sparsity since commits must be full-tree
+  ** commands that always ignore sparsity since commits must be full-tree
 
-      * archive
-      * bundle
-      * commit
-      * format-patch
-      * fast-export
-      * fast-import
-      * commit-tree
+      *** archive
+      *** bundle
+      *** commit
+      *** format-patch
+      *** fast-export
+      *** fast-import
+      *** commit-tree
 
-  * commands that write any modified file to the working tree (conflicted
+  ** commands that write any modified file to the working tree (conflicted
     or not, and whether those paths match sparsity patterns or not):
 
-      * stash
-      * apply (without `--index` or `--cached`)
+      *** stash
+      *** apply (without `--index` or `--cached`)
 
 * Commands that may slightly differ for behavior A vs. behavior B:
 
@@ -396,19 +398,20 @@ understanding these differences can be beneficial.
   behaviors, but may differ in verbosity and types of warning and error
   messages.
 
-  * commands that make modifications to which files are tracked:
-      * add
-      * rm
-      * mv
-      * update-index
+  ** commands that make modifications to which files are tracked:
+
+      *** add
+      *** rm
+      *** mv
+      *** update-index
 
     The fact that files can move between the 'tracked' and 'untracked'
     categories means some commands will have to treat untracked files
     differently.  But if we have to treat untracked files differently,
     then additional commands may also need changes:
 
-      * status
-      * clean
+      *** status
+      *** clean
 
     In particular, `status` may need to report any untracked files outside
     the sparsity specification as an erroneous condition (especially to
@@ -422,9 +425,10 @@ understanding these differences can be beneficial.
     may need to ignore the sparse specification by its nature.  Also, its
     current --[no-]ignore-skip-worktree-entries default is totally bogus.
 
-  * commands for manually tweaking paths in both the index and the working tree
-      * `restore`
-      * the restore-like half of `checkout`
+  ** commands for manually tweaking paths in both the index and the working tree
+
+      *** `restore`
+      *** the restore-like half of `checkout`
 
     These commands should be similar to add/rm/mv in that they should
     only operate on the sparse specification by default, and require a
@@ -435,18 +439,19 @@ understanding these differences can be beneficial.
 
 * Commands that significantly differ for behavior A vs. behavior B:
 
-  * commands that query history
-      * diff (with --cached or REVISION arguments)
-      * grep (with --cached or REVISION arguments)
-      * show (when given commit arguments)
-      * blame (only matters when one or more -C flags are passed)
-	* and annotate
-      * log
-      * whatchanged
-      * ls-files
-      * diff-index
-      * diff-tree
-      * ls-tree
+  ** commands that query history
+
+      *** diff (with --cached or REVISION arguments)
+      *** grep (with --cached or REVISION arguments)
+      *** show (when given commit arguments)
+      *** blame (only matters when one or more -C flags are passed)
+	**** and annotate
+      *** log
+      *** whatchanged (may not exist anymore)
+      *** ls-files
+      *** diff-index
+      *** diff-tree
+      *** ls-tree
 
     Note: for log and whatchanged, revision walking logic is unaffected
     but displaying of patches is affected by scoping the command to the
@@ -460,91 +465,91 @@ understanding these differences can be beneficial.
 
 * Commands I don't know how to classify
 
-  * range-diff
+  ** range-diff
 
     Is this like `log` or `format-patch`?
 
-  * cherry
+  ** cherry
 
     See range-diff
 
 * Commands unaffected by sparse-checkouts
 
-  * shortlog
-  * show-branch
-  * rev-list
-  * bisect
-
-  * branch
-  * describe
-  * fetch
-  * gc
-  * init
-  * maintenance
-  * notes
-  * pull (merge & rebase have the necessary changes)
-  * push
-  * submodule
-  * tag
-
-  * config
-  * filter-branch (works in separate checkout without sparse-checkout setup)
-  * pack-refs
-  * prune
-  * remote
-  * repack
-  * replace
-
-  * bugreport
-  * count-objects
-  * fsck
-  * gitweb
-  * help
-  * instaweb
-  * merge-tree (doesn't touch worktree or index, and merges always compute full-tree)
-  * rerere
-  * verify-commit
-  * verify-tag
-
-  * commit-graph
-  * hash-object
-  * index-pack
-  * mktag
-  * mktree
-  * multi-pack-index
-  * pack-objects
-  * prune-packed
-  * symbolic-ref
-  * unpack-objects
-  * update-ref
-  * write-tree (operates on index, possibly optimized to use sparse dir entries)
-
-  * for-each-ref
-  * get-tar-commit-id
-  * ls-remote
-  * merge-base (merges are computed full tree, so merge base should be too)
-  * name-rev
-  * pack-redundant
-  * rev-parse
-  * show-index
-  * show-ref
-  * unpack-file
-  * var
-  * verify-pack
-
-  * <Everything under 'Interacting with Others' in 'git help --all'>
-  * <Everything under 'Low-level...Syncing' in 'git help --all'>
-  * <Everything under 'Low-level...Internal Helpers' in 'git help --all'>
-  * <Everything under 'External commands' in 'git help --all'>
+  ** shortlog
+  ** show-branch
+  ** rev-list
+  ** bisect
+
+  ** branch
+  ** describe
+  ** fetch
+  ** gc
+  ** init
+  ** maintenance
+  ** notes
+  ** pull (merge & rebase have the necessary changes)
+  ** push
+  ** submodule
+  ** tag
+
+  ** config
+  ** filter-branch (works in separate checkout without sparse-checkout setup)
+  ** pack-refs
+  ** prune
+  ** remote
+  ** repack
+  ** replace
+
+  ** bugreport
+  ** count-objects
+  ** fsck
+  ** gitweb
+  ** help
+  ** instaweb
+  ** merge-tree (doesn't touch worktree or index, and merges always compute full-tree)
+  ** rerere
+  ** verify-commit
+  ** verify-tag
+
+  ** commit-graph
+  ** hash-object
+  ** index-pack
+  ** mktag
+  ** mktree
+  ** multi-pack-index
+  ** pack-objects
+  ** prune-packed
+  ** symbolic-ref
+  ** unpack-objects
+  ** update-ref
+  ** write-tree (operates on index, possibly optimized to use sparse dir entries)
+
+  ** for-each-ref
+  ** get-tar-commit-id
+  ** ls-remote
+  ** merge-base (merges are computed full tree, so merge base should be too)
+  ** name-rev
+  ** pack-redundant
+  ** rev-parse
+  ** show-index
+  ** show-ref
+  ** unpack-file
+  ** var
+  ** verify-pack
+
+  ** <Everything under 'Interacting with Others' in 'git help --all'>
+  ** <Everything under 'Low-level...Syncing' in 'git help --all'>
+  ** <Everything under 'Low-level...Internal Helpers' in 'git help --all'>
+  ** <Everything under 'External commands' in 'git help --all'>
 
 * Commands that might be affected, but who cares?
 
-  * merge-file
-  * merge-index
-  * gitk?
+  ** merge-file
+  ** merge-index
+  ** gitk?
 
 
-=== Behavior classes ===
+== Behavior classes ==
 
 From the above there are a few classes of behavior:
 
@@ -575,18 +580,19 @@ From the above there are a few classes of behavior:
 
     Commands in this class generally behave like the "restrict" class,
     except that:
-      (1) they will ignore the sparse specification and write files with
-	  conflicts to the working tree (thus temporarily expanding the
-	  sparse specification to include such files.)
-      (2) they are grouped with commands which move to a new commit, since
-	  they often create a commit and then move to it, even though we
-	  know there are many exceptions to moving to the new commit.  (For
-	  example, the user may rebase a commit that becomes empty, or have
-	  a cherry-pick which conflicts, or a user could run `merge
-	  --no-commit`, and we also view `apply --index` kind of like `am
-	  --no-commit`.)  As such, these commands can make changes to index
-	  files outside the sparse specification, though they'll mark such
-	  files with SKIP_WORKTREE.
+
+	(1) they will ignore the sparse specification and write files with
+	    conflicts to the working tree (thus temporarily expanding the
+	    sparse specification to include such files.)
+	(2) they are grouped with commands which move to a new commit, since
+	    they often create a commit and then move to it, even though we
+	    know there are many exceptions to moving to the new commit.  (For
+	    example, the user may rebase a commit that becomes empty, or have
+	    a cherry-pick which conflicts, or a user could run `merge
+	    --no-commit`, and we also view `apply --index` kind of like `am
+	    --no-commit`.)  As such, these commands can make changes to index
+	    files outside the sparse specification, though they'll mark such
+	    files with SKIP_WORKTREE.
 
   * "restrict also specially applied to untracked files"
 
@@ -611,37 +617,39 @@ From the above there are a few classes of behavior:
     specification.
 
 
-=== Subcommand-dependent defaults ===
+== Subcommand-dependent defaults ==
 
 Note that we have different defaults depending on the command for the
 desired behavior :
 
   * Commands defaulting to "restrict":
-    * diff-files
-    * diff (without --cached or REVISION arguments)
-    * grep (without --cached or REVISION arguments)
-    * switch
-    * checkout (the switch-like half)
-    * reset (<commit>)
-
-    * restore
-    * checkout (the restore-like half)
-    * checkout-index
-    * reset (with pathspec)
+
+    ** diff-files
+    ** diff (without --cached or REVISION arguments)
+    ** grep (without --cached or REVISION arguments)
+    ** switch
+    ** checkout (the switch-like half)
+    ** reset (<commit>)
+
+    ** restore
+    ** checkout (the restore-like half)
+    ** checkout-index
+    ** reset (with pathspec)
 
     This behavior makes sense; these interact with the working tree.
 
   * Commands defaulting to "restrict modulo conflicts":
-    * merge
-    * rebase
-    * cherry-pick
-    * revert
 
-    * am
-    * apply --index (which is kind of like an `am --no-commit`)
+    ** merge
+    ** rebase
+    ** cherry-pick
+    ** revert
+
+    ** am
+    ** apply --index (which is kind of like an `am --no-commit`)
 
-    * read-tree (especially with -m or -u; is kind of like a --no-commit merge)
-    * reset (<tree-ish>, due to similarity to read-tree)
+    ** read-tree (especially with -m or -u; is kind of like a --no-commit merge)
+    ** reset (<tree-ish>, due to similarity to read-tree)
 
     These also interact with the working tree, but require slightly
     different behavior either so that (a) conflicts can be resolved or (b)
@@ -650,16 +658,17 @@ desired behavior :
     (See also the "Known bugs" section below regarding `am` and `apply`)
 
   * Commands defaulting to "no restrict":
-    * archive
-    * bundle
-    * commit
-    * format-patch
-    * fast-export
-    * fast-import
-    * commit-tree
 
-    * stash
-    * apply (without `--index`)
+    ** archive
+    ** bundle
+    ** commit
+    ** format-patch
+    ** fast-export
+    ** fast-import
+    ** commit-tree
+
+    ** stash
+    ** apply (without `--index`)
 
     These have completely different defaults and perhaps deserve the most
     detailed explanation:
@@ -681,53 +690,59 @@ desired behavior :
     sparse specification then we'll lose changes from the user.
 
   * Commands defaulting to "restrict also specially applied to untracked files":
-    * add
-    * rm
-    * mv
-    * update-index
-    * status
-    * clean (?)
-
-    Our original implementation for the first three of these commands was
-    "no restrict", but it had some severe usability issues:
-      * `git add <somefile>` if honored and outside the sparse
-	specification, can result in the file randomly disappearing later
-	when some subsequent command is run (since various commands
-	automatically clean up unmodified files outside the sparse
-	specification).
-      * `git rm '*.jpg'` could very negatively surprise users if it deletes
-	files outside the range of the user's interest.
-      * `git mv` has similar surprises when moving into or out of the cone,
-	so best to restrict by default
-
-    So, we switched `add` and `rm` to default to "restrict", which made
-    usability problems much less severe and less frequent, but we still got
-    complaints because commands like:
-	git add <file-outside-sparse-specification>
-	git rm <file-outside-sparse-specification>
-    would silently do nothing.  We should instead print an error in those
-    cases to get usability right.
-
-    update-index needs to be updated to match, and status and maybe clean
-    also need to be updated to specially handle untracked paths.
-
-    There may be a difference in here between behavior A and behavior B in
-    terms of verboseness of errors or additional warnings.
+
+    ** add
+    ** rm
+    ** mv
+    ** update-index
+    ** status
+    ** clean (?)
+
+....
+        Our original implementation for the first three of these commands was
+        "no restrict", but it had some severe usability issues:
+
+          * `git add <somefile>` if honored and outside the sparse
+	    specification, can result in the file randomly disappearing later
+	    when some subsequent command is run (since various commands
+	    automatically clean up unmodified files outside the sparse
+	    specification).
+          * `git rm '*.jpg'` could very negatively surprise users if it deletes
+	    files outside the range of the user's interest.
+          * `git mv` has similar surprises when moving into or out of the cone,
+	    so best to restrict by default
+
+        So, we switched `add` and `rm` to default to "restrict", which made
+        usability problems much less severe and less frequent, but we still got
+        complaints because commands like:
+
+	    git add <file-outside-sparse-specification>
+	    git rm <file-outside-sparse-specification>
+
+        would silently do nothing.  We should instead print an error in those
+        cases to get usability right.
+
+        update-index needs to be updated to match, and status and maybe clean
+        also need to be updated to specially handle untracked paths.
+
+        There may be a difference in here between behavior A and behavior B in
+        terms of verboseness of errors or additional warnings.
+....
 
   * Commands falling under "restrict or no restrict dependent upon behavior
     A vs. behavior B"
 
-    * diff (with --cached or REVISION arguments)
-    * grep (with --cached or REVISION arguments)
-    * show (when given commit arguments)
-    * blame (only matters when one or more -C flags passed)
-      * and annotate
-    * log
-      * and variants: shortlog, gitk, show-branch, whatchanged, rev-list
-    * ls-files
-    * diff-index
-    * diff-tree
-    * ls-tree
+    ** diff (with --cached or REVISION arguments)
+    ** grep (with --cached or REVISION arguments)
+    ** show (when given commit arguments)
+    ** blame (only matters when one or more -C flags passed)
+      *** and annotate
+    ** log
+      *** and variants: shortlog, gitk, show-branch, whatchanged, rev-list
+    ** ls-files
+    ** diff-index
+    ** diff-tree
+    ** ls-tree
 
     For now, we default to behavior B for these, which want a default of
     "no restrict".
@@ -751,7 +766,7 @@ desired behavior :
     implemented.
 
 
-=== Sparse specification vs. sparsity patterns ===
+== Sparse specification vs. sparsity patterns ==
 
 In a well-behaved situation, the sparse specification is given directly
 by the $GIT_DIR/info/sparse-checkout file.  However, it can transiently
@@ -823,45 +838,48 @@ under behavior B index operations are lumped with history and tend to
 operate full-tree.
 
 
-=== Implementation Questions ===
-
-  * Do the options --scope={sparse,all} sound good to others?  Are there better
-    options?
-    * Names in use, or appearing in patches, or previously suggested:
-      * --sparse/--dense
-      * --ignore-skip-worktree-bits
-      * --ignore-skip-worktree-entries
-      * --ignore-sparsity
-      * --[no-]restrict-to-sparse-paths
-      * --full-tree/--sparse-tree
-      * --[no-]restrict
-      * --scope={sparse,all}
-      * --focus/--unfocus
-      * --limit/--unlimited
-    * Rationale making me lean slightly towards --scope={sparse,all}:
-      * We want a name that works for many commands, so we need a name that
+== Implementation Questions ==
+
+  * Do the options --scope={sparse,all} sound good to others?  Are there better options?
+
+    ** Names in use, or appearing in patches, or previously suggested:
+
+      *** --sparse/--dense
+      *** --ignore-skip-worktree-bits
+      *** --ignore-skip-worktree-entries
+      *** --ignore-sparsity
+      *** --[no-]restrict-to-sparse-paths
+      *** --full-tree/--sparse-tree
+      *** --[no-]restrict
+      *** --scope={sparse,all}
+      *** --focus/--unfocus
+      *** --limit/--unlimited
+
+    ** Rationale making me lean slightly towards --scope={sparse,all}:
+
+      *** We want a name that works for many commands, so we need a name that
 	does not conflict
-      * We know that we have more than two possible usecases, so it is best
+      *** We know that we have more than two possible usecases, so it is best
 	to avoid a flag that appears to be binary.
-      * --scope={sparse,all} isn't overly long and seems relatively
+      *** --scope={sparse,all} isn't overly long and seems relatively
 	explanatory
-      * `--sparse`, as used in add/rm/mv, is totally backwards for
+      *** `--sparse`, as used in add/rm/mv, is totally backwards for
 	grep/log/etc.  Changing the meaning of `--sparse` for these
 	commands would fix the backwardness, but possibly break existing
 	scripts.  Using a new name pairing would allow us to treat
 	`--sparse` in these commands as a deprecated alias.
-      * There is a different `--sparse`/`--dense` pair for commands using
+      *** There is a different `--sparse`/`--dense` pair for commands using
 	revision machinery, so using that naming might cause confusion
-      * There is also a `--sparse` in both pack-objects and show-branch, which
+      *** There is also a `--sparse` in both pack-objects and show-branch, which
 	don't conflict but do suggest that `--sparse` is overloaded
-      * The name --ignore-skip-worktree-bits is a double negative, is
+      *** The name --ignore-skip-worktree-bits is a double negative, is
 	quite a mouthful, refers to an implementation detail that many
 	users may not be familiar with, and we'd need a negation for it
 	which would probably be even more ridiculously long.  (But we
 	can make --ignore-skip-worktree-bits a deprecated alias for
 	--no-restrict.)
 
-  * If a config option is added (sparse.scope?) what should the values and
+  ** If a config option is added (sparse.scope?) what should the values and
     description be?  "sparse" (behavior A), "worktree-sparse-history-dense"
     (behavior B), "dense" (behavior C)?  There's a risk of confusion,
     because even for Behaviors A and B we want some commands to be
@@ -870,19 +888,20 @@ operate full-tree.
     the primary difference we are focusing is just the history-querying
     commands (log/diff/grep).  Previous config suggestion here: [13]
 
-  * Is `--no-expand` a good alias for ls-files's `--sparse` option?
+  ** Is `--no-expand` a good alias for ls-files's `--sparse` option?
     (`--sparse` does not map to either `--scope=sparse` or `--scope=all`,
     because in non-cone mode it does nothing and in cone-mode it shows the
     sparse directory entries which are technically outside the sparse
     specification)
 
-  * Under Behavior A:
-    * Does ls-files' `--no-expand` override the default `--scope=all`, or
+  ** Under Behavior A:
+
+    *** Does ls-files' `--no-expand` override the default `--scope=all`, or
       does it need an extra flag?
-    * Does ls-files' `-t` option imply `--scope=all`?
-    * Does update-index's `--[no-]skip-worktree` option imply `--scope=all`?
+    *** Does ls-files' `-t` option imply `--scope=all`?
+    *** Does update-index's `--[no-]skip-worktree` option imply `--scope=all`?
 
-  * sparse-checkout: once behavior A is fully implemented, should we take
+  ** sparse-checkout: once behavior A is fully implemented, should we take
     an interim measure to ease people into switching the default?  Namely,
     if folks are not already in a sparse checkout, then require
     `sparse-checkout init/set` to take a
@@ -894,7 +913,7 @@ operate full-tree.
     is seamless for them.
 
 
-=== Implementation Goals/Plans ===
+== Implementation Goals/Plans ==
 
  * Get buy-in on this document in general.
 
@@ -912,25 +931,26 @@ operate full-tree.
    request that they not trigger this bug." flag
 
  * Flags & Config
-   * Make `--sparse` in add/rm/mv a deprecated alias for `--scope=all`
-   * Make `--ignore-skip-worktree-bits` in checkout-index/checkout/restore
+
+   ** Make `--sparse` in add/rm/mv a deprecated alias for `--scope=all`
+   ** Make `--ignore-skip-worktree-bits` in checkout-index/checkout/restore
      a deprecated aliases for `--scope=all`
-   * Create config option (sparse.scope?), tie it to the "Cliff notes"
+   ** Create config option (sparse.scope?), tie it to the "Cliff notes"
      overview
 
-   * Add --scope=sparse (and --scope=all) flag to each of the history querying
+   ** Add --scope=sparse (and --scope=all) flag to each of the history querying
      commands.  IMPORTANT: make sure diff machinery changes don't mess with
      format-patch, fast-export, etc.
 
-=== Known bugs ===
+== Known bugs ==
 
 This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've
 been working on it.
 
-0. Behavior A is not well supported in Git.  (Behavior B didn't used to
+1. Behavior A is not well supported in Git.  (Behavior B didn't used to
    be either, but was the easier of the two to implement.)
 
-1. am and apply:
+2. am and apply:
 
    apply, without `--index` or `--cached`, relies on files being present
    in the working copy, and also writes to them unconditionally.  As
@@ -950,7 +970,7 @@ been working on it.
    files and then complain that those vivified files would be
    overwritten by merge.
 
-2. reset --hard:
+3. reset --hard:
 
    reset --hard provides confusing error message (works correctly, but
    misleads the user into believing it didn't):
@@ -973,13 +993,13 @@ been working on it.
     `git reset --hard` DID remove addme from the index and the working tree, contrary
     to the error message, but in line with how reset --hard should behave.
 
-3. read-tree
+4. read-tree
 
    `read-tree` doesn't apply the 'SKIP_WORKTREE' bit to *any* of the
    entries it reads into the index, resulting in all your files suddenly
    appearing to be "deleted".
 
-4. Checkout, restore:
+5. Checkout, restore:
 
    These command do not handle path & revision arguments appropriately:
 
@@ -1032,7 +1052,7 @@ been working on it.
     S tracked
     H tracked-but-maybe-skipped
 
-5. checkout and restore --staged, continued:
+6. checkout and restore --staged, continued:
 
    These commands do not correctly scope operations to the sparse
    specification, and make it worse by not setting important SKIP_WORKTREE
@@ -1048,56 +1068,82 @@ been working on it.
    the sparse specification, but then it will be important to set the
    SKIP_WORKTREE bits appropriately.
 
-6. Performance issues; see:
-    https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/
+7. Performance issues; see:
+
+   https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/
 
 
-=== Reference Emails ===
+== Reference Emails ==
 
 Emails that detail various bugs we've had in sparse-checkout:
 
-[1] (Original descriptions of behavior A & behavior B)
-    https://lore.kernel.org/git/CABPp-BGJ_Nvi5TmgriD9Bh6eNXE2EDq2f8e8QKXAeYG3BxZafA@mail.gmail.com/
-[2] (Fix stash applications in sparse checkouts; bugs from behavioral differences)
-    https://lore.kernel.org/git/ccfedc7140dbf63ba26a15f93bd3885180b26517.1606861519.git.gitgitgadget@gmail.com/
-[3] (Present-despite-skipped entries)
-    https://lore.kernel.org/git/11d46a399d26c913787b704d2b7169cafc28d639.1642175983.git.gitgitgadget@gmail.com/
-[4] (Clone --no-checkout interaction)
-    https://lore.kernel.org/git/pull.801.v2.git.git.1591324899170.gitgitgadget@gmail.com/ (clone --no-checkout)
-[5] (The need for update_sparsity() and avoiding `read-tree -mu HEAD`)
-    https://lore.kernel.org/git/3a1f084641eb47515b5a41ed4409a36128913309.1585270142.git.gitgitgadget@gmail.com/
-[6] (SKIP_WORKTREE is advisory, not mandatory)
-    https://lore.kernel.org/git/844306c3e86ef67591cc086decb2b760e7d710a3.1585270142.git.gitgitgadget@gmail.com/
-[7] (`worktree add` should copy sparsity settings from current worktree)
-    https://lore.kernel.org/git/c51cb3714e7b1d2f8c9370fe87eca9984ff4859f.1644269584.git.gitgitgadget@gmail.com/
-[8] (Avoid negative surprises in add, rm, and mv)
-    https://lore.kernel.org/git/cover.1617914011.git.matheus.bernardino@usp.br/
-    https://lore.kernel.org/git/pull.1018.v4.git.1632497954.gitgitgadget@gmail.com/
-[9] (Move from out-of-cone to in-cone)
-    https://lore.kernel.org/git/20220630023737.473690-6-shaoxuan.yuan02@gmail.com/
-    https://lore.kernel.org/git/20220630023737.473690-4-shaoxuan.yuan02@gmail.com/
-[10] (Unnecessarily downloading objects outside sparse specification)
-     https://lore.kernel.org/git/CAOLTT8QfwOi9yx_qZZgyGa8iL8kHWutEED7ok_jxwTcYT_hf9Q@mail.gmail.com/
-
-[11] (Stolee's comments on high-level usecases)
-     https://lore.kernel.org/git/1a1e33f6-3514-9afc-0a28-5a6b85bd8014@gmail.com/
+[1] (Original descriptions of behavior A & behavior B):
+
+https://lore.kernel.org/git/CABPp-BGJ_Nvi5TmgriD9Bh6eNXE2EDq2f8e8QKXAeYG3BxZafA@mail.gmail.com/
+
+[2] (Fix stash applications in sparse checkouts; bugs from behavioral differences):
+
+https://lore.kernel.org/git/ccfedc7140dbf63ba26a15f93bd3885180b26517.1606861519.git.gitgitgadget@gmail.com/
+
+[3] (Present-despite-skipped entries):
+
+https://lore.kernel.org/git/11d46a399d26c913787b704d2b7169cafc28d639.1642175983.git.gitgitgadget@gmail.com/
+
+[4] (Clone --no-checkout interaction):
+
+https://lore.kernel.org/git/pull.801.v2.git.git.1591324899170.gitgitgadget@gmail.com/ (clone --no-checkout)
+
+[5] (The need for update_sparsity() and avoiding `read-tree -mu HEAD`):
+
+https://lore.kernel.org/git/3a1f084641eb47515b5a41ed4409a36128913309.1585270142.git.gitgitgadget@gmail.com/
+
+[6] (SKIP_WORKTREE is advisory, not mandatory):
+
+https://lore.kernel.org/git/844306c3e86ef67591cc086decb2b760e7d710a3.1585270142.git.gitgitgadget@gmail.com/
+
+[7] (`worktree add` should copy sparsity settings from current worktree):
+
+https://lore.kernel.org/git/c51cb3714e7b1d2f8c9370fe87eca9984ff4859f.1644269584.git.gitgitgadget@gmail.com/
+
+[8] (Avoid negative surprises in add, rm, and mv):
+
+  * https://lore.kernel.org/git/cover.1617914011.git.matheus.bernardino@usp.br/
+  * https://lore.kernel.org/git/pull.1018.v4.git.1632497954.gitgitgadget@gmail.com/
+
+[9] (Move from out-of-cone to in-cone):
+
+  * https://lore.kernel.org/git/20220630023737.473690-6-shaoxuan.yuan02@gmail.com/
+  * https://lore.kernel.org/git/20220630023737.473690-4-shaoxuan.yuan02@gmail.com/
+
+[10] (Unnecessarily downloading objects outside sparse specification):
+
+https://lore.kernel.org/git/CAOLTT8QfwOi9yx_qZZgyGa8iL8kHWutEED7ok_jxwTcYT_hf9Q@mail.gmail.com/
+
+[11] (Stolee's comments on high-level usecases):
+
+https://lore.kernel.org/git/1a1e33f6-3514-9afc-0a28-5a6b85bd8014@gmail.com/
 
 [12] Others commenting on eventually switching default to behavior A:
+
   * https://lore.kernel.org/git/xmqqh719pcoo.fsf@gitster.g/
   * https://lore.kernel.org/git/xmqqzgeqw0sy.fsf@gitster.g/
   * https://lore.kernel.org/git/a86af661-cf58-a4e5-0214-a67d3a794d7e@github.com/
 
-[13] Previous config name suggestion and description
-  * https://lore.kernel.org/git/CABPp-BE6zW0nJSStcVU=_DoDBnPgLqOR8pkTXK3dW11=T01OhA@mail.gmail.com/
+[13] Previous config name suggestion and description:
+
+   https://lore.kernel.org/git/CABPp-BE6zW0nJSStcVU=_DoDBnPgLqOR8pkTXK3dW11=T01OhA@mail.gmail.com/
 
 [14] Tangential issue: switch to cone mode as default sparse specification mechanism:
-  https://lore.kernel.org/git/a1b68fd6126eb341ef3637bb93fedad4309b36d0.1650594746.git.gitgitgadget@gmail.com/
+
+https://lore.kernel.org/git/a1b68fd6126eb341ef3637bb93fedad4309b36d0.1650594746.git.gitgitgadget@gmail.com/
 
 [15] Lengthy email on grep behavior, covering what should be searched:
-  * https://lore.kernel.org/git/CABPp-BGVO3QdbfE84uF_3QDF0-y2iHHh6G5FAFzNRfeRitkuHw@mail.gmail.com/
+
+https://lore.kernel.org/git/CABPp-BGVO3QdbfE84uF_3QDF0-y2iHHh6G5FAFzNRfeRitkuHw@mail.gmail.com/
 
 [16] Email explaining sparsity patterns vs. SKIP_WORKTREE and history operations,
      search for the parenthetical comment starting "We do not check".
-    https://lore.kernel.org/git/CABPp-BFsCPPNOZ92JQRJeGyNd0e-TCW-LcLyr0i_+VSQJP+GCg@mail.gmail.com/
+
+https://lore.kernel.org/git/CABPp-BFsCPPNOZ92JQRJeGyNd0e-TCW-LcLyr0i_+VSQJP+GCg@mail.gmail.com/
 
 [17] https://lore.kernel.org/git/20220207190320.2960362-1-jonathantanmy@google.com/
diff --git a/Documentation/technical/sparse-index.txt b/Documentation/technical/sparse-index.adoc
index 3b24c1a219..3b24c1a219 100644
--- a/Documentation/technical/sparse-index.txt
+++ b/Documentation/technical/sparse-index.adoc
diff --git a/Documentation/technical/trivial-merge.txt b/Documentation/technical/trivial-merge.adoc
index 1f1c33d0da..1f1c33d0da 100644
--- a/Documentation/technical/trivial-merge.txt
+++ b/Documentation/technical/trivial-merge.adoc
diff --git a/Documentation/technical/unit-tests.txt b/Documentation/technical/unit-tests.adoc
index 5a432b7b29..5a432b7b29 100644
--- a/Documentation/technical/unit-tests.txt
+++ b/Documentation/technical/unit-tests.adoc
diff --git a/Documentation/trace2-target-values.txt b/Documentation/trace2-target-values.adoc
index 06f1953313..06f1953313 100644
--- a/Documentation/trace2-target-values.txt
+++ b/Documentation/trace2-target-values.adoc
diff --git a/Documentation/transfer-data-leaks.txt b/Documentation/transfer-data-leaks.adoc
index 914bacc39e..914bacc39e 100644
--- a/Documentation/transfer-data-leaks.txt
+++ b/Documentation/transfer-data-leaks.adoc
diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.adoc
index bf17012241..57b1646d3e 100644
--- a/Documentation/urls-remotes.txt
+++ b/Documentation/urls-remotes.adoc
@@ -1,4 +1,4 @@
-include::urls.txt[]
+include::urls.adoc[]
 
 REMOTES[[REMOTES]]
 ------------------
@@ -92,5 +92,47 @@ git push uses:
 ------------
 
 
+[[UPSTREAM-BRANCHES]]
+UPSTREAM BRANCHES
+-----------------
 
+Branches in Git can optionally have an upstream remote branch.
+Git defaults to using the upstream branch for remote operations, for example:
 
+* It's the default for `git pull` or `git fetch` with no arguments.
+* It's the default for `git push` with no arguments, with some exceptions.
+  For example, you can use the `branch.<name>.pushRemote` option to push
+  to a different remote than you pull from, and by default with
+  `push.default=simple` the upstream branch you configure must have
+  the same name.
+* Various commands, including `git checkout` and `git status`, 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
+  'origin/main' have diverged, and have 2 and 3 different commits each
+  respectively".
+
+The upstream is stored in `.git/config`, in the "remote" and "merge"
+fields. For example, if `main`'s upstream is `origin/main`:
+
+------------
+[branch "main"]
+   remote = origin
+   merge = refs/heads/main
+------------
+
+You can set an upstream branch explicitly with
+`git push --set-upstream <remote> <branch>`
+but Git will often automatically set the upstream for you, for example:
+
+* When you clone a repository, Git will automatically set the upstream
+  for the default branch.
+* If you have the `push.autoSetupRemote` configuration option set,
+  `git push` will automatically set the upstream the first time you push
+  a branch.
+* Checking out a remote-tracking branch with `git checkout <branch>`
+  will automatically create a local branch with that name and set
+  the upstream to the remote branch.
+
+[NOTE]
+Upstream branches are sometimes referred to as "tracking information",
+as in "set the branch's tracking information".
diff --git a/Documentation/urls.txt b/Documentation/urls.adoc
index 9c871e716a..9c871e716a 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.adoc
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.adoc
index 90a4189358..7696987117 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.adoc
@@ -4240,7 +4240,7 @@ command `git`.  The source side of a builtin is
 - an entry in `BUILTIN_OBJECTS` in the `Makefile`.
 
 Sometimes, more than one builtin is contained in one source file.  For
-example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`,
+example, `cmd_show()` and `cmd_log()` both reside in `builtin/log.c`,
 since they share quite a bit of code.  In that case, the commands which are
 _not_ named like the `.c` file in which they live have to be listed in
 `BUILT_INS` in the `Makefile`.
@@ -4270,7 +4270,7 @@ So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what
 it does.
 
 ------------------------------------------------------------------
-        git_config(git_default_config);
+        repo_config(the_repository, git_default_config);
         if (argc != 3)
 		usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>");
         if (get_sha1(argv[2], sha1))
@@ -4301,11 +4301,11 @@ Now, for the meat:
 
 -----------------------------------------------------------------------------
         case 0:
-                buf = read_object_with_reference(sha1, argv[1], &size, NULL);
+                buf = odb_read_object_peeled(r->objects, sha1, argv[1], &size, NULL);
 -----------------------------------------------------------------------------
 
 This is how you read a blob (actually, not only a blob, but any type of
-object).  To know how the function `read_object_with_reference()` actually
+object).  To know how the function `odb_read_object_peeled()` actually
 works, find the source code for it (something like `git grep
 read_object_with | grep ":[a-z]"` in the Git repository), and read
 the source.
@@ -4354,7 +4354,7 @@ itself!
 [[git-explained]]
 === Git explained
 
-include::glossary-content.txt[]
+include::glossary-content.adoc[]
 
 [[git-quick-start]]
 [appendix]