.cirrus.yml

@@ -1,17 +1,15 @@
 env:
   CIRRUS_CLONE_DEPTH: 1
 
-freebsd_task:
+freebsd_12_task:
   env:
     GIT_PROVE_OPTS: "--timer --jobs 10"
     GIT_TEST_OPTS: "--no-chain-lint --no-bin-wrappers"
-    GIT_SKIP_TESTS: t7815.12
-    MAKEFLAGS: -j4
+    MAKEFLAGS: "-j4"
     DEFAULT_TEST_TARGET: prove
-    DEFAULT_UNIT_TEST_TARGET: unit-tests-prove
     DEVELOPER: 1
   freebsd_instance:
-    image_family: freebsd-14-3
+    image_family: freebsd-12-3
     memory: 2G
   install_script:
     pkg install -y gettext gmake perl5
@@ -21,4 +19,4 @@ freebsd_task:
   build_script:
     - su git -c gmake
   test_script:
-    - su git -c 'gmake test unit-tests'
+    - su git -c 'gmake test'

.clang-format

@@ -12,15 +12,7 @@ UseTab: Always
 TabWidth: 8
 IndentWidth: 8
 ContinuationIndentWidth: 8
-
-# While we do want to enforce a character limit of 80 characters, we often
-# allow lines to overflow that limit to prioritize readability. Setting a
-# character limit here with penalties has been finicky and creates too many
-# false positives.
-#
-# NEEDSWORK: It would be nice if we can find optimal settings to ensure we
-# can re-enable the limit here.
-ColumnLimit: 0
+ColumnLimit: 80
 
 # C Language specifics
 Language: Cpp
@@ -40,9 +32,6 @@ AlignConsecutiveAssignments: false
 # double b = 3.14;
 AlignConsecutiveDeclarations: false
 
-# Align consecutive macro definitions.
-AlignConsecutiveMacros: true
-
 # Align escaped newlines as far left as possible
 # #define A   \
 #   int aaaa; \
@@ -83,10 +72,6 @@ AlwaysBreakAfterReturnType: None
 BinPackArguments: true
 BinPackParameters: true
 
-# Add no space around the bit field
-# unsigned bf:2;
-BitFieldColonSpacing: None
-
 # Attach braces to surrounding context except break before braces on function
 # definitions.
 # void foo()
@@ -111,14 +96,6 @@ BreakStringLiterals: false
 # Switch statement body is always indented one level more than case labels.
 IndentCaseLabels: false
 
-# Indents directives before the hash. Each level uses a single space for
-# indentation.
-# #if FOO
-# # include <foo>
-# #endif
-IndentPPDirectives: AfterHash
-PPIndentWidth: 1
-
 # Don't indent a function definition or declaration if it is wrapped after the
 # type
 IndentWrappedFunctionNames: false
@@ -131,37 +108,22 @@ PointerAlignment: Right
 # x = (int32)y;    not    x = (int32) y;
 SpaceAfterCStyleCast: false
 
-# No space is inserted after the logical not operator
-SpaceAfterLogicalNot: false
-
 # Insert spaces before and after assignment operators
 # int a = 5;    not    int a=5;
 # a += 42;             a+=42;
 SpaceBeforeAssignmentOperators: true
 
-# Spaces will be removed before case colon.
-# case 1: break;    not     case 1 : break;
-SpaceBeforeCaseColon: false
-
 # Put a space before opening parentheses only after control statement keywords.
 # void f() {
 #   if (true) {
 #     f();
 #   }
 # }
-SpaceBeforeParens: ControlStatementsExceptControlMacros
+SpaceBeforeParens: ControlStatements
 
 # Don't insert spaces inside empty '()'
 SpaceInEmptyParentheses: false
 
-# No space before first '[' in arrays
-# int a[5][5];     not      int a [5][5];
-SpaceBeforeSquareBrackets: false
-
-# No space will be inserted into {}
-# while (true) {}    not    while (true) { }
-SpaceInEmptyBlock: false
-
 # The number of spaces before trailing line comments (// - comments).
 # This does not affect trailing block comments (/* - comments).
 SpacesBeforeTrailingComments: 1
@@ -187,30 +149,20 @@ Cpp11BracedListStyle: false
 
 # A list of macros that should be interpreted as foreach loops instead of as
 # function calls. Taken from:
-#   git grep -h '^#define [^[:space:]]*for_\?each[^[:space:]]*(' |
-#   sed "s/^#define /  - '/; s/(.*$/'/" | sort | uniq
+#   git grep -h '^#define [^[:space:]]*for_each[^[:space:]]*(' \
+#   | sed "s,^#define \([^[:space:]]*for_each[^[:space:]]*\)(.*$,  - '\1'," \
+#   | sort | uniq
 ForEachMacros:
+  - 'for_each_abbrev'
   - 'for_each_builtin'
   - 'for_each_string_list_item'
   - 'for_each_ut'
   - 'for_each_wanted_builtin'
-  - 'hashmap_for_each_entry'
-  - 'hashmap_for_each_entry_from'
-  - 'kh_foreach'
-  - 'kh_foreach_value'
   - 'list_for_each'
   - 'list_for_each_dir'
   - 'list_for_each_prev'
   - 'list_for_each_prev_safe'
   - 'list_for_each_safe'
-  - 'strintmap_for_each_entry'
-  - 'strmap_for_each_entry'
-  - 'strset_for_each_entry'
-
-# A list of macros that should be interpreted as conditionals instead of as
-# function calls.
-IfMacros:
-  - 'if_test'
 
 # The maximum number of consecutive empty lines to keep.
 MaxEmptyLinesToKeep: 1
@@ -218,11 +170,15 @@ MaxEmptyLinesToKeep: 1
 # No empty line at the start of a block.
 KeepEmptyLinesAtTheStartOfBlocks: false
 
+# Penalties
+# This decides what order things should be done if a line is too long
+PenaltyBreakAssignment: 10
+PenaltyBreakBeforeFirstCallParameter: 30
+PenaltyBreakComment: 10
+PenaltyBreakFirstLessLess: 0
+PenaltyBreakString: 10
+PenaltyExcessCharacter: 100
+PenaltyReturnTypeOnItsOwnLine: 60
+
 # Don't sort #include's
 SortIncludes: false
-
-# Remove optional braces of control statements (if, else, for, and while)
-# according to the LLVM coding style. This avoids braces on simple
-# single-statement bodies of statements but keeps braces if one side of
-# if/else if/.../else cascade has multi-statement body.
-RemoveBracesLLVM: true

.editorconfig

@@ -4,7 +4,7 @@ insert_final_newline = true
 
 # The settings for C (*.c and *.h) files are mirrored in .clang-format.  Keep
 # them in sync.
-[{*.{c,h,sh,bash,perl,pl,pm,txt,adoc},config.mak.*,Makefile}]
+[*.{c,h,sh,perl,pl,pm,txt}]
 indent_style = tab
 tab_width = 8
 

.gitattributes

