.gitattributes

@@ -1,13 +1,13 @@
-* whitespace=trail,space
-*.[ch] whitespace=indent,trail,space,incomplete diff=cpp
-*.sh whitespace=indent,trail,space,incomplete text eol=lf
+* whitespace=!indent,trail,space
+*.[ch] whitespace=indent,trail,space diff=cpp
+*.sh whitespace=indent,trail,space text eol=lf
 *.perl text eol=lf diff=perl
 *.pl text eof=lf diff=perl
 *.pm text eol=lf diff=perl
 *.py text eol=lf diff=python
 *.bat text eol=crlf
 CODE_OF_CONDUCT.md -whitespace
-/Documentation/**/*.adoc text eol=lf whitespace=trail,space,incomplete
+/Documentation/**/*.adoc text eol=lf
 /command-list.txt text eol=lf
 /GIT-VERSION-GEN text eol=lf
 /mergetools/* text eol=lf

.github/workflows/check-style.yml

@@ -20,7 +20,7 @@ jobs:
       jobname: ClangFormat
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
 

.github/workflows/check-whitespace.yml

@@ -19,7 +19,7 @@ jobs:
   check-whitespace:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
 

.github/workflows/coverity.yml

@@ -38,7 +38,7 @@ jobs:
       COVERITY_LANGUAGE: cxx
       COVERITY_PLATFORM: overridden-below
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v4
       - name: install minimal Git for Windows SDK
         if: contains(matrix.os, 'windows')
         uses: git-for-windows/setup-git-for-windows-sdk@v1

.github/workflows/l10n.yml

@@ -63,7 +63,7 @@ jobs:
             origin \
             ${{ github.ref }} \
             $args
-      - uses: actions/setup-go@v6
+      - uses: actions/setup-go@v5
         with:
           go-version: '>=1.16'
           cache: false

.github/workflows/main.yml

@@ -63,7 +63,7 @@ jobs:
           echo "skip_concurrent=$skip_concurrent" >>$GITHUB_OUTPUT
       - name: skip if the commit or tree was already tested
         id: skip-if-redundant
-        uses: actions/github-script@v8
+        uses: actions/github-script@v7
         if: steps.check-ref.outputs.enabled == 'yes'
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}
@@ -112,7 +112,7 @@ jobs:
       group: windows-build-${{ github.ref }}
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
     - uses: git-for-windows/setup-git-for-windows-sdk@v1
     - name: build
       shell: bash
@@ -123,7 +123,7 @@ jobs:
     - name: zip up tracked files
       run: git archive -o artifacts/tracked.tar.gz HEAD
     - name: upload tracked files and build artifacts
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v4
       with:
         name: windows-artifacts
         path: artifacts
@@ -140,7 +140,7 @@ jobs:
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     steps:
     - name: download tracked files and build artifacts
-      uses: actions/download-artifact@v6
+      uses: actions/download-artifact@v4
       with:
         name: windows-artifacts
         path: ${{github.workspace}}
@@ -157,7 +157,7 @@ jobs:
       run: ci/print-test-failures.sh
     - name: Upload failed tests' directories
       if: failure() && env.FAILED_TEST_ARTIFACTS != ''
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v4
       with:
         name: failed-tests-windows-${{ matrix.nr }}
         path: ${{env.FAILED_TEST_ARTIFACTS}}
@@ -173,10 +173,10 @@ jobs:
       group: vs-build-${{ github.ref }}
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
     - uses: git-for-windows/setup-git-for-windows-sdk@v1
     - name: initialize vcpkg
-      uses: actions/checkout@v5
+      uses: actions/checkout@v4
       with:
         repository: 'microsoft/vcpkg'
         path: 'compat/vcbuild/vcpkg'
@@ -208,7 +208,7 @@ jobs:
     - name: zip up tracked files
       run: git archive -o artifacts/tracked.tar.gz HEAD
     - name: upload tracked files and build artifacts
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v4
       with:
         name: vs-artifacts
         path: artifacts
@@ -226,7 +226,7 @@ jobs:
     steps:
     - uses: git-for-windows/setup-git-for-windows-sdk@v1
     - name: download tracked files and build artifacts
-      uses: actions/download-artifact@v6
+      uses: actions/download-artifact@v4
       with:
         name: vs-artifacts
         path: ${{github.workspace}}
@@ -244,7 +244,7 @@ jobs:
       run: ci/print-test-failures.sh
     - name: Upload failed tests' directories
       if: failure() && env.FAILED_TEST_ARTIFACTS != ''
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v4
       with:
         name: failed-tests-windows-vs-${{ matrix.nr }}
         path: ${{env.FAILED_TEST_ARTIFACTS}}
@@ -258,8 +258,8 @@ jobs:
       group: windows-meson-build-${{ github.ref }}
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     steps:
-    - uses: actions/checkout@v5
-    - uses: actions/setup-python@v6
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
     - name: Set up dependencies
       shell: pwsh
       run: pip install meson ninja
@@ -270,7 +270,7 @@ jobs:
       shell: pwsh
       run: meson compile -C build
     - name: Upload build artifacts
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v4
       with:
         name: windows-meson-artifacts
         path: build
@@ -286,29 +286,19 @@ jobs:
       group: windows-meson-test-${{ matrix.nr }}-${{ github.ref }}
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     steps:
-    - uses: actions/checkout@v5
-    - uses: actions/setup-python@v6
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
     - name: Set up dependencies
       shell: pwsh
       run: pip install meson ninja
     - name: Download build artifacts
-      uses: actions/download-artifact@v6
+      uses: actions/download-artifact@v4
       with:
         name: windows-meson-artifacts
         path: build
     - name: Test
       shell: pwsh
-      run: ci/run-test-slice-meson.sh build ${{matrix.nr}} 10
-    - name: print test failures
-      if: failure() && env.FAILED_TEST_ARTIFACTS != ''
-      shell: bash
-      run: ci/print-test-failures.sh
-    - name: Upload failed tests' directories
-      if: failure() && env.FAILED_TEST_ARTIFACTS != ''
-      uses: actions/upload-artifact@v4
-      with:
-        name: failed-tests-windows-meson-${{ matrix.nr }}
-        path: ${{env.FAILED_TEST_ARTIFACTS}}
+      run: meson test -C build --no-rebuild --print-errorlogs --slice "$(1+${{ matrix.nr }})/10"
 
   regular:
     name: ${{matrix.vector.jobname}} (${{matrix.vector.pool}})
@@ -323,16 +313,16 @@ jobs:
         vector:
           - jobname: osx-clang
             cc: clang
-            pool: macos-14
+            pool: macos-13
           - jobname: osx-reftable
             cc: clang
-            pool: macos-14
+            pool: macos-13
           - jobname: osx-gcc
             cc: gcc-13
-            pool: macos-14
+            pool: macos-13
           - jobname: osx-meson
             cc: clang
-            pool: macos-14
+            pool: macos-13
     env:
       CC: ${{matrix.vector.cc}}
       CC_PACKAGE: ${{matrix.vector.cc_package}}
@@ -341,7 +331,7 @@ jobs:
       TEST_OUTPUT_DIRECTORY: ${{github.workspace}}/t
     runs-on: ${{matrix.vector.pool}}
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
     - run: ci/install-dependencies.sh
     - run: ci/run-build-and-tests.sh
     - name: print test failures
@@ -349,7 +339,7 @@ jobs:
       run: ci/print-test-failures.sh
     - name: Upload failed tests' directories
       if: failure() && env.FAILED_TEST_ARTIFACTS != ''
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v4
       with:
         name: failed-tests-${{matrix.vector.jobname}}
         path: ${{env.FAILED_TEST_ARTIFACTS}}
@@ -362,7 +352,7 @@ jobs:
       CI_JOB_IMAGE: ubuntu-latest
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
     - run: ci/install-dependencies.sh
     - run: ci/run-build-and-minimal-fuzzers.sh
   dockerized:
@@ -389,8 +379,6 @@ jobs:
         - jobname: linux-breaking-changes
           cc: gcc
           image: ubuntu:rolling
-        - jobname: fedora-breaking-changes-meson
-          image: fedora:latest
         - jobname: linux-leaks
           image: ubuntu:rolling
           cc: gcc
@@ -408,6 +396,8 @@ jobs:
         # Supported until 2025-04-02.
         - jobname: linux32
           image: i386/ubuntu:focal
+        - jobname: pedantic
+          image: fedora:latest
         # A RHEL 8 compatible distro.  Supported until 2029-05-31.
         - jobname: almalinux-8
           image: almalinux:8
@@ -439,17 +429,17 @@ jobs:
         else
           apt-get -q update && apt-get -q -y install git
         fi
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
     - run: ci/install-dependencies.sh
     - run: useradd builder --create-home
     - run: chown -R builder .
-    - run: chmod a+w $GITHUB_ENV && sudo --preserve-env --set-home --user=builder ci/run-build-and-tests.sh
+    - run: sudo --preserve-env --set-home --user=builder ci/run-build-and-tests.sh
     - name: print test failures
       if: failure() && env.FAILED_TEST_ARTIFACTS != ''
       run: sudo --preserve-env --set-home --user=builder ci/print-test-failures.sh
     - name: Upload failed tests' directories
       if: failure() && env.FAILED_TEST_ARTIFACTS != ''
-      uses: actions/upload-artifact@v5
+      uses: actions/upload-artifact@v4
       with:
         name: failed-tests-${{matrix.vector.jobname}}
         path: ${{env.FAILED_TEST_ARTIFACTS}}
@@ -464,25 +454,10 @@ jobs:
       group: static-analysis-${{ github.ref }}
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
     - run: ci/install-dependencies.sh
     - run: ci/run-static-analysis.sh
     - run: ci/check-directional-formatting.bash
-  rust-analysis:
-    needs: ci-config
-    if: needs.ci-config.outputs.enabled == 'yes'
-    env:
-      jobname: RustAnalysis
-      CI_JOB_IMAGE: ubuntu:rolling
-    runs-on: ubuntu-latest
-    container: ubuntu:rolling
-    concurrency:
-      group: rust-analysis-${{ github.ref }}
-      cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
-    steps:
-    - uses: actions/checkout@v4
-    - run: ci/install-dependencies.sh
-    - run: ci/run-rust-checks.sh
   sparse:
     needs: ci-config
     if: needs.ci-config.outputs.enabled == 'yes'
@@ -494,7 +469,7 @@ jobs:
       group: sparse-${{ github.ref }}
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
     - name: Install other dependencies
       run: ci/install-dependencies.sh
     - run: make sparse
@@ -510,6 +485,6 @@ jobs:
       CI_JOB_IMAGE: ubuntu-latest
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
     - run: ci/install-dependencies.sh
     - run: ci/test-documentation.sh

.gitignore

@@ -1,6 +1,4 @@
 /fuzz_corpora
-/target/
-/Cargo.lock
 /GIT-BUILD-DIR
 /GIT-BUILD-OPTIONS
 /GIT-CFLAGS
@@ -89,7 +87,6 @@
 /git-init-db
 /git-interpret-trailers
 /git-instaweb
-/git-last-modified
 /git-log
 /git-ls-files
 /git-ls-remote
@@ -142,7 +139,6 @@
 /git-repack
 /git-replace
 /git-replay
-/git-repo
 /git-request-pull
 /git-rerere
 /git-reset

.gitlab-ci.yml

@@ -45,8 +45,6 @@ test:linux:
       - jobname: linux-breaking-changes
         image: ubuntu:20.04
         CC: gcc
-      - jobname: fedora-breaking-changes-meson
-        image: fedora:latest
       - jobname: linux-TEST-vars
         image: ubuntu:20.04
         CC: gcc
@@ -60,6 +58,8 @@ test:linux:
       - jobname: linux-asan-ubsan
         image: ubuntu:rolling
         CC: clang
+      - jobname: pedantic
+        image: fedora:latest
       - jobname: linux-musl-meson
         image: alpine:latest
       - jobname: linux32
@@ -70,8 +70,6 @@ test:linux:
   artifacts:
     paths:
       - t/failed-test-artifacts
-    reports:
-      junit: build/meson-logs/testlog.junit.xml
     when: on_failure
 
 test:osx:
@@ -112,16 +110,8 @@ test:osx:
   artifacts:
     paths:
       - t/failed-test-artifacts
-    reports:
-      junit: build/meson-logs/testlog.junit.xml
     when: on_failure
 
-.windows_before_script: &windows_before_script
-  # Disabling realtime monitoring fails on some of the runners, but it
-  # significantly speeds up test execution in the case where it works. We thus
-  # try our luck, but ignore any failures.
-  - Set-MpPreference -DisableRealtimeMonitoring $true; $true
-
 build:mingw64:
   stage: build
   tags:
@@ -129,7 +119,6 @@ build:mingw64:
   variables:
     NO_PERL: 1
   before_script:
-    - *windows_before_script
     - ./ci/install-sdk.ps1 -directory "git-sdk"
   script:
     - git-sdk/usr/bin/bash.exe -l -c 'ci/make-test-artifacts.sh artifacts'
@@ -146,7 +135,6 @@ test:mingw64:
     - job: "build:mingw64"
       artifacts: true
   before_script:
-    - *windows_before_script
     - git-sdk/usr/bin/bash.exe -l -c 'tar xf artifacts/artifacts.tar.gz'
     - New-Item -Path .git/info -ItemType Directory
     - New-Item .git/info/exclude -ItemType File -Value "/git-sdk"
@@ -160,10 +148,17 @@ test:mingw64:
   tags:
     - saas-windows-medium-amd64
   before_script:
-    - *windows_before_script
-    - choco install -y git meson ninja rust-ms
+    - choco install -y git meson ninja openssl
     - Import-Module $env:ChocolateyInstall\helpers\chocolateyProfile.psm1
     - refreshenv
+    # The certificate store for Python on Windows is broken and fails to fetch
+    # certificates, see https://bugs.python.org/issue36011. This seems to
+    # mostly be an issue with how the GitLab image is set up as it is a
+    # non-issue on GitHub Actions. Work around the issue by importing
+    # cetrificates manually.
+    - Invoke-WebRequest https://curl.haxx.se/ca/cacert.pem -OutFile cacert.pem
+    - openssl pkcs12 -export -nokeys -in cacert.pem -out certs.pfx -passout "pass:"
+    - Import-PfxCertificate -CertStoreLocation Cert:\LocalMachine\Root -FilePath certs.pfx
 
 build:msvc-meson:
   extends: .msvc-meson
@@ -185,9 +180,6 @@ test:msvc-meson:
   script:
     - meson test -C build --no-rebuild --print-errorlogs --slice $Env:CI_NODE_INDEX/$Env:CI_NODE_TOTAL
   parallel: 10
-  artifacts:
-    reports:
-      junit: build/meson-logs/testlog.junit.xml
 
 test:fuzz-smoke-tests:
   image: ubuntu:latest
@@ -212,17 +204,6 @@ static-analysis:
     - ./ci/run-static-analysis.sh
     - ./ci/check-directional-formatting.bash
 
-rust-analysis:
-  image: ubuntu:rolling
-  stage: analyze
-  needs: [ ]
-  variables:
-    jobname: RustAnalysis
-  before_script:
-    - ./ci/install-dependencies.sh
-  script:
-    - ./ci/run-rust-checks.sh
-
 check-whitespace:
   image: ubuntu:latest
   stage: analyze

.mailmap

@@ -81,8 +81,6 @@ Fredrik Kuivinen <frekui@gmail.com> <freku045@student.liu.se>
 Frédéric Heitzmann <frederic.heitzmann@gmail.com>
 Garry Dolley <gdolley@ucla.edu> <gdolley@arpnetworks.com>
 Glen Choo <glencbz@gmail.com> <chooglen@google.com>
-Greg Hurrell <greg@hurrell.net> <greg.hurrell@datadoghq.com>
-Greg Hurrell <greg@hurrell.net> <win@wincent.com>
 Greg Price <price@mit.edu> <price@MIT.EDU>
 Greg Price <price@mit.edu> <price@ksplice.com>
 Heiko Voigt <hvoigt@hvoigt.net> <git-list@hvoigt.net>
@@ -126,7 +124,6 @@ Jon Loeliger <jdl@jdl.com> <jdl@freescale.org>
 Jon Seymour <jon.seymour@gmail.com> <jon@blackcubes.dyndns.org>
 Jonathan Nieder <jrnieder@gmail.com> <jrnieder@uchicago.edu>
 Jonathan del Strother <jon.delStrother@bestbefore.tv> <maillist@steelskies.com>
-Jonathan Tan <jonathantanmy@fastmail.com> <jonathantanmy@google.com>
 Josh Triplett <josh@joshtriplett.org> <josh@freedesktop.org>
 Josh Triplett <josh@joshtriplett.org> <josht@us.ibm.com>
 Julian Phillips <julian@quantumfyre.co.uk> <jp3@quantumfyre.co.uk>

Cargo.toml

@@ -1,10 +0,0 @@
-[package]
-name = "gitcore"
-version = "0.1.0"
-edition = "2018"
-rust-version = "1.49.0"
-
-[lib]
-crate-type = ["staticlib"]
-
-[dependencies]

Documentation/BreakingChanges.adoc

@@ -165,57 +165,6 @@ 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).
@@ -290,31 +239,6 @@ These features will be removed.
 +
 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

Documentation/CodingGuidelines

@@ -650,12 +650,6 @@ 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.

Documentation/Makefile

@@ -34,7 +34,6 @@ 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
@@ -53,7 +52,6 @@ MAN7_TXT += gitcli.adoc
 MAN7_TXT += gitcore-tutorial.adoc
 MAN7_TXT += gitcredentials.adoc
 MAN7_TXT += gitcvs-migration.adoc
-MAN7_TXT += gitdatamodel.adoc
 MAN7_TXT += gitdiffcore.adoc
 MAN7_TXT += giteveryday.adoc
 MAN7_TXT += gitfaq.adoc
@@ -121,29 +119,19 @@ 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/unambiguous-types
 TECH_DOCS += technical/unit-tests
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
@@ -509,26 +497,9 @@ $(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.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
 
@@ -557,8 +528,6 @@ 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
 

Documentation/MyFirstContribution.adoc

@@ -52,15 +52,6 @@ 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
 
@@ -1153,11 +1144,6 @@ 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

Documentation/RelNotes/1.6.2.4.adoc

@@ -37,4 +37,3 @@ exec >/var/tmp/1
 echo O=$(git describe maint)
 O=v1.6.2.3-38-g318b847
 git shortlog --no-merges $O..maint
----

Documentation/RelNotes/2.51.2.adoc

@@ -1,45 +0,0 @@
-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.

Documentation/RelNotes/2.52.0.adoc

@@ -1,454 +0,0 @@
-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.
-
- * The "git refs exists" command that works like "git show-ref --exists"
-   has been added.
-
- * "git repo info" learns the 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
-   ":(optional)" 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.
-
- * "git repo structure", a new command.
-
- * The help text and manual page of "git bisect" command have been
-   made consistent with each other.
-
-
-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.
-
- * AI guidelines has been added to our documentation set.
-
- * Contributed credential helpers (obviously in contrib/) now have "cd
-   $there && make install" target.
-
- * The "MyFirstContribution" tutorial tells the reader how to send out
-   their patches; the section gained a hint to verify the message
-   reached the mailing list.
-
- * The "debug" ref-backend was missing a method implementation, which
-   has been corrected.
-
- * Build procedure for Wincred credential helper has been updated.
-
- * The build procedure based on meson learned to allow builders to
-   specify the directory to install HTML documents.
-
- * Building "git contacts" script (in contrib/) left the resulting
-   file unexecutable, which has been corrected.
-
-
-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).
-
- * Tests did not set up GNUPGHOME correctly, which is fixed but some
-   flaky tests are exposed in t1016, which needs to be addressed
-   before this topic can move forward.
-   (merge 6cd8369ef3 tz/test-prepare-gnupghome later to maint).
-
- * The patterns used in the .gitignore files use backslash in the way
-   documented for fnmatch(3); document as such to reduce confusion.
-   (merge 8a6d158a1d jk/doc-backslash-in-exclude later to maint).
-
- * The version of macos image used in GitHub CI has been updated to
-   macos-14, as the macos-13 that we have been using got deprecated.
-   Perforce binary used there has been changed to arm64 version to
-   match.
-   (merge 73b9cdb7c4 jc/ci-use-macos-14 later to maint).
-   (merge ffff0bb0da jc/ci-use-arm64-p4-on-macos 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).
-   (merge f711f37b05 eb/t1016-hash-transition-fix later to maint).
-   (merge 85333aa1af jk/test-delete-gpgsig-leakfix later to maint).

Documentation/RelNotes/2.53.0.adoc

@@ -1,265 +0,0 @@
-Git v2.53 Release Notes
-=======================
-
-UI, Workflows & Features
-------------------------
-
- * "git maintenance" command learned "is-needed" subcommand to tell if
-   it is necessary to perform various maintenance tasks.
-
- * "git replay" (experimental) learned to perform ref updates itself
-   in a transaction by default, instead of emitting where each refs
-   should point at and leaving the actual update to another command.
-
- * "git blame" learns "--diff-algorithm=<algo>" option.
-
- * "git repo info" learned "--all" option.
-
- * Both "git apply" and "git diff" learn a new whitespace error class,
-   "incomplete-line".
-
- * Add a new manual that describes the data model.
-
- * "git fast-import" learns "--strip-if-invalid" option to drop
-   invalid cryptographic signature from objects.
-
- * The use of "revision" (a connected set of commits) has been
-   clarified in the "git replay" documentation.
-
- * A help message from "git branch" now mentions "git help" instead of
-   "man" when suggesting to read some documentation.
-
- * "git repo struct" learned to take "-z" as a synonym to "--format=nul".
-
- * More object database related information are shown in "git repo
-   structure" output.
-
-
-Performance, Internal Implementation, Development Support etc.
---------------------------------------------------------------
-
- * The list of packfiles used in a running Git process is moved from
-   the packed_git structure into the packfile store.
-
- * Some ref backend storage can hold not just the object name of an
-   annotated tag, but the object name of the object the tag points at.
-   The code to handle this information has been streamlined.
-
- * As "git diff --quiet" only cares about the existence of any
-   changes, disable rename/copy detection to skip more expensive
-   processing whose result will be discarded anyway.
-
- * A part of code paths that deals with loose objects has been cleaned
-   up.
-
- * "make strip" has been taught to strip "scalar" as well as "git".
-
- * Dockerised jobs at the GitHub Actions CI have been taught to show
-   more details of failed tests.
-
- * Code refactoring around object database sources.
-
- * Halve the memory consumed by artificial filepairs created during
-   "git diff --find-copioes-harder", also making the operation run
-   faster.
-
- * The "git_istream" abstraction has been revamped to make it easier
-   to interface with pluggable object database design.
-
- * Rewrite the only use of "mktemp()" that is subject to TOCTOU race
-   and Stop using the insecure "mktemp()" function.
-   (merge 10bba537c4 rs/ban-mktemp later to maint).
-
- * In-code comment update to clarify that single-letter options are
-   outside of the scope of command line completion script.
-   (merge dc8a00fafe jc/completion-no-single-letter-options later to maint).
-
- * MEMZERO_ARRAY() helper is introduced to avoid clearing only the
-   first N bytes of an N-element array whose elements are larger than
-   a byte.
-
- * "git diff-files -R --find-copies-harder" has been taught to use
-   the potential copy sources from the index correctly.
-
- * Require C99 style flexible array member support from all platforms.
-
- * The code path that enumerates promisor objects have been optimized
-   to skip pointlessly parsing blob objects.
-
- * Prepare test suite for Git for Windows that supports symbolic
-   links.
-
- * Use hook API to replace ad-hoc invocation of hook scripts with the
-   run_command() API.
-
-
-Fixes since v2.52
------------------
-
- * Ever since we added whitespace rules for this project, we misspelt
-   an entry, which has been corrected.
-   (merge 358e94dc70 jc/gitattributes-whitespace-no-indent-fix later to maint).
-
- * The code to expand attribute macros has been rewritten to avoid
-   recursion to avoid running out of stack space in an uncontrolled
-   way.
-   (merge 42ed046866 jk/attr-macroexpand-wo-recursion later to maint).
-
- * Adding a repository that uses a different hash function is a no-no,
-   but "git submodule add" did nt prevent it, which has been corrected.
-   (merge 6fe288bfbc bc/submodule-force-same-hash later to maint).
-
- * An earlier check added to osx keychain credential helper to avoid
-   storing the credential itself supplied was overeager and rejected
-   credential material supplied by other helper backends that it would
-   have wanted to store, which has been corrected.
-   (merge 4580bcd235 kn/osxkeychain-idempotent-store-fix later to maint).
-
- * The "git repo structure" subcommand tried to align its output but
-   mixed up byte count and display column width, which has been
-   corrected.
-   (merge 7a03a10a3a jx/repo-struct-utf8width-fix later to maint).
-
- * Yet another corner case fix around renames in the "ort" merge
-   strategy.
-   (merge a562d90a35 en/ort-rename-another-fix later to maint).
-
- * Test leakfix.
-   (merge 14b561e768 jk/test-mktemp-leakfix later to maint).
-
- * Update a version of action used at the GitHub Actrions CI.
-   (merge cd99203f86 js/ci-github-setup-go-update later to maint).
-
- * The "return errno = EFOO, -1" construct, which is heavily used in
-   compat/mingw.c and triggers warnings under "-Wcomma", has been
-   rewritten to avoid the warnings.
-   (merge af3919816f js/mingw-assign-comma-fix later to maint).
-
- * Makefile based build have recently been updated to build a
-   libgit.a that also has reftable and xdiff objects; CMake based
-   build procedure has been updated to match.
-   (merge b0d5c88cca js/cmake-libgit-fix later to maint).
-
- * Under-allocation fix.
-   (merge d22a488482 js/wincred-get-credential-alloc-fix later to maint).
-
- * "git worktree list" attempts to show paths to worktrees while
-   aligning them, but miscounted display columns for the paths when
-   non-ASCII characters were involved, which has been corrected.
-   (merge 08dfa59835 pw/worktree-list-display-width-fix later to maint).
-
- * "Windows+meson" job at the GitHub Actions CI was hard to debug, as
-   it did not show and save failed test artifacts, which has been
-   corrected.
-   (merge 17bd1108ea jk/ci-windows-meson-test-fix later to maint).
-
- * Emulation code clean-up.
-   (merge 2367c6bcd6 gf/win32-pthread-cond-wait-err later to maint).
-
- * Various issues detected by Asan have been corrected.
-   (merge a031b6181a jk/asan-bonanza later to maint).
-
- * "git config get --path" segfaulted on an ":(optional)path" that
-   does not exist, which has been corrected.
-   (merge 0bd16856ff jc/optional-path later to maint).
-
- * The "--committer-date-is-author-date" option of "git am/rebase" is
-   a misguided one.  The documentation is updated to discourage its
-   use.
-   (merge fbf3d0669f kh/doc-committer-date-is-author-date later to maint).
-
- * The option help text given by "git config unset -h" described
-   the "--all" option to "replace", not "unset", multiple variables,
-   which has been corrected.
-   (merge 18bf67b753 rs/config-unset-opthelp-fix later to maint).
-
- * The error message given by "git config set", when the variable
-   being updated has more than one values defined, used old style "git
-   config" syntax with an incorrect option in its hint, both of which
-   have been corrected.
-   (merge df963f0df4 rs/config-set-multi-error-message-fix later to maint).
-
- * "git replay" forgot to omit the "gpgsig-sha256" extended header
-   from the resulting commit the same way it omits "gpgsig", which has
-   been corrected.
-   (merge 9f3a115087 pw/replay-exclude-gpgsig-fix later to maint).
-
- * A few tests have been updated to work under the shell compatible
-   mode of zsh.
-   (merge a92f243a94 bc/zsh-testsuite later to maint).
-
- * The way patience diff finds LCS has been optimized.
-   (merge c7e3b8085b yc/xdiff-patience-optim later to maint).
-
- * Recent optimization to "last-modified" command introduced use of
-   uninitialized block of memory, which has been corrected.
-   (merge fe4e60759b tc/last-modified-active-paths-optimization later to maint).
-
- * "git last-modified" used to mishandle "--" to mark the beginning of
-   pathspec, which has been corrected.
-   (merge 05491b90ce js/last-modified-with-sparse-checkouts later to maint).
-
- * Emulation code clean-up.
-   (merge 42aa7603aa gf/win32-pthread-cond-init later to maint).
-
- * "git submodule add" to add a submodule under <name> segfaulted,
-   when a submodule.<name>.something is already in .gitmodules file
-   without defining where its submodule.<name>.path is, which has been
-   corrected.
-   (merge dd8e8c786e jc/submodule-add later to maint).
-
- * "git fetch" that involves fetching tags, when a tag being fetched
-   needs to overwrite existing one, failed to fetch other tags, which
-   has been corrected.
-   (merge b7b17ec8a6 kn/fix-fetch-backfill-tag-with-batched-ref-updates later to maint).
-
- * Document "rev-list --filter-provided-objects" better.
-   (merge 6d8dc99478 jt/doc-rev-list-filter-provided-objects later to maint).
-
- * Even when there is no changes in the packfile and no need to
-   recompute bitmaps, "git repack" recomputed and updated the MIDX
-   file, which has been corrected.
-   (merge 6ce9d558ce ps/repack-avoid-noop-midx-rewrite later to maint).
-
- * Update HTTP tests to adjust for changes in curl 8.18.0
-   (merge 17f4b01da7 jk/test-curl-updates later to maint).
-
- * Workaround the "iconv" shipped as part of macOS, which is broken
-   handling stateful ISO/IEC 2022 encoded strings.
-   (merge cee341e9dd rs/macos-iconv-workaround later to maint).
-
- * Running "git diff" with "--name-only" and other options that allows
-   us not to look at the blob contents, while objects that are lazily
-   fetched from a promisor remote, caused use-after-free, which has
-   been corrected.
-
- * The ort merge machinery hit an assertion failure in a history with
-   criss-cross merges renamed a directory and a non-directory, which
-   has been corrected.
-   (merge 979ee83e8a en/ort-recursive-d-f-conflict-fix later to maint).
-
- * Other code cleanup, docfix, build fix, etc.
-   (merge 46207a54cc qj/doc-http-bad-want-response later to maint).
-   (merge df90eccd93 kh/doc-commit-extra-references later to maint).
-   (merge f18aa68861 rs/xmkstemp-simplify later to maint).
-   (merge fddba8f737 ja/doc-synopsis-style later to maint).
-   (merge 22ce0cb639 en/xdiff-cleanup-2 later to maint).
-   (merge 8ef7355a8f je/doc-pull later to maint).
-   (merge 48176f953f jc/capability-leak later to maint).
-   (merge 8cbbdc92f7 kh/doc-pre-commit-fix later to maint).
-   (merge d4bc39a4d9 mh/doc-config-gui-gcwarning later to maint).
-   (merge 41d425008a kh/doc-send-email-paragraph-fix later to maint).
-   (merge d4b732899e jc/macports-darwinports later to maint).
-   (merge bab391761d kj/pull-options-decl-cleanup later to maint).
-   (merge 007b8994d4 rs/t4014-git-version-string-fix later to maint).
-   (merge 4ce170c522 ds/doc-scalar-config later to maint).
-   (merge a0c813951a jc/doc-commit-signoff-config later to maint).
-   (merge 8ee262985a ja/doc-misc-fixes later to maint).
-   (merge 1722c2244b mh/doc-core-attributesfile later to maint).
-   (merge c469ca26c5 dk/ci-rust-fix later to maint).
-   (merge 12f0be0857 gf/clear-path-cache-cleanup later to maint).
-   (merge 949df6ed6b js/test-func-comment-fix later to maint).
-   (merge 93f894c001 bc/checkout-error-message-fix later to maint).
-   (merge abf05d856f rs/show-branch-prio-queue later to maint).
-   (merge 06188ea5f3 rs/parse-config-expiry-simplify later to maint).
-   (merge 861dbb1586 dd/t5403-modernise later to maint).

Documentation/SubmittingPatches

@@ -446,34 +446,6 @@ 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.
 
@@ -607,27 +579,14 @@ line via `git format-patch --notes`.
 [[the-topic-summary]]
 *This is EXPERIMENTAL*.
 
-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.
+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.
 
 [[attachment]]
 Do not attach the patch as a MIME attachment, compressed or not.

Documentation/blame-options.adoc

@@ -75,8 +75,7 @@ include::line-range-format.adoc[]
 	iso format is used. For supported values, see the discussion
 	of the --date option at linkgit:git-log[1].
 
---progress::
---no-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

Documentation/config.adoc

@@ -357,9 +357,7 @@ 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
 ~~~~~~~~~

Documentation/config/commitgraph.adoc

@@ -8,17 +8,6 @@ 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

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,9 +290,6 @@ 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
@@ -492,9 +489,10 @@ core.askPass::
 	command-line argument and write the password on its STDOUT.
 
 core.attributesFile::
-	Specifies the pathname to the file that contains attributes (see
-	linkgit:gitattributes[5]), in addition to `.gitattributes` (per-directory)
-	and `.git/info/attributes`. Its default value is
+	In addition to `.gitattributes` (per-directory) and
+	`.git/info/attributes`, Git looks into this file for attributes
+	(see linkgit:gitattributes[5]). Path expansions are made the same
+	way as for `core.excludesFile`. Its default value is
 	`$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not
 	set or empty, `$HOME/.config/git/attributes` is used instead.
 
@@ -533,25 +531,9 @@ core.commentString::
 	commented, and removes them after the editor returns
 	(default '#').
 +
-ifndef::with-breaking-changes[]
-If set to "auto", `git-commit` will select a character that is not
+If set to "auto", `git-commit` would 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
@@ -628,8 +610,6 @@ core.whitespace::
   part of the line terminator, i.e. with it, `trailing-space`
   does not trigger if the character before such a carriage-return
   is not a whitespace (not enabled by default).
-* `incomplete-line` treats the last line of a file that is missing the
-  newline at the end as an error (not enabled by default).
 * `tabwidth=<n>` tells how many character positions a tab occupies; this
   is relevant for `indent-with-non-tab` and when Git fixes `tab-in-indent`
   errors. The default tab width is 8. Allowed values are 1 to 63.

Documentation/config/fetch.adoc

@@ -1,32 +1,32 @@
-`fetch.recurseSubmodules`::
+fetch.recurseSubmodules::
 	This option controls whether `git fetch` (and the underlying fetch
 	in `git pull`) will recursively fetch into populated submodules.
-	This option can be set either to a boolean value or to `on-demand`.
+	This option can be set either to a boolean value or to 'on-demand'.
 	Setting it to a boolean changes the behavior of fetch and pull to
 	recurse unconditionally into submodules when set to true or to not
-	recurse at all when set to false. When set to `on-demand`, fetch and
+	recurse at all when set to false. When set to 'on-demand', fetch and
 	pull will only recurse into a populated submodule when its
 	superproject retrieves a commit that updates the submodule's
 	reference.
-	Defaults to `on-demand`, or to the value of `submodule.recurse` if set.
+	Defaults to 'on-demand', or to the value of 'submodule.recurse' if set.
 
-`fetch.fsckObjects`::
+fetch.fsckObjects::
 	If it is set to true, git-fetch-pack will check all fetched
 	objects. See `transfer.fsckObjects` for what's
-	checked. Defaults to `false`. If not set, the value of
+	checked. Defaults to false. If not set, the value of
 	`transfer.fsckObjects` is used instead.
 
-`fetch.fsck.<msg-id>`::
+fetch.fsck.<msg-id>::
 	Acts like `fsck.<msg-id>`, but is used by
 	linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See
 	the `fsck.<msg-id>` documentation for details.
 
-`fetch.fsck.skipList`::
+fetch.fsck.skipList::
 	Acts like `fsck.skipList`, but is used by
 	linkgit:git-fetch-pack[1] instead of linkgit:git-fsck[1]. See
 	the `fsck.skipList` documentation for details.
 
-`fetch.unpackLimit`::
+fetch.unpackLimit::
 	If the number of objects fetched over the Git native
 	transfer is below this
 	limit, then the objects will be unpacked into loose object
@@ -37,12 +37,12 @@
 	especially on slow filesystems.  If not set, the value of
 	`transfer.unpackLimit` is used instead.
 
-`fetch.prune`::
+fetch.prune::
 	If true, fetch will automatically behave as if the `--prune`
 	option was given on the command line.  See also `remote.<name>.prune`
 	and the PRUNING section of linkgit:git-fetch[1].
 
-`fetch.pruneTags`::
+fetch.pruneTags::
 	If true, fetch will automatically behave as if the
 	`refs/tags/*:refs/tags/*` refspec was provided when pruning,
 	if not set already. This allows for setting both this option
@@ -50,41 +50,41 @@
 	refs. See also `remote.<name>.pruneTags` and the PRUNING
 	section of linkgit:git-fetch[1].
 
-`fetch.all`::
+fetch.all::
 	If true, fetch will attempt to update all available remotes.
 	This behavior can be overridden by passing `--no-all` or by
 	explicitly specifying one or more remote(s) to fetch from.
-	Defaults to `false`.
+	Defaults to false.
 
-`fetch.output`::
+fetch.output::
 	Control how ref update status is printed. Valid values are
 	`full` and `compact`. Default value is `full`. See the
 	OUTPUT section in linkgit:git-fetch[1] for details.
 
-`fetch.negotiationAlgorithm`::
+fetch.negotiationAlgorithm::
 	Control how information about the commits in the local repository
 	is sent when negotiating the contents of the packfile to be sent by
-	the server.  Set to `consecutive` to use an algorithm that walks
-	over consecutive commits checking each one.  Set to `skipping` to
+	the server.  Set to "consecutive" to use an algorithm that walks
+	over consecutive commits checking each one.  Set to "skipping" to
 	use an algorithm that skips commits in an effort to converge
 	faster, but may result in a larger-than-necessary packfile; or set
-	to `noop` to not send any information at all, which will almost
+	to "noop" to not send any information at all, which will almost
 	certainly result in a larger-than-necessary packfile, but will skip
-	the negotiation step.  Set to `default` to override settings made
+	the negotiation step.  Set to "default" to override settings made
 	previously and use the default behaviour.  The default is normally
-	`consecutive`, but if `feature.experimental` is `true`, then the
-	default is `skipping`.  Unknown values will cause `git fetch` to
+	"consecutive", but if `feature.experimental` is true, then the
+	default is "skipping".  Unknown values will cause 'git fetch' to
 	error out.
 +
 See also the `--negotiate-only` and `--negotiation-tip` options to
 linkgit:git-fetch[1].
 
-`fetch.showForcedUpdates`::
-	Set to `false` to enable `--no-show-forced-updates` in
+fetch.showForcedUpdates::
+	Set to false to enable `--no-show-forced-updates` in
 	linkgit:git-fetch[1] and linkgit:git-pull[1] commands.
-	Defaults to `true`.
+	Defaults to true.
 
-`fetch.parallel`::
+fetch.parallel::
 	Specifies the maximal number of fetch operations to be run in parallel
 	at a time (submodules, or remotes when the `--multiple` option of
 	linkgit:git-fetch[1] is in effect).
@@ -94,16 +94,16 @@ A value of 0 will give some reasonable default. If unset, it defaults to 1.
 For submodules, this setting can be overridden using the `submodule.fetchJobs`
 config setting.
 
-`fetch.writeCommitGraph`::
+fetch.writeCommitGraph::
 	Set to true to write a commit-graph after every `git fetch` command
 	that downloads a pack-file from a remote. Using the `--split` option,
 	most executions will create a very small commit-graph file on top of
 	the existing commit-graph file(s). Occasionally, these files will
 	merge and the write may take longer. Having an updated commit-graph
 	file helps performance of many Git commands, including `git merge-base`,
-	`git push -f`, and `git log --graph`. Defaults to `false`.
+	`git push -f`, and `git log --graph`. Defaults to false.
 
-`fetch.bundleURI`::
+fetch.bundleURI::
 	This value stores a URI for downloading Git object data from a bundle
 	URI before performing an incremental fetch from the origin Git server.
 	This is similar to how the `--bundle-uri` option behaves in
@@ -115,9 +115,9 @@ If you modify this value and your repository has a `fetch.bundleCreationToken`
 value, then remove that `fetch.bundleCreationToken` value before fetching from
 the new bundle URI.
 
-`fetch.bundleCreationToken`::
+fetch.bundleCreationToken::
 	When using `fetch.bundleURI` to fetch incrementally from a bundle
-	list that uses the "`creationToken`" heuristic, this config value
+	list that uses the "creationToken" heuristic, this config value
 	stores the maximum `creationToken` value of the downloaded bundles.
 	This value is used to prevent downloading bundles in the future
 	if the advertised `creationToken` is not strictly larger than this

Documentation/config/gui.adoc

@@ -55,8 +55,3 @@ gui.blamehistoryctx::
 	linkgit:gitk[1] for the selected commit, when the `Show History
 	Context` menu item is invoked from 'git gui blame'. If this
 	variable is set to zero, the whole history is shown.
-
-gui.GCWarning::
-	Determines whether linkgit:git-gui[1] should prompt for garbage
-	collection when git detects a large number of loose objects in
-	the repository. The default value is "true".

Documentation/config/maintenance.adoc

@@ -16,36 +16,19 @@ 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.
+	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:
 +
-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.
+* `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. Manual repository maintenance uses the `gc` task.
+  task weekly.
 
 maintenance.<task>.enabled::
 	This boolean config option controls whether the maintenance task
@@ -92,22 +75,6 @@ maintenance.incremental-repack.auto::
 	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

Documentation/config/promisor.adoc

@@ -9,28 +9,6 @@ promisor.advertise::
 	"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"
@@ -50,42 +28,3 @@ promisor.acceptFromServer::
 	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].

Documentation/config/push.adoc

@@ -1,15 +1,15 @@
-`push.autoSetupRemote`::
-	If set to `true` assume `--set-upstream` on default push when no
+push.autoSetupRemote::
+	If set to "true" assume `--set-upstream` on default push when no
 	upstream tracking exists for the current branch; this option
-	takes effect with `push.default` options `simple`, `upstream`,
-	and `current`. It is useful if by default you want new branches
+	takes effect with push.default options 'simple', 'upstream',
+	and 'current'. It is useful if by default you want new branches
 	to be pushed to the default remote (like the behavior of
-	`push.default=current`) and you also want the upstream tracking
+	'push.default=current') and you also want the upstream tracking
 	to be set. Workflows most likely to benefit from this option are
-	`simple` central workflows where all branches are expected to
+	'simple' central workflows where all branches are expected to
 	have the same name on the remote.
 
-`push.default`::
+push.default::
 	Defines the action `git push` should take if no refspec is
 	given (whether from the command-line, config, or elsewhere).
 	Different values are well-suited for
@@ -18,28 +18,24 @@
 	`upstream` is probably what you want.  Possible values are:
 +
 --
-`nothing`;;
-do not push anything (error out) unless a refspec is
-given. This is primarily meant for people who want to
-avoid mistakes by always being explicit.
 
-`current`;;
-push the current branch to update a branch with the same
-name on the receiving end.  Works in both central and non-central
-workflows.
+* `nothing` - do not push anything (error out) unless a refspec is
+  given. This is primarily meant for people who want to
+  avoid mistakes by always being explicit.
 
-`upstream`;;
-push the current branch back to the branch whose
-changes are usually integrated into the current branch (which is
-called `@{upstream}`).  This mode only makes sense if you are
-pushing to the same repository you would normally pull from
-(i.e. central workflow).
+* `current` - push the current branch to update a branch with the same
+  name on the receiving end.  Works in both central and non-central
+  workflows.
 
-`tracking`;;
-this is a deprecated synonym for `upstream`.
+* `upstream` - push the current branch back to the branch whose
+  changes are usually integrated into the current branch (which is
+  called `@{upstream}`).  This mode only makes sense if you are
+  pushing to the same repository you would normally pull from
+  (i.e. central workflow).
 
-`simple`;;
-push the current branch with the same name on the remote.
+* `tracking` - This is a deprecated synonym for `upstream`.
+
+* `simple` - push the current branch with the same name on the remote.
 +
 If you are working on a centralized workflow (pushing to the same repository you
 pull from, which is typically `origin`), then you need to configure an upstream
@@ -48,17 +44,16 @@ branch with the same name.
 This mode is the default since Git 2.0, and is the safest option suited for
 beginners.
 
-`matching`;;
-push all branches having the same name on both ends.
-This makes the repository you are pushing to remember the set of
-branches that will be pushed out (e.g. if you always push `maint`
-and `master` there and no other branches, the repository you push
-to will have these two branches, and your local `maint` and
-`master` will be pushed there).
+* `matching` - push all branches having the same name on both ends.
+  This makes the repository you are pushing to remember the set of
+  branches that will be pushed out (e.g. if you always push 'maint'
+  and 'master' there and no other branches, the repository you push
+  to will have these two branches, and your local 'maint' and
+  'master' will be pushed there).
 +
 To use this mode effectively, you have to make sure _all_ the
 branches you would push out are ready to be pushed out before
-running `git push`, as the whole point of this mode is to allow you
+running 'git push', as the whole point of this mode is to allow you
 to push all of the branches in one go.  If you usually finish work
 on only one branch and push out the result, while other branches are
 unfinished, this mode is not for you.  Also this mode is not
@@ -71,24 +66,24 @@ new default).
 
 --
 
-`push.followTags`::
+push.followTags::
 	If set to true, enable `--follow-tags` option by default.  You
 	may override this configuration at time of push by specifying
 	`--no-follow-tags`.
 
-`push.gpgSign`::
-	May be set to a boolean value, or the string `if-asked`. A true
+push.gpgSign::
+	May be set to a boolean value, or the string 'if-asked'. A true
 	value causes all pushes to be GPG signed, as if `--signed` is
-	passed to linkgit:git-push[1]. The string `if-asked` causes
+	passed to linkgit:git-push[1]. The string 'if-asked' causes
 	pushes to be signed if the server supports it, as if
-	`--signed=if-asked` is passed to `git push`. A false value may
+	`--signed=if-asked` is passed to 'git push'. A false value may
 	override a value from a lower-priority config file. An explicit
 	command-line flag always overrides this config option.
 
-`push.pushOption`::
+push.pushOption::
 	When no `--push-option=<option>` argument is given from the
-	command line, `git push` behaves as if each _<option>_ of
-	this variable is given as `--push-option=<option>`.
+	command line, `git push` behaves as if each <value> of
+	this variable is given as `--push-option=<value>`.
 +
 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
@@ -114,26 +109,26 @@ This will result in only b (a and c are cleared).
 
 ----
 
-`push.recurseSubmodules`::
-	May be `check`, `on-demand`, `only`, or `no`, with the same behavior
-	as that of `push --recurse-submodules`.
-	If not set, `no` is used by default, unless `submodule.recurse` is
-	set (in which case a `true` value means `on-demand`).
+push.recurseSubmodules::
+	May be "check", "on-demand", "only", or "no", with the same behavior
+	as that of "push --recurse-submodules".
+	If not set, 'no' is used by default, unless 'submodule.recurse' is
+	set (in which case a 'true' value means 'on-demand').
 
-`push.useForceIfIncludes`::
-	If set to `true`, it is equivalent to specifying
+push.useForceIfIncludes::
+	If set to "true", it is equivalent to specifying
 	`--force-if-includes` as an option to linkgit:git-push[1]
 	in the command line. Adding `--no-force-if-includes` at the
 	time of push overrides this configuration setting.
 
-`push.negotiate`::
-	If set to `true`, attempt to reduce the size of the packfile
+push.negotiate::
+	If set to "true", attempt to reduce the size of the packfile
 	sent by rounds of negotiation in which the client and the
-	server attempt to find commits in common. If `false`, Git will
+	server attempt to find commits in common. If "false", Git will
 	rely solely on the server's ref advertisement to find commits
 	in common.
 
-`push.useBitmaps`::
-	If set to `false`, disable use of bitmaps for `git push` even if
-	`pack.useBitmaps` is `true`, without preventing other git operations
-	from using bitmaps. Default is `true`.
+push.useBitmaps::
+	If set to "false", disable use of bitmaps for "git push" even if
+	`pack.useBitmaps` is "true", without preventing other git operations
+	from using bitmaps. Default is true.

Documentation/config/replay.adoc

@@ -1,11 +0,0 @@
-replay.refAction::
-	Specifies the default mode for handling reference updates in
-	`git replay`. The value can be:
-+
---
-	* `update`: Update refs directly using an atomic transaction (default behavior).
-	* `print`: Output update-ref commands for pipeline use.
---
-+
-This setting can be overridden with the `--ref-action` command-line option.
-When not configured, `git replay` defaults to `update` mode.

Documentation/config/sendemail.adoc

@@ -88,8 +88,6 @@ sendemail.smtpServer::
 sendemail.smtpServerPort::
 sendemail.smtpServerOption::
 sendemail.smtpUser::
-sendemail.imapSentFolder::
-sendemail.useImapOnly::
 sendemail.thread::
 sendemail.transferEncoding::
 sendemail.validate::

Documentation/config/stash.adoc

@@ -1,32 +1,14 @@
-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`::
+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}
+	the untracked files of a stash entry.  Defaults to false. See
+	the description of the 'show' command in linkgit:git-stash[1].
 
-`stash.showPatch`::
+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}
+	See the description of the 'show' command in linkgit:git-stash[1].
 
-`stash.showStat`::
+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}
+	See the description of the 'show' command in linkgit:git-stash[1].

Documentation/config/tag.adoc

@@ -1,23 +1,17 @@
-`tag.forceSignAnnotated`::
+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.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`::
+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
+	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.
+	behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options.

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

Documentation/diff-algorithm-option.adoc

@@ -1,20 +0,0 @@
-`--diff-algorithm=(patience|minimal|histogram|myers)`::
-	Choose a diff algorithm. The variants are as follows:
-+
---
-   `default`;;
-   `myers`;;
-	The basic greedy diff algorithm. Currently, this is the default.
-   `minimal`;;
-	Spend extra time to make sure the smallest possible diff is
-	produced.
-   `patience`;;
-	Use "patience diff" algorithm when generating patches.
-   `histogram`;;
-	This algorithm extends the patience algorithm to "support
-	low-occurrence common elements".
---
-+
-For instance, if you configured the `diff.algorithm` variable to a
-non-default value and want to use the default one, then you
-have to use `--diff-algorithm=default` option.

Documentation/diff-format.adoc

@@ -103,7 +103,6 @@ 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

Documentation/diff-options.adoc

@@ -197,7 +197,26 @@ and starts with _<text>_, this algorithm attempts to prevent it from
 appearing as a deletion or addition in the output. It uses the "patience
 diff" algorithm internally.
 
-include::diff-algorithm-option.adoc[]
+`--diff-algorithm=(patience|minimal|histogram|myers)`::
+	Choose a diff algorithm. The variants are as follows:
++
+--
+   `default`;;
+   `myers`;;
+	The basic greedy diff algorithm. Currently, this is the default.
+   `minimal`;;
+	Spend extra time to make sure the smallest possible diff is
+	produced.
+   `patience`;;
+	Use "patience diff" algorithm when generating patches.
+   `histogram`;;
+	This algorithm extends the patience algorithm to "support
+	low-occurrence common elements".
+--
++
+For instance, if you configured the `diff.algorithm` variable to a
+non-default value and want to use the default one, then you
+have to use `--diff-algorithm=default` option.
 
 `--stat[=<width>[,<name-width>[,<count>]]]`::
 	Generate a diffstat. By default, as much space as necessary
@@ -486,8 +505,7 @@ endif::git-format-patch[]
 	Turn off rename detection, even when the configuration
 	file gives the default to do so.
 
-`--rename-empty`::
-`--no-rename-empty`::
+`--[no-]rename-empty`::
 	Whether to use empty blobs as rename source.
 
 ifndef::git-format-patch[]
@@ -875,33 +893,5 @@ 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].

Documentation/fetch-options.adoc

@@ -1,41 +1,40 @@
-`--all`::
-`--no-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`.
 
-`-a`::
-`--append`::
+-a::
+--append::
 	Append ref names and object names of fetched refs to the
 	existing contents of `.git/FETCH_HEAD`.  Without this
 	option old data in `.git/FETCH_HEAD` will be overwritten.
 
-`--atomic`::
+--atomic::
 	Use an atomic transaction to update local refs. Either all refs are
 	updated, or on error, no refs are updated.
 
-`--depth=<depth>`::
+--depth=<depth>::
 	Limit fetching to the specified number of commits from the tip of
 	each remote branch history. If fetching to a 'shallow' repository
 	created by `git clone` with `--depth=<depth>` option (see
 	linkgit:git-clone[1]), deepen or shorten the history to the specified
 	number of commits. Tags for the deepened commits are not fetched.
 
-`--deepen=<depth>`::
-	Similar to `--depth`, except it specifies the number of commits
+--deepen=<depth>::
+	Similar to --depth, except it specifies the number of commits
 	from the current shallow boundary instead of from the tip of
 	each remote branch history.
 
-`--shallow-since=<date>`::
+--shallow-since=<date>::
 	Deepen or shorten the history of a shallow repository to
-	include all reachable commits after _<date>_.
+	include all reachable commits after <date>.
 
-`--shallow-exclude=<ref>`::
+--shallow-exclude=<ref>::
 	Deepen or shorten the history of a shallow repository to
 	exclude commits reachable from a specified remote branch or tag.
 	This option can be specified multiple times.
 
-`--unshallow`::
+--unshallow::
 	If the source repository is complete, convert a shallow
 	repository to a complete one, removing all the limitations
 	imposed by shallow repositories.
@@ -43,13 +42,13 @@
 If the source repository is shallow, fetch as much as possible so that
 the current repository has the same history as the source repository.
 
-`--update-shallow`::
+--update-shallow::
 	By default when fetching from a shallow repository,
 	`git fetch` refuses refs that require updating
-	`.git/shallow`. This option updates `.git/shallow` and accepts such
+	.git/shallow. This option updates .git/shallow and accepts such
 	refs.
 
-`--negotiation-tip=(<commit>|<glob>)`::
+--negotiation-tip=<commit|glob>::
 	By default, Git will report, to the server, commits reachable
 	from all local refs to find common commits in an attempt to
 	reduce the size of the to-be-received packfile. If specified,
@@ -69,28 +68,27 @@ See also the `fetch.negotiationAlgorithm` and `push.negotiate`
 configuration variables documented in linkgit:git-config[1], and the
 `--negotiate-only` option below.
 
-`--negotiate-only`::
+--negotiate-only::
 	Do not fetch anything from the server, and instead print the
-	ancestors of the provided `--negotiation-tip=` arguments,
+	ancestors of the provided `--negotiation-tip=*` arguments,
 	which we have in common with the server.
 +
-This is incompatible with `--recurse-submodules=(yes|on-demand)`.
+This is incompatible with `--recurse-submodules=[yes|on-demand]`.
 Internally this is used to implement the `push.negotiate` option, see
 linkgit:git-config[1].
 
-`--dry-run`::
+--dry-run::
 	Show what would be done, without making any changes.
 
-`--porcelain`::
+--porcelain::
 	Print the output to standard output in an easy-to-parse format for
 	scripts. See section OUTPUT in linkgit:git-fetch[1] for details.
 +
-This is incompatible with `--recurse-submodules=(yes|on-demand)` and takes
+This is incompatible with `--recurse-submodules=[yes|on-demand]` and takes
 precedence over the `fetch.output` config option.
 
 ifndef::git-pull[]
-`--write-fetch-head`::
-`--no-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
@@ -98,65 +96,61 @@ ifndef::git-pull[]
 	file is never written.
 endif::git-pull[]
 
-`-f`::
-`--force`::
+-f::
+--force::
+	When 'git fetch' is used with `<src>:<dst>` refspec, it may
+	refuse to update the local branch as discussed
 ifdef::git-pull[]
-When `git fetch` is used with `<src>:<dst>` refspec, it may
-refuse to update the local branch as discussed
-in the _<refspec>_ part of the linkgit:git-fetch[1]
-documentation.
+	in the `<refspec>` part of the linkgit:git-fetch[1]
+	documentation.
 endif::git-pull[]
 ifndef::git-pull[]
-When `git fetch` is used with `<src>:<dst>` refspec, it may
-refuse to update the local branch as discussed in the _<refspec>_ part below.
+	in the `<refspec>` part below.
 endif::git-pull[]
-This option overrides that check.
+	This option overrides that check.
 
-`-k`::
-`--keep`::
+-k::
+--keep::
 	Keep downloaded pack.
 
 ifndef::git-pull[]
-`--multiple`::
-	Allow several _<repository>_ and _<group>_ arguments to be
-	specified. No __<refspec>__s may be specified.
+--multiple::
+	Allow several <repository> and <group> arguments to be
+	specified. No <refspec>s may be specified.
 
-`--auto-maintenance`::
-`--no-auto-maintenance`::
-`--auto-gc`::
-`--no-auto-gc`::
+--[no-]auto-maintenance::
+--[no-]auto-gc::
 	Run `git maintenance run --auto` at the end to perform automatic
-	repository maintenance if needed.
+	repository maintenance if needed. (`--[no-]auto-gc` is a synonym.)
 	This is enabled by default.
 
-`--write-commit-graph`::
-`--no-write-commit-graph`::
+--[no-]write-commit-graph::
 	Write a commit-graph after fetching. This overrides the config
 	setting `fetch.writeCommitGraph`.
 endif::git-pull[]
 
-`--prefetch`::
+--prefetch::
 	Modify the configured refspec to place all refs into the
 	`refs/prefetch/` namespace. See the `prefetch` task in
 	linkgit:git-maintenance[1].
 
-`-p`::
-`--prune`::
+-p::
+--prune::
 	Before fetching, remove any remote-tracking references that no
 	longer exist on the remote.  Tags are not subject to pruning
 	if they are fetched only because of the default tag
-	auto-following or due to a `--tags` option.  However, if tags
+	auto-following or due to a --tags option.  However, if tags
 	are fetched due to an explicit refspec (either on the command
 	line or in the remote configuration, for example if the remote
-	was cloned with the `--mirror` option), then they are also
+	was cloned with the --mirror option), then they are also
 	subject to pruning. Supplying `--prune-tags` is a shorthand for
 	providing the tag refspec.
 ifndef::git-pull[]
 +
 See the PRUNING section below for more details.
 
-`-P`::
-`--prune-tags`::
+-P::
+--prune-tags::
 	Before fetching, remove any local tags that no longer exist on
 	the remote if `--prune` is enabled. This option should be used
 	more carefully, unlike `--prune` it will remove any local
@@ -169,17 +163,17 @@ See the PRUNING section below for more details.
 endif::git-pull[]
 
 ifndef::git-pull[]
-`-n`::
+-n::
 endif::git-pull[]
-`--no-tags`::
+--no-tags::
 	By default, tags that point at objects that are downloaded
 	from the remote repository are fetched and stored locally.
 	This option disables this automatic tag following. The default
-	behavior for a remote may be specified with the `remote.<name>.tagOpt`
+	behavior for a remote may be specified with the remote.<name>.tagOpt
 	setting. See linkgit:git-config[1].
 
 ifndef::git-pull[]
-`--refetch`::
+--refetch::
 	Instead of negotiating with the server to avoid transferring commits and
 	associated objects that are already present locally, this option fetches
 	all objects as a fresh clone would. Use this to reapply a partial clone
@@ -188,29 +182,29 @@ ifndef::git-pull[]
 	object database pack consolidation to remove any duplicate objects.
 endif::git-pull[]
 
-`--refmap=<refspec>`::
+--refmap=<refspec>::
 	When fetching refs listed on the command line, use the
 	specified refspec (can be given more than once) to map the
 	refs to remote-tracking branches, instead of the values of
-	`remote.<name>.fetch` configuration variables for the remote
-	repository.  Providing an empty _<refspec>_ to the
+	`remote.*.fetch` configuration variables for the remote
+	repository.  Providing an empty `<refspec>` to the
 	`--refmap` option causes Git to ignore the configured
 	refspecs and rely entirely on the refspecs supplied as
 	command-line arguments. See section on "Configured Remote-tracking
 	Branches" for details.
 
-`-t`::
-`--tags`::
+-t::
+--tags::
 	Fetch all tags from the remote (i.e., fetch remote tags
 	`refs/tags/*` into local tags with the same name), in addition
 	to whatever else would otherwise be fetched.  Using this
-	option alone does not subject tags to pruning, even if `--prune`
+	option alone does not subject tags to pruning, even if --prune
 	is used (though tags may be pruned anyway if they are also the
 	destination of an explicit refspec; see `--prune`).
 
 ifndef::git-pull[]
-`--recurse-submodules[=(yes|on-demand|no)]`::
-	Control if and under what conditions new commits of
+--recurse-submodules[=(yes|on-demand|no)]::
+	This option controls if and under what conditions new commits of
 	submodules should be fetched too. When recursing through submodules,
 	`git fetch` always attempts to fetch "changed" submodules, that is, a
 	submodule that has commits that are referenced by a newly fetched
@@ -220,19 +214,19 @@ ifndef::git-pull[]
 	adds a new submodule, that submodule cannot be fetched until it is
 	cloned e.g. by `git submodule update`.
 +
-When set to `on-demand`, only changed submodules are fetched. When set
-to `yes`, all populated submodules are fetched and submodules that are
-both unpopulated and changed are fetched. When set to `no`, submodules
+When set to 'on-demand', only changed submodules are fetched. When set
+to 'yes', all populated submodules are fetched and submodules that are
+both unpopulated and changed are fetched. When set to 'no', submodules
 are never fetched.
 +
 When unspecified, this uses the value of `fetch.recurseSubmodules` if it
-is set (see linkgit:git-config[1]), defaulting to `on-demand` if unset.
-When this option is used without any value, it defaults to `yes`.
+is set (see linkgit:git-config[1]), defaulting to 'on-demand' if unset.
+When this option is used without any value, it defaults to 'yes'.
 endif::git-pull[]
 
-`-j <n>`::
-`--jobs=<n>`::
-	Parallelize all forms of fetching up to _<n>_ jobs at a time.
+-j::
+--jobs=<n>::
+	Number of parallel children to be used for all forms of fetching.
 +
 If the `--multiple` option was specified, the different remotes will be fetched
 in parallel. If multiple submodules are fetched, they will be fetched in
@@ -243,12 +237,12 @@ Typically, parallel recursive and multi-remote fetches will be faster. By
 default fetches are performed sequentially, not in parallel.
 
 ifndef::git-pull[]
-`--no-recurse-submodules`::
+--no-recurse-submodules::
 	Disable recursive fetching of submodules (this has the same effect as
 	using the `--recurse-submodules=no` option).
 endif::git-pull[]
 
-`--set-upstream`::
+--set-upstream::
 	If the remote is fetched successfully, add upstream
 	(tracking) reference, used by argument-less
 	linkgit:git-pull[1] and other commands. For more information,
@@ -256,57 +250,57 @@ endif::git-pull[]
 	linkgit:git-config[1].
 
 ifndef::git-pull[]
-`--submodule-prefix=<path>`::
-	Prepend _<path>_ to paths printed in informative messages
+--submodule-prefix=<path>::
+	Prepend <path> to paths printed in informative messages
 	such as "Fetching submodule foo".  This option is used
 	internally when recursing over submodules.
 
-`--recurse-submodules-default=(yes|on-demand)`::
+--recurse-submodules-default=[yes|on-demand]::
 	This option is used internally to temporarily provide a
-	non-negative default value for the `--recurse-submodules`
+	non-negative default value for the --recurse-submodules
 	option.  All other methods of configuring fetch's submodule
 	recursion (such as settings in linkgit:gitmodules[5] and
 	linkgit:git-config[1]) override this option, as does
-	specifying `--[no-]recurse-submodules` directly.
+	specifying --[no-]recurse-submodules directly.
 
-`-u`::
-`--update-head-ok`::
-	By default `git fetch` refuses to update the head which
+-u::
+--update-head-ok::
+	By default 'git fetch' refuses to update the head which
 	corresponds to the current branch.  This flag disables the
-	check.  This is purely for the internal use for `git pull`
-	to communicate with `git fetch`, and unless you are
+	check.  This is purely for the internal use for 'git pull'
+	to communicate with 'git fetch', and unless you are
 	implementing your own Porcelain you are not supposed to
 	use it.
 endif::git-pull[]
 
-`--upload-pack <upload-pack>`::
+--upload-pack <upload-pack>::
 	When given, and the repository to fetch from is handled
-	by `git fetch-pack`, `--exec=<upload-pack>` is passed to
+	by 'git fetch-pack', `--exec=<upload-pack>` is passed to
 	the command to specify non-default path for the command
 	run on the other end.
 
 ifndef::git-pull[]
-`-q`::
-`--quiet`::
-	Pass `--quiet` to `git-fetch-pack` and silence any other internally
+-q::
+--quiet::
+	Pass --quiet to git-fetch-pack and silence any other internally
 	used git commands. Progress is not reported to the standard error
 	stream.
 
-`-v`::
-`--verbose`::
+-v::
+--verbose::
 	Be verbose.
 endif::git-pull[]
 
-`--progress`::
+--progress::
 	Progress status is reported on the standard error stream
-	by default when it is attached to a terminal, unless `-q`
+	by default when it is attached to a terminal, unless -q
 	is specified. This flag forces progress status even if the
 	standard error stream is not directed to a terminal.
 
-`-o <option>`::
-`--server-option=<option>`::
+-o <option>::
+--server-option=<option>::
 	Transmit the given string to the server when communicating using
-	protocol version 2.  The given string must not contain a _NUL_ or _LF_
+	protocol version 2.  The given string must not contain a NUL or LF
 	character.  The server's handling of server options, including
 	unknown ones, is server-specific.
 	When multiple `--server-option=<option>` are given, they are all
@@ -315,23 +309,23 @@ endif::git-pull[]
 	the values of configuration variable `remote.<name>.serverOption`
 	are used instead.
 
-`--show-forced-updates`::
+--show-forced-updates::
 	By default, git checks if a branch is force-updated during
-	fetch. This can be disabled through `fetch.showForcedUpdates`, but
-	the `--show-forced-updates` option guarantees this check occurs.
+	fetch. This can be disabled through fetch.showForcedUpdates, but
+	the --show-forced-updates option guarantees this check occurs.
 	See linkgit:git-config[1].
 
-`--no-show-forced-updates`::
+--no-show-forced-updates::
 	By default, git checks if a branch is force-updated during
-	fetch. Pass `--no-show-forced-updates` or set `fetch.showForcedUpdates`
+	fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates
 	to false to skip this check for performance reasons. If used during
-	`git-pull` the `--ff-only` option will still check for forced updates
+	'git-pull' the --ff-only option will still check for forced updates
 	before attempting a fast-forward update. See linkgit:git-config[1].
 
-`-4`::
-`--ipv4`::
+-4::
+--ipv4::
 	Use IPv4 addresses only, ignoring IPv6 addresses.
 
-`-6`::
-`--ipv6`::
+-6::
+--ipv6::
 	Use IPv6 addresses only, ignoring IPv4 addresses.

Documentation/for-each-ref-options.adoc

@@ -1,85 +0,0 @@
-`<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.

Documentation/fsck-msgids.adoc

@@ -10,12 +10,6 @@
 `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.
 
@@ -44,9 +38,6 @@
 `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.
 
@@ -113,6 +104,9 @@
 `gitmodulesParse`::
 	(INFO) Could not parse `.gitmodules` blob.
 
+`gitmodulesLarge`;
+	(ERROR) `.gitmodules` blob is too large to parse.
+
 `gitmodulesPath`::
 	(ERROR) `.gitmodules` path is invalid.
 

Documentation/git-add.adoc

@@ -16,18 +16,18 @@ git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [-
 
 DESCRIPTION
 -----------
-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.
+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.
 
-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`.
+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.
 
 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,10 +37,12 @@ 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. 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.
+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.
 
 Please see linkgit:git-commit[1] for alternative ways to add content to a
 commit.
@@ -342,14 +344,13 @@ 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 - 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
+       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
        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

Documentation/git-am.adoc

@@ -48,8 +48,7 @@ OPTIONS
 --keep-non-patch::
 	Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
 
---keep-cr::
---no-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
@@ -162,13 +161,6 @@ Valid <action> for the `--whitespace` option are:
 	commit creation as the committer date. This allows the
 	user to lie about the committer date by using the same
 	value as the author date.
-+
-WARNING: The history walking machinery assumes that commits have
-non-decreasing commit timestamps. You should consider if you really need
-to use this option. Then you should only use this option to override the
-committer date when applying commits on top of a base which commit is
-older (in terms of the commit date) than the oldest patch you are
-applying.
 
 --ignore-date::
 	By default the command records the date from the e-mail

Documentation/git-backfill.adoc

@@ -57,8 +57,7 @@ OPTIONS
 	blobs seen at a given path. The default minimum batch size is
 	50,000.
 
-`--sparse`::
-`--no-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`.

Documentation/git-bisect.adoc

@@ -9,22 +9,26 @@ git-bisect - Use binary search to find the commit that introduced a bug
 SYNOPSIS
 --------
 [verse]
-'git bisect' start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
-		   [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
-'git bisect' (bad|new|<term-new>) [<rev>]
-'git bisect' (good|old|<term-old>) [<rev>...]
-'git bisect' terms [--term-(good|old) | --term-(bad|new)]
-'git bisect' skip [(<rev>|<range>)...]
-'git bisect' next
-'git bisect' reset [<commit>]
-'git bisect' (visualize|view)
-'git bisect' replay <logfile>
-'git bisect' log
-'git bisect' run <cmd> [<arg>...]
-'git bisect' help
+'git bisect' <subcommand> <options>
 
 DESCRIPTION
 -----------
+The command takes various subcommands, and different options depending
+on the subcommand:
+
+ git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>]
+		  [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...]
+ git bisect (bad|new|<term-new>) [<rev>]
+ git bisect (good|old|<term-old>) [<rev>...]
+ git bisect terms [--term-(good|old) | --term-(bad|new)]
+ git bisect skip [(<rev>|<range>)...]
+ git bisect reset [<commit>]
+ git bisect (visualize|view)
+ git bisect replay <logfile>
+ git bisect log
+ git bisect run <cmd> [<arg>...]
+ git bisect help
+
 This command uses a binary search algorithm to find which commit in
 your project's history introduced a bug. You use it by first telling
 it a "bad" commit that is known to contain the bug, and a "good"
@@ -291,19 +295,6 @@ $ git bisect skip v2.5 v2.5..v2.6
 This tells the bisect process that the commits between `v2.5` and
 `v2.6` (inclusive) should be skipped.
 
-Bisect next
-~~~~~~~~~~~
-
-Normally, after marking a revision as good or bad, Git automatically
-computes and checks out the next revision to test. However, if you need to
-explicitly request the next bisection step, you can use:
-
-------------
-$ git bisect next
-------------
-
-You might use this to resume the bisection process after interrupting it
-by checking out a different revision.
 
 Cutting down bisection by giving more parameters to bisect start
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Documentation/git-blame.adoc

@@ -85,8 +85,6 @@ include::blame-options.adoc[]
 	Ignore whitespace when comparing the parent's version and
 	the child's to find where the lines came from.
 
-include::diff-algorithm-option.adoc[]
-
 --abbrev=<n>::
 	Instead of using the default 7+1 hexadecimal digits as the
 	abbreviated object name, use <m>+1 digits, where <m> is at

Documentation/git-cat-file.adoc

@@ -62,10 +62,8 @@ OPTIONS
 	or to ask for a "blob" with `<object>` being a tag object that
 	points at it.
 
---mailmap::
---no-mailmap::
---use-mailmap::
---no-use-mailmap::
+--[no-]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].

Documentation/git-check-attr.adoc

@@ -19,8 +19,7 @@ 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.

Documentation/git-check-ignore.adoc

@@ -25,13 +25,11 @@ 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
@@ -51,8 +49,7 @@ 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

Documentation/git-check-ref-format.adoc

@@ -98,8 +98,7 @@ a branch.
 
 OPTIONS
 -------
---allow-onelevel::
---no-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`.

Documentation/git-checkout.adoc

@@ -12,29 +12,25 @@ 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] <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>...]
 
 DESCRIPTION
 -----------
-
-`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.
+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>]`::
-	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.
+	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>_.
 +
 If _<branch>_ is not found but there does exist a tracking branch in
 exactly one remote (call it _<remote>_) with a matching name and
@@ -44,63 +40,68 @@ exactly one remote (call it _<remote>_) with a matching name and
 $ git checkout -b <branch> --track <remote>/<branch>
 ------------
 +
-Running `git checkout` without specifying a branch has no effect except
-to print out the tracking information for the current 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 <new-branch> [<start-point>]`::
+`git checkout (-b|-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.
+	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.
 +
-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.
+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>
+------------
++
+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>`::
 
-	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.
+	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.
++
+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]`::
+`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]`::
 
-	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").
+	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>_.
 +
-For example, `git checkout main file.txt` will replace `file.txt`
-with the version from `main`.
-
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...`::
-`git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
-
-	Replace the specified files and/or directories with the version from
-	the index.
-+
-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.
+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 two modes, but lets you use the
+	This is similar to the previous mode, 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.
@@ -154,14 +155,16 @@ of it").
 	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.
+	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.
 
 `-t`::
 `--track[=(direct|inherit)]`::
 	When creating a new branch, set up "upstream" configuration. See
-	`--track` in linkgit:git-branch[1] for details. As a convenience,
-	--track without -b implies branch creation.
+	`--track` in linkgit:git-branch[1] for details.
 +
 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
@@ -331,7 +334,7 @@ include::diff-context-options.adoc[]
 	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
@@ -508,18 +511,14 @@ $ git log -g -2 HEAD
 ARGUMENT DISAMBIGUATION
 -----------------------
 
-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
-----------
+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.
 
 EXAMPLES
 --------

Documentation/git-clone.adoc

@@ -272,8 +272,7 @@ corresponding `--mirror` and `--no-tags` options instead.
 	reachable from a specified remote branch or tag.  This option
 	can be specified multiple times.
 
-`--single-branch`::
-`--no-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.
@@ -283,8 +282,7 @@ corresponding `--mirror` and `--no-tags` options instead.
 	branch when `--single-branch` clone was made, no remote-tracking
 	branch is created.
 
-`--tags`::
-`--no-tags`::
+`--[no-]tags`::
 	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
@@ -315,12 +313,10 @@ 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)
 
-`--shallow-submodules`::
-`--no-shallow-submodules`::
+`--[no-]shallow-submodules`::
 	All submodules which are cloned will be shallow with a depth of 1.
 
-`--remote-submodules`::
-`--no-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

Documentation/git-commit-graph.adoc

@@ -34,8 +34,7 @@ OPTIONS
 	object directory, `git commit-graph ...` will exit with non-zero
 	status.
 
---progress::
---no-progress::
+--[no-]progress::
 	Turn progress on/off explicitly. If neither is specified, progress is
 	shown if standard error is connected to a terminal.
 
@@ -71,7 +70,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. `--changed-paths` is implied by config `commitGraph.changedPaths=true`.
+data.
 +
 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

Documentation/git-commit.adoc

@@ -146,8 +146,7 @@ See linkgit:git-rebase[1] for details.
 	linkgit:git-status[1] for details. Implies `--dry-run`.
 
 `--branch`::
-	Show the branch and tracking info even in short-format. See
-	linkgit:git-status[1] for details.
+	Show the branch and tracking info even in short-format.
 
 `--porcelain`::
 	When doing a dry-run, give the output in a porcelain-ready
@@ -155,13 +154,12 @@ See linkgit:git-rebase[1] for details.
 	`--dry-run`.
 
 `--long`::
-	When doing a dry-run, give the output in the long-format. This
-	is the default output of linkgit:git-status[1]. Implies
-	`--dry-run`.
+	When doing a dry-run, give the output in the long-format.
+	Implies `--dry-run`.
 
 `-z`::
 `--null`::
-	When showing `short` or `porcelain` linkgit:git-status[1] output, print the
+	When showing `short` or `porcelain` status output, print the
 	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
@@ -216,8 +214,7 @@ include::signoff-option.adoc[]
 	each trailer would appear, and other details.
 
 `-n`::
-`--verify`::
-`--no-verify`::
+`--[no-]verify`::
 	Bypass the `pre-commit` and `commit-msg` hooks.
 	See also linkgit:githooks[5].
 
@@ -284,7 +281,6 @@ 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 ...

Documentation/git-config.adoc

@@ -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.
@@ -295,8 +295,7 @@ Valid `<type>`'s include:
 	When the color setting for `name` is undefined, the command uses
 	`color.ui` as fallback.
 
---includes::
---no-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

Documentation/git-difftool.adoc

@@ -77,8 +77,7 @@ 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`.
 
---symlinks::
---no-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
@@ -95,8 +94,7 @@ instead.  `--no-symlinks` is the default on Windows.
 	Additionally, `$BASE` is set in the environment.
 
 -g::
---gui::
---no-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
@@ -106,8 +104,7 @@ instead.  `--no-symlinks` is the default on Windows.
 	fallback in the order of `merge.guitool`, `diff.tool`,
 	`merge.tool` until a tool is found.
 
---trust-exit-code::
---no-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.

Documentation/git-fast-import.adoc

@@ -66,27 +66,6 @@ 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 `--signed-commits=<mode>` below, except that the
-	`strip-if-invalid` mode is not yet supported. Like for signed
-	commits, the default mode is `verbatim`.
-
-`--signed-commits=<mode>`::
-	Specify how to handle signed commits. The following <mode>s
-	are supported:
-+
-* `verbatim`, which is the default, will silently import commit
-  signatures.
-* `warn-verbatim` will import them, but will display a warning.
-* `abort` will make this program die when encountering a signed
-  commit.
-* `strip` will silently make the commits unsigned.
-* `warn-strip` will make them unsigned, but will display a warning.
-* `strip-if-invalid` will check signatures and, if they are invalid,
-  will strip them and display a warning. The validation is performed
-  in the same way as linkgit:git-verify-commit[1] does it.
-
 Options for Frontends
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -132,8 +111,7 @@ Locations of Marks Files
 	Like --import-marks but instead of erroring out, silently
 	skips the file if it does not exist.
 
---relative-marks::
---no-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.
@@ -627,11 +605,9 @@ 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

Documentation/git-fetch.adoc

@@ -8,11 +8,11 @@ git-fetch - Download objects and refs from another repository
 
 SYNOPSIS
 --------
-[synopsis]
-git fetch [<options>] [<repository> [<refspec>...]]
-git fetch [<options>] <group>
-git fetch --multiple [<options>] [(<repository>|<group>)...]
-git fetch --all [<options>]
+[verse]
+'git fetch' [<options>] [<repository> [<refspec>...]]
+'git fetch' [<options>] <group>
+'git fetch' --multiple [<options>] [(<repository> | <group>)...]
+'git fetch' --all [<options>]
 
 
 DESCRIPTION
@@ -20,19 +20,19 @@ DESCRIPTION
 Fetch branches and/or tags (collectively, "refs") from one or more
 other repositories, along with the objects necessary to complete their
 histories.  Remote-tracking branches are updated (see the description
-of _<refspec>_ below for ways to control this behavior).
+of <refspec> below for ways to control this behavior).
 
 By default, any tag that points into the histories being fetched is
 also fetched; the effect is to fetch tags that
 point at branches that you are interested in.  This default behavior
-can be changed by using the `--tags` or `--no-tags` options or by
-configuring `remote.<name>.tagOpt`.  By using a refspec that fetches tags
+can be changed by using the --tags or --no-tags options or by
+configuring remote.<name>.tagOpt.  By using a refspec that fetches tags
 explicitly, you can fetch tags that do not point into branches you
 are interested in as well.
 
-`git fetch` can fetch from either a single named repository or URL,
-or from several repositories at once if _<group>_ is given and
-there is a `remotes.<group>` entry in the configuration file.
+'git fetch' can fetch from either a single named repository or URL,
+or from several repositories at once if <group> is given and
+there is a remotes.<group> entry in the configuration file.
 (See linkgit:git-config[1]).
 
 When no remote is specified, by default the `origin` remote will be used,
@@ -48,15 +48,15 @@ include::fetch-options.adoc[]
 
 include::pull-fetch-param.adoc[]
 
-`--stdin`::
+--stdin::
 	Read refspecs, one per line, from stdin in addition to those provided
-	as arguments. The "tag _<name>_" format is not supported.
+	as arguments. The "tag <name>" format is not supported.
 
 include::urls-remotes.adoc[]
 
-[[CRTB]]
-CONFIGURED REMOTE-TRACKING BRANCHES
------------------------------------
+
+CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
+-------------------------------------------
 
 You often interact with the same remote repository by
 regularly and repeatedly fetching from it.  In order to keep track
@@ -84,13 +84,13 @@ This configuration is used in two ways:
 
 * When `git fetch` is run with explicit branches and/or tags
   to fetch on the command line, e.g. `git fetch origin master`, the
-  _<refspec>s_ given on the command line determine what are to be
+  <refspec>s given on the command line determine what are to be
   fetched (e.g. `master` in the example,
   which is a short-hand for `master:`, which in turn means
-  "fetch the `master` branch but I do not explicitly say what
+  "fetch the 'master' branch but I do not explicitly say what
   remote-tracking branch to update with it from the command line"),
   and the example command will
-  fetch _only_ the `master` branch.  The `remote.<repository>.fetch`
+  fetch _only_ the 'master' branch.  The `remote.<repository>.fetch`
   values determine which
   remote-tracking branch, if any, is updated.  When used in this
   way, the `remote.<repository>.fetch` values do not have any
@@ -144,9 +144,9 @@ tracking branches that are deleted, but any local tag that doesn't
 exist on the remote.
 
 This might not be what you expect, i.e. you want to prune remote
-_<name>_, but also explicitly fetch tags from it, so when you fetch
+`<name>`, but also explicitly fetch tags from it, so when you fetch
 from it you delete all your local tags, most of which may not have
-come from the _<name>_ remote in the first place.
+come from the `<name>` remote in the first place.
 
 So be careful when using this with a refspec like
 `refs/tags/*:refs/tags/*`, or any other refspec which might map
@@ -213,11 +213,11 @@ of the form:
 <flag> <old-object-id> <new-object-id> <local-reference>
 -------------------------------
 
-The status of up-to-date refs is shown only if the `--verbose` option is
+The status of up-to-date refs is shown only if the --verbose option is
 used.
 
 In compact output mode, specified with configuration variable
-fetch.output, if either entire _<from>_ or _<to>_ is found in the
+fetch.output, if either entire `<from>` or `<to>` is found in the
 other string, it will be substituted with `*` in the other string. For
 example, `master -> origin/master` becomes `master -> origin/*`.
 
@@ -303,7 +303,7 @@ include::config/fetch.adoc[]
 
 BUGS
 ----
-Using `--recurse-submodules` can only fetch new commits in submodules that are
+Using --recurse-submodules can only fetch new commits in submodules that are
 present locally e.g. in `$GIT_DIR/modules/`. If the upstream adds a new
 submodule, that submodule cannot be fetched until it is cloned e.g. by `git
 submodule update`. This is expected to be fixed in a future Git version.

Documentation/git-fmt-merge-msg.adoc

@@ -35,8 +35,7 @@ OPTIONS
 	Do not list one-line descriptions from the actual commits being
 	merged.
 
---summary::
---no-summary::
+--[no-]summary::
 	Synonyms to --log and --no-log; these are deprecated and will be
 	removed in the future.
 

Documentation/git-for-each-ref.adoc

@@ -14,21 +14,108 @@ git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
 		   [--merged[=<object>]] [--no-merged[=<object>]]
 		   [--contains[=<object>]] [--no-contains[=<object>]]
 		   [(--exclude=<pattern>)...] [--start-after=<marker>]
-		   [ --stdin | (<pattern>...)]
+		   [ --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
 -------
-include::for-each-ref-options.adoc[]
+<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.
+
+--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.
 
 FIELD NAMES
 -----------
@@ -39,44 +126,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, strip _<n>_
+	The option core.warnAmbiguousRefs is used to select the strict
+	abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<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
@@ -98,103 +185,100 @@ 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)
-`N`;; for no signature.
+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: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:<commit-ish>`::
+ahead-behind:<committish>::
 	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:<commit-ish>`::
-	In at most one row, `(<commit-ish>)` will appear to indicate the ref
+is-base:<committish>::
+	In at most one row, `(<committish>)` will appear to indicate the ref
 	that is most likely the ref used as a starting point for the branch
-	that produced _<commit-ish>_. This choice is made using a heuristic:
+	that produced `<committish>`. This choice is made using a heuristic:
 	choose the ref that minimizes the number of commits in the
-	first-parent history of _<commit-ish>_ and not in the first-parent
+	first-parent history of `<committish>` and not in the first-parent
 	history of the ref.
 +
 For example, consider the following figure of first-parent histories of
@@ -228,29 +312,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
-_<commit-ish>_ does not intersect the first-parent histories of the
+`<committish>` does not intersect the first-parent histories of the
 filtered refs.
 
-`describe[:<option>,...]`::
+describe[:options]::
 	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 `glob`(7) _<pattern>_,
-	excluding the `refs/tags/` prefix; see the corresponding option
+match=<pattern>;;
+	Only consider tags matching the given `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 `glob`(7) _<pattern>_,
-	excluding the `refs/tags/` prefix; see the corresponding option
+exclude=<pattern>;;
+	Do not consider tags matching the given `glob(7)` pattern,
+	excluding the "refs/tags/" prefix; see the corresponding option
 	in linkgit:git-describe[1] for details.
 --
 
@@ -282,7 +366,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`,
@@ -292,10 +376,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.
@@ -303,19 +387,19 @@ The message in a commit or a tag object is `contents`, from which
 	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[:<option>,...]` (or by using the historical alias
-`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers`
+are obtained as `trailers[:options]` (or by using the historical alias
+`contents:trailers[:options]`). For valid [:option] values see `trailers`
 section of linkgit:git-log[1].
 
 For sorting purposes, fields with numeric values sort in numeric order
@@ -335,8 +419,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
@@ -354,7 +438,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)
@@ -365,7 +449,7 @@ 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
@@ -433,7 +517,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.
 
 ------------
@@ -441,7 +525,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.
 
 ------------

Documentation/git-format-patch.adoc

@@ -295,8 +295,7 @@ 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`.
 
---force-in-body-from::
---no-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
@@ -315,8 +314,7 @@ feeding the result to `git send-email`.
 	`Cc:`, and custom) headers added so far from config or command
 	line.
 
---cover-letter::
---no-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.
@@ -381,8 +379,7 @@ configuration options in linkgit:git-notes[1] to use this workflow).
 The default is `--no-notes`, unless the `format.notes` configuration is
 set.
 
---signature=<signature>::
---no-signature::
+--[no-]signature=<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
@@ -414,8 +411,7 @@ 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::
---base[=<commit>]::
+--[no-]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

Documentation/git-fsck.adoc

@@ -31,8 +31,7 @@ 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.
 
---dangling::
---no-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.
 
@@ -98,16 +97,14 @@ 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/`.
 
---progress::
---no-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::
+--[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.

Documentation/git-gc.adoc

@@ -53,13 +53,11 @@ configuration options such as `gc.auto` and `gc.autoPackLimit`, all
 other housekeeping tasks (e.g. rerere, working trees, reflog...) will
 be performed as well.
 
---detach::
---no-detach::
+--[no-]detach::
 	Run in the background if the system supports it. This option overrides
 	the `gc.autoDetach` config.
 
---cruft::
---no-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.

Documentation/git-http-fetch.adoc

@@ -25,11 +25,8 @@ 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.
 

Documentation/git-index-pack.adoc

@@ -36,8 +36,7 @@ OPTIONS
 	fails if the name of packed archive does not end
 	with .pack).
 
---rev-index::
---no-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

Documentation/git-init.adoc

@@ -77,15 +77,9 @@ 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
-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.
+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).
 
 `--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
 

Documentation/git-last-modified.adoc

@@ -1,54 +0,0 @@
-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

Documentation/git-log.adoc

@@ -73,10 +73,8 @@ used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`,
 	Print out the ref name given on the command line by which each
 	commit was reached.
 
-`--mailmap`::
-`--no-mailmap`::
-`--use-mailmap`::
-`--no-use-mailmap`::
+`--[no-]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].

Documentation/git-maintenance.adoc

@@ -12,7 +12,6 @@ SYNOPSIS
 'git maintenance' run [<options>]
 'git maintenance' start [--scheduler=<scheduler>]
 'git maintenance' (stop|register|unregister) [<options>]
-'git maintenance' is-needed [<options>]
 
 
 DESCRIPTION
@@ -85,16 +84,6 @@ The `unregister` subcommand will report an error if the current repository
 is not already registered. Use the `--force` option to return success even
 when the current repository is not registered.
 
-is-needed::
-    Check whether maintenance needs to be run without actually running it.
-    Exits with a 0 status code if maintenance needs to be run, 1 otherwise.
-    Ideally used with the '--auto' flag.
-+
-If one or more `--task` options are specified, then those tasks are checked
-in that order. Otherwise, the tasks are determined by which
-`maintenance.<task>.enabled` config options are true. By default, only
-`maintenance.gc.enabled` is true.
-
 TASKS
 -----
 
@@ -194,8 +183,6 @@ OPTIONS
 	in the `gc.auto` config setting, or when the number of pack-files
 	exceeds the `gc.autoPackLimit` config setting. Not compatible with
 	the `--schedule` option.
-	When combined with the `is-needed` subcommand, check if the required
-	thresholds are met without actually running maintenance.
 
 --schedule::
 	When combined with the `run` subcommand, run maintenance tasks

Documentation/git-merge-tree.adoc

@@ -59,8 +59,7 @@ OPTIONS
 	do not list filenames multiple times if they have multiple
 	conflicting stages).
 
---messages::
---no-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

Documentation/git-multi-pack-index.adoc

@@ -25,8 +25,7 @@ OPTIONS
 +
 `<dir>` must be an alternate of the current repository.
 
---progress::
---no-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`.

Documentation/git-p4.adoc

@@ -66,7 +66,6 @@ Clone
 ~~~~~
 Generally, 'git p4 clone' is used to create a new Git directory
 from an existing p4 repository:
-
 ------------
 $ git p4 clone //depot/path/project
 ------------

Documentation/git-pack-objects.adoc

@@ -243,8 +243,7 @@ depth is 4095.
 	Add --no-reuse-object if you want to force a uniform compression
 	level on all data no matter the source.
 
---sparse::
---no-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.

Documentation/git-pack-refs.adoc

@@ -45,7 +45,58 @@ unpacked.
 OPTIONS
 -------
 
-include::pack-refs-options.adoc[]
+--all::
+
+The command by default packs all tags and refs that are already
+packed, and leaves other refs
+alone.  This is because branches are expected to be actively
+developed and packing their tips does not help performance.
+This option causes all refs to be packed as well, with the exception
+of hidden refs, broken refs, and symbolic refs. Useful for a repository
+with many branches of historical interests.
+
+--no-prune::
+
+The command usually removes loose refs under `$GIT_DIR/refs`
+hierarchy after packing them.  This option tells it not to.
+
+--auto::
+
+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": 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
+	  maintains the property that N is at least twice as big as N+1. Only
+	  tables that violate this property are compacted.
+
+--include <pattern>::
+
+Pack refs based on a `glob(7)` pattern. Repetitions of this option
+accumulate inclusion patterns. If a ref is both included in `--include` and
+`--exclude`, `--exclude` takes precedence. Using `--include` will preclude all
+tags from being included by default. Symbolic refs and broken refs will never
+be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear
+and reset the list of patterns.
+
+--exclude <pattern>::
+
+Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option
+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

Documentation/git-patch-id.adoc

@@ -7,8 +7,8 @@ git-patch-id - Compute unique ID for a patch
 
 SYNOPSIS
 --------
-[synopsis]
-git patch-id [--stable | --unstable | --verbatim]
+[verse]
+'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,35 +30,35 @@ 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
+  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
+  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
+  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`.
+This is the default if patchid.stable is set to true.
 
-`--unstable`::
+--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

Documentation/git-pull.adoc

@@ -8,73 +8,86 @@ git-pull - Fetch from and integrate with another repository or a local branch
 
 SYNOPSIS
 --------
-[synopsis]
-git pull [<options>] [<repository> [<refspec>...]]
+[verse]
+'git pull' [<options>] [<repository> [<refspec>...]]
 
 
 DESCRIPTION
 -----------
 
-Integrate changes from a remote repository into the current branch.
+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`).
 
-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.
+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.
 
-There are 4 main options for integrating the remote branch:
+<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.
 
-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`
+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`.
 
-You can also set the configuration options `pull.rebase`, `pull.squash`,
-or `pull.ff` with your preferred behaviour.
+Assume the following history exists and the current branch is
+"`master`":
 
-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`.
+------------
+	  A---B---C master on origin
+	 /
+    D---E---F---G master
+	^
+	origin/master in your repository
+------------
+
+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
+------------
+
+See linkgit:git-merge[1] for details, including how conflicts
+are presented and handled.
+
+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.
+
+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].
 
 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`::
+-q::
+--quiet::
 	This is passed to both underlying git-fetch to squelch reporting of
 	during transfer, and underlying git-merge to squelch output during
 	merging.
 
-`-v`::
-`--verbose`::
-	Pass `--verbose` to git-fetch and git-merge.
+-v::
+--verbose::
+	Pass --verbose to git-fetch and git-merge.
 
-`--recurse-submodules[=(yes|on-demand|no)]`::
-`--no-recurse-submodules`::
+--[no-]recurse-submodules[=(yes|on-demand|no)]::
 	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
@@ -91,20 +104,21 @@ Options related to merging
 
 include::merge-options.adoc[]
 
-`-r`::
-`--rebase[=(true|merges|false|interactive)]`::
-`true`;; rebase the current branch on top of the upstream
+-r::
+--rebase[=(false|true|merges|interactive)]::
+	When true, rebase the current branch on top of the upstream
 	branch after fetching. If there is a remote-tracking branch
 	corresponding to the upstream branch and the upstream branch
 	was rebased since last fetched, the rebase uses that information
-	to avoid rebasing non-local changes. This is the default.
-
-`merges`;; rebase using `git rebase --rebase-merges` so that
+	to avoid rebasing non-local changes.
++
+When set to `merges`, rebase using `git rebase --rebase-merges` so that
 the local merge commits are included in the rebase (see
 linkgit:git-rebase[1] for details).
-`false`;; merge the upstream branch into the current branch.
-`interactive`;; enable the interactive mode of rebase.
-
++
+When false, merge the upstream branch into the current branch.
++
+When `interactive`, enable the interactive mode of rebase.
 +
 See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
 linkgit:git-config[1] if you want to make `git pull` always use
@@ -116,8 +130,8 @@ It rewrites history, which does not bode well when you
 published that history already.  Do *not* use this option
 unless you have read linkgit:git-rebase[1] carefully.
 
-`--no-rebase`::
-	This is shorthand for `--rebase=false`.
+--no-rebase::
+	This is shorthand for --rebase=false.
 
 Options related to fetching
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -130,7 +144,6 @@ include::urls-remotes.adoc[]
 
 include::merge-strategies.adoc[]
 
-[[DEFAULT-BEHAVIOUR]]
 DEFAULT BEHAVIOUR
 -----------------
 
@@ -177,7 +190,7 @@ uses the refspec from the configuration or
 rules apply:
 
 . If `branch.<name>.merge` configuration for the current
-  branch _<name>_ exists, that is the name of the branch at the
+  branch `<name>` exists, that is the name of the branch at the
   remote site that is merged.
 
 . If the refspec is a globbing one, nothing is merged.
@@ -197,9 +210,9 @@ $ git pull
 $ git pull origin
 ------------------------------------------------
 +
-Normally the branch merged in is the `HEAD` of the remote repository,
-but the choice is determined by the `branch.<name>.remote` and
-`branch.<name>.merge` options; see linkgit:git-config[1] for details.
+Normally the branch merged in is the HEAD of the remote repository,
+but the choice is determined by the branch.<name>.remote and
+branch.<name>.merge options; see linkgit:git-config[1] for details.
 
 * Merge into the current branch the remote branch `next`:
 +
@@ -207,7 +220,7 @@ but the choice is determined by the `branch.<name>.remote` and
 $ git pull origin next
 ------------------------------------------------
 +
-This leaves a copy of `next` temporarily in `FETCH_HEAD`, and
+This leaves a copy of `next` temporarily in FETCH_HEAD, and
 updates the remote-tracking branch `origin/next`.
 The same can be done by invoking fetch and merge:
 +
@@ -218,14 +231,14 @@ $ git merge origin/next
 
 
 If you tried a pull which resulted in complex conflicts and
-would want to start over, you can recover with `git reset`.
+would want to start over, you can recover with 'git reset'.
 
 
 include::transfer-data-leaks.adoc[]
 
 BUGS
 ----
-Using `--recurse-submodules` can only fetch new commits in already checked
+Using --recurse-submodules can only fetch new commits in already checked
 out submodules right now. When e.g. upstream added a new submodule in the
 just fetched commits of the superproject the submodule itself cannot be
 fetched, making it impossible to check out that submodule later without

Documentation/git-push.adoc

@@ -8,125 +8,150 @@ git-push - Update remote refs along with associated objects
 
 SYNOPSIS
 --------
-[synopsis]
-git push [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
-	 [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose]
-	 [-u | --set-upstream] [-o <string> | --push-option=<string>]
-	 [--[no-]signed | --signed=(true|false|if-asked)]
-	 [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]]
-	 [--no-verify] [<repository> [<refspec>...]]
+[verse]
+'git push' [--all | --branches | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
+	   [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-q | --quiet] [-v | --verbose]
+	   [-u | --set-upstream] [-o <string> | --push-option=<string>]
+	   [--[no-]signed|--signed=(true|false|if-asked)]
+	   [--force-with-lease[=<refname>[:<expect>]] [--force-if-includes]]
+	   [--no-verify] [<repository> [<refspec>...]]
 
 DESCRIPTION
 -----------
 
-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.
-
-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`.
-
-The `<repository>` argument defaults to the upstream for the current branch,
-or `origin` if there's no configured upstream.
-
-To decide which branches, tags, or other refs to push, Git uses
-(in order of precedence):
-
-1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
-   or the `--all`, `--mirror`, or `--tags` options
-2. The `remote.<name>.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.
+Updates remote refs using local refs, while sending objects
+necessary to complete the given refs.
 
 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
--------
-_<repository>_::
+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'.
+
+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`).
+
+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.
+
+
+OPTIONS[[OPTIONS]]
+------------------
+<repository>::
 	The "remote" repository that is the destination of a push
 	operation.  This parameter can be either a URL
 	(see the section <<URLS,GIT URLS>> below) or the name
 	of a remote (see the section <<REMOTES,REMOTES>> below).
 
-`<refspec>...`::
+<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 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 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 _<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> 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>`.
 +
-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.
+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.
 +
-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.
+--
+* If <dst> unambiguously refers to a ref on the <repository> remote,
+  then push to that ref.
 
-Not all updates are allowed: see PUSH RULES below for the details.
+* If <src> resolves to a ref starting with refs/heads/ or refs/tags/,
+  then prepend that to <dst>.
 
-`--all`::
-`--branches`::
+* 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>`.
+
+--all::
+--branches::
 	Push all branches (i.e. refs under `refs/heads/`); cannot be
 	used with other <refspec>.
 
-`--prune`::
+--prune::
 	Remove remote branches that don't have a local counterpart. For example
 	a remote branch `tmp` will be removed if a local branch with the same
 	name doesn't exist any more. This also respects refspecs, e.g.
@@ -134,7 +159,7 @@ Not all updates are allowed: see PUSH RULES below for the details.
 	make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo`
 	doesn't exist.
 
-`--mirror`::
+--mirror::
 	Instead of naming each ref to push, specifies that all
 	refs under `refs/` (which includes but is not
 	limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
@@ -145,26 +170,26 @@ Not all updates are allowed: see PUSH RULES below for the details.
 	if the configuration option `remote.<remote>.mirror` is
 	set.
 
-`-n`::
-`--dry-run`::
+-n::
+--dry-run::
 	Do everything except actually send the updates.
 
-`--porcelain`::
+--porcelain::
 	Produce machine-readable output.  The output status line for each ref
 	will be tab-separated and sent to stdout instead of stderr.  The full
 	symbolic names of the refs will be given.
 
-`-d`::
-`--delete`::
+-d::
+--delete::
 	All listed refs are deleted from the remote repository. This is
 	the same as prefixing all refs with a colon.
 
-`--tags`::
+--tags::
 	All refs under `refs/tags` are pushed, in
 	addition to refspecs explicitly listed on the command
 	line.
 
-`--follow-tags`::
+--follow-tags::
 	Push all the refs that would be pushed without this option,
 	and also push annotated tags in `refs/tags` that are missing
 	from the remote but are pointing at commit-ish that are
@@ -172,34 +197,27 @@ Not all updates are allowed: see PUSH RULES below for the details.
 	with configuration variable `push.followTags`.  For more
 	information, see `push.followTags` in linkgit:git-config[1].
 
-`--signed`::
-`--no-signed`::
-`--signed=(true|false|if-asked)`::
+--[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
-	logged. Possible values are:
-`false`;;
-`--no-signed`;;
-no signing will be attempted.
-`true`;;
-`--signed`;;
-the push will fail if the server does not support signed pushes.
-`if-asked`;;
-sign if and only if the server supports signed pushes.  The push
-will also fail if the actual call to `gpg --sign` fails.  See
-linkgit:git-receive-pack[1] for the details on the receiving end.
+	logged.  If `false` or `--no-signed`, no signing will be
+	attempted.  If `true` or `--signed`, the push will fail if the
+	server does not support signed pushes.  If set to `if-asked`,
+	sign if and only if the server supports signed pushes.  The push
+	will also fail if the actual call to `gpg --sign` fails.  See
+	linkgit:git-receive-pack[1] for the details on the receiving end.
 
-`--atomic`::
-`--no-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.
 
-`-o <option>`::
-`--push-option=<option>`::
+-o <option>::
+--push-option=<option>::
 	Transmit the given string to the server, which passes them to
 	the pre-receive as well as the post-receive hook. The given string
-	must not contain a _NUL_ or _LF_ character.
+	must not contain a NUL or LF character.
 	When multiple `--push-option=<option>` are given, they are
 	all sent to the other side in the order listed on the
 	command line.
@@ -207,22 +225,21 @@ linkgit:git-receive-pack[1] for the details on the receiving end.
 	line, the values of configuration variable `push.pushOption`
 	are used instead.
 
-`--receive-pack=<git-receive-pack>`::
-`--exec=<git-receive-pack>`::
+--receive-pack=<git-receive-pack>::
+--exec=<git-receive-pack>::
 	Path to the 'git-receive-pack' program on the remote
 	end.  Sometimes useful when pushing to a remote
 	repository over ssh, and you do not have the program in
-	a directory on the default `$PATH`.
+	a directory on the default $PATH.
 
-`--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
+--[no-]force-with-lease::
+--force-with-lease=<refname>::
+--force-with-lease=<refname>:<expect>::
+	Usually, "git push" refuses to update a remote ref that is
 	not an ancestor of the local ref used to overwrite it.
 +
 This option overrides this restriction if the current value of the
-remote ref is the expected value.  `git push` fails otherwise.
+remote ref is the expected value.  "git push" fails otherwise.
 +
 Imagine that you have to rebase what you have already published.
 You will have to bypass the "must fast-forward" rule in order to
@@ -244,16 +261,16 @@ current value to be the same as the remote-tracking branch we have
 for them.
 +
 `--force-with-lease=<refname>`, without specifying the expected value, will
-protect _<refname>_ (alone), if it is going to be updated, by
+protect the named ref (alone), if it is going to be updated, by
 requiring its current value to be the same as the remote-tracking
 branch we have for it.
 +
-`--force-with-lease=<refname>:<expect>` will protect _<refname>_ (alone),
+`--force-with-lease=<refname>:<expect>` will protect the named ref (alone),
 if it is going to be updated, by requiring its current value to be
-the same as the specified value _<expect>_ (which is allowed to be
+the same as the specified value `<expect>` (which is allowed to be
 different from the remote-tracking branch we have for the refname,
 or we do not even have to have such a remote-tracking branch when
-this form is used).  If _<expect>_ is the empty string, then the named ref
+this form is used).  If `<expect>` is the empty string, then the named ref
 must not already exist.
 +
 Note that all forms other than `--force-with-lease=<refname>:<expect>`
@@ -261,7 +278,7 @@ that specifies the expected current value of the ref explicitly are
 still experimental and their semantics may change as we gain experience
 with this feature.
 +
-`--no-force-with-lease` will cancel all the previous `--force-with-lease` on the
+"--no-force-with-lease" will cancel all the previous --force-with-lease on the
 command line.
 +
 A general note on safety: supplying this option without an expected
@@ -281,29 +298,23 @@ If your editor or some other system is running `git fetch` in the
 background for you a way to mitigate this is to simply set up another
 remote:
 +
-----
-git remote add origin-push $(git config remote.origin.url)
-git fetch origin-push
-----
+	git remote add origin-push $(git config remote.origin.url)
+	git fetch origin-push
 +
 Now when the background process runs `git fetch origin` the references
 on `origin-push` won't be updated, and thus commands like:
 +
-----
-git push --force-with-lease origin-push
-----
+	git push --force-with-lease origin-push
 +
 Will fail unless you manually run `git fetch origin-push`. This method
 is of course entirely defeated by something that runs `git fetch
 --all`, in that case you'd need to either disable it or do something
 more tedious like:
 +
-----
-git fetch              # update 'master' from remote
-git tag base master    # mark our base point
-git rebase -i master   # rewrite some commits
-git push --force-with-lease=master:base master:master
-----
+	git fetch              # update 'master' from remote
+	git tag base master    # mark our base point
+	git rebase -i master   # rewrite some commits
+	git push --force-with-lease=master:base master:master
 +
 I.e. create a `base` tag for versions of the upstream code that you've
 seen and are willing to overwrite, then rewrite history, and finally
@@ -319,26 +330,27 @@ verify if updates from the remote-tracking refs that may have been
 implicitly updated in the background are integrated locally before
 allowing a forced update.
 
-`-f`::
-`--force`::
-	Usually, `git push` will refuse to update a branch that is not an
-	ancestor of the commit being pushed.
+-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.
 +
-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.
+This flag disables these checks, and 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
-destinations configured with `remote.<name>.push` may overwrite refs
+destinations configured with `remote.*.push` may overwrite refs
 other than the current branch (including local refs that are
 strictly behind their remote counterpart).  To force a push to only
 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.
 
-`--force-if-includes`::
-`--no-force-if-includes`::
+--[no-]force-if-includes::
 	Force an update only if the tip of the remote-tracking ref
 	has been integrated locally.
 +
@@ -354,78 +366,70 @@ a "no-op".
 +
 Specifying `--no-force-if-includes` disables this behavior.
 
-`--repo=<repository>`::
-	This option is equivalent to the _<repository>_ argument. If both
+--repo=<repository>::
+	This option is equivalent to the <repository> argument. If both
 	are specified, the command-line argument takes precedence.
 
-`-u`::
-`--set-upstream`::
+-u::
+--set-upstream::
 	For every branch that is up to date or successfully pushed, add
 	upstream (tracking) reference, used by argument-less
 	linkgit:git-pull[1] and other commands. For more information,
 	see `branch.<name>.merge` in linkgit:git-config[1].
 
-`--thin`::
-`--no-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
 	`--thin`.
 
-`-q`::
-`--quiet`::
+-q::
+--quiet::
 	Suppress all output, including the listing of updated refs,
 	unless an error occurs. Progress is not reported to the standard
 	error stream.
 
-`-v`::
-`--verbose`::
+-v::
+--verbose::
 	Run verbosely.
 
-`--progress`::
+--progress::
 	Progress status is reported on the standard error stream
-	by default when it is attached to a terminal, unless `-q`
+	by default when it is attached to a terminal, unless -q
 	is specified. This flag forces progress status even if the
 	standard error stream is not directed to a terminal.
 
-`--no-recurse-submodules`::
-`--recurse-submodules=(check|on-demand|only|no)`::
+--no-recurse-submodules::
+--recurse-submodules=check|on-demand|only|no::
 	May be used to make sure all submodule commits used by the
 	revisions to be pushed are available on a remote-tracking branch.
-	Possible values are:
-`check`;;
-        Git will verify that all submodule commits that
+	If 'check' is used Git will verify that all submodule commits that
 	changed in the revisions to be pushed are available on at least one
 	remote of the submodule. If any commits are missing the push will
-	be aborted and exit with non-zero status.
-`on-demand`;;
+	be aborted and exit with non-zero status. If 'on-demand' is used
 	all submodules that changed in the revisions to be pushed will be
-	pushed. If `on-demand` was not able to push all necessary revisions it will
-	also be aborted and exit with non-zero status.
-`only`;;
-	all submodules will be pushed while the superproject is left
-	unpushed.
-`no`;;
-	override the `push.recurseSubmodules` configuration variable when no
-	submodule recursion is required. Similar to using `--no-recurse-submodules`.
-
+	pushed. If on-demand was not able to push all necessary revisions it will
+	also be aborted and exit with non-zero status. If 'only' is used all
+	submodules will be pushed while the superproject is left
+	unpushed. A value of 'no' or using `--no-recurse-submodules` can be used
+	to override the push.recurseSubmodules configuration variable when no
+	submodule recursion is required.
 +
-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`.
+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".
 
-`--verify`::
-`--no-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.
+	default is --verify, giving the hook a chance to prevent the
+	push.  With --no-verify, the hook is bypassed completely.
 
-`-4`::
-`--ipv4`::
+-4::
+--ipv4::
 	Use IPv4 addresses only, ignoring IPv6 addresses.
 
-`-6`::
-`--ipv6`::
+-6::
+--ipv6::
 	Use IPv6 addresses only, ignoring IPv4 addresses.
 
 include::urls-remotes.adoc[]
@@ -444,16 +448,16 @@ representing the status of a single ref. Each line is of the form:
  <flag> <summary> <from> -> <to> (<reason>)
 -------------------------------
 
-If `--porcelain` is used, then each line of the output is of the form:
+If --porcelain is used, then each line of the output is of the form:
 
 -------------------------------
  <flag> \t <from>:<to> \t <summary> (<reason>)
 -------------------------------
 
-The status of up-to-date refs is shown only if `--porcelain` or `--verbose`
+The status of up-to-date refs is shown only if --porcelain or --verbose
 option is used.
 
-_<flag>_::
+flag::
 	A single character indicating the status of the ref:
 (space);; for a successfully pushed fast-forward;
 `+`;; for a successful forced update;
@@ -462,7 +466,7 @@ _<flag>_::
 `!`;; for a ref that was rejected or failed to push; and
 `=`;; for a ref that was up to date and did not need pushing.
 
-_<summary>_::
+summary::
 	For a successfully pushed ref, the summary shows the old and new
 	values of the ref in a form suitable for using as an argument to
 	`git log` (this is `<old>..<new>` in most cases, and
@@ -504,45 +508,6 @@ 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
 ------------------------
 
@@ -603,7 +568,7 @@ Updating A with the resulting merge commit will fast-forward and your
 push will be accepted.
 
 Alternatively, you can rebase your change between X and B on top of A,
-with `git pull --rebase`, and push the result back.  The rebase will
+with "git pull --rebase", and push the result back.  The rebase will
 create a new commit D that builds the change between X and B on top of
 A.
 
@@ -621,12 +586,12 @@ accepted.
 There is another common situation where you may encounter non-fast-forward
 rejection when you try to push, and it is possible even when you are
 pushing into a repository nobody else pushes into. After you push commit
-A yourself (in the first picture in this section), replace it with `git
-commit --amend` to produce commit B, and you try to push it out, because
+A yourself (in the first picture in this section), replace it with "git
+commit --amend" to produce commit B, and you try to push it out, because
 forgot that you have pushed A out already. In such a case, and only if
 you are certain that nobody in the meantime fetched your earlier commit A
-(and started building on top of it), you can run `git push --force` to
-overwrite it. In other words, `git push --force` is a method reserved for
+(and started building on top of it), you can run "git push --force" to
+overwrite it. In other words, "git push --force" is a method reserved for
 a case where you do mean to lose history.
 
 
@@ -644,18 +609,18 @@ EXAMPLES
 	variable) if it has the same name as the current branch, and
 	errors out without pushing otherwise.
 +
-The default behavior of this command when no _<refspec>_ is given can be
+The default behavior of this command when no <refspec> is given can be
 configured by setting the `push` option of the remote, or the `push.default`
 configuration variable.
 +
 For example, to default to pushing only the current branch to `origin`
-use `git config remote.origin.push HEAD`.  Any valid _<refspec>_ (like
+use `git config remote.origin.push HEAD`.  Any valid <refspec> (like
 the ones in the examples below) can be configured as the default for
 `git push origin`.
 
 `git push origin :`::
 	Push "matching" branches to `origin`. See
-	_<refspec>_ in the <<OPTIONS,OPTIONS>> section above for a
+	<refspec> in the <<OPTIONS,OPTIONS>> section above for a
 	description of "matching" branches.
 
 `git push origin master`::
@@ -732,7 +697,6 @@ a `git gc` command on the origin repository.
 
 include::transfer-data-leaks.adoc[]
 
-[[CONFIGURATION]]
 CONFIGURATION
 -------------
 

Documentation/git-range-diff.adoc

@@ -96,8 +96,7 @@ diff.
 --remerge-diff::
 	Convenience option, equivalent to `--diff-merges=remerge`.
 
---notes[=<ref>]::
---no-notes::
+--[no-]notes[=<ref>]::
 	This flag is passed to the `git log` program
 	(see linkgit:git-log[1]) that generates the patches.
 

Documentation/git-read-tree.adoc

@@ -100,8 +100,7 @@ OPTIONS
 	directories the index file and index output file are
 	located in.
 
---recurse-submodules::
---no-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

Documentation/git-rebase.adoc

@@ -16,12 +16,49 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-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 `<branch>` is specified, `git rebase` will perform an automatic
+`git switch <branch>` before doing anything else.  Otherwise
+it remains on the current branch.
 
-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.
+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":
 
 ------------
           A---B---C topic
@@ -29,11 +66,13 @@ history, and you want to "catch up" to the work done on the `master` branch.
     D---E---F---G master
 ------------
 
-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`.
+From this point, the result of either of the following commands:
+
+
+    git rebase master
+    git rebase master topic
+
+would be:
 
 ------------
                   A'--B'--C' topic
@@ -41,56 +80,30 @@ shortcut for `git checkout topic && git rebase master`.
     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 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:
+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):
 
-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
+------------
+          A---B---C topic
+         /
+    D---E---A'---F master
+------------
 
-   git rebase --continue
+will result in:
 
-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
-----------------------------------------
+------------
+                   B'---C' topic
+                  /
+    D---E---A'---F master
+------------
 
 Here is how you would transplant a topic branch based on one
 branch to another, to pretend that you forked the topic branch
@@ -173,6 +186,28 @@ 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
 ------------
 
@@ -218,8 +253,6 @@ 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
@@ -474,13 +507,6 @@ See also INCOMPATIBLE OPTIONS below.
 	Instead of using the current time as the committer date, use
 	the author date of the commit being rebased as the committer
 	date. This option implies `--force-rebase`.
-+
-WARNING: The history walking machinery assumes that commits have
-non-decreasing commit timestamps. You should consider if you really need
-to use this option. Then you should only use this option to override the
-committer date when rebasing commits on top of a base which commit is
-older (in terms of the commit date) than the oldest commit you are
-applying (in terms of the author date).
 
 --ignore-date::
 --reset-author-date::
@@ -661,7 +687,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

Documentation/git-refs.adoc

@@ -11,15 +11,6 @@ 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
 -----------
@@ -29,67 +20,43 @@ This command provides low-level access to refs.
 COMMANDS
 --------
 
-`migrate`::
+migrate::
 	Migrate ref store between different formats.
 
-`verify`::
+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`:
+The following options are specific to 'git refs migrate':
 
-`--ref-format=<format>`::
+--ref-format=<format>::
 	The ref format to migrate the ref store to. Can be one of:
 +
 include::ref-storage-format.adoc[]
 
-`--dry-run`::
+--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`::
+--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`:
+The following options are specific to 'git refs verify':
 
-`--strict`::
+--strict::
 	Enable stricter error checking. This will cause warnings to be
 	reported as errors. See linkgit:git-fsck[1].
 
-`--verbose`::
+--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
 -----------------
 

Documentation/git-repack.adoc

@@ -77,14 +77,14 @@ to the new separate pack will be written.
 	Only useful with `--cruft -d`.
 
 --max-cruft-size=<n>::
-	Override `--max-pack-size` for cruft packs. Inherits the value of
+	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>`
-	bytes, which can optionally
+	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

Documentation/git-replay.adoc

@@ -9,17 +9,16 @@ git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos t
 SYNOPSIS
 --------
 [verse]
-(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) [--ref-action[=<mode>]] <revision-range>
+(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) <revision-range>...
 
 DESCRIPTION
 -----------
 
-Takes a range of commits and replays them onto a new location. Leaves
-the working tree and the index untouched. By default, updates the
-relevant references using an atomic transaction (all refs update or
-none). Use `--ref-action=print` to avoid automatic ref updates and
-instead get update commands that can be piped to `git update-ref --stdin`
-(see the <<output,OUTPUT>> section below).
+Takes ranges of commits and replays them onto a new location. Leaves
+the working tree and the index untouched, and updates no references.
+The output of this command is meant to be used as input to
+`git update-ref --stdin`, which would update the relevant branches
+(see the OUTPUT section below).
 
 THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
 
@@ -30,51 +29,33 @@ OPTIONS
 	Starting point at which to create the new commits.  May be any
 	valid commit, and not just an existing branch name.
 +
-When `--onto` is specified, the branch(es) in the revision range will be
-updated to point at the new commits, similar to the way `git rebase --update-refs`
-updates multiple branches in the affected range.
+When `--onto` is specified, the update-ref command(s) in the output will
+update the branch(es) in the revision range to point at the new
+commits, similar to the way how `git rebase --update-refs` updates
+multiple branches in the affected range.
 
 --advance <branch>::
 	Starting point at which to create the new commits; must be a
 	branch name.
 +
-The history is replayed on top of the <branch> and <branch> is updated to
-point at the tip of the resulting history. This is different from `--onto`,
-which uses the target only as a starting point without updating it.
-
---contained::
-	Update all branches that point at commits in
-	<revision-range>. Requires `--onto`.
-
---ref-action[=<mode>]::
-	Control how references are updated. The mode can be:
-+
---
-	* `update` (default): Update refs directly using an atomic transaction.
-	  All refs are updated or none are (all-or-nothing behavior).
-	* `print`: Output update-ref commands for pipeline use. This is the
-	  traditional behavior where output can be piped to `git update-ref --stdin`.
---
-+
-The default mode can be configured via the `replay.refAction` configuration variable.
+When `--advance` is specified, the update-ref command(s) in the output
+will update the branch passed as an argument to `--advance` to point at
+the new commits (in other words, this mimics a cherry-pick operation).
 
 <revision-range>::
-	Range of commits to replay; see "Specifying Ranges" in
-	linkgit:git-rev-parse[1]. In `--advance <branch>` mode, the
-	range should have a single tip, so that it's clear to which tip the
-	advanced <branch> should point.
+	Range of commits to replay. More than one <revision-range> can
+	be passed, but in `--advance <branch>` mode, they should have
+	a single tip, so that it's clear where <branch> should point
+	to. See "Specifying Ranges" in linkgit:git-rev-parse[1] and the
+	"Commit Limiting" options below.
 
 include::rev-list-options.adoc[]
 
-[[output]]
 OUTPUT
 ------
 
-By default, or with `--ref-action=update`, this command produces no output on
-success, as refs are updated directly using an atomic transaction.
-
-When using `--ref-action=print`, the output is usable as input to
-`git update-ref --stdin`. It is of the form:
+When there are no conflicts, the output of this command is usable as
+input to `git update-ref --stdin`.  It is of the form:
 
 	update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
 	update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
@@ -85,10 +66,6 @@ the shape of the history being replayed.  When using `--advance`, the
 number of refs updated is always one, but for `--onto`, it can be one
 or more (rebasing multiple branches simultaneously is supported).
 
-There is no stderr output on conflicts; see the <<exit-status,EXIT
-STATUS>> section below.
-
-[[exit-status]]
 EXIT STATUS
 -----------
 
@@ -104,14 +81,6 @@ To simply rebase `mybranch` onto `target`:
 
 ------------
 $ git replay --onto target origin/main..mybranch
-------------
-
-The refs are updated atomically and no output is produced on success.
-
-To see what would be updated without actually updating:
-
-------------
-$ git replay --ref-action=print --onto target origin/main..mybranch
 update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH}
 ------------
 
@@ -119,29 +88,33 @@ To cherry-pick the commits from mybranch onto target:
 
 ------------
 $ git replay --advance target origin/main..mybranch
+update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH}
 ------------
 
 Note that the first two examples replay the exact same commits and on
 top of the exact same new base, they only differ in that the first
-updates mybranch to point at the new commits and the second updates
-target to point at them.
+provides instructions to make mybranch point at the new commits and
+the second provides instructions to make target point at them.
 
 What if you have a stack of branches, one depending upon another, and
 you'd really like to rebase the whole set?
 
 ------------
 $ git replay --contained --onto origin/main origin/main..tipbranch
+update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
+update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
+update refs/heads/tipbranch ${NEW_tipbranch_HASH} ${OLD_tipbranch_HASH}
 ------------
 
-All three branches (`branch1`, `branch2`, and `tipbranch`) are updated
-atomically.
-
 When calling `git replay`, one does not need to specify a range of
 commits to replay using the syntax `A..B`; any range expression will
 do:
 
 ------------
 $ git replay --onto origin/main ^base branch1 branch2 branch3
+update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH}
+update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH}
+update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH}
 ------------
 
 This will simultaneously rebase `branch1`, `branch2`, and `branch3`,

Documentation/git-repo.adoc

@@ -1,122 +0,0 @@
-git-repo(1)
-===========
-
-NAME
-----
-git-repo - Retrieve information about the repository
-
-SYNOPSIS
---------
-[synopsis]
-git repo info [--format=(keyvalue|nul) | -z] [--all | <key>...]
-git repo structure [--format=(table|keyvalue|nul) | -z]
-
-DESCRIPTION
------------
-Retrieve information about the repository.
-
-THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
-
-COMMANDS
---------
-`info [--format=(keyvalue|nul) | -z] [--all | <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 `--all` flag requests the values for all the available keys.
-+
-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) | -z]`::
-	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
-* Total inflated size of reachable objects by type
-* Total disk size of reachable objects 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.
-+
-`-z` is an alias for `--format=nul`.
-
-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

Documentation/git-reset.adoc

@@ -90,8 +90,7 @@ but carries forward unmerged index entries.
 	If a file that is different between _<commit>_ and `HEAD` has local
 	changes, reset is aborted.
 
-`--recurse-submodules`::
-`--no-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

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,12 +324,11 @@ 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|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-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-ref-format::
 	Show the reference storage format used for the repository.

Documentation/git-send-email.adoc

@@ -115,8 +115,7 @@ illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`:
 Only necessary if `--compose` is also set.  If `--compose`
 is not set, this will be prompted for.
 
---outlook-id-fix::
---no-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.
 +
@@ -208,7 +207,7 @@ Sending
 	for your own case. Default is the value of `sendemail.smtpEncryption`.
 
 --smtp-domain=<FQDN>::
-	Specify the Fully Qualified Domain Name (FQDN) used in the
+	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
@@ -245,7 +244,7 @@ a password is obtained using linkgit:git-credential[1].
 	Disable SMTP authentication. Short hand for `--smtp-auth=none`.
 
 --smtp-server=<host>::
-	Specify the outgoing SMTP server to use (e.g.
+	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
@@ -258,7 +257,7 @@ command names.  For those use cases, consider using `--sendmail-cmd`
 instead.
 
 --smtp-server-port=<port>::
-	Specify a port different from the default port (SMTP
+	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)
@@ -266,7 +265,7 @@ instead.
 	`sendemail.smtpServerPort` configuration variable.
 
 --smtp-server-option=<option>::
-	Specify the outgoing SMTP server option to use.
+	If set, specifies the outgoing SMTP server option to use.
 	Default value can be specified by the `sendemail.smtpServerOption`
 	configuration option.
 +
@@ -277,7 +276,7 @@ must be used for each option.
 --smtp-ssl::
 	Legacy alias for `--smtp-encryption ssl`.
 
---smtp-ssl-cert-path <path>::
+--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
@@ -300,31 +299,6 @@ must be used for each option.
 	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
@@ -346,11 +320,11 @@ Automating
 --no-to::
 --no-cc::
 --no-bcc::
-	Clear any list of `To:`, `Cc:`, `Bcc:` addresses previously
+	Clears any list of `To:`, `Cc:`, `Bcc:` addresses previously
 	set via config.
 
 --no-identity::
-	Clear the previously read value of `sendemail.identity` set
+	Clears the previously read value of `sendemail.identity` set
 	via config, if any.
 
 --to-cmd=<command>::
@@ -376,8 +350,7 @@ Automating
 --no-header-cmd::
 	Disable any header command in use.
 
---chain-reply-to::
---no-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
@@ -391,22 +364,19 @@ Automating
 	values in the `sendemail` section. The default identity is
 	the value of `sendemail.identity`.
 
---signed-off-by-cc::
---no-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::
+--[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::
+--[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`
@@ -437,14 +407,12 @@ 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::
+--[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::
+--[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`
@@ -462,8 +430,7 @@ exists when `git send-email` is asked to add it (especially note that
 Failure to do so may not produce the expected result in the
 recipient's MUA.
 
---mailmap::
---no-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
@@ -492,8 +459,7 @@ have been specified, in which case default to `compose`.
 --dry-run::
 	Do everything except actually send the emails.
 
---format-patch::
---no-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
@@ -503,18 +469,17 @@ have been specified, in which case default to `compose`.
 	Make `git send-email` less verbose.  One line per email should be
 	all that is output.
 
---validate::
---no-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.
+		*	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,

Documentation/git-send-pack.adoc

@@ -71,8 +71,7 @@ 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.
 
---signed::
---no-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

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

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 | clean) [<options>]
+'git sparse-checkout' (init | list | set | add | reapply | disable | check-rules) [<options>]
 
 
 DESCRIPTION
@@ -111,37 +111,6 @@ 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.
@@ -295,50 +264,34 @@ 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

Documentation/git-stash.adoc

@@ -7,24 +7,24 @@ git-stash - Stash the changes in a dirty working directory away
 
 SYNOPSIS
 --------
-[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]
+[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]
 	     [-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 export (--print | --to-ref <ref>) [<stash>...]
-git stash import <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
 -----------
@@ -38,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.
 
@@ -47,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,
@@ -65,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
@@ -88,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
@@ -96,12 +96,12 @@ command to control what is shown and how. See linkgit:git-log[1].
 	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
@@ -112,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
@@ -132,51 +132,54 @@ 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).
+	'Examples' below for a possible strategy).
+
+drop [-q|--quiet] [<stash>]::
 
-`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 ( --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 <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`.
@@ -184,12 +187,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
@@ -197,15 +200,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
@@ -221,8 +224,8 @@ The `--patch` option implies `--keep-index`.  You can use
 
 include::diff-context-options.adoc[]
 
-`-S`::
-`--staged`::
+-S::
+--staged::
 	This option is only valid for `push` and `save` commands.
 +
 Stash only the changes that are currently staged. This is similar to
@@ -231,49 +234,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`::
+--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`::
+--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
@@ -283,11 +286,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`, 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
@@ -416,7 +419,6 @@ CONFIGURATION
 
 include::includes/cmd-config-section-all.adoc[]
 
-:git-stash: 1
 include::config/stash.adoc[]
 
 

Documentation/git-submodule.adoc

@@ -442,8 +442,7 @@ options carefully.
 	clone with a history truncated to the specified number of revisions.
 	See linkgit:git-clone[1]
 
---recommend-shallow::
---no-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
@@ -455,8 +454,7 @@ options carefully.
 	Clone new submodules in parallel with as many jobs.
 	Defaults to the `submodule.fetchJobs` option.
 
---single-branch::
---no-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.
 

Documentation/git-svn.adoc

@@ -1012,11 +1012,9 @@ 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

Documentation/git-tag.adoc

@@ -3,26 +3,26 @@ git-tag(1)
 
 NAME
 ----
-git-tag - Create, list, delete or verify tags
+git-tag - Create, list, delete or verify a tag object signed with GPG
 
 
 SYNOPSIS
 --------
-[synopsis]
-git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
+[verse]
+'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,17 +38,15 @@ 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 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.
+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.
 
 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 cryptographic signature. Whereas a
+tagging message, and an optional GnuPG signature. Whereas a
 "lightweight" tag is simply a name for an object (usually a commit
 object).
 
@@ -60,134 +58,129 @@ lightweight tags by default.
 
 OPTIONS
 -------
-`-a`::
-`--annotate`::
+-a::
+--annotate::
 	Make an unsigned, annotated tag object
 
-`-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].
+-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].
 
-`--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 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].
+-u <key-id>::
+--local-user=<key-id>::
+	Make a GPG-signed tag, using the given key.
 
-`-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 cryptographic signature of the given tags.
+-v::
+--verify::
+	Verify the GPG signature of the given tag names.
 
-`-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 _<commit>_ (`HEAD` if not
+--contains [<commit>]::
+	Only list tags which contain the specified commit (HEAD if not
 	specified). Implies `--list`.
 
-`--no-contains [<commit>]`::
-	Only list tags which don't contain _<commit>_ (`HEAD` if
+--no-contains [<commit>]::
+	Only list tags which don't contain the specified commit (HEAD if
 	not specified). Implies `--list`.
 
-`--merged [<commit>]`::
-	Only list tags whose commits are reachable from
-	_<commit>_ (`HEAD` if not specified).
+--merged [<commit>]::
+	Only list tags whose commits are 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).
+--no-merged [<commit>]::
+	Only list tags whose commits are not reachable from the specified
+	commit (`HEAD` if not specified).
 
-`--points-at [<object>]`::
-	Only list tags of _<object>_ (`HEAD` if not
+--points-at <object>::
+	Only list tags of the given object (HEAD if not
 	specified). Implies `--list`.
 
-`-m <msg>`::
-`--message=<msg>`::
-	Use _<msg>_ (instead of prompting).
+-m <msg>::
+--message=<msg>::
+	Use the given tag message (instead of prompting).
 	If multiple `-m` options are given, their values are
 	concatenated as separate paragraphs.
 	Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
 	is given.
 
-`-F <file>`::
-`--file=<file>`::
-	Take the tag message from _<file>_.  Use `-` to
+-F <file>::
+--file=<file>::
+	Take the tag message from the given file.  Use '-' to
 	read the message from the standard input.
 	Implies `-a` if none of `-a`, `-s`, or `-u <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
@@ -197,68 +190,58 @@ 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`::
-	Let further edit the message taken from file with `-F` and command line with
-	`-m`.
+-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.
 
-`--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.
+--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.
 
-`--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 = <key-id>
+    signingKey = <gpg-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] for more details and other configuration
-variables.
+See linkgit:git-config[1].
 
 DISCUSSION
 ----------
@@ -269,7 +252,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
@@ -285,12 +268,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
@@ -342,7 +325,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:
 
 ------------
@@ -420,14 +403,6 @@ 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
 -----
 

Documentation/git-update-index.adoc

@@ -86,8 +86,7 @@ OPTIONS
 --chmod=(+|-)x::
         Set the execute permissions on the updated files.
 
---assume-unchanged::
---no-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
@@ -109,21 +108,18 @@ you will need to handle the situation manually.
 	Like `--refresh`, but checks stat information unconditionally,
 	without regard to the "assume unchanged" setting.
 
---skip-worktree::
---no-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.
 
 
---ignore-skip-worktree-entries::
---no-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.
 
---fsmonitor-valid::
---no-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

Documentation/git-upload-pack.adoc

@@ -25,8 +25,7 @@ repository.  For push operations, see 'git send-pack'.
 OPTIONS
 -------
 
---strict::
---no-strict::
+--[no-]strict::
 	Do not try <directory>/.git/ if <directory> is not a Git directory.
 
 --timeout=<n>::

Documentation/git-worktree.adoc

@@ -8,16 +8,16 @@ git-worktree - Manage multiple working trees
 
 SYNOPSIS
 --------
-[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>
+[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>
 
 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`).
+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,72 +154,69 @@ 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].
 
-`--checkout`::
-`--no-checkout`::
-	By default, `add` checks out _<commit-ish>_, however, `--no-checkout` can
+--[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].
 
-`--guess-remote`::
-`--no-guess-remote`::
-	With `worktree add <path>`, without _<commit-ish>_, instead
+--[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.
 
-`--relative-paths`::
-`--no-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].
@@ -227,60 +224,59 @@ 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.
 
-`--track`::
-`--no-track`::
-	When creating a new branch, if _<commit-ish>_ is a branch,
+--[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
@@ -522,13 +518,6 @@ $ 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

Documentation/gitcli.adoc

@@ -216,20 +216,6 @@ $ git describe --abbrev=10 HEAD  # correct
 $ 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, the above is 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
 ------------------------------------
 

Documentation/gitdatamodel.adoc

@@ -1,305 +0,0 @@
-gitdatamodel(7)
-===============
-
-NAME
-----
-gitdatamodel - Git's core data model
-
-SYNOPSIS
---------
-gitdatamodel
-
-DESCRIPTION
------------
-
-It's not necessary to understand Git's data model to use Git, but it's
-very helpful when reading Git's documentation so that you know what it
-means when the documentation says "object", "reference" or "index".
-
-Git's core operations use 4 kinds of data:
-
-1. <<objects,Objects>>: commits, trees, blobs, and tag objects
-2. <<references,References>>: branches, tags,
-   remote-tracking branches, etc
-3. <<index,The index>>, also known as the staging area
-4. <<reflogs,Reflogs>>: logs of changes to references ("ref log")
-
-[[objects]]
-OBJECTS
--------
-
-All of the commits and files in a Git repository are stored as "Git objects".
-Git objects never change after they're created, and every object has an ID,
-like `1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a`.
-
-This means that if you have an object's ID, you can always recover its
-exact contents as long as the object hasn't been deleted.
-
-Every object has:
-
-[[object-id]]
-1. an *ID* (aka "object name"), which is a cryptographic hash of its
-  type and contents.
-  It's fast to look up a Git object using its ID.
-  This is usually represented in hexadecimal, like
-  `1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a`.
-2. a *type*. There are 4 types of objects:
-   <<commit,commits>>, <<tree,trees>>, <<blob,blobs>>,
-   and <<tag-object,tag objects>>.
-3. *contents*. The structure of the contents depends on the type.
-
-Here's how each type of object is structured:
-
-[[commit]]
-commit::
-    A commit contains these required fields
-    (though there are other optional fields):
-+
-1. The full directory structure of all the files in that version of the
-   repository and each file's contents, stored as the *<<tree,tree>>* ID
-   of the commit's top-level directory
-2. Its *parent commit ID(s)*. The first commit in a repository has 0 parents,
-  regular commits have 1 parent, merge commits have 2 or more parents
-3. An *author* and the time the commit was authored
-4. A *committer* and the time the commit was committed
-5. A *commit message*
-+
-Here's how an example commit is stored:
-+
-----
-tree 1b61de420a21a2f1aaef93e38ecd0e45e8bc9f0a
-parent 4ccb6d7b8869a86aae2e84c56523f8705b50c647
-author Maya <maya@example.com> 1759173425 -0400
-committer Maya <maya@example.com> 1759173425 -0400
-
-Add README
-----
-+
-Like all other objects, commits can never be changed after they're created.
-For example, "amending" a commit with `git commit --amend` creates a new
-commit with the same parent.
-+
-Git does not store the diff for a commit: when you ask Git to show
-the commit with linkgit:git-show[1], it calculates the diff from its
-parent on the fly.
-
-[[tree]]
-tree::
-    A tree is how Git represents a directory.
-    It can contain files or other trees (which are subdirectories).
-    It lists, for each item in the tree:
-+
-1. The *filename*, for example `hello.py`
-2. The *file type*, which must be one of these five types:
-  - *regular file*
-  - *executable file*
-  - *symbolic link*
-  - *directory*
-  - *gitlink* (for use with submodules)
-3. The <<object-id,*object ID*>> with the contents of the file, directory,
-   or gitlink.
-+
-For example, this is how a tree containing one directory (`src`) and one file
-(`README.md`) is stored:
-+
-----
-100644 blob 8728a858d9d21a8c78488c8b4e70e531b659141f README.md
-040000 tree 89b1d2e0495f66d6929f4ff76ff1bb07fc41947d src
-----
-
-NOTE: In the output above, Git displays the file type of each tree entry
-using a format that's loosely modelled on Unix file modes (`100644` is
-"regular file", `100755` is "executable file", `120000` is "symbolic
-link", `040000` is "directory", and `160000` is "gitlink"). It also
-displays the object's type: `blob` for files and symlinks, `tree` for
-directories, and `commit` for gitlinks.
-
-[[blob]]
-blob::
-    A blob object contains a file's contents.
-+
-When you make a commit, Git stores the full contents of each file that
-you changed as a blob.
-For example, if you have a commit that changes 2 files in a repository
-with 1000 files, that commit will create 2 new blobs, and use the
-previous blob ID for the other 998 files.
-This means that commits can use relatively little disk space even in a
-very large repository.
-
-[[tag-object]]
-tag object::
-    Tag objects contain these required fields
-    (though there are other optional fields):
-+
-1. The *ID* of the object it references
-2. The *type* of the object it references
-3. The *tagger* and tag date
-4. A *tag message*, similar to a commit message
-
-Here's how an example tag object is stored:
-
-----
-object 750b4ead9c87ceb3ddb7a390e6c7074521797fb3
-type commit
-tag v1.0.0
-tagger Maya <maya@example.com> 1759927359 -0400
-
-Release version 1.0.0
-----
-
-NOTE: All of the examples in this section were generated with
-`git cat-file -p <object-id>`.
-
-[[references]]
-REFERENCES
-----------
-
-References are a way to give a name to a commit.
-It's easier to remember "the changes I'm working on are on the `turtle`
-branch" than "the changes are in commit bb69721404348e".
-Git often uses "ref" as shorthand for "reference".
-
-References can either refer to:
-
-1. An object ID, usually a <<commit,commit>> ID
-2. Another reference. This is called a "symbolic reference"
-
-References are stored in a hierarchy, and Git handles references
-differently based on where they are in the hierarchy.
-Most references are under `refs/`. Here are the main types:
-
-[[branch]]
-branches: `refs/heads/<name>`::
-    A branch refers to a commit ID.
-    That commit is the latest commit on the branch.
-+
-To get the history of commits on a branch, Git will start at the commit
-ID the branch references, and then look at the commit's parent(s),
-the parent's parent, etc.
-
-[[tag]]
-tags: `refs/tags/<name>`::
-    A tag refers to a commit ID, tag object ID, or other object ID.
-    There are two types of tags:
-    1. "Annotated tags", which reference a <<tag-object,tag object>> ID
-       which contains a tag message
-    2. "Lightweight tags", which reference a commit, blob, or tree ID
-       directly
-+
-Even though branches and tags both refer to a commit ID, Git
-treats them very differently.
-Branches are expected to change over time: when you make a commit, Git
-will update your <<HEAD,current branch>> to point to the new commit.
-Tags are usually not changed after they're created.
-
-[[HEAD]]
-HEAD: `HEAD`::
-    `HEAD` is where Git stores your current <<branch,branch>>,
-    if there is a current branch. `HEAD` can either be:
-+
-1. A symbolic reference to your current branch, for example `ref:
-   refs/heads/main` if your current branch is `main`.
-2. A direct reference to a commit ID. In this case there is no current branch.
-   This is called "detached HEAD state", see the DETACHED HEAD section
-   of linkgit:git-checkout[1] for more.
-
-[[remote-tracking-branch]]
-remote-tracking branches: `refs/remotes/<remote>/<branch>`::
-    A remote-tracking branch refers to a commit ID.
-    It's how Git stores the last-known state of a branch in a remote
-    repository. `git fetch` updates remote-tracking branches. When
-    `git status` says "you're up to date with origin/main", it's looking at
-    this.
-+
-`refs/remotes/<remote>/HEAD` is a symbolic reference to the remote's
-default branch. This is the branch that `git clone` checks out by default.
-
-[[other-refs]]
-Other references::
-    Git tools may create references anywhere under `refs/`.
-    For example, linkgit:git-stash[1], linkgit:git-bisect[1],
-    and linkgit:git-notes[1] all create their own references
-    in `refs/stash`, `refs/bisect`, etc.
-    Third-party Git tools may also create their own references.
-+
-Git may also create references other than `HEAD` at the base of the
-hierarchy, like `ORIG_HEAD`.
-
-NOTE: Git may delete objects that aren't "reachable" from any reference
-or <<reflogs,reflog>>.
-An object is "reachable" if we can find it by following tags to whatever
-they tag, commits to their parents or trees, and trees to the trees or
-blobs that they contain.
-For example, if you amend a commit with `git commit --amend`,
-there will no longer be a branch that points at the old commit.
-The old commit is recorded in the current branch's <<reflogs,reflog>>,
-so it is still "reachable", but when the reflog entry expires it may
-become unreachable and get deleted.
-Reachable objects will never be deleted.
-
-[[index]]
-THE INDEX
----------
-The index, also known as the "staging area", is a list of files and
-the contents of each file, stored as a <<blob,blob>>.
-You can add files to the index or update the contents of a file in the
-index with linkgit:git-add[1]. This is called "staging" the file for commit.
-
-Unlike a <<tree,tree>>, the index is a flat list of files.
-When you commit, Git converts the list of files in the index to a
-directory <<tree,tree>> and uses that tree in the new <<commit,commit>>.
-
-Each index entry has 4 fields:
-
-1. The *file type*, which must be one of:
-  - *regular file*
-  - *executable file*
-  - *symbolic link*
-  - *gitlink* (for use with submodules)
-2. The *<<blob,blob>>* ID of the file,
-   or (rarely) the *<<commit,commit>>* ID of the submodule
-3. The *stage number*, either 0, 1, 2, or 3. This is normally 0, but if
-   there's a merge conflict there can be multiple versions of the same
-   filename in the index.
-4. The *file path*, for example `src/hello.py`
-
-It's extremely uncommon to look at the index directly: normally you'd
-run `git status` to see a list of changes between the index and <<HEAD,HEAD>>.
-But you can use `git ls-files --stage` to see the index.
-Here's the output of `git ls-files --stage` in a repository with 2 files:
-
-----
-100644 8728a858d9d21a8c78488c8b4e70e531b659141f 0 README.md
-100644 665c637a360874ce43bf74018768a96d2d4d219a 0 src/hello.py
-----
-
-[[reflogs]]
-REFLOGS
--------
-
-Every time a branch, remote-tracking branch, or HEAD is updated, Git
-updates a log called a "reflog" for that <<references,reference>>.
-This means that if you make a mistake and "lose" a commit, you can
-generally recover the commit ID by running `git reflog <reference>`.
-
-A reflog is a list of log entries. Each entry has:
-
-1. The *commit ID*
-2. *Timestamp* when the change was made
-3. *Log message*, for example `pull: Fast-forward`
-
-Reflogs only log changes made in your local repository.
-They are not shared with remotes.
-
-You can view a reflog with `git reflog <reference>`.
-For example, here's the reflog for a `main` branch which has changed twice:
-
-----
-$ git reflog main --date=iso --no-decorate
-750b4ea main@{2025-09-29 15:17:05 -0400}: commit: Add README
-4ccb6d7 main@{2025-09-29 15:16:48 -0400}: commit (initial): Initial commit
-----
-
-GIT
----
-Part of the linkgit:git[1] suite

Documentation/gitfaq.adoc

@@ -83,25 +83,6 @@ Windows would be the configuration `"C:\Program Files\Vim\gvim.exe" --nofork`,
 which quotes the filename with spaces and specifies the `--nofork` option to
 avoid backgrounding the process.
 
-[[sign-off]]
-Why not have `commit.signoff` and other configuration variables?::
-	Git intentionally does not (and will not) provide a
-	configuration variable, such as `commit.signoff`, to
-	automatically add `--signoff` by default.  The reason is to
-	protect the legal and intentional significance of a sign-off.
-	If there were more automated and widely publicized ways for
-	sign-offs to be appended, it would become easier for someone
-	to argue later that a "Signed-off-by" trailer was just added
-	out of habit or by automation, without the committer's full
-	awareness or intent to certify their agreement with the
-	Developer Certificate of Origin (DCO) or a similar statement.
-	This could undermine the sign-off’s credibility in legal or
-	contractual situations.
-+
-There exists `format.signoff`, but that is a historical mistake, and
-it is not an excuse to add more mistakes of the same kind on top.
-
-
 Credentials
 -----------
 

Documentation/gitformat-loose.adoc

@@ -1,53 +0,0 @@
-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

Documentation/gitformat-pack.adoc

@@ -32,10 +32,6 @@ 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:
@@ -84,16 +80,6 @@ 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
@@ -106,11 +92,6 @@ 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