@@ -1,19 +1,18 @@
-* 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/**/*.txt text eol=lf
 /command-list.txt text eol=lf
 /GIT-VERSION-GEN text eol=lf
 /mergetools/* text eol=lf
 /t/oid-info/* text eol=lf
-/Documentation/git-merge.adoc conflict-marker-size=32
-/Documentation/git-merge-file.adoc conflict-marker-size=32
-/Documentation/gitk.adoc conflict-marker-size=32
-/Documentation/user-manual.adoc conflict-marker-size=32
+/Documentation/git-merge.txt conflict-marker-size=32
+/Documentation/gitk.txt conflict-marker-size=32
+/Documentation/user-manual.txt conflict-marker-size=32
 /t/t????-*.sh conflict-marker-size=32

.github/workflows/check-style.yml

@@ -1,34 +0,0 @@
-name: check-style
-
-# Get the repository with all commits to ensure that we can analyze
-# all of the commits contributed via the Pull Request.
-
-on:
-  pull_request:
-    types: [opened, synchronize]
-
-# Avoid unnecessary builds. Unlike the main CI jobs, these are not
-# ci-configurable (but could be).
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  check-style:
-    env:
-      CC: clang
-      jobname: ClangFormat
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v5
-      with:
-        fetch-depth: 0
-
-    - run: ci/install-dependencies.sh
-
-    - name: git clang-format
-      continue-on-error: true
-      id: check_out
-      run: |
-        ./ci/run-style-check.sh \
-          "${{github.event.pull_request.base.sha}}"

.github/workflows/check-whitespace.yml

@@ -19,14 +19,73 @@ jobs:
   check-whitespace:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
     - name: git log --check
       id: check_out
       run: |
-        ./ci/check-whitespace.sh \
-          "${{github.event.pull_request.base.sha}}" \
-          "$GITHUB_STEP_SUMMARY" \
-          "https://github.com/${{github.repository}}"
+        baseSha=${{github.event.pull_request.base.sha}}
+        problems=()
+        commit=
+        commitText=
+        commitTextmd=
+        goodparent=
+        while read dash sha etc
+        do
+          case "${dash}" in
+          "---")
+            if test -z "${commit}"
+            then
+              goodparent=${sha}
+            fi
+            commit="${sha}"
+            commitText="${sha} ${etc}"
+            commitTextmd="[${sha}](https://github.com/${{ github.repository }}/commit/${sha}) ${etc}"
+            ;;
+          "")
+            ;;
+          *)
+            if test -n "${commit}"
+            then
+              problems+=("1) --- ${commitTextmd}")
+              echo ""
+              echo "--- ${commitText}"
+              commit=
+            fi
+            case "${dash}" in
+            *:[1-9]*:) # contains file and line number information
+              dashend=${dash#*:}
+              problems+=("[${dash}](https://github.com/${{ github.repository }}/blob/${{github.event.pull_request.head.ref}}/${dash%%:*}#L${dashend%:}) ${sha} ${etc}")
+              ;;
+            *)
+              problems+=("\`${dash} ${sha} ${etc}\`")
+              ;;
+            esac
+            echo "${dash} ${sha} ${etc}"
+            ;;
+          esac
+        done <<< $(git log --check --pretty=format:"---% h% s" ${baseSha}..)
+
+        if test ${#problems[*]} -gt 0
+        then
+          if test -z "${commit}"
+          then
+            goodparent=${baseSha: 0:7}
+          fi
+          echo "🛑 Please review the Summary output for further information."
+          echo "### :x: A whitespace issue was found in one or more of the commits." >$GITHUB_STEP_SUMMARY
+          echo "" >>$GITHUB_STEP_SUMMARY
+          echo "Run these commands to correct the problem:" >>$GITHUB_STEP_SUMMARY
+          echo "1. \`git rebase --whitespace=fix ${goodparent}\`" >>$GITHUB_STEP_SUMMARY
+          echo "1. \`git push --force\`" >>$GITHUB_STEP_SUMMARY
+          echo " " >>$GITHUB_STEP_SUMMARY
+          echo "Errors:" >>$GITHUB_STEP_SUMMARY
+          for i in "${problems[@]}"
+          do
+            echo "${i}" >>$GITHUB_STEP_SUMMARY
+          done
+
+          exit 2
+        fi

.github/workflows/coverity.yml

@@ -38,14 +38,14 @@ jobs:
       COVERITY_LANGUAGE: cxx
       COVERITY_PLATFORM: overridden-below
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v3
       - name: install minimal Git for Windows SDK
         if: contains(matrix.os, 'windows')
         uses: git-for-windows/setup-git-for-windows-sdk@v1
       - run: ci/install-dependencies.sh
         if: contains(matrix.os, 'ubuntu') || contains(matrix.os, 'macos')
         env:
-          CI_JOB_IMAGE: ${{ matrix.os }}
+          runs_on_pool: ${{ matrix.os }}
 
       # The Coverity site says the tool is usually updated twice yearly, so the
       # MD5 of download can be used to determine whether there's been an update.
@@ -98,7 +98,7 @@ jobs:
       # A cache miss will add ~30s to create, but a cache hit will save minutes.
       - name: restore the Coverity Build Tool
         id: cache
-        uses: actions/cache/restore@v4
+        uses: actions/cache/restore@v3
         with:
           path: ${{ runner.temp }}/cov-analysis
           key: cov-build-${{ env.COVERITY_LANGUAGE }}-${{ env.COVERITY_PLATFORM }}-${{ steps.lookup.outputs.hash }}
@@ -141,19 +141,15 @@ jobs:
           esac
       - name: cache the Coverity Build Tool
         if: steps.cache.outputs.cache-hit != 'true'
-        uses: actions/cache/save@v4
+        uses: actions/cache/save@v3
         with:
           path: ${{ runner.temp }}/cov-analysis
           key: cov-build-${{ env.COVERITY_LANGUAGE }}-${{ env.COVERITY_PLATFORM }}-${{ steps.lookup.outputs.hash }}
       - name: build with cov-build
         run: |
-          export PATH="$PATH:$RUNNER_TEMP/cov-analysis/bin" &&
+          export PATH="$RUNNER_TEMP/cov-analysis/bin:$PATH" &&
           cov-configure --gcc &&
-          if ! cov-build --dir cov-int make
-          then
-            cat cov-int/build-log.txt
-            exit 1
-          fi
+          cov-build --dir cov-int make
       - name: package the build
         run: tar -czvf cov-int.tgz cov-int
       - name: submit the build to Coverity Scan

.github/workflows/l10n.yml

@@ -63,10 +63,9 @@ jobs:
             origin \
             ${{ github.ref }} \
             $args
-      - uses: actions/setup-go@v6
+      - uses: actions/setup-go@v2
         with:
           go-version: '>=1.16'
-          cache: false
       - name: Install git-po-helper
         run: go install github.com/git-l10n/git-po-helper@main
       - name: Install other dependencies
@@ -92,13 +91,14 @@ jobs:
           cat git-po-helper.out
           exit $exit_code
       - name: Create comment in pull request for report
-        uses: mshick/add-pr-comment@v2
+        uses: mshick/add-pr-comment@v1
         if: >-
           always() &&
           github.event_name == 'pull_request_target' &&
           env.COMMENT_BODY != ''
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
+          repo-token-user-login: 'github-actions[bot]'
           message: >
             ${{ steps.check-commits.outcome == 'failure' && 'Errors and warnings' || 'Warnings' }}
             found by [git-po-helper](https://github.com/git-l10n/git-po-helper#readme) in workflow

.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,9 +157,9 @@ 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 }}
+        name: failed-tests-windows
         path: ${{env.FAILED_TEST_ARTIFACTS}}
   vs-build:
     name: win+VS build
@@ -173,20 +173,24 @@ 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'
     - name: download vcpkg artifacts
-      uses: git-for-windows/get-azure-pipelines-artifact@v0
-      with:
-        repository: git/git
-        definitionId: 9
+      shell: powershell
+      run: |
+        $urlbase = "https://dev.azure.com/git/git/_apis/build/builds"
+        $id = ((Invoke-WebRequest -UseBasicParsing "${urlbase}?definitions=9&statusFilter=completed&resultFilter=succeeded&`$top=1").content | ConvertFrom-JSON).value[0].id
+        $downloadUrl = ((Invoke-WebRequest -UseBasicParsing "${urlbase}/$id/artifacts").content | ConvertFrom-JSON).value[0].resource.downloadUrl
+        (New-Object Net.WebClient).DownloadFile($downloadUrl, "compat.zip")
+        Expand-Archive compat.zip -DestinationPath . -Force
+        Remove-Item compat.zip
     - name: add msbuild to PATH
-      uses: microsoft/setup-msbuild@v2
+      uses: microsoft/setup-msbuild@v1
     - name: copy dlls to root
       shell: cmd
       run: compat\vcbuild\vcpkg_copy_dlls.bat release
@@ -208,7 +212,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 +230,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}}
@@ -242,74 +246,12 @@ jobs:
       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@v5
-      with:
-        name: failed-tests-windows-vs-${{ matrix.nr }}
-        path: ${{env.FAILED_TEST_ARTIFACTS}}
-
-  windows-meson-build:
-    name: win+Meson build
-    needs: ci-config
-    if: needs.ci-config.outputs.enabled == 'yes'
-    runs-on: windows-latest
-    concurrency:
-      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
-    - name: Set up dependencies
-      shell: pwsh
-      run: pip install meson ninja
-    - name: Setup
-      shell: pwsh
-      run: meson setup build --vsenv -Dbuildtype=release -Dperl=disabled -Dcredential_helpers=wincred
-    - name: Compile
-      shell: pwsh
-      run: meson compile -C build
-    - name: Upload build artifacts
-      uses: actions/upload-artifact@v5
-      with:
-        name: windows-meson-artifacts
-        path: build
-  windows-meson-test:
-    name: win+Meson test
-    runs-on: windows-latest
-    needs: [ci-config, windows-meson-build]
-    strategy:
-      fail-fast: false
-      matrix:
-        nr: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
-    concurrency:
-      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
-    - name: Set up dependencies
-      shell: pwsh
-      run: pip install meson ninja
-    - name: Download build artifacts
-      uses: actions/download-artifact@v6
-      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 }}
+        name: failed-tests-windows
         path: ${{env.FAILED_TEST_ARTIFACTS}}
-
   regular:
     name: ${{matrix.vector.jobname}} (${{matrix.vector.pool}})
     needs: ci-config
@@ -321,27 +263,40 @@ jobs:
       fail-fast: false
       matrix:
         vector:
+          - jobname: linux-sha256
+            cc: clang
+            pool: ubuntu-latest
+          - jobname: linux-gcc
+            cc: gcc
+            cc_package: gcc-8
+            pool: ubuntu-20.04
+          - jobname: linux-TEST-vars
+            cc: gcc
+            cc_package: gcc-8
+            pool: ubuntu-20.04
           - jobname: osx-clang
             cc: clang
-            pool: macos-14
-          - jobname: osx-reftable
-            cc: clang
-            pool: macos-14
+            pool: macos-13
           - jobname: osx-gcc
             cc: gcc-13
-            pool: macos-14
-          - jobname: osx-meson
+            pool: macos-13
+          - jobname: linux-gcc-default
+            cc: gcc
+            pool: ubuntu-latest
+          - jobname: linux-leaks
+            cc: gcc
+            pool: ubuntu-latest
+          - jobname: linux-asan-ubsan
             cc: clang
-            pool: macos-14
+            pool: ubuntu-latest
     env:
       CC: ${{matrix.vector.cc}}
       CC_PACKAGE: ${{matrix.vector.cc_package}}
       jobname: ${{matrix.vector.jobname}}
-      CI_JOB_IMAGE: ${{matrix.vector.pool}}
-      TEST_OUTPUT_DIRECTORY: ${{github.workspace}}/t
+      runs_on_pool: ${{matrix.vector.pool}}
     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,22 +304,10 @@ 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}}
-  fuzz-smoke-test:
-    name: fuzz smoke test
-    needs: ci-config
-    if: needs.ci-config.outputs.enabled == 'yes'
-    env:
-      CC: clang
-      CI_JOB_IMAGE: ubuntu-latest
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v5
-    - run: ci/install-dependencies.sh
-    - run: ci/run-build-and-minimal-fuzzers.sh
   dockerized:
     name: ${{matrix.vector.jobname}} (${{matrix.vector.image}})
     needs: ci-config
@@ -376,80 +319,29 @@ jobs:
       fail-fast: false
       matrix:
         vector:
-        - jobname: linux-sha256
-          image: ubuntu:rolling
-          cc: clang
-        - jobname: linux-reftable
-          image: ubuntu:rolling
-          cc: clang
-        - jobname: linux-TEST-vars
-          image: ubuntu:20.04
-          cc: gcc
-          cc_package: gcc-8
-        - 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
-        - jobname: linux-reftable-leaks
-          image: ubuntu:rolling
-          cc: gcc
-        - jobname: linux-asan-ubsan
-          image: ubuntu:rolling
-          cc: clang
-        - jobname: linux-meson
-          image: ubuntu:rolling
-          cc: gcc
-        - jobname: linux-musl-meson
-          image: alpine:latest
-        # Supported until 2025-04-02.
+        - jobname: linux-musl
+          image: alpine
         - jobname: linux32
-          image: i386/ubuntu:focal
-        # A RHEL 8 compatible distro.  Supported until 2029-05-31.
-        - jobname: almalinux-8
-          image: almalinux:8
-        # Supported until 2026-08-31.
-        - jobname: debian-11
-          image: debian:11
+          image: daald/ubuntu32:xenial
+        - jobname: pedantic
+          image: fedora
     env:
       jobname: ${{matrix.vector.jobname}}
-      CC: ${{matrix.vector.cc}}
-      CI_JOB_IMAGE: ${{matrix.vector.image}}
-      CUSTOM_PATH: /custom
     runs-on: ubuntu-latest
     container: ${{matrix.vector.image}}
     steps:
-    - name: prepare libc6 for actions
+    - uses: actions/checkout@v4
+      if: matrix.vector.jobname != 'linux32'
+    - uses: actions/checkout@v1 # cannot be upgraded because Node.js Actions aren't supported in this container
       if: matrix.vector.jobname == 'linux32'
-      run: apt -q update && apt -q -y install libc6-amd64 lib64stdc++6
-    - name: install git in container
-      run: |
-        if command -v git
-        then
-          : # nothing to do
-        elif command -v apk
-        then
-          apk add --update git
-        elif command -v dnf
-        then
-          dnf -yq update && dnf -yq install git
-        else
-          apt-get -q update && apt-get -q -y install git
-        fi
-    - uses: actions/checkout@v5
-    - 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: ci/install-docker-dependencies.sh
+    - run: 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
+      run: ci/print-test-failures.sh
     - name: Upload failed tests' directories
-      if: failure() && env.FAILED_TEST_ARTIFACTS != ''
-      uses: actions/upload-artifact@v5
+      if: failure() && env.FAILED_TEST_ARTIFACTS != '' && matrix.vector.jobname != 'linux32'
+      uses: actions/upload-artifact@v4
       with:
         name: failed-tests-${{matrix.vector.jobname}}
         path: ${{env.FAILED_TEST_ARTIFACTS}}
@@ -458,43 +350,35 @@ jobs:
     if: needs.ci-config.outputs.enabled == 'yes'
     env:
       jobname: StaticAnalysis
-      CI_JOB_IMAGE: ubuntu-22.04
     runs-on: ubuntu-22.04
     concurrency:
       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'
     env:
       jobname: sparse
-      CI_JOB_IMAGE: ubuntu-22.04
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-20.04
     concurrency:
       group: sparse-${{ github.ref }}
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     steps:
-    - uses: actions/checkout@v5
+    - name: Download a current `sparse` package
+      # Ubuntu's `sparse` version is too old for us
+      uses: git-for-windows/get-azure-pipelines-artifact@v0
+      with:
+        repository: git/git
+        definitionId: 10
+        artifact: sparse-20.04
+    - name: Install the current `sparse` package
+      run: sudo dpkg -i sparse-20.04/sparse_*.deb
+    - uses: actions/checkout@v4
     - name: Install other dependencies
       run: ci/install-dependencies.sh
     - run: make sparse
@@ -507,9 +391,8 @@ jobs:
       cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }}
     env:
       jobname: Documentation
-      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
@@ -11,9 +9,9 @@
 /GIT-PYTHON-VARS
 /GIT-SCRIPT-DEFINES
 /GIT-SPATCH-DEFINES
-/GIT-TEST-SUITES
 /GIT-USER-AGENT
 /GIT-VERSION-FILE
+/bin-wrappers/
 /git
 /git-add
 /git-am
@@ -21,7 +19,6 @@
 /git-apply
 /git-archimport
 /git-archive
-/git-backfill
 /git-bisect
 /git-blame
 /git-branch
@@ -57,7 +54,6 @@
 /git-diff
 /git-diff-files
 /git-diff-index
-/git-diff-pairs
 /git-diff-tree
 /git-difftool
 /git-difftool--helper
@@ -89,7 +85,6 @@
 /git-init-db
 /git-interpret-trailers
 /git-instaweb
-/git-last-modified
 /git-log
 /git-ls-files
 /git-ls-remote
@@ -131,7 +126,6 @@
 /git-rebase
 /git-receive-pack
 /git-reflog
-/git-refs
 /git-remote
 /git-remote-http
 /git-remote-https
@@ -141,8 +135,6 @@
 /git-remote-ext
 /git-repack
 /git-replace
-/git-replay
-/git-repo
 /git-request-pull
 /git-rerere
 /git-reset
@@ -200,11 +192,9 @@
 /config-list.h
 /command-list.h
 /hook-list.h
-/version-def.h
 *.tar.gz
 *.dsc
 *.deb
-/git.rc
 /git.spec
 *.exe
 *.[aos]
@@ -256,5 +246,3 @@ Release/
 /git.VC.db
 *.dSYM
 /contrib/buildsystems/out
-/contrib/libgit-rs/target
-/contrib/libgit-sys/target

.gitlab-ci.yml

@@ -1,28 +1,16 @@
 default:
   timeout: 2h
 
-stages:
-  - build
-  - test
-  - analyze
-
 workflow:
   rules:
     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
     - if: $CI_COMMIT_TAG
     - if: $CI_COMMIT_REF_PROTECTED == "true"
 
-test:linux:
+test:
   image: $image
-  stage: test
-  needs: [ ]
-  tags:
-    - saas-linux-medium-amd64
-  variables:
-    CUSTOM_PATH: "/custom"
-    TEST_OUTPUT_DIRECTORY: "/tmp/test-output"
   before_script:
-    - ./ci/install-dependencies.sh
+    - ./ci/install-docker-dependencies.sh
   script:
     - useradd builder --create-home
     - chown -R builder "${CI_PROJECT_DIR}"
@@ -32,240 +20,34 @@ test:linux:
       if test "$CI_JOB_STATUS" != 'success'
       then
         sudo --preserve-env --set-home --user=builder ./ci/print-test-failures.sh
-        mv "$TEST_OUTPUT_DIRECTORY"/failed-test-artifacts t/
       fi
   parallel:
     matrix:
       - jobname: linux-sha256
-        image: ubuntu:rolling
+        image: ubuntu:latest
         CC: clang
-      - jobname: linux-reftable
-        image: ubuntu:rolling
-        CC: clang
-      - jobname: linux-breaking-changes
+      - jobname: linux-gcc
         image: ubuntu:20.04
         CC: gcc
-      - jobname: fedora-breaking-changes-meson
-        image: fedora:latest
+        CC_PACKAGE: gcc-8
       - jobname: linux-TEST-vars
         image: ubuntu:20.04
         CC: gcc
         CC_PACKAGE: gcc-8
-      - jobname: linux-leaks
-        image: ubuntu:rolling
+      - jobname: linux-gcc-default
+        image: ubuntu:latest
         CC: gcc
-      - jobname: linux-reftable-leaks
-        image: ubuntu:rolling
+      - jobname: linux-leaks
+        image: ubuntu:latest
         CC: gcc
       - jobname: linux-asan-ubsan
-        image: ubuntu:rolling
+        image: ubuntu:latest
         CC: clang
-      - jobname: linux-musl-meson
+      - jobname: pedantic
+        image: fedora:latest
+      - jobname: linux-musl
         image: alpine:latest
-      - jobname: linux32
-        image: i386/ubuntu:20.04
-      - jobname: linux-meson
-        image: ubuntu:rolling
-        CC: gcc
   artifacts:
     paths:
       - t/failed-test-artifacts
-    reports:
-      junit: build/meson-logs/testlog.junit.xml
     when: on_failure
-
-test:osx:
-  image: $image
-  stage: test
-  needs: [ ]
-  tags:
-    - saas-macos-medium-m1
-  variables:
-    TEST_OUTPUT_DIRECTORY: "/Volumes/RAMDisk"
-  before_script:
-    # Create a 4GB RAM disk that we use to store test output on. This small hack
-    # significantly speeds up tests by more than a factor of 2 because the
-    # macOS runners use network-attached storage as disks, which is _really_
-    # slow with the many small writes that our tests do.
-    - sudo diskutil apfs create $(hdiutil attach -nomount ram://8192000) RAMDisk
-    - ./ci/install-dependencies.sh
-  script:
-    - ./ci/run-build-and-tests.sh
-  after_script:
-    - |
-      if test "$CI_JOB_STATUS" != 'success'
-      then
-        ./ci/print-test-failures.sh
-        mv "$TEST_OUTPUT_DIRECTORY"/failed-test-artifacts t/
-      fi
-  parallel:
-    matrix:
-      - jobname: osx-clang
-        image: macos-14-xcode-15
-        CC: clang
-      - jobname: osx-reftable
-        image: macos-14-xcode-15
-        CC: clang
-      - jobname: osx-meson
-        image: macos-14-xcode-15
-        CC: clang
-  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:
-    - saas-windows-medium-amd64
-  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'
-  artifacts:
-    paths:
-      - artifacts
-      - git-sdk
-
-test:mingw64:
-  stage: test
-  tags:
-    - saas-windows-medium-amd64
-  needs:
-    - 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"
-  script:
-    - git-sdk/usr/bin/bash.exe -l -c "ci/run-test-slice.sh $CI_NODE_INDEX $CI_NODE_TOTAL"
-  after_script:
-    - git-sdk/usr/bin/bash.exe -l -c 'ci/print-test-failures.sh'
-  parallel: 10
-
-.msvc-meson:
-  tags:
-    - saas-windows-medium-amd64
-  before_script:
-    - *windows_before_script
-    - choco install -y git meson ninja rust-ms
-    - Import-Module $env:ChocolateyInstall\helpers\chocolateyProfile.psm1
-    - refreshenv
-
-build:msvc-meson:
-  extends: .msvc-meson
-  stage: build
-  script:
-    - meson setup build --vsenv -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred
-    - meson compile -C build
-  artifacts:
-    paths:
-      - build
-
-test:msvc-meson:
-  extends: .msvc-meson
-  stage: test
-  timeout: 6h
-  needs:
-    - job: "build:msvc-meson"
-      artifacts: true
-  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
-  stage: test
-  needs: [ ]
-  variables:
-    CC: clang
-  before_script:
-    - ./ci/install-dependencies.sh
-  script:
-    - ./ci/run-build-and-minimal-fuzzers.sh
-
-static-analysis:
-  image: ubuntu:22.04
-  stage: analyze
-  needs: [ ]
-  variables:
-    jobname: StaticAnalysis
-  before_script:
-    - ./ci/install-dependencies.sh
-  script:
-    - ./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
-  needs: [ ]
-  before_script:
-    - ./ci/install-dependencies.sh
-  # Since $CI_MERGE_REQUEST_TARGET_BRANCH_SHA is only defined for merged
-  # pipelines, we fallback to $CI_MERGE_REQUEST_DIFF_BASE_SHA, which should
-  # be defined in all pipelines.
-  script:
-    - |
-      R=${CI_MERGE_REQUEST_TARGET_BRANCH_SHA:-${CI_MERGE_REQUEST_DIFF_BASE_SHA:?}} || exit
-      ./ci/check-whitespace.sh "$R"
-  rules:
-    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
-
-check-style:
-  image: ubuntu:latest
-  stage: analyze
-  needs: [ ]
-  allow_failure: true
-  variables:
-    CC: clang
-    jobname: ClangFormat
-  before_script:
-    - ./ci/install-dependencies.sh
-  # Since $CI_MERGE_REQUEST_TARGET_BRANCH_SHA is only defined for merged
-  # pipelines, we fallback to $CI_MERGE_REQUEST_DIFF_BASE_SHA, which should
-  # be defined in all pipelines.
-  script:
-    - |
-      R=${CI_MERGE_REQUEST_TARGET_BRANCH_SHA:-${CI_MERGE_REQUEST_DIFF_BASE_SHA:?}} || exit
-      ./ci/run-style-check.sh "$R"
-  rules:
-    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
-
-documentation:
-  image: ubuntu:latest
-  stage: analyze
-  needs: [ ]
-  variables:
-    jobname: Documentation
-  before_script:
-    - ./ci/install-dependencies.sh
-  script:
-    - ./ci/test-documentation.sh

.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>
@@ -155,7 +152,6 @@ Lars Doelle <lars.doelle@on-line ! de>
 Lars Doelle <lars.doelle@on-line.de>
 Lars Noschinski <lars@public.noschinski.de> <lars.noschinski@rwth-aachen.de>
 Li Hong <leehong@pku.edu.cn>
-Linus Arver <linus@ucla.edu> <linusa@google.com>
 Linus Torvalds <torvalds@linux-foundation.org> <torvalds@evo.osdl.org>
 Linus Torvalds <torvalds@linux-foundation.org> <torvalds@g5.osdl.org>
 Linus Torvalds <torvalds@linux-foundation.org> <torvalds@osdl.org>
@@ -260,7 +256,6 @@ Stefan Naewe <stefan.naewe@gmail.com> <stefan.naewe@googlemail.com>
 Stefan Sperling <stsp@elego.de> <stsp@stsp.name>
 Štěpán Němec <stepnem@gmail.com> <stepan.nemec@gmail.com>
 Stephen Boyd <bebarino@gmail.com> <sboyd@codeaurora.org>
-Stephen P. Smith <ishchis2@gmail.com> <ischis2@cox.net>
 Steven Drake <sdrake@xnet.co.nz> <sdrake@ihug.co.nz>
 Steven Grimm <koreth@midwinter.com> <sgrimm@sgrimm-mbp.local>
 Steven Grimm <koreth@midwinter.com> koreth@midwinter.com

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

@@ -0,0 +1 @@
+*.txt whitespace

Documentation/.gitignore

@@ -6,15 +6,12 @@
 *.pdf
 git.info
 gitman.info
-howto-index.adoc
+howto-index.txt
 doc.dep
-cmds-*.adoc
-mergetools-*.adoc
-SubmittingPatches.adoc
+cmds-*.txt
+mergetools-*.txt
+SubmittingPatches.txt
 tmp-doc-diff/
-tmp-meson-diff/
 GIT-ASCIIDOCFLAGS
 /.build/
 /GIT-EXCLUDED-PROGRAMS
-/asciidoc.conf
-/asciidoctor-extensions.rb

Documentation/BreakingChanges.adoc

@@ -1,335 +0,0 @@
-= Upcoming breaking changes
-
-The Git project aims to ensure backwards compatibility to the best extent
-possible. Minor releases will not break backwards compatibility unless there is
-a very strong reason to do so, like for example a security vulnerability.
-
-Regardless of that, due to the age of the Git project, it is only natural to
-accumulate a backlog of backwards-incompatible changes that will eventually be
-required to keep the project aligned with a changing world. These changes fall
-into several categories:
-
-* Changes to long established defaults.
-* Concepts that have been replaced with a superior design.
-* Concepts, commands, configuration or options that have been lacking in major
-  ways and that cannot be fixed and which will thus be removed without any
-  replacement.
-
-Explicitly not included in this list are fixes to minor bugs that may cause a
-change in user-visible behavior.
-
-The Git project irregularly releases breaking versions that deliberately break
-backwards compatibility with older versions. This is done to ensure that Git
-remains relevant, safe and maintainable going forward. The release cadence of
-breaking versions is typically measured in multiple years. We had the following
-major breaking releases in the past:
-
-* Git 1.6.0, released in August 2008.
-* Git 2.0, released in May 2014.
-
-We use <major>.<minor> release numbers these days, starting from Git 2.0. For
-future releases, our plan is to increment <major> in the release number when we
-make the next breaking release. Before Git 2.0, the release numbers were
-1.<major>.<minor> with the intention to increment <major> for "usual" breaking
-releases, reserving the jump to Git 2.0 for really large backward-compatibility
-breaking changes.
-
-The intent of this document is to track upcoming deprecations for future
-breaking releases. Furthermore, this document also tracks what will _not_ be
-deprecated. This is done such that the outcome of discussions document both
-when the discussion favors deprecation, but also when it rejects a deprecation.
-
-Items should have a clear summary of the reasons why we do or do not want to
-make the described change that can be easily understood without having to read
-the mailing list discussions. If there are alternatives to the changed feature,
-those alternatives should be pointed out to our users.
-
-All items should be accompanied by references to relevant mailing list threads
-where the deprecation was discussed. These references use message-IDs, which
-can visited via
-
-  https://lore.kernel.org/git/$message_id/
-
-to see the message and its surrounding discussion. Such a reference is there to
-make it easier for you to find how the project reached consensus on the
-described item back then.
-
-This is a living document as the environment surrounding the project changes
-over time. If circumstances change, an earlier decision to deprecate or change
-something may need to be revisited from time to time. So do not take items on
-this list to mean "it is settled, do not waste our time bringing it up again".
-
-== Procedure
-
-Discussing the desire to make breaking changes, declaring that breaking
-changes are made at a certain version boundary, and recording these
-decisions in this document, are necessary but not sufficient.
-Because such changes are expected to be numerous, and the design and
-implementation of them are expected to span over time, they have to
-be deployable trivially at such a version boundary, prepared over long
-time.
-
-The breaking changes MUST be guarded with the a compile-time switch,
-WITH_BREAKING_CHANGES, to help this process.  When built with it,
-the resulting Git binary together with its documentation would
-behave as if these breaking changes slated for the next big version
-boundary are already in effect.  We also have a CI job to exercise
-the work-in-progress version of Git with these breaking changes.
-
-
-== Git 3.0
-
-The following subsections document upcoming breaking changes for Git 3.0. There
-is no planned release date for this breaking version yet.
-
-Proposed changes and removals only include items which are "ready" to be done.
-In other words, this is not supposed to be a wishlist of features that should
-be changed to or replaced in case the alternative was implemented already.
-
-=== Changes
-
-* The default hash function for new repositories will be changed from "sha1"
-  to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays
-  recommended against in FIPS 140-2 and similar certifications. Furthermore,
-  there are practical attacks on SHA-1 that weaken its cryptographic properties:
-+
-  ** The SHAppening (2015). The first demonstration of a practical attack
-     against SHA-1 with 2^57 operations.
-  ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations.
-  ** Birthday-Near-Collision (2019). This attack allows for chosen prefix
-     attacks with 2^68 operations.
-  ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63
-     operations.
-+
-While we have protections in place against known attacks, it is expected
-that more attacks against SHA-1 will be found by future research. Paired
-with the ever-growing capability of hardware, it is only a matter of time
-before SHA-1 will be considered broken completely. We want to be prepared
-and will thus change the default hash algorithm to "sha256" for newly
-initialized repositories.
-+
-An important requirement for this change is that the ecosystem is ready to
-support the "sha256" object format. This includes popular Git libraries,
-applications and forges.
-+
-There is no plan to deprecate the "sha1" object format at this point in time.
-+
-Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
-<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>,
-<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
-
-* The default storage format for references in newly created repositories will
-  be changed from "files" to "reftable". The "reftable" format provides
-  multiple advantages over the "files" format:
-+
-  ** It is impossible to store two references that only differ in casing on
-     case-insensitive filesystems with the "files" format. This issue is common
-     on Windows and macOS platforms. As the "reftable" backend does not use
-     filesystem paths to encode reference names this problem goes away.
-  ** Similarly, macOS normalizes path names that contain unicode characters,
-     which has the consequence that you cannot store two names with unicode
-     characters that are encoded differently with the "files" backend. Again,
-     this is not an issue with the "reftable" backend.
-  ** Deleting references with the "files" backend requires Git to rewrite the
-     complete "packed-refs" file. In large repositories with many references
-     this file can easily be dozens of megabytes in size, in extreme cases it
-     may be gigabytes. The "reftable" backend uses tombstone markers for
-     deleted references and thus does not have to rewrite all of its data.
-  ** Repository housekeeping with the "files" backend typically performs
-     all-into-one repacks of references. This can be quite expensive, and
-     consequently housekeeping is a tradeoff between the number of loose
-     references that accumulate and slow down operations that read references,
-     and compressing those loose references into the "packed-refs" file. The
-     "reftable" backend uses geometric compaction after every write, which
-     amortizes costs and ensures that the backend is always in a
-     well-maintained state.
-  ** Operations that write multiple references at once are not atomic with the
-     "files" backend. Consequently, Git may see in-between states when it reads
-     references while a reference transaction is in the process of being
-     committed to disk.
-  ** Writing many references at once is slow with the "files" backend because
-     every reference is created as a separate file. The "reftable" backend
-     significantly outperforms the "files" backend by multiple orders of
-     magnitude.
-  ** The reftable backend uses a binary format with prefix compression for
-     reference names. As a result, the format uses less space compared to the
-     "packed-refs" file.
-+
-Users that get immediate benefit from the "reftable" backend could continue to
-opt-in to the "reftable" format manually by setting the "init.defaultRefFormat"
-config. But defaults matter, and we think that overall users will have a better
-experience with less platform-specific quirks when they use the new backend by
-default.
-+
-A prerequisite for this change is that the ecosystem is ready to support the
-"reftable" format. Most importantly, alternative implementations of Git like
-JGit, libgit2 and Gitoxide need to support it.
-
-* In new repositories, the default branch name will be `main`. We have been
-  warning that the default name will change since 675704c74dd (init:
-  provide useful advice about init.defaultBranch, 2020-12-11).  The new name
-  matches the default branch name used in new repositories by many of the
-  big Git forges.
-
-* Git will require Rust as a mandatory part of the build process. While Git
-  already started to adopt Rust in Git 2.49, all parts written in Rust are
-  optional for the time being. This includes:
-+
-  ** The Rust wrapper around libgit.a that is part of "contrib/" and which has
-     been introduced in Git 2.49.
-  ** Subsystems that have an alternative implementation in Rust to test
-     interoperability between our C and Rust codebase.
-  ** Newly written features that are not mission critical for a fully functional
-     Git client.
-+
-These changes are meant as test balloons to allow distributors of Git to prepare
-for Rust becoming a mandatory part of the build process. There will be multiple
-milestones for the introduction of Rust:
-+
---
-1. Initially, with Git 2.52, support for Rust will be auto-detected by Meson and
-   disabled in our Makefile so that the project can sort out the initial
-   infrastructure.
-2. In Git 2.53, both build systems will default-enable support for Rust.
-   Consequently, builds will break by default if Rust is not available on the
-   build host. The use of Rust can still be explicitly disabled via build
-   flags.
-3. In Git 3.0, the build options will be removed and support for Rust is
-   mandatory.
---
-+
-You can explicitly ask both Meson and our Makefile-based system to enable Rust
-by saying `meson configure -Drust=enabled` and `make WITH_RUST=YesPlease`,
-respectively.
-+
-The Git project will declare the last version before Git 3.0 to be a long-term
-support release. This long-term release will receive important bug fixes for at
-least four release cycles and security fixes for six release cycles. The Git
-project will hand over maintainership of the long-term release to distributors
-in case they need to extend the life of that long-term release even further.
-Details of how this long-term release will be handed over to the community will
-be discussed once the Git project decides to stop officially supporting it.
-+
-We will evaluate the impact on downstream distributions before making Rust
-mandatory in Git 3.0. If we see that the impact on downstream distributions
-would be significant, we may decide to defer this change to a subsequent minor
-release. This evaluation will also take into account our own experience with
-how painful it is to keep Rust an optional component.
-
-=== Removals
-
-* Support for grafting commits has long been superseded by git-replace(1).
-  Grafts are inferior to replacement refs:
-+
-  ** Grafts are a local-only mechanism and cannot be shared across
-     repositories.
-  ** Grafts can lead to hard-to-diagnose problems when transferring objects
-     between repositories.
-+
-The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
-info/grafts as outdated, 2014-03-05) and will be removed.
-+
-Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
-
-* The git-pack-redundant(1) command can be used to remove redundant pack files.
-  The subcommand is unusably slow and the reason why nobody reports it as a
-  performance bug is suspected to be the absence of users. We have nominated
-  the command for removal and have started to emit a user-visible warning in
-  c3b58472be (pack-redundant: gauge the usage before proposing its removal,
-  2020-08-25) whenever the command is executed.
-+
-So far there was a single complaint about somebody still using the command, but
-that complaint did not cause us to reverse course. On the contrary, we have
-doubled down on the deprecation and starting with 4406522b76 (pack-redundant:
-escalate deprecation warning to an error, 2023-03-23), the command dies unless
-the user passes the `--i-still-use-this` option.
-+
-There have not been any subsequent complaints, so this command will finally be
-removed.
-+
-Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>,
-    <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>,
-    <20230323204047.GA9290@coredump.intra.peff.net>,
-
-* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/"
-  and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in
-  the repository configuration.
-+
-The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull:
-short-hand notation for remote repositories., 2005-07-16) and was superseded by
-6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin.,
-2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That
-commit already mentions an upcoming deprecation of the ".git/branches/"
-directory, and starting with a1d4aa7424 (Add repository-layout document.,
-2005-09-01) we have also marked this layout as deprecated. Eventually we also
-started to migrate away from ".git/remotes/" in favor of config-based remotes,
-and we have marked the directory as legacy in 3d3d282146 (Documentation:
-Grammar correction, wording fixes and cleanup, 2011-08-23)
-+
-As our documentation mentions, these directories are unlikely to be used in
-modern repositories and most users aren't even aware of these mechanisms. They
-have been deprecated for almost 20 years and 14 years respectively, and we are
-not aware of any active users that have complained about this deprecation.
-Furthermore, the ".git/branches/" directory is nowadays misleadingly named and
-may cause confusion as "branches" are almost exclusively used in the context of
-references.
-+
-These features will be removed.
-
-* Support for "--stdin" option in the "name-rev" command was
-  deprecated (and hidden from the documentation) in the Git 2.40
-  timeframe, in preference to its synonym "--annotate-stdin".  Git 3.0
-  removes the support for "--stdin" altogether.
-
-* The git-whatchanged(1) command has outlived its usefulness more than
-  10 years ago, and takes more keystrokes to type than its rough
-  equivalent `git log --raw`.  We have nominated the command for
-  removal, have changed the command to refuse to work unless the
-  `--i-still-use-this` option is given, and asked the users to report
-  when they do so.
-+
-The command will be removed.
-
-* Support for `core.commentString=auto` has been deprecated and will
-  be removed in Git 3.0.
-+
-cf. <xmqqa59i45wc.fsf@gitster.g>
-
-* Support for `core.preferSymlinkRefs=true` has been deprecated and will be
-  removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
-  out in favor of using plain files using the textual representation of
-  symbolic refs.
-+
-Symbolic references were initially always stored as a symbolic link. This was
-changed in 9b143c6e15 (Teach update-ref about a symbolic ref stored in a
-textfile., 2005-09-25), where a new textual symref format was introduced to
-store those symbolic refs in a plain file. In 9f0bb90d16
-(core.prefersymlinkrefs: use symlinks for .git/HEAD, 2006-05-02), the Git
-project switched the default to use the textual symrefs in favor of symbolic
-links.
-+
-The migration away from symbolic links has happened almost 20 years ago by now,
-and there is no known reason why one should prefer them nowadays. Furthermore,
-symbolic links are not supported on some platforms.
-+
-Note that only the writing side for such symbolic links is deprecated. Reading
-such symbolic links is still supported for now.
-
-== Superseded features that will not be deprecated
-
-Some features have gained newer replacements that aim to improve the design in
-certain ways. The fact that there is a replacement does not automatically mean
-that the old way of doing things will eventually be removed. This section tracks
-those features with newer alternatives.
-
-* The features git-checkout(1) offers are covered by the pair of commands
-  git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still
-  widespread, and it is not expected that this will change anytime soon, all
-  three commands will stay.
-+
-This decision may get revisited in case we ever figure out that there are
-almost no users of any of the commands anymore.
-+
-Cf. <xmqqttjazwwa.fsf@gitster.g>,
-<xmqqleeubork.fsf@gitster.g>,
-<112b6568912a6de6672bf5592c3a718e@manjaro.org>.

Documentation/CodingGuidelines

@@ -44,7 +44,7 @@ code are expected to match the style the surrounding code already
 uses (even if it doesn't match the overall style of existing code).
 
 But if you must have a list of rules, here are some language
-specific ones. Note that Documentation/ToolsForGit.adoc document
+specific ones. Note that Documentation/ToolsForGit.txt document
 has a collection of tips to help you use some external tools
 to conform to these guidelines.
 
@@ -185,51 +185,8 @@ For shell scripts specifically (not exhaustive):
 
  - Even though "local" is not part of POSIX, we make heavy use of it
    in our test suite.  We do not use it in scripted Porcelains, and
-   hopefully nobody starts using "local" before all shells that matter
-   support it (notably, ksh from AT&T Research does not support it yet).
-
- - Some versions of shell do not understand "export variable=value",
-   so we write "variable=value" and then "export variable" on two
-   separate lines.
-
- - Some versions of dash have broken variable assignment when prefixed
-   with "local", "export", and "readonly", in that the value to be
-   assigned goes through field splitting at $IFS unless quoted.
-
-	(incorrect)
-	local variable=$value
-	local variable=$(command args)
-
-	(correct)
-	local variable="$value"
-	local variable="$(command args)"
-
- - The common construct
-
-	VAR=VAL command args
-
-   to temporarily set and export environment variable VAR only while
-   "command args" is running is handy, but this triggers an
-   unspecified behaviour according to POSIX when used for a command
-   that is not an external command (like shell functions).  Indeed,
-   dash 0.5.10.2-6 on Ubuntu 20.04, /bin/sh on FreeBSD 13, and AT&T
-   ksh all make a temporary assignment without exporting the variable,
-   in such a case.  As it does not work portably across shells, do not
-   use this syntax for shell functions.  A common workaround is to do
-   an explicit export in a subshell, like so:
-
-	(incorrect)
-	VAR=VAL func args
-
-	(correct)
-	(
-		VAR=VAL &&
-		export VAR &&
-		func args
-	)
-
-   but be careful that the effect "func" makes to the variables in the
-   current shell will be lost across the subshell boundary.
+   hopefully nobody starts using "local" before they are reimplemented
+   in C ;-)
 
  - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g.
    "\xc2\xa2") in printf format strings, since hexadecimal escape
@@ -241,16 +198,6 @@ For C programs:
  - We use tabs to indent, and interpret tabs as taking up to
    8 spaces.
 
- - Nested C preprocessor directives are indented after the hash by one
-   space per nesting level.
-
-	#if FOO
-	# include <foo.h>
-	# if BAR
-	#  include <bar.h>
-	# endif
-	#endif
-
  - We try to keep to at most 80 characters per line.
 
  - As a Git developer we assume you have a reasonably modern compiler
@@ -258,14 +205,6 @@ For C programs:
    ensure your patch is clear of all compiler warnings we care about,
    by e.g. "echo DEVELOPER=1 >>config.mak".
 
- - When using DEVELOPER=1 mode, you may see warnings from the compiler
-   like "error: unused parameter 'foo' [-Werror=unused-parameter]",
-   which indicates that a function ignores its argument. If the unused
-   parameter can't be removed (e.g., because the function is used as a
-   callback and has to match a certain interface), you can annotate
-   the individual parameters with the UNUSED (or MAYBE_UNUSED)
-   keyword, like "int foo UNUSED".
-
  - We try to support a wide range of C compilers to compile Git with,
    including old ones.  As of Git v2.35.0 Git requires C99 (we check
    "__STDC_VERSION__"). You should not use features from a newer C
@@ -279,7 +218,7 @@ For C programs:
    . since around 2007 with 2b6854c863a, we have been using
      initializer elements which are not computable at load time. E.g.:
 
-	const char *args[] = { "constant", variable, NULL };
+	const char *args[] = {"constant", variable, NULL};
 
    . since early 2012 with e1327023ea, we have been using an enum
      definition whose last element is followed by a comma.  This, like
@@ -298,17 +237,6 @@ For C programs:
    . since late 2021 with 44ba10d6, we have had variables declared in
      the for loop "for (int i = 0; i < 10; i++)".
 
-   . since late 2023 with 8277dbe987 we have been using the bool type
-     from <stdbool.h>.
-
-   C99 features we have test balloons for:
-
-   . since late 2024 with v2.48.0-rc0~20, we have test balloons for
-     compound literal syntax, e.g., (struct foo){ .member = value };
-     our hope is that no platforms we care about have trouble using
-     them, and officially adopt its wider use in mid 2026.  Do not add
-     more use of the syntax until that happens.
-
    New C99 features that we cannot use yet:
 
    . %z and %zu as a printf() argument for a size_t (the %z being for
@@ -322,12 +250,7 @@ For C programs:
      v12.01, 2022-03-28).
 
  - Variables have to be declared at the beginning of the block, before
-   the first statement (i.e. -Wdeclaration-after-statement).  It is
-   encouraged to have a blank line between the end of the declarations
-   and the first statement in the block.
-
- - Do not explicitly initialize global variables to 0 or NULL;
-   instead, let BSS take care of the zero initialization.
+   the first statement (i.e. -Wdeclaration-after-statement).
 
  - NULL pointers shall be written as NULL, not as 0.
 
@@ -347,13 +270,6 @@ For C programs:
         while( condition )
 		func (bar+1);
 
- - A binary operator (other than ",") and ternary conditional "?:"
-   have a space on each side of the operator to separate it from its
-   operands.  E.g. "A + 1", not "A+1".
-
- - A unary operator (other than "." and "->") have no space between it
-   and its operand.  E.g. "(char *)ptr", not "(char *) ptr".
-
  - Do not explicitly compare an integral value with constant 0 or '\0',
    or a pointer value with constant NULL.  For instance, to validate that
    counted array <ptr, cnt> is initialized but has no elements, write:
@@ -530,41 +446,12 @@ For C programs:
    detail.
 
  - The first #include in C files, except in platform specific compat/
-   implementations and sha1dc/, must be <git-compat-util.h>.  This
-   header file insulates other header files and source files from
-   platform differences, like which system header files must be
-   included in what order, and what C preprocessor feature macros must
-   be defined to trigger certain features we expect out of the system.
-   A collorary to this is that C files should not directly include
-   system header files themselves.
-
-   There are some exceptions, because certain group of files that
-   implement an API all have to include the same header file that
-   defines the API and it is convenient to include <git-compat-util.h>
-   there.  Namely:
-
-   - the implementation of the built-in commands in the "builtin/"
-     directory that include "builtin.h" for the cmd_foo() prototype
-     definition,
-
-   - the test helper programs in the "t/helper/" directory that include
-     "t/helper/test-tool.h" for the cmd__foo() prototype definition,
-
-   - the xdiff implementation in the "xdiff/" directory that includes
-     "xdiff/xinclude.h" for the xdiff machinery internals,
-
-   - the unit test programs in "t/unit-tests/" directory that include
-     "t/unit-tests/test-lib.h" that gives them the unit-tests
-     framework, and
-
-   - the source files that implement reftable in the "reftable/"
-     directory that include "reftable/system.h" for the reftable
-     internals,
-
-   are allowed to assume that they do not have to include
-   <git-compat-util.h> themselves, as it is included as the first
-   '#include' in these header files.  These headers must be the first
-   header file to be "#include"d in them, though.
+   implementations and sha1dc/, must be either "git-compat-util.h" or
+   one of the approved headers that includes it first for you.  (The
+   approved headers currently include "builtin.h",
+   "t/helper/test-tool.h", "xdiff/xinclude.h", or
+   "reftable/system.h".)  You do not have to include more than one of
+   these.
 
  - A C file must directly include the header files that declare the
    functions and the types it uses, except for the functions and types
@@ -597,64 +484,7 @@ For C programs:
    Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or
    run `GIT_DEBUGGER="<debugger> <debugger-args>" ./bin-wrappers/git foo` to
    use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb"
-   ./bin-wrappers/git log` (See `bin-wrappers/wrap-for-bin.sh`.)
-
- - The primary data structure that a subsystem 'S' deals with is called
-   `struct S`. Functions that operate on `struct S` are named
-   `S_<verb>()` and should generally receive a pointer to `struct S` as
-   first parameter. E.g.
-
-	struct strbuf;
-
-	void strbuf_add(struct strbuf *buf, ...);
-
-	void strbuf_reset(struct strbuf *buf);
-
-    is preferred over:
-
-	struct strbuf;
-
-	void add_string(struct strbuf *buf, ...);
-
-	void reset_strbuf(struct strbuf *buf);
-
- - There are several common idiomatic names for functions performing
-   specific tasks on a structure `S`:
-
-    - `S_init()` initializes a structure without allocating the
-      structure itself.
-
-    - `S_release()` releases a structure's contents without reinitializing
-      the structure for immediate reuse, and without freeing the structure
-      itself.
-
-    - `S_clear()` is equivalent to `S_release()` followed by `S_init()`
-      such that the structure is directly usable after clearing it. When
-      `S_clear()` is provided, `S_init()` shall not allocate resources
-      that need to be released again.
-
-    - `S_free()` releases a structure's contents and frees the
-      structure.
-
- - Function names should be clear and descriptive, accurately reflecting
-   their purpose or behavior. Arbitrary suffixes that do not add meaningful
-   context can lead to confusion, particularly for newcomers to the codebase.
-
-   Historically, the '_1' suffix has been used in situations where:
-
-   - A function handles one element among a group that requires similar
-     processing.
-   - A recursive function has been separated from its setup phase.
-
-   The '_1' suffix can be used as a concise way to indicate these specific
-   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;
+   ./bin-wrappers/git log` (See `wrap-for-bin.sh`.)
 
 For Perl programs:
 
@@ -724,30 +554,16 @@ Program Output
 
 Error Messages
 
- - Do not end a single-sentence error message with a full stop.
+ - Do not end error messages with a full stop.
 
  - Do not capitalize the first word, only because it is the first word
-   in the message ("unable to open '%s'", not "Unable to open '%s'").  But
+   in the message ("unable to open %s", not "Unable to open %s").  But
    "SHA-3 not supported" is fine, because the reason the first word is
    capitalized is not because it is at the beginning of the sentence,
    but because the word would be spelled in capital letters even when
    it appeared in the middle of the sentence.
 
- - Say what the error is first ("cannot open '%s'", not "%s: cannot open").
-
- - Enclose the subject of an error inside a pair of single quotes,
-   e.g. `die(_("unable to open '%s'"), path)`.
-
- - Unless there is a compelling reason not to, error messages from
-   porcelain commands should be marked for translation, e.g.
-   `die(_("bad revision %s"), revision)`.
-
- - Error messages from the plumbing commands are sometimes meant for
-   machine consumption and should not be marked for translation,
-   e.g., `die("bad revision %s", revision)`.
-
- - BUG("message") are for communicating the specific error to developers,
-   thus should not be translated.
+ - Say what the error is first ("cannot open %s", not "%s: cannot open")
 
 
 Externally Visible Names
@@ -776,7 +592,7 @@ Externally Visible Names
 Writing Documentation:
 
  Most (if not all) of the documentation pages are written in the
- AsciiDoc format in *.adoc files (e.g. Documentation/git.adoc), and
+ AsciiDoc format in *.txt files (e.g. Documentation/git.txt), and
  processed into HTML and manpages (e.g. git.html and git.1 in the
  same directory).
 
@@ -796,15 +612,15 @@ Writing Documentation:
   - Prefer succinctness and matter-of-factly describing functionality
     in the abstract.  E.g.
 
-     `--short`:: Emit output in the short-format.
+     --short:: Emit output in the short-format.
 
     and avoid something like these overly verbose alternatives:
 
-     `--short`:: Use this to emit output in the short-format.
-     `--short`:: You can use this to get output in the short-format.
-     `--short`:: A user who prefers shorter output could....
-     `--short`:: Should a person and/or program want shorter output, he
-                 she/they/it can...
+     --short:: Use this to emit output in the short-format.
+     --short:: You can use this to get output in the short-format.
+     --short:: A user who prefers shorter output could....
+     --short:: Should a person and/or program want shorter output, he
+               she/they/it can...
 
     This practice often eliminates the need to involve human actors in
     your description, but it is a good practice regardless of the
@@ -814,12 +630,12 @@ Writing Documentation:
     addressing the hypothetical user, and possibly "we" when
     discussing how the program might react to the user.  E.g.
 
-      You can use this option instead of `--xyz`, but we might remove
+      You can use this option instead of --xyz, but we might remove
       support for it in future versions.
 
     while keeping in mind that you can probably be less verbose, e.g.
 
-      Use this instead of `--xyz`. This option might be removed in future
+      Use this instead of --xyz. This option might be removed in future
       versions.
 
   - If you still need to refer to an example person that is
@@ -837,87 +653,19 @@ Writing Documentation:
  The same general rule as for code applies -- imitate the existing
  conventions.
 
-
-Markup:
-
- Literal parts (e.g. use of command-line options, command names,
- branch names, URLs, pathnames (files and directories), configuration and
- environment variables) must be typeset as verbatim (i.e. wrapped with
- backticks):
-   `--pretty=oneline`
-   `git rev-list`
-   `remote.pushDefault`
-   `http://git.example.com`
-   `.git/config`
-   `GIT_DIR`
-   `HEAD`
-   `umask`(2)
-
- An environment variable must be prefixed with "$" only when referring to its
- value and not when referring to the variable itself, in this case there is
- nothing to add except the backticks:
-   `GIT_DIR` is specified
-   `$GIT_DIR/hooks/pre-receive`
-
- Word phrases enclosed in `backtick characters` are rendered literally
- and will not be further expanded. The use of `backticks` to achieve the
- previous rule means that literal examples should not use AsciiDoc
- escapes.
-   Correct:
-      `--pretty=oneline`
-   Incorrect:
-      `\--pretty=oneline`
-
- Placeholders are spelled in lowercase and enclosed in
- angle brackets surrounded by underscores:
-   _<file>_
-   _<commit>_
-
- If a placeholder has multiple words, they are separated by dashes:
-   _<new-branch-name>_
-   _<template-directory>_
-
- When needed, use a distinctive identifier for placeholders, usually
- made of a qualification and a type:
-   _<git-dir>_
-   _<key-id>_
-
-Characters are also surrounded by underscores:
-   _LF_, _CR_, _CR_/_LF_, _NUL_, _EOF_
-
- Git's Asciidoc processor has been tailored to treat backticked text
- as complex synopsis. When literal and placeholders are mixed, you can
- use the backtick notation which will take care of correctly typesetting
- the content.
-   `--jobs <n>`
-   `--sort=<key>`
-   `<directory>/.git`
-   `remote.<name>.mirror`
-   `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
-
-As a side effect, backquoted placeholders are correctly typeset, but
-this style is not recommended.
-
- When documenting multiple related `git config` variables, place them on
- a separate line instead of separating them by commas.  For example, do
- not write this:
-   `core.var1`, `core.var2`::
-	Description common to `core.var1` and `core.var2`.
-
-Instead write this:
-   `core.var1`::
-   `core.var2`::
-	Description common to `core.var1` and `core.var2`.
-
-Synopsis Syntax
-
- The synopsis (a paragraph with [synopsis] attribute) is automatically
- formatted by the toolchain and does not need typesetting.
-
  A few commented examples follow to provide reference when writing or
  modifying command usage strings and synopsis sections in the manual
  pages:
 
+ Placeholders are spelled in lowercase and enclosed in angle brackets:
+   <file>
+   --sort=<key>
+   --abbrev[=<n>]
+
+ If a placeholder has multiple words, they are separated by dashes:
+   <new-branch-name>
+   --template=<template-directory>
+
  Possibility of multiple occurrences is indicated by three dots:
    <file>...
    (One or more of <file>.)
@@ -926,9 +674,6 @@ Synopsis Syntax
    [<file>...]
    (Zero or more of <file>.)
 
- An optional parameter needs to be typeset with unconstrained pairs
-   [<repository>]
-
    --exec-path[=<path>]
    (Option with an optional argument.  Note that the "=" is inside the
    brackets.)
@@ -952,14 +697,14 @@ Synopsis Syntax
     Don't: --track[=(direct | inherit)]
 
  Parentheses are used for grouping:
-   [(<rev>|<range>)...]
+   [(<rev> | <range>)...]
    (Any number of either <rev> or <range>.  Parens are needed to make
    it clear that "..." pertains to both <rev> and <range>.)
 
    [(-p <parent>)...]
    (Any number of option -p, each with one <parent> argument.)
 
-   git remote set-head <name> (-a|-d|<branch>)
+   git remote set-head <name> (-a | -d | <branch>)
    (One and only one of "-a", "-d" or "<branch>" _must_ (no square
    brackets) be provided.)
 
@@ -975,6 +720,37 @@ Synopsis Syntax
    the user would type into a shell and use 'Git' (uppercase first letter)
    when talking about the version control system and its properties.
 
+ A few commented examples follow to provide reference when writing or
+ modifying paragraphs or option/command explanations that contain options
+ or commands:
+
+ Literal examples (e.g. use of command-line options, command names,
+ branch names, URLs, pathnames (files and directories), configuration and
+ environment variables) must be typeset in monospace (i.e. wrapped with
+ backticks):
+   `--pretty=oneline`
+   `git rev-list`
+   `remote.pushDefault`
+   `http://git.example.com`
+   `.git/config`
+   `GIT_DIR`
+   `HEAD`
+
+ An environment variable must be prefixed with "$" only when referring to its
+ value and not when referring to the variable itself, in this case there is
+ nothing to add except the backticks:
+   `GIT_DIR` is specified
+   `$GIT_DIR/hooks/pre-receive`
+
+ Word phrases enclosed in `backtick characters` are rendered literally
+ and will not be further expanded. The use of `backticks` to achieve the
+ previous rule means that literal examples should not use AsciiDoc
+ escapes.
+   Correct:
+      `--pretty=oneline`
+   Incorrect:
+      `\--pretty=oneline`
+
  If some place in the documentation needs to typeset a command usage
  example with inline substitutions, it is fine to use +monospaced and
  inline substituted text+ instead of `monospaced literal text`, and with

Documentation/DecisionMaking.adoc

@@ -1,74 +0,0 @@
-Decision-Making Process in the Git Project
-==========================================
-
-Introduction
-------------
-This document describes the current decision-making process in the Git
-project. It is a descriptive rather than prescriptive doc; that is, we want to
-describe how things work in practice rather than explicitly recommending any
-particular process or changes to the current process.
-
-Here we document how the project makes decisions for discussions
-(with or without patches), in scale larger than an individual patch
-series (which is fully covered by the SubmittingPatches document).
-
-
-Larger Discussions (with patches)
----------------------------------
-As with discussions on an individual patch series, starting a larger-scale
-discussion often begins by sending a patch or series to the list. This might
-take the form of an initial design doc, with implementation following in later
-iterations of the series (for example,
-link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or
-link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]),
-or it might include a full implementation from the beginning.
-In either case, discussion progresses the same way for an individual patch series,
-until consensus is reached or the topic is dropped.
-
-
-Larger Discussions (without patches)
-------------------------------------
-Occasionally, larger discussions might occur without an associated patch series.
-These may be very large-scale technical decisions that are beyond the scope of
-even a single large patch series, or they may be more open-ended,
-policy-oriented discussions (examples:
-link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust]
-or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]).
-In either case, discussion progresses as described above for general patch series.
-
-For larger discussions without a patch series or other concrete implementation,
-it may be hard to judge when consensus has been reached, as there are not any
-official guidelines. If discussion stalls at this point, it may be helpful to
-restart discussion with an RFC patch series (such as a partial, unfinished
-implementation or proof of concept) that can be more easily debated.
-
-When consensus is reached that it is a good idea, the original
-proposer is expected to coordinate the effort to make it happen,
-with help from others who were involved in the discussion, as
-needed.
-
-For decisions that require code changes, it is often the case that the original
-proposer will follow up with a patch series, although it is also common for
-other interested parties to provide an implementation (or parts of the
-implementation, for very large changes).
-
-For non-technical decisions such as community norms or processes, it is up to
-the community as a whole to implement and sustain agreed-upon changes.
-The project leadership committee (PLC) may help the implementation of
-policy decisions.
-
-
-Other Discussion Venues
------------------------
-Occasionally decision proposals are presented off-list, e.g. at the semi-regular
-Contributors' Summit. While higher-bandwidth face-to-face discussion is often
-useful for quickly reaching consensus among attendees, generally we expect to
-summarize the discussion in notes that can later be presented on-list. For an
-example, see the thread
-link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes
-from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay.
-
-We prefer that "official" discussion happens on the list so that the full
-community has opportunity to engage in discussion. This also means that the
-mailing list archives contain a more-or-less complete history of project
-discussions and decisions.

Documentation/Makefile

@@ -1,11 +1,6 @@
-# The default target of this Makefile is...
-all::
-
 # Import tree-wide shared Makefile behavior and libraries
 include ../shared.mak
 
-.PHONY: FORCE
-
 # Guard against environment variables
 MAN1_TXT =
 MAN5_TXT =
@@ -20,58 +15,55 @@ OBSOLETE_HTML =
 -include GIT-EXCLUDED-PROGRAMS
 
 MAN1_TXT += $(filter-out \
-		$(patsubst %,%.adoc,$(EXCLUDED_PROGRAMS)) \
-		$(addsuffix .adoc, $(ARTICLES) $(SP_ARTICLES)), \
-		$(wildcard git-*.adoc))
-MAN1_TXT += git.adoc
-MAN1_TXT += gitk.adoc
-MAN1_TXT += gitweb.adoc
-MAN1_TXT += scalar.adoc
+		$(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \
+		$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
+		$(wildcard git-*.txt))
+MAN1_TXT += git.txt
+MAN1_TXT += gitk.txt
+MAN1_TXT += gitweb.txt
+MAN1_TXT += scalar.txt
 
 # man5 / man7 guides (note: new guides should also be added to command-list.txt)
-MAN5_TXT += gitattributes.adoc
-MAN5_TXT += gitformat-bundle.adoc
-MAN5_TXT += gitformat-chunk.adoc
-MAN5_TXT += gitformat-commit-graph.adoc
-MAN5_TXT += gitformat-index.adoc
-MAN5_TXT += gitformat-loose.adoc
-MAN5_TXT += gitformat-pack.adoc
-MAN5_TXT += gitformat-signature.adoc
-MAN5_TXT += githooks.adoc
-MAN5_TXT += gitignore.adoc
-MAN5_TXT += gitmailmap.adoc
-MAN5_TXT += gitmodules.adoc
-MAN5_TXT += gitprotocol-capabilities.adoc
-MAN5_TXT += gitprotocol-common.adoc
-MAN5_TXT += gitprotocol-http.adoc
-MAN5_TXT += gitprotocol-pack.adoc
-MAN5_TXT += gitprotocol-v2.adoc
-MAN5_TXT += gitrepository-layout.adoc
-MAN5_TXT += gitweb.conf.adoc
+MAN5_TXT += gitattributes.txt
+MAN5_TXT += gitformat-bundle.txt
+MAN5_TXT += gitformat-chunk.txt
+MAN5_TXT += gitformat-commit-graph.txt
+MAN5_TXT += gitformat-index.txt
+MAN5_TXT += gitformat-pack.txt
+MAN5_TXT += gitformat-signature.txt
+MAN5_TXT += githooks.txt
+MAN5_TXT += gitignore.txt
+MAN5_TXT += gitmailmap.txt
+MAN5_TXT += gitmodules.txt
+MAN5_TXT += gitprotocol-capabilities.txt
+MAN5_TXT += gitprotocol-common.txt
+MAN5_TXT += gitprotocol-http.txt
+MAN5_TXT += gitprotocol-pack.txt
+MAN5_TXT += gitprotocol-v2.txt
+MAN5_TXT += gitrepository-layout.txt
+MAN5_TXT += gitweb.conf.txt
 
-MAN7_TXT += gitcli.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
-MAN7_TXT += gitglossary.adoc
-MAN7_TXT += gitpacking.adoc
-MAN7_TXT += gitnamespaces.adoc
-MAN7_TXT += gitremote-helpers.adoc
-MAN7_TXT += gitrevisions.adoc
-MAN7_TXT += gitsubmodules.adoc
-MAN7_TXT += gittutorial-2.adoc
-MAN7_TXT += gittutorial.adoc
-MAN7_TXT += gitworkflows.adoc
+MAN7_TXT += gitcli.txt
+MAN7_TXT += gitcore-tutorial.txt
+MAN7_TXT += gitcredentials.txt
+MAN7_TXT += gitcvs-migration.txt
+MAN7_TXT += gitdiffcore.txt
+MAN7_TXT += giteveryday.txt
+MAN7_TXT += gitfaq.txt
+MAN7_TXT += gitglossary.txt
+MAN7_TXT += gitnamespaces.txt
+MAN7_TXT += gitremote-helpers.txt
+MAN7_TXT += gitrevisions.txt
+MAN7_TXT += gitsubmodules.txt
+MAN7_TXT += gittutorial-2.txt
+MAN7_TXT += gittutorial.txt
+MAN7_TXT += gitworkflows.txt
 
-HOWTO_TXT += $(wildcard howto/*.adoc)
+HOWTO_TXT += $(wildcard howto/*.txt)
 
-DOC_DEP_TXT += $(wildcard *.adoc)
-DOC_DEP_TXT += $(wildcard config/*.adoc)
-DOC_DEP_TXT += $(wildcard includes/*.adoc)
+DOC_DEP_TXT += $(wildcard *.txt)
+DOC_DEP_TXT += $(wildcard config/*.txt)
+DOC_DEP_TXT += $(wildcard includes/*.txt)
 
 ifdef MAN_FILTER
 MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
@@ -80,8 +72,8 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
 MAN_FILTER = $(MAN_TXT)
 endif
 
-MAN_XML = $(patsubst %.adoc,%.xml,$(MAN_TXT))
-MAN_HTML = $(patsubst %.adoc,%.html,$(MAN_TXT))
+MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
+MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
 GIT_MAN_REF = master
 
 OBSOLETE_HTML += everyday.html
@@ -108,43 +100,28 @@ SP_ARTICLES += howto/rebase-from-internal-branch
 SP_ARTICLES += howto/keep-canonical-history-correct
 SP_ARTICLES += howto/maintain-git
 SP_ARTICLES += howto/coordinate-embargoed-releases
-API_DOCS = $(patsubst %.adoc,%,$(filter-out technical/api-index-skel.adoc technical/api-index.adoc, $(wildcard technical/api-*.adoc)))
+API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
 SP_ARTICLES += $(API_DOCS)
 
-TECH_DOCS += BreakingChanges
-TECH_DOCS += DecisionMaking
 TECH_DOCS += ReviewingGuidelines
 TECH_DOCS += MyFirstContribution
 TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
 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
 
@@ -152,9 +129,9 @@ ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
 HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML)
 DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML))
 
-DOC_MAN1 = $(patsubst %.adoc,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
-DOC_MAN5 = $(patsubst %.adoc,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
-DOC_MAN7 = $(patsubst %.adoc,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
+DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
+DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
+DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
 
 prefix ?= $(HOME)
 bindir ?= $(prefix)/bin
@@ -167,12 +144,16 @@ man5dir = $(mandir)/man5
 man7dir = $(mandir)/man7
 # DESTDIR =
 
+GIT_DATE := $(shell git show --quiet --pretty='%as')
+
 ASCIIDOC = asciidoc
 ASCIIDOC_EXTRA =
 ASCIIDOC_HTML = xhtml11
 ASCIIDOC_DOCBOOK = docbook
 ASCIIDOC_CONF = -f asciidoc.conf
-ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF)
+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
+		-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' \
+		-arevdate='$(GIT_DATE)'
 ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
 TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
 TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
@@ -197,10 +178,6 @@ endif
 -include ../config.mak.autogen
 -include ../config.mak
 
-# Set GIT_VERSION_OVERRIDE such that version_gen knows to substitute
-# GIT_VERSION in case it was set by the user.
-GIT_VERSION_OVERRIDE := $(GIT_VERSION)
-
 ifndef NO_MAN_BOLD_LITERAL
 XMLTO_EXTRA += -m manpage-bold-literal.xsl
 endif
@@ -224,30 +201,16 @@ ASCIIDOC_DOCBOOK = docbook5
 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
-ASCIIDOC_EXTRA += -adocinfo=shared
 ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
-
-asciidoctor-extensions.rb: asciidoctor-extensions.rb.in FORCE
-	$(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@)
-else
-asciidoc.conf: asciidoc.conf.in FORCE
-	$(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@)
 endif
 
-ifdef WITH_BREAKING_CHANGES
-ASCIIDOC_EXTRA += -awith-breaking-changes
-endif
-
-ASCIIDOC_DEPS += docinfo.html
-
 SHELL_PATH ?= $(SHELL)
 # Shell quote;
 SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
 
-ASCIIDOC_EXTRA += -abuild_dir='$(shell pwd)'
 ifdef DEFAULT_PAGER
 DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER))
 ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)'
@@ -258,7 +221,7 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR))
 ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'
 endif
 
-all:: html man
+all: html man
 
 html: $(DOC_HTML)
 
@@ -298,46 +261,59 @@ install-pdf: pdf
 install-html: html
 	'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
 
-mergetools_txt = mergetools-diff.adoc mergetools-merge.adoc
+../GIT-VERSION-FILE: FORCE
+	$(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE
+
+ifneq ($(filter-out lint-docs clean,$(MAKECMDGOALS)),)
+-include ../GIT-VERSION-FILE
+endif
 
 #
 # Determine "include::" file references in asciidoc files.
 #
 docdep_prereqs = \
-	$(mergetools_txt) \
+	mergetools-list.made $(mergetools_txt) \
 	cmd-list.made $(cmds_txt)
 
 doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl
-	$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl "$(shell pwd)" >$@ $(QUIET_STDERR)
+	$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR)
 
 ifneq ($(MAKECMDGOALS),clean)
 -include doc.dep
 endif
 
-cmds_txt = cmds-ancillaryinterrogators.adoc \
-	cmds-ancillarymanipulators.adoc \
-	cmds-mainporcelain.adoc \
-	cmds-plumbinginterrogators.adoc \
-	cmds-plumbingmanipulators.adoc \
-	cmds-synchingrepositories.adoc \
-	cmds-synchelpers.adoc \
-	cmds-guide.adoc \
-	cmds-developerinterfaces.adoc \
-	cmds-userinterfaces.adoc \
-	cmds-purehelpers.adoc \
-	cmds-foreignscminterface.adoc
+cmds_txt = cmds-ancillaryinterrogators.txt \
+	cmds-ancillarymanipulators.txt \
+	cmds-mainporcelain.txt \
+	cmds-plumbinginterrogators.txt \
+	cmds-plumbingmanipulators.txt \
+	cmds-synchingrepositories.txt \
+	cmds-synchelpers.txt \
+	cmds-guide.txt \
+	cmds-developerinterfaces.txt \
+	cmds-userinterfaces.txt \
+	cmds-purehelpers.txt \
+	cmds-foreignscminterface.txt
 
 $(cmds_txt): cmd-list.made
 
-cmd-list.made: cmd-list.sh ../command-list.txt $(MAN1_TXT)
-	$(QUIET_GEN)$(SHELL_PATH) ./cmd-list.sh .. . $(cmds_txt) && \
+cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
+	$(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \
 	date >$@
 
-mergetools-%.adoc: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
-mergetools-diff.adoc:
-	$(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. diff $@
-mergetools-merge.adoc:
-	$(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. merge $@
+mergetools_txt = mergetools-diff.txt mergetools-merge.txt
+
+$(mergetools_txt): mergetools-list.made
+
+mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
+	$(QUIET_GEN) \
+	$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=diff && \
+		. ../git-mergetool--lib.sh && \
+		show_tool_names can_diff' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-diff.txt && \
+	$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=merge && \
+		. ../git-mergetool--lib.sh && \
+		show_tool_names can_merge' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-merge.txt && \
+	date >$@
 
 TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
 
@@ -353,21 +329,16 @@ clean:
 	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
 	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
 	$(RM) *.pdf
-	$(RM) howto-index.adoc howto/*.html doc.dep
-	$(RM) technical/*.html technical/api-index.adoc
-	$(RM) SubmittingPatches.adoc
+	$(RM) howto-index.txt howto/*.html doc.dep
+	$(RM) technical/*.html technical/api-index.txt
+	$(RM) SubmittingPatches.txt
 	$(RM) $(cmds_txt) $(mergetools_txt) *.made
 	$(RM) GIT-ASCIIDOCFLAGS
-	$(RM) asciidoc.conf asciidoctor-extensions.rb
-	$(RM) -rf tmp-meson-diff
 
-docinfo.html: docinfo-html.in
-	$(QUIET_GEN)$(RM) $@ && cat $< >$@
-
-$(MAN_HTML): %.html : %.adoc $(ASCIIDOC_DEPS)
+$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<
 
-$(OBSOLETE_HTML): %.html : %.adoco $(ASCIIDOC_DEPS)
+$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
 manpage-prereqs := $(wildcard manpage*.xsl)
@@ -380,22 +351,22 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 %.7 : %.xml $(manpage-prereqs)
 	$(manpage-cmd)
 
-%.xml : %.adoc $(ASCIIDOC_DEPS)
+%.xml : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
 
-user-manual.xml: user-manual.adoc $(ASCIIDOC_DEPS)
+user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<
 
-technical/api-index.adoc: technical/api-index-skel.adoc \
-	technical/api-index.sh $(patsubst %,%.adoc,$(API_DOCS))
-	$(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.adoc
+technical/api-index.txt: technical/api-index-skel.txt \
+	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
+	$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
 
 technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
-$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.adoc \
-	$(ASCIIDOC_DEPS)
-	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.adoc
+$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
+	asciidoc.conf GIT-ASCIIDOCFLAGS
+	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
 
-SubmittingPatches.adoc: SubmittingPatches
+SubmittingPatches.txt: SubmittingPatches
 	$(QUIET_GEN) cp $< $@
 
 XSLT = docbook.xsl
@@ -410,9 +381,9 @@ user-manual.html: user-manual.xml $(XSLT)
 git.info: user-manual.texi
 	$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi
 
-user-manual.texi: user-manual.xml fix-texi.sh
+user-manual.texi: user-manual.xml
 	$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \
-	$(SHELL_PATH) fix-texi.sh <$@+ >$@ && \
+	$(PERL_PATH) fix-texi.perl <$@+ >$@ && \
 	$(RM) $@+
 
 user-manual.pdf: user-manual.xml
@@ -429,19 +400,19 @@ gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
 gitman.info: gitman.texi
 	$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $<
 
-$(patsubst %.adoc,%.texi,$(MAN_TXT)): %.texi : %.xml
+$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
 	$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@
 
-howto-index.adoc: howto/howto-index.sh $(HOWTO_TXT)
-	$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@
+howto-index.txt: howto-index.sh $(HOWTO_TXT)
+	$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@
 
-$(patsubst %,%.html,$(ARTICLES)) : %.html : %.adoc $(ASCIIDOC_DEPS)
-	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.adoc
+$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
+	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
 howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
-$(patsubst %.adoc,%.html,$(HOWTO_TXT)): %.html : %.adoc $(ASCIIDOC_DEPS)
+$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS
 	$(QUIET_ASCIIDOC) \
 	sed -e '1,/^$$/d' $< | \
 	$(TXT_TO_HTML) - >$@
@@ -472,9 +443,9 @@ print-man1:
 	@for i in $(MAN1_TXT); do echo $$i; done
 
 ## Lint: gitlink
-LINT_DOCS_GITLINK = $(patsubst %.adoc,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
+LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
 $(LINT_DOCS_GITLINK): lint-gitlink.perl
-$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.adoc
+$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
 	$(call mkdir_p_parent_template)
 	$(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \
 		$< \
@@ -486,17 +457,17 @@ $(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.adoc
 lint-docs-gitlink: $(LINT_DOCS_GITLINK)
 
 ## Lint: man-end-blurb
-LINT_DOCS_MAN_END_BLURB = $(patsubst %.adoc,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
+LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
 $(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl
-$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.adoc
+$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt
 	$(call mkdir_p_parent_template)
 	$(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@
 .PHONY: lint-docs-man-end-blurb
 
 ## Lint: man-section-order
-LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.adoc,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
+LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
 $(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl
-$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.adoc
+$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt
 	$(call mkdir_p_parent_template)
 	$(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@
 .PHONY: lint-docs-man-section-order
@@ -505,62 +476,19 @@ lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER)
 .PHONY: lint-docs-fsck-msgids
 LINT_DOCS_FSCK_MSGIDS = .build/lint-docs/fsck-msgids.ok
 $(LINT_DOCS_FSCK_MSGIDS): lint-fsck-msgids.perl
-$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.adoc
+$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt
 	$(call mkdir_p_parent_template)
 	$(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \
-		../fsck.h fsck-msgids.adoc $@
+		../fsck.h fsck-msgids.txt $@
+
 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
-
-.PHONY: lint-docs-meson
-lint-docs-meson:
-	@# awk acts up when trying to match single quotes, so we use \047 instead.
-	@mkdir -p tmp-meson-diff && \
-	awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^  \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \
-		grep -v -e '#' -e '^$$' | \
-		sort >tmp-meson-diff/meson.adoc && \
-	ls git*.adoc scalar.adoc | \
-		grep -v -e git-bisect-lk2009.adoc \
-			-e git-pack-redundant.adoc \
-			-e git-tools.adoc \
-			-e git-whatchanged.adoc \
-			>tmp-meson-diff/actual.adoc && \
-	if ! cmp tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; then \
-		echo "Meson man pages differ from actual man pages:"; \
-		diff -u tmp-meson-diff/meson.adoc tmp-meson-diff/actual.adoc; \
-		exit 1; \
-	fi
-
 ## Lint: list of targets above
 .PHONY: lint-docs
 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
 
 ifeq ($(wildcard po/Makefile),po/Makefile)
 doc-l10n install-l10n::

Documentation/MyFirstContribution.txt

@@ -21,7 +21,7 @@ This tutorial aims to summarize the following documents, but the reader may find
 useful additional context:
 
 - `Documentation/SubmittingPatches`
-- `Documentation/howto/new-command.adoc`
+- `Documentation/howto/new-command.txt`
 
 [[getting-help]]
 === Getting Help
@@ -40,6 +40,14 @@ the list by sending an email to <git+subscribe@vger.kernel.org>
 The https://lore.kernel.org/git[archive] of this mailing list is
 available to view in a browser.
 
+==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com]
+
+This mailing list is targeted to new contributors and was created as a place to
+post questions and receive answers outside of the public eye of the main list.
+Veteran contributors who are especially interested in helping mentor newcomers
+are present on the list. In order to avoid search indexers, group membership is
+required to view messages; anyone can join and no approval is required.
+
 ==== https://web.libera.chat/#git-devel[#git-devel] on Libera Chat
 
 This IRC channel is for conversations between Git contributors. If someone is
@@ -52,15 +60,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
 
@@ -151,31 +150,15 @@ command in `builtin/psuh.c`. Create that file, and within it, write the entry
 point for your command in a function matching the style and signature:
 
 ----
-int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
-	     const char *prefix UNUSED, struct repository *repo UNUSED)
+int cmd_psuh(int argc, const char **argv, const char *prefix)
 ----
 
-A few things to note:
-
-* A subcommand implementation takes its command line arguments
-  in `int argc` + `const char **argv`, like `main()` would.
-
-* It also takes two extra parameters, `prefix` and `repo`. What
-  they mean will not be discussed until much later.
-
-* Because this first example will not use any of the parameters,
-  your compiler will give warnings on unused parameters. As the
-  list of these four parameters is mandated by the API to add
-  new built-in commands, you cannot omit them. Instead, you add
-  `UNUSED` to each of them to tell the compiler that you *know*
-  you are not (yet) using it.
-
 We'll also need to add the declaration of psuh; open up `builtin.h`, find the
 declaration for `cmd_pull`, and add a new line for `psuh` immediately before it,
 in order to keep the declarations alphabetically sorted:
 
 ----
-int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo);
+int cmd_psuh(int argc, const char **argv, const char *prefix);
 ----
 
 Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to
@@ -191,8 +174,7 @@ Throughout the tutorial, we will mark strings for translation as necessary; you
 should also do so when writing your user-facing commands in the future.
 
 ----
-int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
-	     const char *prefix UNUSED, struct repository *repo UNUSED)
+int cmd_psuh(int argc, const char **argv, const char *prefix)
 {
 	printf(_("Pony saying hello goes here.\n"));
 	return 0;
@@ -305,9 +287,8 @@ on the reference implementation linked at the top of this document.
 It's probably useful to do at least something besides printing out a string.
 Let's start by having a look at everything we get.
 
-Modify your `cmd_psuh` implementation to dump the args you're passed,
-keeping existing `printf()` calls in place; because the args are now
-used, remove the `UNUSED` macro from them:
+Modify your `cmd_psuh` implementation to dump the args you're passed, keeping
+existing `printf()` calls in place:
 
 ----
 	int i;
@@ -331,8 +312,7 @@ on the command line, including the name of our command. (If `prefix` is empty
 for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so
 helpful. So what other context can we get?
 
-Add a line to `#include "config.h"` and `#include "repository.h"`.
-Then, add the following bits to the function body:
+Add a line to `#include "config.h"`. Then, add the following bits to the
 function body:
 
 ----
@@ -340,18 +320,18 @@ function body:
 
 ...
 
-	repo_config(repo, git_default_config, NULL);
-	if (repo_config_get_string_tmp(repo, "user.name", &cfg_name))
+	git_config(git_default_config, NULL);
+	if (git_config_get_string_tmp("user.name", &cfg_name) > 0)
 		printf(_("No name is found in config\n"));
 	else
 		printf(_("Your name: %s\n"), cfg_name);
 ----
 
-`repo_config()` will grab the configuration from config files known to Git and
-apply standard precedence rules. `repo_config_get_string_tmp()` will look up
+`git_config()` will grab the configuration from config files known to Git and
+apply standard precedence rules. `git_config_get_string_tmp()` will look up
 a specific key ("user.name") and give you the value. There are a number of
 single-key lookup functions like this one; you can see them all (and more info
-about how to use `repo_config()`) in `Documentation/technical/api-config.adoc`.
+about how to use `git_config()`) in `Documentation/technical/api-config.txt`.
 
 You should see that the name printed matches the one you see when you run:
 
@@ -384,10 +364,9 @@ status_init_config(&s, git_status_config);
 ----
 
 But as we drill down, we can find that `status_init_config()` wraps a call
-to `repo_config()`. Let's modify the code we wrote in the previous commit.
+to `git_config()`. Let's modify the code we wrote in the previous commit.
 
 Be sure to include the header to allow you to use `struct wt_status`:
-
 ----
 #include "wt-status.h"
 ----
@@ -400,8 +379,8 @@ prepare it, and print its contents:
 
 ...
 
-	wt_status_prepare(repo, &status);
-	repo_config(repo, git_default_config, &status);
+	wt_status_prepare(the_repository, &status);
+	git_config(git_default_config, &status);
 
 ...
 
@@ -482,10 +461,10 @@ $ ./bin-wrappers/git help psuh
 
 Your new command is undocumented! Let's fix that.
 
-Take a look at `Documentation/git-*.adoc`. These are the manpages for the
+Take a look at `Documentation/git-*.txt`. These are the manpages for the
 subcommands that Git knows about. You can open these up and take a look to get
 acquainted with the format, but then go ahead and make a new file
-`Documentation/git-psuh.adoc`. Like with most of the documentation in the Git
+`Documentation/git-psuh.txt`. Like with most of the documentation in the Git
 project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing
 Documentation" section). Use the following template to fill out your own
 manpage:
@@ -564,7 +543,7 @@ Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end.
 That's because `-h` is a special case which your command should handle by
 printing usage.
 
-Take a look at `Documentation/technical/api-parse-options.adoc`. This is a handy
+Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy
 tool for pulling out options you need to be able to handle, and it takes a
 usage string.
 
@@ -917,13 +896,10 @@ Now you should be able to go and check out your newly created branch on GitHub.
 === Sending a PR to GitGitGadget
 
 In order to have your code tested and formatted for review, you need to start by
-opening a Pull Request against either `gitgitgadget/git` or `git/git`. Head to
-https://github.com/gitgitgadget/git or https://github.com/git/git and open a PR
-either with the "New pull request" button or the convenient "Compare & pull
-request" button that may appear with the name of your newly pushed branch.
-
-The differences between using `gitgitgadget/git` and `git/git` as your base can
-be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)
+opening a Pull Request against `gitgitgadget/git`. Head to
+https://github.com/gitgitgadget/git and open a PR either with the "New pull
+request" button or the convenient "Compare & pull request" button that may
+appear with the name of your newly pushed branch.
 
 Review the PR's title and description, as they're used by GitGitGadget
 respectively as the subject and body of the cover letter for your change. Refer
@@ -1112,14 +1088,14 @@ This gives reviewers a summary of what they're in for when reviewing your topic.
 The one generated for `psuh` from the sample implementation looks like this:
 
 ----
- Documentation/git-psuh.adoc | 40 +++++++++++++++++++++
- Makefile                    |  1 +
- builtin.h                   |  1 +
- builtin/psuh.c              | 73 ++++++++++++++++++++++++++++++++++++++
- git.c                       |  1 +
- t/t9999-psuh-tutorial.sh    | 12 +++++++
+ Documentation/git-psuh.txt | 40 +++++++++++++++++++++
+ Makefile                   |  1 +
+ builtin.h                  |  1 +
+ builtin/psuh.c             | 73 ++++++++++++++++++++++++++++++++++++++
+ git.c                      |  1 +
+ t/t9999-psuh-tutorial.sh   | 12 +++++++
  6 files changed, 128 insertions(+)
- create mode 100644 Documentation/git-psuh.adoc
+ create mode 100644 Documentation/git-psuh.txt
  create mode 100644 builtin/psuh.c
  create mode 100755 t/t9999-psuh-tutorial.sh
 ----
@@ -1140,24 +1116,10 @@ $ git send-email --to=target@example.com psuh/*.patch
 NOTE: Check `git help send-email` for some other options which you may find
 valuable, such as changing the Reply-to address or adding more CC and BCC lines.
 
-:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are +
-not part of the core `git` binary and must be called directly. Clone the Git +
-codebase and run `perl contrib/contacts/git-contacts`.]
-
-NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can
-list potential reviewers. In addition, you can do `git send-email
---cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to
-automatically pass this list of emails to `send-email`.
-
 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/MyFirstObjectWalk.txt

@@ -15,7 +15,7 @@ revision walk is used for operations like `git log`.
 
 === Related Reading
 
-- `Documentation/user-manual.adoc` under "Hacking Git" contains some coverage of
+- `Documentation/user-manual.txt` under "Hacking Git" contains some coverage of
   the revision walker in its various incarnations.
 - `revision.h`
 - https://eagain.net/articles/git-for-computer-scientists/[Git for Computer Scientists]
@@ -43,7 +43,7 @@ Open up a new file `builtin/walken.c` and set up the command handler:
 #include "builtin.h"
 #include "trace.h"
 
-int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo)
+int cmd_walken(int argc, const char **argv, const char *prefix)
 {
 	trace_printf(_("cmd_walken incoming...\n"));
 	return 0;
@@ -83,36 +83,23 @@ int cmd_walken(int argc, const char **argv, const char *prefix)
 }
 ----
 
-Also add the relevant line in `builtin.h` near `cmd_version()`:
+Also add the relevant line in `builtin.h` near `cmd_whatchanged()`:
 
 ----
-int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo);
+int cmd_walken(int argc, const char **argv, const char *prefix);
 ----
 
-Include the command in `git.c` in `commands[]` near the entry for `version`,
+Include the command in `git.c` in `commands[]` near the entry for `whatchanged`,
 maintaining alphabetical ordering:
 
 ----
 { "walken", cmd_walken, RUN_SETUP },
 ----
 
-Add an entry for the new command in the both the Make and Meson build system,
-before the entry for `worktree`:
+Add it to the `Makefile` near the line for `builtin/worktree.o`:
 
-- In the `Makefile`:
 ----
-...
 BUILTIN_OBJS += builtin/walken.o
-...
-----
-
-- In the `meson.build` file:
-----
-builtin_sources = [
-   ...
-  'builtin/walken.c',
-   ...
-]
 ----
 
 Build and test out your command, without forgetting to ensure the `DEVELOPER`
@@ -125,7 +112,7 @@ $ GIT_TRACE=1 ./bin-wrappers/git walken
 ----
 
 NOTE: For a more exhaustive overview of the new command process, take a look at
-`Documentation/MyFirstContribution.adoc`.
+`Documentation/MyFirstContribution.txt`.
 
 NOTE: A reference implementation can be found at
 https://github.com/nasamuffin/git/tree/revwalk.
@@ -145,7 +132,7 @@ used to track the allocated size of the list.
 Per entry, we find:
 
 `item` is the object provided upon which to base the object walk. Items in Git
-can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.adoc`.)
+can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.txt`.)
 
 `name` is the object ID (OID) of the object - a hex string you may be familiar
 with from using Git to organize your source in the past. Check the tutorial
@@ -154,7 +141,7 @@ from.
 
 `whence` indicates some information about what to do with the parents of the
 specified object. We'll explore this flag more later on; take a look at
-`Documentation/revisions.adoc` to get an idea of what could set the `whence`
+`Documentation/revisions.txt` to get an idea of what could set the `whence`
 value.
 
 `flags` are used to hint the beginning of the revision walk and are the first
@@ -166,7 +153,7 @@ can be used during the walk, as well.
 
 This one is quite a bit longer, and many fields are only used during the walk
 by `revision.c` - not configuration options. Most of the configurable flags in
-`struct rev_info` have a mirror in `Documentation/rev-list-options.adoc`. It's a
+`struct rev_info` have a mirror in `Documentation/rev-list-options.txt`. It's a
 good idea to take some time and read through that document.
 
 == Basic Commit Walk
@@ -206,7 +193,7 @@ initialization functions.
 
 Next, we should have a look at any relevant configuration settings (i.e.,
 settings readable and settable from `git config`). This is done by providing a
-callback to `repo_config()`; within that callback, you can also invoke methods
+callback to `git_config()`; within that callback, you can also invoke methods
 from other components you may need that need to intercept these options. Your
 callback will be invoked once per each configuration value which Git knows about
 (global, local, worktree, etc.).
@@ -223,25 +210,24 @@ We'll also need to include the `config.h` header:
 
 ...
 
-static int git_walken_config(const char *var, const char *value,
-			     const struct config_context *ctx, void *cb)
+static int git_walken_config(const char *var, const char *value, void *cb)
 {
 	/*
 	 * For now, we don't have any custom configuration, so fall back to
 	 * the default config.
 	 */
-	return git_default_config(var, value, ctx, cb);
+	return git_default_config(var, value, cb);
 }
 ----
 
-Make sure to invoke `repo_config()` with it in your `cmd_walken()`:
+Make sure to invoke `git_config()` with it in your `cmd_walken()`:
 
 ----
-int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo)
+int cmd_walken(int argc, const char **argv, const char *prefix)
 {
 	...
 
-	repo_config(repo, git_walken_config, NULL);
+	git_config(git_walken_config, NULL);
 
 	...
 }
@@ -263,14 +249,14 @@ We'll also need to include the `revision.h` header:
 
 ...
 
-int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo)
+int cmd_walken(int argc, const char **argv, const char *prefix)
 {
 	/* This can go wherever you like in your declarations.*/
 	struct rev_info rev;
 	...
 
-	/* This should go after the repo_config() call. */
-	repo_init_revisions(repo, &rev, prefix);
+	/* This should go after the git_config() call. */
+	repo_init_revisions(the_repository, &rev, prefix);
 
 	...
 }
@@ -300,7 +286,6 @@ static void final_rev_info_setup(struct rev_info *rev)
 ====
 Instead of using the shorthand `add_head_to_pending()`, you could do
 something like this:
-
 ----
 	struct setup_revision_opt opt;
 
@@ -309,7 +294,6 @@ something like this:
 	opt.revarg_opt = REVARG_COMMITTISH;
 	setup_revisions(argc, argv, rev, &opt);
 ----
-
 Using a `setup_revision_opt` gives you finer control over your walk's starting
 point.
 ====
@@ -318,7 +302,7 @@ Then let's invoke `final_rev_info_setup()` after the call to
 `repo_init_revisions()`:
 
 ----
-int cmd_walken(int argc, const char **argv, const char *prefix, struct repository *repo)
+int cmd_walken(int argc, const char **argv, const char *prefix)
 {
 	...
 
@@ -405,11 +389,10 @@ modifying `rev_info.grep_filter`, which is a `struct grep_opt`.
 First some setup. Add `grep_config()` to `git_walken_config()`:
 
 ----
-static int git_walken_config(const char *var, const char *value,
-			     const struct config_context *ctx, void *cb)
+static int git_walken_config(const char *var, const char *value, void *cb)
 {
-	grep_config(var, value, ctx, cb);
-	return git_default_config(var, value, ctx, cb);
+	grep_config(var, value, cb);
+	return git_default_config(var, value, cb);
 }
 ----
 
@@ -540,7 +523,7 @@ about each one.
 
 We can base our work on an example. `git pack-objects` prepares all kinds of
 objects for packing into a bitmap or packfile. The work we are interested in
-resides in `builtin/pack-objects.c:get_object_list()`; examination of that
+resides in `builtins/pack-objects.c:get_object_list()`; examination of that
 function shows that the all-object walk is being performed by
 `traverse_commit_list()` or `traverse_commit_list_filtered()`. Those two
 functions reside in `list-objects.c`; examining the source shows that, despite
@@ -725,7 +708,7 @@ objects grows along with the Git project.
 === Adding a Filter
 
 There are a handful of filters that we can apply to the object walk laid out in
-`Documentation/rev-list-options.adoc`. These filters are typically useful for
+`Documentation/rev-list-options.txt`. These filters are typically useful for
 operations such as creating packfiles or performing a partial clone. They are
 defined in `list-objects-filter-options.h`. For the purposes of this tutorial we
 will use the "tree:1" filter, which causes the walk to omit all trees and blobs
@@ -749,8 +732,8 @@ walk we've just performed:
 	} else {
 		trace_printf(
 			_("Filtered object walk with filterspec 'tree:1'.\n"));
-
-		parse_list_objects_filter(&rev->filter, "tree:1");
+		CALLOC_ARRAY(rev->filter, 1);
+		parse_list_objects_filter(rev->filter, "tree:1");
 	}
 	traverse_commit_list(rev, walken_show_commit,
 			     walken_show_object, NULL);
@@ -769,12 +752,10 @@ points to the same tree object as its grandparent.)
 === Counting Omitted Objects
 
 We also have the capability to enumerate all objects which were omitted by a
-filter, like with `git log --filter=<spec> --filter-print-omitted`. To do this,
-change `traverse_commit_list()` to `traverse_commit_list_filtered()`, which is
-able to populate an `omitted` list.  Asking for this list of filtered objects
-may cause performance degradations, however, because in this case, despite
-filtering objects, the possibly much larger set of all reachable objects must
-be processed in order to populate that list.
+filter, like with `git log --filter=<spec> --filter-print-omitted`. Asking
+`traverse_commit_list_filtered()` to populate the `omitted` list means that our
+object walk does not perform any better than an unfiltered object walk; all
+reachable objects are walked in order to populate the list.
 
 First, add the `struct oidset` and related items we will use to iterate it:
 
@@ -795,9 +776,8 @@ static void walken_object_walk(
 	...
 ----
 
-Replace the call to `traverse_commit_list()` with
-`traverse_commit_list_filtered()` and pass a pointer to the `omitted` oidset
-defined and initialized above:
+Modify the call to `traverse_commit_list_filtered()` to include your `omitted`
+object:
 
 ----
 	...
@@ -863,7 +843,7 @@ those lines without having to recompile.
 With only that change, run again (but save yourself some scrollback):
 
 ----
-$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | head -n 10
+$ GIT_TRACE=1 ./bin-wrappers/git walken | head -n 10
 ----
 
 Take a look at the top commit with `git show` and the object ID you printed; it
@@ -891,7 +871,7 @@ of the first handful:
 
 ----
 $ make
-$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | tail -n 10
+$ GIT_TRACE=1 ./bin-wrappers git walken | tail -n 10
 ----
 
 The last commit object given should have the same OID as the one we saw at the

Documentation/RelNotes/1.6.2.4.txt

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