diff --git a/.editorconfig b/.editorconfig index 2d3929b5916a14..82e121a41754b5 100644 --- a/.editorconfig +++ b/.editorconfig @@ -8,6 +8,10 @@ insert_final_newline = true indent_style = tab tab_width = 8 +[templates/hooks/*.sample] +indent_style = tab +tab_width = 8 + [*.py] indent_style = space indent_size = 4 diff --git a/.gitattributes b/.gitattributes index 700743c3f5ef99..26490ad60a74d0 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2,7 +2,7 @@ *.[ch] whitespace=indent,trail,space,incomplete diff=cpp *.sh whitespace=indent,trail,space,incomplete text eol=lf *.perl text eol=lf diff=perl -*.pl text eof=lf diff=perl +*.pl text eol=lf diff=perl *.pm text eol=lf diff=perl *.py text eol=lf diff=python *.bat text eol=crlf @@ -17,3 +17,5 @@ CODE_OF_CONDUCT.md -whitespace /Documentation/gitk.adoc conflict-marker-size=32 /Documentation/user-manual.adoc conflict-marker-size=32 /t/t????-*.sh conflict-marker-size=32 +/t/unit-tests/clar/test/expected/* whitespace=-blank-at-eof +/templates/hooks/*.sample whitespace=indent,trail,space,incomplete text eol=lf diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c8755e38de81ca..93042128d60d21 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -10,7 +10,8 @@ conveniently send your Pull Requests commits to our mailing list. Please read ["A note from the maintainer"](https://git.kernel.org/pub/scm/git/git.git/plain/MaintNotes?h=todo) to learn how the Git project is managed, and how you can work with it. -In addition, we highly recommend you to read [our submission guidelines](../Documentation/SubmittingPatches). +In addition, we highly recommend you to read +[our submission guidelines](https://git-scm.com/docs/SubmittingPatches). If you prefer video, then [this talk](https://www.youtube.com/watch?v=Q7i_qQW__q4&feature=youtu.be&t=6m4s) might be useful to you as the presenter walks you through the contribution diff --git a/.github/workflows/check-style.yml b/.github/workflows/check-style.yml index 19a145d4ad0c5a..108a2de903310c 100644 --- a/.github/workflows/check-style.yml +++ b/.github/workflows/check-style.yml @@ -20,7 +20,7 @@ jobs: jobname: ClangFormat runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 with: fetch-depth: 0 diff --git a/.github/workflows/check-whitespace.yml b/.github/workflows/check-whitespace.yml index 928fd4cfe2456d..ea6f49f742108e 100644 --- a/.github/workflows/check-whitespace.yml +++ b/.github/workflows/check-whitespace.yml @@ -19,7 +19,7 @@ jobs: check-whitespace: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 with: fetch-depth: 0 diff --git a/.github/workflows/coverity.yml b/.github/workflows/coverity.yml index cfa17d394a7dbc..58a78f1eb3f836 100644 --- a/.github/workflows/coverity.yml +++ b/.github/workflows/coverity.yml @@ -38,10 +38,10 @@ jobs: COVERITY_LANGUAGE: cxx COVERITY_PLATFORM: overridden-below steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - name: install minimal Git for Windows SDK if: contains(matrix.os, 'windows') - uses: git-for-windows/setup-git-for-windows-sdk@v1 + uses: git-for-windows/setup-git-for-windows-sdk@v2 - run: ci/install-dependencies.sh if: contains(matrix.os, 'ubuntu') || contains(matrix.os, 'macos') env: @@ -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@v5 with: path: ${{ runner.temp }}/cov-analysis key: cov-build-${{ env.COVERITY_LANGUAGE }}-${{ env.COVERITY_PLATFORM }}-${{ steps.lookup.outputs.hash }} @@ -141,7 +141,7 @@ jobs: esac - name: cache the Coverity Build Tool if: steps.cache.outputs.cache-hit != 'true' - uses: actions/cache/save@v4 + uses: actions/cache/save@v5 with: path: ${{ runner.temp }}/cov-analysis key: cov-build-${{ env.COVERITY_LANGUAGE }}-${{ env.COVERITY_PLATFORM }}-${{ steps.lookup.outputs.hash }} diff --git a/.github/workflows/l10n.yml b/.github/workflows/l10n.yml index 95e55134bdbed4..114a12a9e59f60 100644 --- a/.github/workflows/l10n.yml +++ b/.github/workflows/l10n.yml @@ -92,7 +92,7 @@ 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@v3 if: >- always() && github.event_name == 'pull_request_target' && diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 27ebf2c8cc2e64..cf341d74dbff21 100644 --- a/.github/workflows/main.yml +++ b/.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@v9 if: steps.check-ref.outputs.enabled == 'yes' with: github-token: ${{secrets.GITHUB_TOKEN}} @@ -112,8 +112,8 @@ jobs: group: windows-build-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v5 - - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - uses: actions/checkout@v6 + - uses: git-for-windows/setup-git-for-windows-sdk@v2 - name: build shell: bash env: @@ -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@v7 with: name: windows-artifacts path: artifacts @@ -140,24 +140,24 @@ 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@v8 with: name: windows-artifacts path: ${{github.workspace}} - name: extract tracked files and build artifacts shell: bash run: tar xf artifacts.tar.gz && tar xf tracked.tar.gz - - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - uses: git-for-windows/setup-git-for-windows-sdk@v2 - name: test shell: bash - run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10 + run: . /etc/profile && ci/run-test-slice.sh $((${{matrix.nr}} + 1)) 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@v5 + uses: actions/upload-artifact@v7 with: name: failed-tests-windows-${{ matrix.nr }} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -173,10 +173,10 @@ jobs: group: vs-build-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v5 - - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - uses: actions/checkout@v6 + - uses: git-for-windows/setup-git-for-windows-sdk@v2 - name: initialize vcpkg - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: repository: 'microsoft/vcpkg' path: 'compat/vcbuild/vcpkg' @@ -186,7 +186,7 @@ jobs: repository: git/git definitionId: 9 - name: add msbuild to PATH - uses: microsoft/setup-msbuild@v2 + uses: microsoft/setup-msbuild@v3 - name: copy dlls to root shell: cmd run: compat\vcbuild\vcpkg_copy_dlls.bat release @@ -208,7 +208,7 @@ jobs: - name: zip up tracked files run: git archive -o artifacts/tracked.tar.gz HEAD - name: upload tracked files and build artifacts - uses: actions/upload-artifact@v5 + uses: actions/upload-artifact@v7 with: name: vs-artifacts path: artifacts @@ -224,9 +224,9 @@ jobs: group: vs-test-${{ matrix.nr }}-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - uses: git-for-windows/setup-git-for-windows-sdk@v2 - name: download tracked files and build artifacts - uses: actions/download-artifact@v6 + uses: actions/download-artifact@v8 with: name: vs-artifacts path: ${{github.workspace}} @@ -237,14 +237,14 @@ jobs: shell: bash env: NO_SVN_TESTS: 1 - run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10 + run: . /etc/profile && ci/run-test-slice.sh $((${{matrix.nr}} + 1)) 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@v5 + uses: actions/upload-artifact@v7 with: name: failed-tests-windows-vs-${{ matrix.nr }} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -258,7 +258,7 @@ jobs: group: windows-meson-build-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - uses: actions/setup-python@v6 - name: Set up dependencies shell: pwsh @@ -270,7 +270,7 @@ jobs: shell: pwsh run: meson compile -C build - name: Upload build artifacts - uses: actions/upload-artifact@v5 + uses: actions/upload-artifact@v7 with: name: windows-meson-artifacts path: build @@ -286,26 +286,26 @@ jobs: group: windows-meson-test-${{ matrix.nr }}-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - 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 + uses: actions/download-artifact@v8 with: name: windows-meson-artifacts path: build - name: Test - shell: pwsh - run: ci/run-test-slice-meson.sh build ${{matrix.nr}} 10 + shell: bash + run: ci/run-test-slice-meson.sh build $((${{matrix.nr}} + 1)) 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 + uses: actions/upload-artifact@v7 with: name: failed-tests-windows-meson-${{ matrix.nr }} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -341,7 +341,7 @@ jobs: TEST_OUTPUT_DIRECTORY: ${{github.workspace}}/t runs-on: ${{matrix.vector.pool}} steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - run: ci/install-dependencies.sh - run: ci/run-build-and-tests.sh - name: print test failures @@ -349,7 +349,7 @@ jobs: run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v5 + uses: actions/upload-artifact@v7 with: name: failed-tests-${{matrix.vector.jobname}} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -362,7 +362,7 @@ jobs: CI_JOB_IMAGE: ubuntu-latest runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - run: ci/install-dependencies.sh - run: ci/run-build-and-minimal-fuzzers.sh dockerized: @@ -407,7 +407,7 @@ jobs: image: alpine:latest # Supported until 2025-04-02. - jobname: linux32 - image: i386/ubuntu:focal + image: i386/ubuntu:20.04 # A RHEL 8 compatible distro. Supported until 2029-05-31. - jobname: almalinux-8 image: almalinux:8 @@ -439,17 +439,17 @@ jobs: else apt-get -q update && apt-get -q -y install git fi - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - run: ci/install-dependencies.sh - run: useradd builder --create-home - run: chown -R builder . - - run: sudo --preserve-env --set-home --user=builder ci/run-build-and-tests.sh + - run: chmod a+w $GITHUB_ENV && sudo --preserve-env --set-home --user=builder ci/run-build-and-tests.sh - name: print test failures if: failure() && env.FAILED_TEST_ARTIFACTS != '' run: sudo --preserve-env --set-home --user=builder ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v5 + uses: actions/upload-artifact@v7 with: name: failed-tests-${{matrix.vector.jobname}} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -464,7 +464,7 @@ jobs: group: static-analysis-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - run: ci/install-dependencies.sh - run: ci/run-static-analysis.sh - run: ci/check-directional-formatting.bash @@ -480,7 +480,7 @@ jobs: group: rust-analysis-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - run: ci/install-dependencies.sh - run: ci/run-rust-checks.sh sparse: @@ -494,7 +494,7 @@ jobs: group: sparse-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - name: Install other dependencies run: ci/install-dependencies.sh - run: make sparse @@ -510,6 +510,6 @@ jobs: CI_JOB_IMAGE: ubuntu-latest runs-on: ubuntu-latest steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - run: ci/install-dependencies.sh - run: ci/test-documentation.sh diff --git a/.gitignore b/.gitignore index 78a45cb5bec991..4da58c6754899e 100644 --- a/.gitignore +++ b/.gitignore @@ -71,6 +71,7 @@ /git-for-each-ref /git-for-each-repo /git-format-patch +/git-format-rev /git-fsck /git-fsck-objects /git-fsmonitor--daemon @@ -79,6 +80,7 @@ /git-grep /git-hash-object /git-help +/git-history /git-hook /git-http-backend /git-http-fetch @@ -181,6 +183,7 @@ /git-update-server-info /git-upload-archive /git-upload-pack +/git-url-parse /git-var /git-verify-commit /git-verify-pack diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index b419a84e2cc660..1a8e90932cc292 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -42,15 +42,15 @@ test:linux: - jobname: linux-reftable image: ubuntu:rolling CC: clang - - jobname: linux-breaking-changes - image: ubuntu:20.04 - CC: gcc - - jobname: fedora-breaking-changes-meson - image: fedora:latest - jobname: linux-TEST-vars image: ubuntu:20.04 CC: gcc CC_PACKAGE: gcc-8 + - jobname: linux-breaking-changes + image: ubuntu:rolling + CC: gcc + - jobname: fedora-breaking-changes-meson + image: fedora:latest - jobname: linux-leaks image: ubuntu:rolling CC: gcc @@ -60,13 +60,20 @@ test:linux: - 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: linux32 image: i386/ubuntu:20.04 - - jobname: linux-meson - image: ubuntu:rolling - CC: gcc + # 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 artifacts: paths: - t/failed-test-artifacts @@ -79,7 +86,7 @@ test:osx: stage: test needs: [ ] tags: - - saas-macos-medium-m1 + - saas-macos-large-m2pro variables: TEST_OUTPUT_DIRECTORY: "/Volumes/RAMDisk" before_script: @@ -101,13 +108,13 @@ test:osx: parallel: matrix: - jobname: osx-clang - image: macos-14-xcode-15 + image: macos-15-xcode-16 CC: clang - jobname: osx-reftable - image: macos-14-xcode-15 + image: macos-26-xcode-26 CC: clang - jobname: osx-meson - image: macos-14-xcode-15 + image: macos-26-xcode-26 CC: clang artifacts: paths: @@ -157,19 +164,27 @@ test:mingw64: parallel: 10 .msvc-meson: + variables: + TEST_OUTPUT_DIRECTORY: "C:/Git-Test" tags: - saas-windows-medium-amd64 + cache: + key: + files: + - ci/install-dependencies.ps1 + paths: + - .dependencies before_script: - *windows_before_script - - choco install -y git meson ninja rust-ms - - Import-Module $env:ChocolateyInstall\helpers\chocolateyProfile.psm1 - - refreshenv + - ./ci/install-dependencies.ps1 + - $env:Path = "C:\Meson;C:\Rust\bin;$env:Path" + - New-Item -Path $env:TEST_OUTPUT_DIRECTORY -ItemType Directory build:msvc-meson: extends: .msvc-meson stage: build script: - - meson setup build --vsenv -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred + - meson setup build --vsenv -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred -Dtest_output_directory="$TEST_OUTPUT_DIRECTORY" - meson compile -C build artifacts: paths: @@ -183,11 +198,21 @@ test:msvc-meson: - job: "build:msvc-meson" artifacts: true script: - - meson test -C build --no-rebuild --print-errorlogs --slice $Env:CI_NODE_INDEX/$Env:CI_NODE_TOTAL + - | + & "C:/Program Files/Git/usr/bin/bash.exe" -l -c 'ci/run-test-slice-meson.sh build $CI_NODE_INDEX $CI_NODE_TOTAL' + after_script: + - | + if ($env:CI_JOB_STATUS -ne "success") { + & "C:/Program Files/Git/usr/bin/bash.exe" -l -c 'ci/print-test-failures.sh' + Move-Item -Path "$env:TEST_OUTPUT_DIRECTORY/failed-test-artifacts" -Destination t/ + } parallel: 10 artifacts: + paths: + - t/failed-test-artifacts reports: junit: build/meson-logs/testlog.junit.xml + when: on_failure test:fuzz-smoke-tests: image: ubuntu:latest diff --git a/.mailmap b/.mailmap index 7b3198171fad1e..c2e3939beb286d 100644 --- a/.mailmap +++ b/.mailmap @@ -107,6 +107,9 @@ Jason Riedy Jay Soffian Jean-Noël Avila Jean-Noel Avila Jean-Noël Avila Jean-Noël AVILA +Jean-Noël Avila Jean-Noel Avila +Jean-Noël Avila Jean-Noël AVILA +Jean-Noël Avila Jean-Noël Avila via GitGitGadget Jeff King Jeff Muizelaar Jens Axboe @@ -140,8 +143,8 @@ Junio C Hamano Kaartic Sivaraam Karl Wiberg Karl Hasselström Karl Wiberg -Karsten Blees -Karsten Blees +Karsten Blees +Karsten Blees Kay Sievers Kay Sievers Kazuki Saitoh kazuki saitoh @@ -221,11 +224,14 @@ Peter Krefting Peter Krefting Petr Baudis Petr Baudis -Phil Hord +Phil Hord +Phil Hord Philip Jägenstedt Philip Oakley # secondary Philipp A. Hartmann Philippe Bruhat +Phillip Wood +Phillip Wood Ralf Thielow Ramsay Jones Ramkumar Ramachandra @@ -277,6 +283,7 @@ Thomas Ackermann Thomas Rast Thomas Rast Thomas Rast +Tian Yuchen Timo Hirvonen Toby Allsopp Tom Grennan diff --git a/.tsan-suppressions b/.tsan-suppressions index 5ba86d68459e61..d84883bd90f9a6 100644 --- a/.tsan-suppressions +++ b/.tsan-suppressions @@ -7,7 +7,6 @@ # A static variable is written to racily, but we always write the same value, so # in practice it (hopefully!) doesn't matter. race:^want_color$ -race:^transfer_debug$ # A boolean value, which tells whether the replace_map has been initialized or # not, is read racily with an update. As this variable is written to only once, diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc index f814450d2f65ac..73bb939359c72e 100644 --- a/Documentation/BreakingChanges.adoc +++ b/Documentation/BreakingChanges.adoc @@ -190,7 +190,7 @@ 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. +2. In Git 2.55, 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. @@ -216,6 +216,30 @@ 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. +* The default value of `safe.bareRepository` will change from `all` to + `explicit`. It is all too easy for an attacker to trick a user into cloning a + repository that contains an embedded bare repository with malicious hooks + configured. If the user enters that subdirectory and runs any Git command, Git + discovers the bare repository and the hooks fire. The user does not even need + to run a Git command explicitly: many shell prompts run `git status` in the + background to display branch and dirty state information, and `git status` in + turn may invoke the fsmonitor hook if so configured, making the user + vulnerable the moment they `cd` into the directory. The `safe.bareRepository` + configuration variable was introduced in 8959555cee (setup_git_directory(): + add an owner check for the top-level directory, 2022-03-02) with a default of + `all` to preserve backwards compatibility. ++ +Changing the default to `explicit` means that Git will refuse to work with bare +repositories that are discovered implicitly by walking up the directory tree. +Bare repositories specified explicitly via the `--git-dir` command-line option +or the `GIT_DIR` environment variable continue to work regardless of this +setting. Repositories that look like a `.git` directory, a worktree, or a +submodule directory are also unaffected. ++ +Users who rely on implicit discovery of bare repositories can restore the +previous behavior by setting `safe.bareRepository=all` in their global or +system configuration. + === Removals * Support for grafting commits has long been superseded by git-replace(1). diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index df72fe01772a18..c06f5d3071968c 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -33,6 +33,16 @@ Git in general, a few rough rules are: achieve and why the changes were necessary (more on this in the accompanying SubmittingPatches document). + - A label "NEEDSWORK:" followed by a description of the things to + be done is a way to leave in-code comments to document design + decisions yet to be made. 80% of the work to resolve a NEEDSWORK + comment is to decide if it still makes sense to do so, since the + situation around the codebase may have changed since the comment + was written. It can be a very valid change to remove an existing + NEEDSWORK comment without doing anything else, with the commit log + message describing a good argument why it does not make sense to do + the thing the NEEDSWORK comment mentioned. + Make your code readable and sensible, and don't try to be clever. As for more concrete guidelines, just imitate the existing code @@ -430,6 +440,8 @@ For C programs: */ _("Here is a translatable string explained by the above."); + We do not use // comments. + - Double negation is often harder to understand than no negation at all. @@ -656,6 +668,37 @@ For C programs: unsigned other_field:1; unsigned field_with_longer_name:1; + - When a function `F` accepts flags, those flags should be defined as `enum + F_flags`. Individual flag definitions should start with `F` and be in + all-uppercase letters. Flag values should be represented via bit shifts. + E.g. + + enum frobnicate_flags { + FROBNICATE_FOO = (1 << 0), + FROBNICATE_BAR = (1 << 1), + }; + + int frobnicate(enum frobnicate_flags flags); + + - Array names should be named in the singular form if the individual items are + subject of use. E.g.: + + char *dog[] = ...; + walk_dog(dog[0]); + walk_dog(dog[1]); + + Cases where the array is employed as a whole rather than as its unit parts, + the plural form is preferable. E.g: + + char *dogs[] = ...; + walk_all_dogs(dogs); + + - For file timestamps, do not use "st_mtim" (and other timestamp + members in "struct stat") unconditionally; not everybody is POSIX + (grep for USE_ST_TIMESPEC). If you only need a timestamp in whole + second resolution, "st_mtime" should work fine everywhere. + + For Perl programs: - Most of the C guidelines above apply. diff --git a/Documentation/Makefile b/Documentation/Makefile index 47208269a2e124..2699f0b24af192 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -143,6 +143,7 @@ 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 diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index f186dfbc898fd4..b9fdefce0224c9 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -331,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so helpful. So what other context can we get? -Add a line to `#include "config.h"` and `#include "repository.h"`. +Add a line to `#include "config.h"`, `#include "repository.h"` and +`#include "environment.h"`. Then, add the following bits to the function body: function body: @@ -351,7 +352,7 @@ function body: apply standard precedence rules. `repo_config_get_string_tmp()` will look up a specific key ("user.name") and give you the value. There are a number of single-key lookup functions like this one; you can see them all (and more info -about how to use `repo_config()`) in `Documentation/technical/api-config.adoc`. +about how to use `repo_config()`) in `config.h`. You should see that the name printed matches the one you see when you run: @@ -429,6 +430,7 @@ Add the following includes: ---- #include "commit.h" #include "pretty.h" +#include "strbuf.h" ---- Then, add the following lines within your implementation of `cmd_psuh()` near @@ -503,8 +505,8 @@ git-psuh - Delight users' typo with a shy horse SYNOPSIS -------- -[verse] -'git-psuh [...]' +[synopsis] +git psuh [...] DESCRIPTION ----------- @@ -726,9 +728,10 @@ $ prove -j$(nproc) --shuffle t[0-9]*.sh ---- NOTE: You can also do this with `make test` or use any testing harness which can -speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the -tests are run in, which makes them resilient against unwanted inter-test -dependencies. `prove` also makes the output nicer. +speak TAP. `prove` can run concurrently. `-j$(nproc)` runs tests using all +available CPUs in parallel, but the job count can be adjusted as needed. +`shuffle` randomizes the order the tests are run in, which makes them resilient +against unwanted inter-test dependencies. `prove` also makes the output nicer. Go ahead and commit this change, as well. diff --git a/Documentation/RelNotes/2.53.0.adoc b/Documentation/RelNotes/2.53.0.adoc index c4dfeb1c23b406..2668c2e99639d7 100644 --- a/Documentation/RelNotes/2.53.0.adoc +++ b/Documentation/RelNotes/2.53.0.adoc @@ -20,6 +20,30 @@ UI, Workflows & Features * Add a new manual that describes the data model. + * "git fast-import" learns "--signed-commits=strip-if-invalid" option + to drop invalid cryptographic signature from objects. + + * The use of "revision" (a connected set of commits) has been + clarified in the "git replay" documentation. + + * A help message from "git branch" now mentions "git help" instead of + "man" when suggesting to read some documentation. + + * "git repo struct" learned to take "-z" as a synonym to "--format=nul". + + * More object database related information are shown in "git repo + structure" output. + + * Improve the error message when a bad argument is given to the + `--onto` option of "git replay". Test coverage of "git replay" has + been improved. + + * The iconv library on macOS fails to correctly handle stateful + ISO/IEC 2022:1994 encoded strings. Work it around instead of + replacing it wholesale from homebrew. + + * Upstream symbolic link support on Windows from Git-for-Windows. + Performance, Internal Implementation, Development Support etc. -------------------------------------------------------------- @@ -38,6 +62,68 @@ Performance, Internal Implementation, Development Support etc. * A part of code paths that deals with loose objects has been cleaned up. + * "make strip" has been taught to strip "scalar" as well as "git". + + * Dockerized jobs at the GitHub Actions CI have been taught to show + more details of failed tests. + + * Code refactoring around object database sources. + + * Halve the memory consumed by artificial filepairs created during + "git diff --find-copies-harder", also making the operation run + faster. + + * The "git_istream" abstraction has been revamped to make it easier + to interface with pluggable object database design. + + * Rewrite the only use of "mktemp()" that is subject to TOCTOU race + and Stop using the insecure "mktemp()" function. + (merge 10bba537c4 rs/ban-mktemp later to maint). + + * In-code comment update to clarify that single-letter options are + outside of the scope of command line completion script. + (merge dc8a00fafe jc/completion-no-single-letter-options later to maint). + + * MEMZERO_ARRAY() helper is introduced to avoid clearing only the + first N bytes of an N-element array whose elements are larger than + a byte. + + * "git diff-files -R --find-copies-harder" has been taught to use + the potential copy sources from the index correctly. + + * Require C99 style flexible array member support from all platforms. + + * The code path that enumerates promisor objects have been optimized + to skip pointlessly parsing blob objects. + + * Prepare test suite for Git for Windows that supports symbolic + links. + + * Import newer version of "clar", unit testing framework. + (merge 84071a6dea ps/clar-integers later to maint). + + * The packfile_store data structure is moved from object store to odb + source. + + * The object-info API has been cleaned up. + + * Further preparation to upstream symbolic link support on Windows. + + * Remove implicit reliance on the_repository global in the APIs + around tree objects and make it explicit which repository to work + in. + + * "git bugreport" and "git version --build-options" learned to + include use of 'gettext' feature, to make it easier to diagnose + problems around l10n. + + * Dscho observed that SVN tests are taking too much time in CI leak + checking tasks, but most time is spent not in our code but in libsvn + code (which happen to be written in Perl), whose leaks have little + value to discover for us. Skip SVN, P4, and CVS tests in the leak + checking tasks. + (merge 047bd7dfe3 js/ci-leak-skip-svn later to maint). + Fixes since v2.52 ----------------- @@ -52,7 +138,7 @@ Fixes since v2.52 (merge 42ed046866 jk/attr-macroexpand-wo-recursion later to maint). * Adding a repository that uses a different hash function is a no-no, - but "git submodule add" did nt prevent it, which has been corrected. + but "git submodule add" did not prevent it, which has been corrected. (merge 6fe288bfbc bc/submodule-force-same-hash later to maint). * An earlier check added to osx keychain credential helper to avoid @@ -73,7 +159,7 @@ Fixes since v2.52 * Test leakfix. (merge 14b561e768 jk/test-mktemp-leakfix later to maint). - * Update a version of action used at the GitHub Actrions CI. + * Update a version of action used at the GitHub Actions CI. (merge cd99203f86 js/ci-github-setup-go-update later to maint). * The "return errno = EFOO, -1" construct, which is heavily used in @@ -105,8 +191,146 @@ Fixes since v2.52 * Various issues detected by Asan have been corrected. (merge a031b6181a jk/asan-bonanza later to maint). + * "git config get --path" segfaulted on an ":(optional)path" that + does not exist, which has been corrected. + (merge 0bd16856ff jc/optional-path later to maint). + + * The "--committer-date-is-author-date" option of "git am/rebase" is + a misguided one. The documentation is updated to discourage its + use. + (merge fbf3d0669f kh/doc-committer-date-is-author-date later to maint). + + * The option help text given by "git config unset -h" described + the "--all" option to "replace", not "unset", multiple variables, + which has been corrected. + (merge 18bf67b753 rs/config-unset-opthelp-fix later to maint). + + * The error message given by "git config set", when the variable + being updated has more than one values defined, used old style "git + config" syntax with an incorrect option in its hint, both of which + have been corrected. + (merge df963f0df4 rs/config-set-multi-error-message-fix later to maint). + + * "git replay" forgot to omit the "gpgsig-sha256" extended header + from the resulting commit the same way it omits "gpgsig", which has + been corrected. + (merge 9f3a115087 pw/replay-exclude-gpgsig-fix later to maint). + + * A few tests have been updated to work under the shell compatible + mode of zsh. + (merge a92f243a94 bc/zsh-testsuite later to maint). + + * The way patience diff finds LCS has been optimized. + (merge c7e3b8085b yc/xdiff-patience-optim later to maint). + + * Recent optimization to "last-modified" command introduced use of + uninitialized block of memory, which has been corrected. + (merge fe4e60759b tc/last-modified-active-paths-optimization later to maint). + + * "git last-modified" used to mishandle "--" to mark the beginning of + pathspec, which has been corrected. + (merge 05491b90ce js/last-modified-with-sparse-checkouts later to maint). + + * Emulation code clean-up. + (merge 42aa7603aa gf/win32-pthread-cond-init later to maint). + + * "git submodule add" to add a submodule under segfaulted, + when a submodule..something is already in .gitmodules file + without defining where its submodule..path is, which has been + corrected. + (merge dd8e8c786e jc/submodule-add later to maint). + + * "git fetch" that involves fetching tags, when a tag being fetched + needs to overwrite existing one, failed to fetch other tags, which + has been corrected. + (merge b7b17ec8a6 kn/fix-fetch-backfill-tag-with-batched-ref-updates later to maint). + + * Document "rev-list --filter-provided-objects" better. + (merge 6d8dc99478 jt/doc-rev-list-filter-provided-objects later to maint). + + * Even when there is no changes in the packfile and no need to + recompute bitmaps, "git repack" recomputed and updated the MIDX + file, which has been corrected. + (merge 6ce9d558ce ps/repack-avoid-noop-midx-rewrite later to maint). + + * Update HTTP tests to adjust for changes in curl 8.18.0 + (merge 17f4b01da7 jk/test-curl-updates later to maint). + + * Workaround the "iconv" shipped as part of macOS, which is broken + handling stateful ISO/IEC 2022 encoded strings. + (merge cee341e9dd rs/macos-iconv-workaround later to maint). + + * Running "git diff" with "--name-only" and other options that allows + us not to look at the blob contents, while objects that are lazily + fetched from a promisor remote, caused use-after-free, which has + been corrected. + + * The ort merge machinery hit an assertion failure in a history with + criss-cross merges renamed a directory and a non-directory, which + has been corrected. + (merge 979ee83e8a en/ort-recursive-d-f-conflict-fix later to maint). + + * Diagnose invalid bundle-URI that lack the URI entry, instead of + crashing. + (merge 7796c14a1a sb/bundle-uri-without-uri later to maint). + + * Mailmap update for Karsten + (merge e97678c4ef js/mailmap-karsten-blees later to maint). + + * Perf-test fixes. + (merge 79d301c767 jk/t-perf-fixes later to maint). + + * Fix for a performance regression in "git cat-file". + (merge 9e8b448dd8 jk/cat-file-avoid-bitmap-when-unneeded later to maint). + + * Update a FAQ entry on synching two separate repositories using the + "git stash export/import" recently introduced. + (merge 02fc44a989 bc/doc-stash-import-export later to maint). + + * "git fsck" used inconsistent set of refs to show a confused + warning, which has been corrected. + + * Some error messages from the http transport layer lacked the + terminating newline, which has been corrected. + (merge a8227ae8d5 kt/http-backend-errors later to maint). + + * "git repack --geometric" did not work with promisor packs, which + has been corrected. + + * The logic that avoids reusing MIDX files with a wrong checksum was + broken, which has been corrected. + * Other code cleanup, docfix, build fix, etc. (merge 46207a54cc qj/doc-http-bad-want-response later to maint). (merge df90eccd93 kh/doc-commit-extra-references later to maint). (merge f18aa68861 rs/xmkstemp-simplify later to maint). (merge fddba8f737 ja/doc-synopsis-style later to maint). + (merge 22ce0cb639 en/xdiff-cleanup-2 later to maint). + (merge 8ef7355a8f je/doc-pull later to maint). + (merge 48176f953f jc/capability-leak later to maint). + (merge 8cbbdc92f7 kh/doc-pre-commit-fix later to maint). + (merge d4bc39a4d9 mh/doc-config-gui-gcwarning later to maint). + (merge 41d425008a kh/doc-send-email-paragraph-fix later to maint). + (merge d4b732899e jc/macports-darwinports later to maint). + (merge bab391761d kj/pull-options-decl-cleanup later to maint). + (merge 007b8994d4 rs/t4014-git-version-string-fix later to maint). + (merge 4ce170c522 ds/doc-scalar-config later to maint). + (merge a0c813951a jc/doc-commit-signoff-config later to maint). + (merge 8ee262985a ja/doc-misc-fixes later to maint). + (merge 1722c2244b mh/doc-core-attributesfile later to maint). + (merge c469ca26c5 dk/ci-rust-fix later to maint). + (merge 12f0be0857 gf/clear-path-cache-cleanup later to maint). + (merge 949df6ed6b js/test-func-comment-fix later to maint). + (merge 93f894c001 bc/checkout-error-message-fix later to maint). + (merge abf05d856f rs/show-branch-prio-queue later to maint). + (merge 06188ea5f3 rs/parse-config-expiry-simplify later to maint). + (merge 861dbb1586 dd/t5403-modernise later to maint). + (merge acffc5e9e5 ja/doc-synopsis-style-more later to maint). + (merge 6c5c7e7071 ac/t1420-use-more-direct-check later to maint). + (merge 2ac93bfcbc ds/builtin-doc-update later to maint). + (merge 3f051fc9c9 kh/doc-patch-id later to maint). + (merge 555c8464e5 je/doc-reset later to maint). + (merge 220f888d7e ps/t1410-cleanup later to maint). + (merge 5814b04c02 ps/config-doc-get-urlmatch-fix later to maint). + (merge 5ae594f30b sb/doc-update-ref-markup-fix later to maint). + (merge bc8556d066 ty/t1005-test-path-is-helpers later to maint). diff --git a/Documentation/RelNotes/2.54.0.adoc b/Documentation/RelNotes/2.54.0.adoc new file mode 100644 index 00000000000000..7bfc351c9a2dd6 --- /dev/null +++ b/Documentation/RelNotes/2.54.0.adoc @@ -0,0 +1,588 @@ +Git v2.54 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * "git add -p" and friends note what the current status of the hunk + being shown is. + + * "git history" history rewriting (experimental) command has been + added. + + * "git replay" is taught to drop commits that become empty (not the + ones that are empty in the original). + + * The help text and the documentation for the "--expire" option of + "git worktree [list|prune]" have been improved. + + * When "git show-index" is run outside a repository, it silently + defaults to SHA-1; the tool now warns when this happens. + + * "git merge-file" can be run outside a repository, but it ignored + all configuration, even the per-user ones. The command now uses + available configuration files to find its customization. + + * "auto filter" logic for large-object promisor remote. + + * "git rev-list" and friends learn "--maximal-only" to show only the + commits that are not reachable by other commits. + + * Command line completion (in contrib/) update for + "stash import/export". + + * "git repo info" learns "--keys" action to list known keys. + + * Extend the alias configuration syntax to allow aliases using + characters outside ASCII alphanumeric (plus '-'). + + * A signature on a commit that was GPG signed a long time ago ought to + be still valid after the key that was used to sign it has expired, + but we showed them in alarming red. + + * "git subtree split --prefix=P " now checks the prefix P + against the tree of the (potentially quite different from the + current working tree) given commit. + + * "git add -p" learned a new mode that allows the user to revisit a + file that was already dealt with. + + * Allow the directory in which reference backends store their data to + be specified. + + * "gitweb" has been taught to be mobile friendly. + + * "git apply --directory=./un/../normalized/path" now normalizes the + given path before using it. + + * "git maintenance" starts using the "geometric" strategy by default. + + * "git config list" is taught to show the values interpreted for + specific type with "--type=" option. + + * "git add " has been taught to honor + submodule..ignore that is set to "all" (and requires "git add + -f" to override it). + + * Hook commands are now allowed to be defined (possibly centrally) + in the configuration files, and run multiple of them for the same + hook event. + + * The way end-users can add their own "git " subcommand by + storing "git-" in a directory on their $PATH has not been + documented clearly, which has been corrected. + + * "git send-email" learns to pass hostname/port to Authen::SASL + module. + + * "git send-email" learns to support use of client-side certificates. + + * "git send-email" has learned to be a bit more careful when it + accepts charset to use from the end-user, to avoid 'y' (mistaken + 'yes' when expecting a charset like 'UTF-8') and other nonsense. + + * "git status" learned to show comparison between the current branch + and various other branches listed on status.compareBranches + configuration. + + * "git repo structure" command learns to report maximum values on + various aspects of objects it inspects. + + * "git rebase" learns "--trailer" option to drive the + interpret-trailers machinery. + + * "git fast-import" learned to optionally replace signature on + commits whose signatures get invalidated due to replaying by + signing afresh. + + * "git history" learned the "split" subcommand. + + * The reference-transaction hook was taught to be triggered before + taking locks on references in the "preparing" phase. + + * "git apply" now reports the name of the input file along with the + line number when it encounters a corrupt patch, and correctly + resets the line counter when processing multiple patch files. + + * The HTTP transport learned to react to "429 Too Many Requests". + + * "git repo info -h" and "git repo structure -h" limit their help output + to the part that is specific to the subcommand. + + * "git format-patch --cover-letter" learns to use a simpler format + instead of the traditional shortlog format to list its commits with + a new --commit-list-format option and format.commitListFormat + configuration variable. + + * `git backfill` learned to accept revision and pathspec arguments. + + * "git replay" (experimental) learns, in addition to "pick" and + "replay", a new operating mode "revert". + + * "git replay" now supports replaying down to the root commit. + + * Handling of signed commits and tags in fast-import has been made more + configurable. + + * "git config list" is the official way to spell "git config -l" and + "git config --list". Use it to update the documentation. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * Avoid local submodule repository directory paths overlapping with + each other by encoding submodule names before using them as path + components. + + * The string_list API gains a new helper, string_list_sort_u(), and + new unit tests to extend coverage. + + * Improve set-up time of a perf test. + + * ISO C23 redefines strchr and friends that traditionally took + a const pointer and returned a non-const pointer derived from it to + preserve constness (i.e., if you ask for a substring in a const + string, you get a const pointer to the substring). Update code + paths that used non-const pointer to receive their results that did + not have to be non-const to adjust. + + * Rename three functions around the commit_list data structure. + + * Transaction to create objects (or not) is currently tied to the + repository, but in the future a repository can have multiple object + sources, which may have different transaction mechanisms. Make the + odb transaction API per object source. + + * "git merge-ours" is taught to work better in a sparse checkout. + + * Allow recording process ID of the process that holds the lock next + to a lockfile for diagnosis. + + * Reduce dependency on the_repository of xdiff-interface layer. + + * Code clean-up to use the commit_stack API. + + * "git diff --anchored=" has been optimized. + + * A CodingGuidelines update. + + * Add process ancestry data to trace2 on macOS to match what we + already do on Linux and Windows. Also adjust the way Windows + implementation reports this information to match the other two. + + * A handful of places used refs_for_each_ref_in() API incorrectly, + which has been corrected. + + * Some tests assumed "iconv" is available without honoring ICONV + prerequisite, which has been corrected. + + * Revamp object enumeration API around odb. + + * Additional tests were introduced to see the interaction with netrc + auth with auth failure on the http transport. + + * A couple of bugs in use of flag bits around odb API has been + corrected, and the flag bits reordered. + + * Plumb gitk/git-gui build and install procedure in meson based + builds. + + * The code to accept shallow "git push" has been optimized. + + * Simplify build procedure for oxskeychain (in contrib/). + + * Fix dependency screw-up in meson-based builds. + + * Wean the mailmap code off of the_repository dependency. + + * API clean-up for the worktree subsystem. + + * The last uses of the_repository in "tree-diff.c" have been + eradicated. + + * Clean-up the code around "git repo info" command. + + * Mark the merge-ort codebase to prevent more uses of the_repository + from getting added. + + * The core.attributesfile is intended to be set per repository, but + was kept track of by a single global variable in-core, which has + been corrected by moving it to per-repository data structure. + + * Use the hook API to replace ad-hoc invocation of hook scripts via + the run_command() API. + + * Code refactoring around refs-for-each-* API functions. + + * The parse-options API learned to notice an options[] array with + duplicated long options. + (merge 237e520d81 rs/parse-options-duplicated-long-options later to maint). + + * The code to maintain mapping between object names in multiple hash + functions is being added, written in Rust. + + * A bit of OIDmap API enhancement and cleanup. + + * Move gitlab CI from macOS 14 images that are being deprecated. + + * The object source API is getting restructured to allow plugging new + backends. + + * Reduce dependence on the global the_hash_algo and the_repository + variables of wt-status code path. + + * The way combined list-object filter options are parsed has been + revamped. + + * Editorconfig filename patterns were specified incorrectly, making + many source files inside subdirectories unaffected, which has been + corrected. + + * The run_command() API lost its implicit dependency on the singleton + `the_repository` instance. + + * The unit test helper function was taught to use backslash + + mnemonic notation for certain control characters like "\t", instead + of octal notation like "\011". + + * Adjust test-lint to allow "sed -E" to use ERE in the patterns. + + * Clar (unit testing framework) update from the upstream. + + * Reduce system overhead "git upload-pack" spends on relaying "git + pack-objects" output to the "git fetch" running on the other end of + the connection. + + * Add a coccinelle rule to break the build when "struct strbuf" gets + passed by value. + + * Further work on incremental repacking using MIDX/bitmap + + * The logic to count objects has been cleaned up. + + * Tweak the build infrastructure by moving tools around. + + * Uses of prio_queue as a LIFO stack of commits have been written + with commit_stack. + + * The cleanup of remaining bitmaps in "ahead_behind()" has been + simplified. + + * split-index.c has been updated to not use the global the_repository + and the_hash_algo variables. + + * The unsigned integer that is used as a bitset to specify the kind + of branches interpret_branch_name() function has been changed to + use a dedicated enum type. + + * Various updates to contrib/diff-highlight, including documentation + updates, test improvements, and color configuration handling. + + * Code paths that loop over another array to push each element into a + strvec have been rewritten to use strvec_pushv() instead. + + * In case homebrew breaks REG_ENHANCED again, leave an in-code comment + to suggest use of our replacement regex as a workaround. + + * MinGW build updates. + + * The way dash 0.5.13 handles non-ASCII contents in here-doc + is buggy and breaks our existing tests, which unfortunately + have been rewritten to avoid triggering the bug. + + * Object name handling (disambiguation and abbreviation) has been + refactored to be backend-generic, moving logic into the respective + object database backends. + + * pack-objects's --stdin-packs=follow mode learns to handle + excluded-but-open packs. + + * A few code paths that spawned child processes for network + connection weren't wait(2)ing for their children and letting "init" + reap them instead; they have been tightened. + + * Adjust the codebase for C23 that changes functions like strchr() + that discarded constness when they return a pointer into a const + string to preserve constness. + + * A handful of inappropriate uses of the_repository have been + rewritten to use the right repository structure instance in the + read-cache.c codepath. + + * Internals of "git fsck" have been refactored to not depend on the + global `the_repository` variable. + + * Reduce dependency on `the_repository` in add-patch.c file. + + * The way the "git log -L:" feature is bolted onto the + log/diff machinery is being reworked a bit to make the feature + compatible with more diff options, like -S/G. + + * Further work to adjust the codebase for C23 that changes functions + like strchr() that discarded constness when they return a pointer into + a const string to preserve constness. + + * "git rev-list --maximal-only" has been optimized by borrowing the + logic used by "git show-branch --independent", which computes the + same kind of information much more efficiently. + + +Fixes since v2.53 +----------------- + + * HTTP transport failed to authenticate in some code paths, which has + been corrected. + (merge ed0f7a62f7 ap/http-probe-rpc-use-auth later to maint). + + * The computation of column width made by "git diff --stat" was + confused when pathnames contain non-ASCII characters. + (merge 04f5d95ef7 lp/diff-stat-utf8-display-width-fix later to maint). + + * The "-z" and "--max-depth" documentation (and implementation of + "-z") in the "git last-modified" command have been updated. + (merge 9dcc09bed1 tc/last-modified-options-cleanup later to maint). + + * A handful of code paths that started using batched ref update API + (after Git 2.51 or so) lost detailed error output, which have been + corrected. + (merge eff9299eac kn/ref-batch-output-error-reporting-fix later to maint). + + * "git blame --ignore-revs=... --color-lines" did not account for + ignored revisions passing blame to the same commit an adjacent line + gets blamed for. + (merge d519082d4e rs/blame-ignore-colors-fix later to maint). + + * Coccinelle rules update. + (merge 60614838a4 tc/memzero-array later to maint). + + * Giving "git last-modified" a tree (not a commit-ish) died an + uncontrolled death, which has been corrected. + (merge 525ef52301 tc/last-modified-not-a-tree later to maint). + + * Test contrib/ things in CI to catch breakages before they enter the + "next" branch. + (merge c591c3ceff jc/ci-test-contrib-too later to maint). + + * A handful of documentation pages have been modernized to use the + "synopsis" style. + (merge a34d1d53a6 ja/doc-synopsis-style-even-more later to maint). + + * Small clean-up of xdiff library to remove unnecessary data + duplication. + (merge 5086213bd2 pw/xdiff-cleanups later to maint). + + * Update sample commit-msg hook to complain when a log message has + material mailinfo considers the end of log message in the middle. + (merge 83804c361b pw/commit-msg-sample-hook later to maint). + + * "git pack-objects --stdin-packs" with "--exclude-promisor-objects" + fetched objects that are promised, which was not wanted. This has + been fixed. + (merge f4eff7116d ps/pack-concat-wo-backfill later to maint). + + * "git switch ", in an attempt to create a local branch + after a remote tracking branch of the same name gave an advice + message to disambiguate using "git checkout", which has been + updated to use "git switch". + (merge 12fee11f21 jc/checkout-switch-restore later to maint). + + * It does not make much sense to apply the "incomplete-line" + whitespace rule to symbolic links, whose contents almost always + lack the final newline. "git apply" and "git diff" are now taught + to exclude them for a change to symbolic links. + (merge 6a41481c6d jc/whitespace-incomplete-line later to maint). + + * "git format-patch --from=" did not honor the command line + option when writing out the cover letter, which has been corrected. + + * Update build procedure for mergetool documentation in meson-based builds. + (merge 58e4eeeeb5 pw/meson-doc-mergetool later to maint). + + * An earlier attempt to optimize "git subtree" discarded too much + relevant histories, which has been corrected. + + * A prefetch call can be triggered to access a stale diff_queue entry + after diffcore-break breaks a filepair into two and freed the + original entry that is no longer used, leading to a segfault, which + has been corrected. + (merge 2d88ab078d hy/diff-lazy-fetch-with-break-fix later to maint). + + * "git fetch --deepen" that tries to go beyond merged branch used to + get confused where the updated shallow points are, which has been + corrected. + (merge 3ef68ff40e sp/shallow-deepen-relative-fix later to maint). + + * "fsck" iterates over packfiles and its access to pack data caused + the list to be permuted, which caused it to loop forever; the code + to access pack data by "fsck" has been updated to avoid this. + (merge 13eb65d366 ps/fsck-stream-from-the-right-object-instance later to maint). + + * "git log --graph --stat" did not count the display width of colored + graph part of its own output correctly, which has been corrected. + (merge 064b869efc lp/diff-stat-utf8-display-width-fix later to maint). + + * The configuration variable format.noprefix did not behave as a + proper boolean variable, which has now been fixed and documented. + (merge ea3a62c40e kh/format-patch-noprefix-is-boolean later to maint). + + * CI fix. + (merge eb35167dd4 ps/ci-reduce-gitlab-envsize later to maint). + + * "git diff --no-index --find-object=" outside a + repository of course wouldn't be able to find the object and died + while parsing the command line. The command is made to die in a + bit more user-friendly way. + (merge b0ddc7947c mm/diff-no-index-find-object later to maint). + + * Fix typo-induced breakages in fsmonitor-watchman sample hook. + (merge 41366e4677 pt/fsmonitor-watchman-sample-fix later to maint). + + * "git for-each-repo" started from a secondary worktree did not work + as expected, which has been corrected. + (merge e87493b9b4 ds/for-each-repo-w-worktree later to maint). + + * The construct 'test "$(command)" = expectation' loses the exit + status from the command, which has been fixed by breaking up the + statement into pieces. + (merge d3edca979a fp/t3310-unhide-git-failures later to maint). + + * While discovering a ".git" directory, the code treats any stat() + failure as a sign that a filesystem entity .git does not exist + there, and ignores ".git" that is not a "gitdir" file or a + directory. The code has been tightened to notice and report + filesystem corruption better. + (merge 1dd27bfbfd ty/setup-error-tightening later to maint). + + * Plug a few leaks where mmap'ed memory regions are not unmapped. + (merge a8a69bbb64 jk/unleak-mmap later to maint). + + * A test now uses the symbolic constant $ZERO_OID instead of 40 "0" to + work better with SHA-256 as well as SHA-1. + (merge 30310f3cc4 ss/t3200-test-zero-oid later to maint). + + * Instead of hardcoded 'origin', use the configured default remote + when fetching from submodules. + (merge 3b5fb32da8 ng/submodule-default-remote later to maint). + + * The code in "git help" that shows configuration items in sorted + order was awkwardly organized and prone to bugs. + + * "imap-send" used to use functions whose use is going to be removed + with OpenSSL 4.0; rewrite them using public API that has been + available since OpenSSL 1.1 since 2016 or so. + (merge 6392a0b75d bb/imap-send-openssl-4.0-prep later to maint). + + * Fix an example in the user-manual. + (merge 5514f14617 gj/user-manual-fix-grep-example later to maint). + + * The final clean-up phase of the diff output could turn the result of + histogram diff algorithm suboptimal, which has been corrected. + (merge e417277ae9 yc/histogram-hunk-shift-fix later to maint). + + * "git diff -U" was too lenient in its command line parsing and + took an empty string as a valid . + (merge 4f6a803aba ty/doc-diff-u-wo-number later to maint). + + * The handling of the incomplete lines at the end by "git + diff-highlight" has been fixed. + + * merge-file --object-id used to trigger a BUG when run in a linked + worktree, which has been fixed. + (merge 57246b7c62 mr/merge-file-object-id-worktree-fix later to maint). + + * "git apply -p" parses more carefully now. + (merge d05d84c5f5 mf/apply-p-no-atoi later to maint). + + * A test to run a .bat file with whitespaces in the name with arguments + with whitespaces in them was flaky in that sometimes it got killed + before it produced expected side effects, which has been rewritten to + make it more robust. + (merge 3ad4921838 jk/t0061-bat-test-update later to maint). + + * "git ls-remote '+refs/tags/*:refs/tags/*' https://..." run outside a + repository would dereference a NULL while trying to see if the given + refspec is a single-object refspec, which has been corrected. + (merge 4e5dc601dd kj/refspec-parsing-outside-repository later to maint). + + * Fix a regression in writing the commit-graph where commits with dates + exceeding 34 bits (beyond year 2514) could cause an underflow and + crash Git during the generation data overflow chunk writing. + + * The value of a wrong pointer variable was referenced in an error + message that reported that it shouldn't be NULL. + (merge 753ecf4205 yc/path-walk-fix-error-reporting later to maint). + + * The check in "receive-pack" to prevent a checked out branch from + getting updated via updateInstead mechanism has been corrected. + + * "git backfill" is capable of auto-detecting a sparsely checked out + working tree, which was broken. + (merge 339eba65a7 th/backfill-auto-detect-sparseness-fix later to maint). + + * add_files_to_cache() used diff_files() to detect only the paths that + are different between the index and the working tree and add them, + which does not need rename detection, which interfered with unnecessary + conflicts. + (merge c0ce43376b ng/add-files-to-cache-wo-rename later to maint). + + * Doc mark-up update for entries in the glossary with bulleted lists. + (merge a65cbd87ea jk/doc-markup-sub-list-indentation later to maint). + + * CI dependency updates. + (merge 4bdb17e3a8 jc/ci-github-actions-use-checkout-v5 later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge d79fff4a11 jk/remote-tracking-ref-leakfix later to maint). + (merge 7a747f972d dd/t5403-modernise later to maint). + (merge 81021871ea sp/myfirstcontribution-include-update later to maint). + (merge 49223593fd ac/sparse-checkout-string-list-cleanup later to maint). + (merge a824421d36 sp/t5500-cleanup later to maint). + (merge df1c5d7ed7 kh/doc-shortlog-fix later to maint). + (merge 2d45507f15 am/doc-github-contributiong-link-to-submittingpatches later to maint). + (merge 68060b9262 hs/t9160-test-paths later to maint). + (merge 486386c687 cs/subtree-reftable-testfix later to maint). + (merge 0728012c53 jc/diff-highlight-main-master-testfix later to maint). + (merge 831989ef38 mc/doc-send-email-signed-off-by-cc later to maint). + (merge c44b3f3203 sd/doc-my1c-api-config-reference-fix later to maint). + (merge 6c21e53bad rs/version-wo-the-repository later to maint). + (merge 10c68d2577 rs/clean-includes later to maint). + (merge 168d575719 bk/t2003-modernise later to maint). + (merge 6bfef81c9a kh/doc-rerere-options-xref later to maint). + (merge aaf3cc3d8d sd/t7003-test-path-is-helpers later to maint). + (merge 2668b6bdc4 jc/doc-rerere-update later to maint). + (merge 2f99f50f2d jc/doc-cg-c-comment later to maint). + (merge a454cdca42 kh/doc-am-format-sendmail later to maint). + (merge 8b0061b5c5 jk/ref-filter-lrstrip-optim later to maint). + (merge 5133837392 ps/ci-gitlab-msvc-updates later to maint). + (merge 143e84958c db/doc-fetch-jobs-auto later to maint). + (merge 0678e01f02 ap/use-test-seq-f-more later to maint). + (merge 96286f14b0 ty/symlinks-use-unsigned-for-bitset later to maint). + (merge b10e0cb1f3 kh/doc-am-xref later to maint). + (merge ed84bc1c0d kh/doc-patch-id-4 later to maint). + (merge 7451864bfa sc/pack-redundant-leakfix later to maint). + (merge f87593ab1a cx/fetch-display-ubfix later to maint). + (merge a66c8c7f91 jk/repo-structure-cleanup later to maint). + (merge 5ee8782f87 ss/test-that-that-typofix later to maint). + (merge f31b322008 fp/t3310-test-path-is-helpers later to maint). + (merge b22ed4c4f9 kj/path-micro-code-cleanup later to maint). + (merge a56fa1ca05 lp/doc-gitprotocol-pack-fixes later to maint). + (merge 0d6bb8b541 ss/t3700-modernize later to maint). + (merge 63c00a677b ss/t9123-setup-inside-test-expect-success later to maint). + (merge beca0ca4be os/doc-git-custom-commands later to maint). + (merge 4c223571be ty/patch-ids-document-lazy-eval later to maint). + (merge 476365ac85 jc/doc-wholesale-replace-before-next later to maint). + (merge 35f220b639 ss/submodule--helper-use-xmalloc later to maint). + (merge 02cbae61df cf/constness-fixes later to maint). + (merge 69efd53c81 ms/t7605-test-path-is-helpers later to maint). + (merge d39cef3a1a ss/t0410-delete-object-cleanup later to maint). + (merge 2f05039717 rj/pack-refs-tests-path-is-helpers later to maint). + (merge 2594747ad1 jk/transport-color-leakfix later to maint). + (merge 48430e44ac mf/t0008-cleanup later to maint). + (merge fc8a4f15e7 gi/doc-boolean-config-typofix later to maint). + (merge 37182267a0 kh/doc-interpret-trailers-1 later to maint). + (merge f64c50e768 jc/rerere-modern-strbuf-handling later to maint). + (merge 699248d89e th/t8003-unhide-git-failures later to maint). + (merge d8e34f971b za/t2000-modernise later to maint). + (merge 849988bc74 th/t6101-unhide-git-failures later to maint). + (merge 0f0ce07625 sp/doc-gitignore-oowt later to maint). diff --git a/Documentation/RelNotes/2.54.1.adoc b/Documentation/RelNotes/2.54.1.adoc new file mode 100644 index 00000000000000..f561dbba54d029 --- /dev/null +++ b/Documentation/RelNotes/2.54.1.adoc @@ -0,0 +1,29 @@ +Git v2.54.1 Release Notes +========================= + +This release is primarily to merge fixes accumulated on the 'master' +front to prepare for 2.55 release that are still relevant to 2.54.x +maintenance track. + +Fixes since v2.54 +----------------- + + * Headers from glibc 2.43 when used with clang does not allow + disabling C11 language features, causing build failures.. + + * Revert a recent change that introduced a regression to help mksh users. + + * Update various GitHub Actions versions. + + * Avoid hitting the pathname limit for socks proxy socket during the + test. + + * To help Windows 10 installations, avoid removing files whose + contents are still mmap()'ed. + + * Stop using unmaintained custom allocator in Windows build which was + the last user of the code. + + * Further update to the i18n alias support to avoid regressions. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.55.0.adoc b/Documentation/RelNotes/2.55.0.adoc new file mode 100644 index 00000000000000..8543cad65e491f --- /dev/null +++ b/Documentation/RelNotes/2.55.0.adoc @@ -0,0 +1,458 @@ +Git v2.55 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * Hook scripts defined via the configuration system can now be + configured to run in parallel. + + * The userdiff driver for the Scheme language has been extended to + cover other Lisp dialects. + + * Terminal control sequences coming over the sideband while talking + to a remote repository are mostly disabled by default, except for + ANSI color escape sequences. + + * "ort" merge backend improvements. + + * "git checkout -m another-branch" was invented to deal with local + changes to paths that are different between the current and the new + branch, but it gave only one chance to resolve conflicts. The command + was taught to create a stash to save the local changes. + + * A new builtin "git format-rev" is introduced for pretty formatting + one revision expression per line or commit object names found in + running text. + + * "git history" learned "fixup" command. + + * The internal URL parsing logic has been made accessible via a new + subcommand "git url-parse". + + * Misspelt proxy URL (e.g., httt://...) did not trigger any warning + or failure, which has been corrected. + + * Document the fact that .git/info/exclude is shared across worktrees + linked to the same repository. + + * The command line parser for "git diff" learned a few options take + only non-negative integers. + + * The graph output from commands like "git log --graph" can now be + limited to a specified number of lanes, preventing overly wide output + in repositories with many branches. + + * The fsmonitor daemon has been implemented for Linux. + + * "git cat-file --batch" learns an in-line command "mailmap" + that lets the user toggle use of mailmap. + + * The "git pack-objects --path-walk" traversal has been integrated + with several object filters, including blobless and sparse filters. + + * "git push" learned to take a "remote group" name to push to, which + causes pushes to multiple places, just like "git fetch" would do. + + * The 'git-jump' command (in contrib/) has been taught to automatically + pick a mode (merge, diff, or ws) when invoked without arguments. + + * The documentation for `push.default = simple` has been clarified to + better explain its behavior, making it clear that it pushes the + current branch to a same-named branch on the remote, and detailing + the upstream requirements for centralized workflows. + + * The documentation for "--word-diff" has been extended with a bit of + implementation detail of where these different words come from. + + * "git config foo.bar=baz" is not likely to be a request to read the + value of such a variable with '=' in its name; rather it is plausible + that the user meant "git config set foo.bar baz". Give advice when + giving an error message. + + * "git rev-list" (and "git log" family of commands) learned a new "--max-count-oldest" + that picks oldest N commits in the range instead of the usual newest. + + * Various AsciiDoc markup fixes in 'git config' documentation and + related files to ensure lists and formatting are rendered correctly. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * Promisor remote handling has been refactored and fixed in + preparation for auto-configuration of advertised remotes. + + * Rust support is enabled by default (but still allows opting out) in + some future version of Git. + + * Preparation of the xdiff/ codebase to work with Rust. + + * Use a larger buffer size in the code paths to ingest pack stream. + + * Refactor service routines in the ref subsystem backends. + + * Shrink wasted memory in Myers diff that does not account for common + prefix and suffix removal. + + * Enable expensive tests to catch topics that may cause breakages on + integration branches closer to their origin in the contributor PR + builds. + + * "git merge-base" optimization. + + * The limit_list() function that is one of the core part of the + revision traversal infrastructure has been optimized by replacing + its use of linear list with priority queue. + + * In a lazy clone, "git cherry" and "git grep" often fetch necessary + blob objects one by one from promisor remotes. It has been corrected + to collect necessary object names and fetch them in bulk to gain + reasonable performance. + + * The logic to determine that branches in an octopus merge are + independent has been optimized. + + * The consistency checks for the files reference backend have been updated + to skip lock files earlier, avoiding unnecessary parsing of + intermediate files. + + * The negotiation tip options in "git fetch" have been reworked to + allow requiring certain refs to be sent as "have" lines, and to + restrict negotiation to a specific set of refs. + + * The repacking code has been refactored and compaction of MIDX layers + have been implemented, and incremental strategy that does not require + all-into-one repacking has been introduced. + + * ODB transaction interface is being reworked to explicitly handle + object writes. + + * Add a new odb "in-memory" source that is meant to only hold + tentative objects (like the virtual blob object that represents the + working tree file used by "git blame"). + + * Many uses of the_repository has been updated to use a more + appropriate struct repository instance in setup.c codepath. + + * Revision traversal optimization. + + * Build update. + + * The logic to lazy-load trees from the commit-graph has been made + more robust by falling back to reading the commit object when + the commit-graph is no longer available. + + * The "name" argument in git_connect() and related functions has been + converted to a "service" enum to improve type safety and clarify its + purpose. + + * 'git restore --staged' has been optimized to avoid unnecessarily expanding + the sparse index when operating on paths within the sparse checkout + definition, by handling sparse directory entries at the tree level. + + * "git stash -p" has been optimized by reusing cached index + entries in its temporary index, avoiding unnecessary lstat() + calls on unchanged files. + + * The check for non-stale commits in the priority queue used by + `paint_down_to_common` and `ahead_behind` has been optimized by + replacing an O(N) scan with an O(1) counter, yielding performance + improvements in repositories with wide histories. + + * Reachability bitmap generation has been significantly optimized. By + reordering tree traversal, caching object positions, and refining how + pseudo-merge bitmaps are constructed, the performance of "git repack + --write-midx-bitmaps" is improved, especially for large repositories + and when using pseudo-merges. + + * Adding a decimal integer with strbuf_addf("%u") appears commonly; + they have been optimized by using a custom formatter. + + * Formatting object name in full hexadecimal form has been optimized + by using a new strbuf_add_oid_hex() helper function. + + * Encourage original authors to monitor the CI status. + + * The `git log -L` implementation has been refactored to use the + standard diff output pipeline, enabling pickaxe and diff-filter to + work as expected. Additionally, metadata-only diff formats like + --raw and --name-only are now supported with -L. + + * The loose object source has been refactored into a proper `struct + odb_source`. + + * Guidelines on how to write a cover letter for a multi-patch series + have been added to SubmittingPatches, which also got a new marker + to separate the section for typofixes. + + * The setup logic to discover and configure repositories has been + refactored, and the initialization of the object database has been + centralized. + + * Many core configuration variables have been migrated from global + variables into 'repo_config_values' to tie them to a specific + repository instance, avoiding cross-repository state leakage. + + * Streaming revision walks have been optimized by using a priority queue + for date-sorting commits, speeding up walks repositories with many + merges. + + * A recent regression in t7527 that broke TAP output has been fixed, + some other test noise that also broke TAP output has been silenced, + and 'prove' is now configured to fail on invalid TAP output to + prevent future regressions. + + * A handful of inappropriate uses of the_repository have been + rewritten to use the right repository structure instance in the + unpack-trees.c codepath. + + * "git index-pack" has been optimized by retaining child bases in the + delta cache instead of immediately freeing them, letting the existing + cache limit policy decide eviction. + + * `git ls-files --modified` and `git ls-files --deleted` have been + optimized to filter with pathspec before calling lstat() when there is + only a single pathspec item, avoiding unnecessary filesystem access + for entries that will not be shown. + + * The UNUSED macro in 'compat/posix.h' has been updated to use a + newly introduced GIT_CLANG_PREREQ macro for compiler version + checks, and the existing GIT_GNUC_PREREQ macro has been modernized + to use explicit major/minor comparisons rather than bit-shifting. + + * Wean the Windows builds in GitLab CI procedure away from + (unfortunately unreliable) Chocolatey to install dependencies. + (merge 0e7b51fed2 ps/gitlab-ci-windows later to maint). + + * Build-fix for 32-bit Windows. + + * Xcode 15 and later has a linker set to complain when the same library + archive is listed twice on the command line. Squelch the annoyance. + + +Fixes since v2.54 +----------------- + + * Code clean-up to use the right instance of a repository instance in + calls inside refs subsystem. + (merge 57c590feb9 sp/refs-reduce-the-repository later to maint). + + * The check that implements the logic to see if an in-core cache-tree + is fully ready to write out a tree object was broken, which has + been corrected. + (merge 521731213c dl/cache-tree-fully-valid-fix later to maint). + + * The test suite harness and many individual test scripts have been + updated to work correctly when 'set -e' is in effect, which helps + detect misspelled test commands. + (merge ffe8005b9d ps/test-set-e-clean later to maint). + + * Revert a recent change that introduced a regression to help mksh users. + + * Update various GitHub Actions versions. + + * Avoid hitting the pathname limit for socks proxy socket during the + test.. + + * To help Windows 10 installations, avoid removing files whose + contents are still mmap()'ed. + + * The 'git backfill' command now rejects revision-limiting options that + are incompatible with its operation, uses standard documentation for + revision ranges, and includes blobs from boundary commits by default + to improve performance of subsequent operations. + (merge a1ad4a0fca en/backfill-fixes-and-edges later to maint). + + * "git grep" update. + (merge 9ff4b5ab1b rs/grep-column-only-match-fix later to maint). + + * Headers from glibc 2.43 when used with clang does not allow + disabling C11 language features, causing build failures.. + + * The 'http.emptyAuth=auto' configuration now correctly attempts + Negotiate authentication before falling back to manual credentials. + This allows seamless Kerberos ticket-based authentication without + requiring users to explicitly set 'http.emptyAuth=true'. + (merge 4919938d28 mc/http-emptyauth-negotiate-fix later to maint). + + * Ramifications of turning off commit-graph has been documented a bit + more clearly. + (merge 48c855bb8f kh/doc-commit-graph later to maint). + + * "git rebase --update-refs", when used with an rebase.instructionFormat + with "%d" (describe) in it, tried to update local branch HEAD by + mistake, which has been corrected. + (merge 106b6885c7 ag/rebase-update-refs-limit-to-branches later to maint). + + * Tweak the way how sideband messages from remote are printed while + we talk with a remote repository to avoid tickling terminal + emulator glitches. + (merge 31e8fcabd8 rs/sideband-clear-line-before-print later to maint). + + * The configuration variable submodule.fetchJobs was not read correctly, + which has been corrected. + (merge aa45a5902f sj/submodule-update-clone-config-fix later to maint). + + * Update code paths that assumed "unsigned long" was long enough for + "size_t". + (merge 7a094d68a2 js/objects-larger-than-4gb-on-windows later to maint). + + * Stop using unmaintained custom allocator in Windows build which was + the last user of the code. + + * The computation to shorten the filenames shown in diffstat measured + width of individual UTF-8 characters to add up, but forgot to take + into account error cases (e.g., an invalid UTF-8 sequence, or a + control character). + (merge 09d86a3b98 en/diffstat-utf8-truncation-fix later to maint). + + * Some tests assume that bare repository accesses are by default + allowed; rewrite some of them to avoid the assumption, rewrite + others to explicitly set safe.bareRepository to allow them. + (merge 985b38ca6c js/adjust-tests-to-explicitly-access-bare-repo later to maint). + + * Signing commit with custom encoding was passing the data to be + signed at a wrong stage in the pipeline, which has been corrected. + (merge 7735d7eee3 bc/sign-commit-with-custom-encoding later to maint). + + * Further update to the i18n alias support to avoid regressions. + + * "git fetch --deepen=" in a full clone truncated the history to + commits deep, which has been corrected to be a no-op instead. + (merge 2431f5e0e5 sp/shallow-deepen-on-non-shallow-repo-fix later to maint). + + * "git maintenance" that goes background did not use the lockfile to + prevent multiple maintenance processes from running at the same + time, which has been corrected. + (merge 29364f1624 ps/maintenance-daemonize-lockfix later to maint). + + * Remove ineffective strbuf presizing that would have computed an + allocation that would not have fit in the available memory anyway, + or too small due to integer wraparound to cause immediate automatic + growing. + (merge a9ce8526dc jk/pretty-no-strbuf-presizing later to maint). + + * The HTTP walker misinterpreted the alternates file that gives an + absolute path when the server URL does not have the final slash + (i.e., "https://example.com" not "https://example.com/"). + (merge b92387cd55 jk/dumb-http-alternate-fix later to maint). + + * "git bisect" now uses the selected terms (e.g., old/new) more + consistently in its output. + (merge cb55991825 jr/bisect-custom-terms-in-output later to maint). + + * Update GitLab CI jobs that exercise macOS. + (merge 62319b49bb ps/gitlab-ci-macOS-improvements later to maint). + + * "Friday noon" asked in the morning on Sunday was parsed to be one + day before the specified time, which has been corrected. + (merge b809304101 ta/approxidate-noon-fix later to maint). + + * The GIT_WORK_TREE variable prepared to invoke the push-to-checkout + hook was leaking into the environment even when there was no hook + used and broke the default push-to-deploy (i.e., let "git checkout" + update the working tree only when the working tree is clean). + (merge 44d04e4426 ar/receive-pack-worktree-env later to maint). + + * A batch of documentation pages has been updated to use the modern + synopsis style. + (merge 2ef248ae45 ja/doc-synopsis-style-again later to maint). + + * The "promisor.quiet" configuration variable was not used from + relevant submodules when commands like "grep --recurse-submodules" + triggered a lazy fetch, which has been corrected. + (merge fa1468a1f7 th/promisor-quiet-per-repo later to maint). + + * Correct use of sockaddr API in "git daemon". + (merge 422a5bf575 st/daemon-sockaddr-fixes later to maint). + + * A memory leak in `fetch_and_setup_pack_index()` when verification of + the downloaded pack index fails has been plugged. Also an obsolete + `unlink()` call on parse failure has been cleaned up. + + * In t3070-wildmatch, "via ls-files" test variants with patterns + containing backslash escapes are now skipped on Windows, avoiding 36 + test failures caused by pathspec separator conversion. + (merge 8c84e6802c kk/wildmatch-windows-ls-files-prereq later to maint). + + * A linker warning on macOS when building with Xcode 16.3 or newer has + been avoided by passing -fno-common to the compiler when a + sufficiently new linker is detected. + (merge 5cd4d0d850 hn/macos-linker-warning later to maint). + + * Documentation and tests have been added to clarify that Git's internal + raw timestamp format requires a `@` prefix for values less than + 100,000,000 to prevent ambiguity with other formats like YYYYMMDD. + (merge 4018dc29ee ls/doc-raw-timestamp-prefix later to maint). + + * Wording used in "format-patch --subject-prefix" documentation + has been improved. + (merge 4a1eb9304a lo/doc-format-patch-subject-prefix later to maint). + + * Advanced emulation of kill() used on Windows in GfW has been + upstreamed to improve the symptoms like left-behind .lock files and + that fails to let the child clean-up itself when it gets killed. + (merge 363f1d8b3a js/win-kill-child-more-gently later to maint). + + * The 'git describe --contains --all' command has been fixed to + properly honor the '--match' and '--exclude' options by passing + them down to 'git name-rev' with the appropriate reference + prefixes. + (merge 1891707d1b jk/describe-contains-all-match-fix later to maint). + + * Various typos, grammatical errors, and duplicated words in both + documentation and code comments have been corrected. + (merge dc6068df67 wy/docs-typofixes later to maint). + + * The subprocess handshake during startup has been made gentler by using + packet_read_line_gently() instead of packet_read_line() to prevent the + parent Git process from dying abruptly when a configured subprocess + (e.g., a clean/smudge filter) fails to start. + (merge 061a68e443 mm/subprocess-handshake-fix later to maint). + + * The TSAN race in transfer_debug() within transport-helper.c has been + resolved by initializing the debug flag early in + bidirectional_transfer_loop() before spawning worker threads, allowing + the removal of a TSAN suppression. + (merge 85704eda18 ps/transport-helper-tsan-fix later to maint). + + * 'git describe' has been taught to pass the 'refs/tags/' prefix down to + the ref iterator when '--all' is not requested, avoiding unnecessary + iteration over non-tag refs. + (merge 55088ac8a4 td/describe-tag-iteration later to maint). + + * compute_reachable_generation_numbers() in commit-graph used a 32-bit + integer to accumulate parent generations, which is OK for generation + number v1 (topological levels), but with generation number v2 + (adjusted committer timestamps), it truncated timestamps beyond + 2106. Fixed by widening the accumulator to timestamp_t. + (merge fbcc5408fc en/commit-graph-timestamp-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 80f4b802e9 ja/doc-difftool-synopsis-style later to maint). + (merge b96490241e jc/doc-timestamps-in-stat later to maint). + (merge ef85286e51 ss/t7004-unhide-git-failures later to maint). + (merge 7584d10bc2 mf/format-patch-cover-letter-format-docfix later to maint). + (merge 8547908eb3 pw/rename-to-get-current-worktree later to maint). + (merge 890229b3f3 sg/t6112-unwanted-tilde-expansion-fix later to maint). + (merge ab9753e7bc kh/doc-restore-double-underscores-fix later to maint). + (merge 4a9e097228 za/t2000-modernise-more later to maint). + (merge b635fd0725 kh/doc-log-decorate-list later to maint). + (merge 65ea197dca jk/commit-sign-overflow-fix later to maint). + (merge 3ccb16052a jk/apply-leakfix later to maint). + (merge 5e6e8dc786 tb/pseudo-merge-bugfixes later to maint). + (merge 6d09e798bc pb/doc-diff-format-updates later to maint). + (merge 34a891a2d3 rs/trailer-fold-optim later to maint). + (merge 499f9048e0 ps/t3903-cover-stash-include-untracked later to maint). + (merge b56ab270aa jk/sq-dequote-cleanup later to maint). + (merge 29d9fdcf10 rs/use-builtin-add-overflow-explicitly-on-clang later to maint). + (merge d9982e8290 ed/check-connected-close-err-fd-2.53 later to maint). + (merge 1740cc35d0 ed/check-connected-close-err-fd later to maint). + (merge f4d7eb3d1c sp/doc-range-diff-takes-notes later to maint). + (merge 83e7f3bd2b kh/free-commit-list later to maint). + (merge d1b72b29e9 am/doc-tech-hash-typofix later to maint). + (merge 014c454799 ak/typofixes later to maint). + (merge 522ea8ef7d js/osxkeychain-build-wo-rust later to maint). + (merge e8f12e0e95 jc/t1400-fifo-cleanup later to maint). + (merge 0bf506efd4 kw/gitattributes-typofix later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index e270ccbe85b087..f042bb5aaf4a45 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -37,11 +37,36 @@ most likely to be knowledgeable enough to help you, but they have no obligation to help you (i.e. you ask them for help, you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would help you find out who they are. ++ +It is also a good idea to check whether your topic has been discussed +previously on the mailing list, or whether similar work is already in +progress. Prior discussions may contain useful context, design +considerations, or earlier attempts at solving the same problem. Being +aware of such discussions can help you avoid duplicating work and may +allow you to coordinate with other contributors working in the same +area. . You get comments and suggestions for improvements. You may even get them in an "on top of your change" patch form. You are expected to respond to them with "Reply-All" on the mailing list, while taking them into account while preparing an updated set of patches. ++ +It is often beneficial to allow some time for reviewers to provide +feedback before sending a new version, rather than sending an updated +series immediately after receiving a review. This helps collect broader +input and avoids unnecessary churn from many rapid iterations. + +. These early update iterations are expected to be full replacements, + not incremental updates on top of what you posted already. If you + are correcting mistakes you made in the previous iteration that a + reviewer noticed and pointed out in their review, you _fix_ that + mistake by rewriting your history (e.g., by using "git rebase -i") + to pretend that you never made the mistake in the first place. In + other words, this is a chance to pretend to be a perfect developer, + and you are expected to take advantage of that. In the larger + picture, nobody is interested in your earlier mistakes. Just + present a logical progression made by a perfect developer who makes + no mistakes while working on the topic. . Polish, refine, and re-send your patches to the list and to the people who spent their time to improve your patch. Go back to step (2). @@ -67,7 +92,7 @@ help you find out who they are. topic are appropriate, so such an incremental updates are limited to small corrections and polishing. After a topic cooks for some time (like 7 calendar days) in 'next' without needing further tweaks on - top, it gets merged to the 'master' branch and wait to become part + top, it gets merged to the 'master' branch and waits to become part of the next major release. In the following sections, many techniques and conventions are listed @@ -212,6 +237,7 @@ Do not forget to update the documentation to describe the updated behavior and make sure that the resulting documentation set formats well (try the Documentation/doc-diff script). +[[typofixes]] We currently have a liberal mixture of US and UK English norms for spelling and grammar, which is somewhat unfortunate. A huge patch that touches the files all over the place only to correct the inconsistency @@ -446,6 +472,30 @@ highlighted above. Only capitalize the very first letter of the trailer, i.e. favor "Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". +[[cover-letter]] +=== Cover Letter + +The purpose of your cover letter is to sell your changes, explain what +they are about, and get your target audience interested enough to read +the patches. + +. Every code change comes with risk of regression and maintenance cost. + The cover letter should clearly communicate why the value of your + proposed change is worth applying. You can also describe how the risk + is reduced by the design choices you made while writing the patches. + +. Make sure your target audience can understand what the patches are + about and why they are needed without prior context. + +. For a second or subsequent iteration of the same topic, make sure + people who missed the earlier discussion can still understand what + the patches are about, so they can judge if the topic is worth their + time to read and comment on. + +. To help those who are familiar with earlier iterations, give a + summary of changes since the previous rounds. + + [[ai]] === Use of Artificial Intelligence (AI) @@ -792,6 +842,17 @@ relevant for debugging. Then fix the problem and push your fix to your GitHub fork. This will trigger a new CI build to ensure all tests pass. +Even if you do not use GitHub CI to test your changes, pay close +attention to new failures on the branches when the maintainer pushes +out after your topic gets merged to the 'seen' branch to make sure +that your topic is not breaking the CI, and retract your breaking +topic quickly while you fix the breakage you caused. + +To see maintainer's push, keep an eye on this page: + + `https://github.com/git/git/actions/workflows/main.yml?query=event%3Apush+actor%3Agitster` + + [[mua]] == MUA specific hints diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in index ff9ea0a2944511..93c63b284a9669 100644 --- a/Documentation/asciidoc.conf.in +++ b/Documentation/asciidoc.conf.in @@ -81,12 +81,24 @@ endif::backend-xhtml11[] ifdef::backend-docbook[] ifdef::doctype-manpage[] +[blockdef-open] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + +[blockdef-listing] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + [paradef-default] synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::doctype-manpage[] endif::backend-docbook[] ifdef::backend-xhtml11[] +[blockdef-open] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + +[blockdef-listing] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + [paradef-default] synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::backend-xhtml11[] diff --git a/Documentation/blame-options.adoc b/Documentation/blame-options.adoc index 1fb948fc76f3ab..1ae1222b6b5ffa 100644 --- a/Documentation/blame-options.adoc +++ b/Documentation/blame-options.adoc @@ -1,105 +1,105 @@ --b:: +`-b`:: Show blank SHA-1 for boundary commits. This can also be controlled via the `blame.blankBoundary` config option. ---root:: +`--root`:: Do not treat root commits as boundaries. This can also be controlled via the `blame.showRoot` config option. ---show-stats:: +`--show-stats`:: Include additional statistics at the end of blame output. --L ,:: --L ::: - Annotate only the line range given by ',', - or by the function name regex ''. +`-L ,`:: +`-L :`:: + Annotate only the line range given by `,`, + or by the function name regex __. May be specified multiple times. Overlapping ranges are allowed. + -'' and '' are optional. `-L ` or `-L ,` spans from -'' to end of file. `-L ,` spans from start of file to ''. +__ and __ are optional. `-L ` or `-L ,` spans from +__ to end of file. `-L ,` spans from start of file to __. + include::line-range-format.adoc[] --l:: +`-l`:: Show long rev (Default: off). --t:: +`-t`:: Show raw timestamp (Default: off). --S :: - Use revisions from revs-file instead of calling linkgit:git-rev-list[1]. +`-S `:: + Use revisions from __ instead of calling + linkgit:git-rev-list[1]. ---reverse ..:: +`--reverse ..`:: Walk history forward instead of backward. Instead of showing the revision in which a line appeared, this shows the last revision in which a line has existed. This requires a range of - revision like START..END where the path to blame exists in - START. `git blame --reverse START` is taken as `git blame - --reverse START..HEAD` for convenience. + revision like `..` where the path to blame exists in + __. `git blame --reverse ` is taken as `git blame + --reverse ..HEAD` for convenience. ---first-parent:: +`--first-parent`:: Follow only the first parent commit upon seeing a merge commit. This option can be used to determine when a line was introduced to a particular integration branch, rather than when it was introduced to the history overall. --p:: ---porcelain:: +`-p`:: +`--porcelain`:: Show in a format designed for machine consumption. ---line-porcelain:: +`--line-porcelain`:: Show the porcelain format, but output commit information for each line, not just the first time a commit is referenced. - Implies --porcelain. + Implies `--porcelain`. ---incremental:: +`--incremental`:: Show the result incrementally in a format designed for machine consumption. ---encoding=:: - Specifies the encoding used to output author names +`--encoding=`:: + Specify the encoding used to output author names and commit summaries. Setting it to `none` makes blame output unconverted data. For more information see the discussion about encoding in the linkgit:git-log[1] manual page. ---contents :: - Annotate using the contents from the named file, starting from - if it is specified, and HEAD otherwise. You may specify '-' to make +`--contents `:: + Annotate using the contents from __, starting from __ + if it is specified, and `HEAD` otherwise. You may specify `-` to make the command read from the standard input for the file contents. ---date :: - Specifies the format used to output dates. If --date is not - provided, the value of the blame.date config variable is - used. If the blame.date config variable is also not set, the +`--date `:: + Specify the format used to output dates. If `--date` is not + provided, the value of the `blame.date` config variable is + used. If the `blame.date` config variable is also not set, the iso format is used. For supported values, see the discussion - of the --date option at linkgit:git-log[1]. + of the `--date` option at linkgit:git-log[1]. ---progress:: ---no-progress:: - Progress status is reported on the standard error stream - by default when it is attached to a terminal. This flag - enables progress reporting even if not attached to a - terminal. Can't use `--progress` together with `--porcelain` - or `--incremental`. +`--progress`:: +`--no-progress`:: + Enable progress reporting on the standard error stream even if + not attached to a terminal. By default, progress status is + reported only when it is attached. You can't use `--progress` + together with `--porcelain` or `--incremental`. --M[]:: +`-M[]`:: Detect moved or copied lines within a file. When a commit moves or copies a block of lines (e.g. the original file - has A and then B, and the commit changes it to B and then - A), the traditional 'blame' algorithm notices only half of + has _A_ and then _B_, and the commit changes it to _B_ and then + _A_), the traditional `blame` algorithm notices only half of the movement and typically blames the lines that were moved - up (i.e. B) to the parent and assigns blame to the lines that - were moved down (i.e. A) to the child commit. With this + up (i.e. _B_) to the parent and assigns blame to the lines that + were moved down (i.e. _A_) to the child commit. With this option, both groups of lines are blamed on the parent by running extra passes of inspection. + - is optional but it is the lower bound on the number of +__ is optional, but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying within a file for it to associate those lines with the parent commit. The default value is 20. --C[]:: +`-C[]`:: In addition to `-M`, detect lines moved or copied from other files that were modified in the same commit. This is useful when you reorganize your program and move code @@ -109,14 +109,14 @@ commit. The default value is 20. option is given three times, the command additionally looks for copies from other files in any commit. + - is optional but it is the lower bound on the number of +__ is optional, but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying between files for it to associate those lines with the parent commit. And the default value is 40. If there are more than one -`-C` options given, the argument of the last `-C` will +`-C` options given, the __ argument of the last `-C` will take effect. ---ignore-rev :: +`--ignore-rev `:: Ignore changes made by the revision when assigning blame, as if the change never happened. Lines that were changed or added by an ignored commit will be blamed on the previous commit that changed that line or @@ -126,26 +126,26 @@ take effect. another commit will be marked with a `?` in the blame output. If the `blame.markUnblamableLines` config option is set, then those lines touched by an ignored commit that we could not attribute to another revision are - marked with a '*'. In the porcelain modes, we print 'ignored' and - 'unblamable' on a newline respectively. + marked with a `*`. In the porcelain modes, we print `ignored` and + `unblamable` on a newline respectively. ---ignore-revs-file :: - Ignore revisions listed in `file`, which must be in the same format as an +`--ignore-revs-file `:: + Ignore revisions listed in __, which must be in the same format as an `fsck.skipList`. This option may be repeated, and these files will be processed after any files specified with the `blame.ignoreRevsFile` config option. An empty file name, `""`, will clear the list of revs from previously processed files. ---color-lines:: +`--color-lines`:: Color line annotations in the default format differently if they come from the same commit as the preceding line. This makes it easier to distinguish code blocks introduced by different commits. The color defaults to cyan and can be adjusted using the `color.blame.repeatedLines` config option. ---color-by-age:: - Color line annotations depending on the age of the line in the default format. - The `color.blame.highlightRecent` config option controls what color is used for - each range of age. +`--color-by-age`:: + Color line annotations depending on the age of the line in + the default format. The `color.blame.highlightRecent` config + option controls what color is used for each range of age. --h:: +`-h`:: Show help message. diff --git a/Documentation/config.adoc b/Documentation/config.adoc index 62eebe7c54501c..15b1a4d5934758 100644 --- a/Documentation/config.adoc +++ b/Documentation/config.adoc @@ -276,13 +276,15 @@ boolean:: When a variable is said to take a boolean value, many synonyms are accepted for 'true' and 'false'; these are all case-insensitive. - ++ +-- true;; Boolean true literals are `yes`, `on`, `true`, and `1`. Also, a variable defined without `= ` is taken as true. false;; Boolean false literals are `no`, `off`, `false`, `0` and the empty string. +-- + When converting a value to its canonical form using the `--type=bool` type specifier, 'git config' will ensure that the output is "true" or @@ -451,6 +453,8 @@ include::config/guitool.adoc[] include::config/help.adoc[] +include::config/hook.adoc[] + include::config/http.adoc[] include::config/i18n.adoc[] @@ -523,6 +527,8 @@ include::config/sequencer.adoc[] include::config/showbranch.adoc[] +include::config/sideband.adoc[] + include::config/sparse.adoc[] include::config/splitindex.adoc[] diff --git a/Documentation/config/alias.adoc b/Documentation/config/alias.adoc index 80ce17d2deb269..dc6ca0ee0813cc 100644 --- a/Documentation/config/alias.adoc +++ b/Documentation/config/alias.adoc @@ -1,12 +1,47 @@ alias.*:: - Command aliases for the linkgit:git[1] command wrapper - e.g. - after defining `alias.last = cat-file commit HEAD`, the invocation - `git last` is equivalent to `git cat-file commit HEAD`. To avoid - confusion and troubles with script usage, aliases that - hide existing Git commands are ignored except for deprecated - commands. Arguments are split by - spaces, the usual shell quoting and escaping are supported. - A quote pair or a backslash can be used to quote them. +alias.*.command:: + Command aliases for the linkgit:git[1] command wrapper. Aliases + can be defined using two syntaxes: ++ +-- +1. Without a subsection, e.g., `[alias] co = checkout`. The alias + name ("co" in this example) is + limited to ASCII alphanumeric characters and `-`, + and is matched case-insensitively. +2. With a subsection, e.g., `[alias "co"] command = checkout`. The + alias name can contain any characters (except for newlines and NUL bytes), + including UTF-8, and is matched case-sensitively as raw bytes. + You define the action of the alias in the `command`. +-- ++ +Examples: ++ +---- +# Without subsection (ASCII alphanumeric and dash only) +[alias] + co = checkout + st = status + +# With subsection (allows any characters, including UTF-8) +[alias "hämta"] + command = fetch +[alias "rätta till"] + command = commit --amend +---- ++ +With a Git alias defined, e.g., ++ + $ git config --global alias.last "cat-file commit HEAD" + # Which is equivalent to + $ git config --global alias.last.command "cat-file commit HEAD" ++ +`git last` is equivalent to `git cat-file commit HEAD`. ++ +To avoid confusion and troubles with script usage, aliases that +hide existing Git commands are ignored except for deprecated +commands. Arguments are split by +spaces, the usual shell quoting and escaping are supported. +A quote pair or a backslash can be used to quote them. + Note that the first word of an alias does not necessarily have to be a command. It can be a command-line option that will be passed into the diff --git a/Documentation/config/am.adoc b/Documentation/config/am.adoc index 5bcad2efb11639..250e6b5047365d 100644 --- a/Documentation/config/am.adoc +++ b/Documentation/config/am.adoc @@ -1,14 +1,20 @@ -am.keepcr:: - If true, git-am will call git-mailsplit for patches in mbox format - with parameter `--keep-cr`. In this case git-mailsplit will +`am.keepcr`:: + If true, linkgit:git-am[1] will call linkgit:git-mailsplit[1] + for patches in mbox format with parameter `--keep-cr`. In this + case linkgit:git-mailsplit[1] will not remove `\r` from lines ending with `\r\n`. Can be overridden by giving `--no-keep-cr` from the command line. - See linkgit:git-am[1], linkgit:git-mailsplit[1]. -am.threeWay:: - By default, `git am` will fail if the patch does not apply cleanly. When - set to true, this setting tells `git am` to fall back on 3-way merge if - the patch records the identity of blobs it is supposed to apply to and - we have those blobs available locally (equivalent to giving the `--3way` - option from the command line). Defaults to `false`. - See linkgit:git-am[1]. +`am.threeWay`:: + By default, linkgit:git-am[1] will fail if the patch does not + apply cleanly. When set to true, this setting tells + linkgit:git-am[1] to fall back on 3-way merge if the patch + records the identity of blobs it is supposed to apply to and we + have those blobs available locally (equivalent to giving the + `--3way` option from the command line). Defaults to `false`. + +`am.messageId`:: + Add a `Message-ID` trailer based on the email header to the + commit when using linkgit:git-am[1] (see + linkgit:git-interpret-trailers[1]). See also the `--message-id` + and `--no-message-id` options. diff --git a/Documentation/config/apply.adoc b/Documentation/config/apply.adoc index f9908e210a838d..36fcea62914ae6 100644 --- a/Documentation/config/apply.adoc +++ b/Documentation/config/apply.adoc @@ -1,11 +1,16 @@ -apply.ignoreWhitespace:: - When set to 'change', tells 'git apply' to ignore changes in +`apply.ignoreWhitespace`:: + When set to `change`, tells `git apply` to ignore changes in whitespace, in the same way as the `--ignore-space-change` option. - When set to one of: no, none, never, false, it tells 'git apply' to + When set to one of: `no`, `none`, `never`, `false`, it tells `git apply` to respect all whitespace differences. +ifndef::git-apply[] See linkgit:git-apply[1]. +endif::git-apply[] -apply.whitespace:: - Tells 'git apply' how to handle whitespace, in the same way - as the `--whitespace` option. See linkgit:git-apply[1]. +`apply.whitespace`:: + Tells `git apply` how to handle whitespace, in the same way + as the `--whitespace` option. +ifndef::git-apply[] + See linkgit:git-apply[1]. +endif::git-apply[] diff --git a/Documentation/config/bitmap-pseudo-merge.adoc b/Documentation/config/bitmap-pseudo-merge.adoc index 1f264eca99b847..6bf52c80ba786c 100644 --- a/Documentation/config/bitmap-pseudo-merge.adoc +++ b/Documentation/config/bitmap-pseudo-merge.adoc @@ -47,8 +47,8 @@ will be updated more often than a reference pointing at an old commit. bitmapPseudoMerge..sampleRate:: Determines the proportion of non-bitmapped commits (among reference tips) which are selected for inclusion in an - unstable pseudo-merge bitmap. Must be between `0` and `1` - (inclusive). The default is `1`. + unstable pseudo-merge bitmap. Must be greater than `0` and + less than or equal to `1`. The default is `1`. bitmapPseudoMerge..threshold:: Determines the minimum age of non-bitmapped commits (among diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc index 01202da7cd4a36..a0ebf03e2eb050 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -348,6 +348,17 @@ confusion unless you know what you are doing (e.g. you are creating a read-only snapshot of the same index to a location different from the repository's usual working tree). +core.lockfilePid:: + If true, Git will create a PID file alongside lock files. When a + lock acquisition fails and a PID file exists, Git can provide + additional diagnostic information about the process holding the + lock, including whether it is still running. Defaults to `false`. ++ +The PID file is named by inserting `~pid` before the `.lock` suffix. +For example, if the lock file is `index.lock`, the PID file will be +`index~pid.lock`. The file contains a single line in the format +`pid ` followed by a newline. + core.logAllRefUpdates:: Enable the reflog. Updates to a ref is logged to the file "`$GIT_DIR/logs/`", by appending the new and old @@ -492,10 +503,9 @@ core.askPass:: command-line argument and write the password on its STDOUT. core.attributesFile:: - In addition to `.gitattributes` (per-directory) and - `.git/info/attributes`, Git looks into this file for attributes - (see linkgit:gitattributes[5]). Path expansions are made the same - way as for `core.excludesFile`. Its default value is + Specifies the pathname to the file that contains attributes (see + linkgit:gitattributes[5]), in addition to `.gitattributes` (per-directory) + and `.git/info/attributes`. Its default value is `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/attributes` is used instead. diff --git a/Documentation/config/difftool.adoc b/Documentation/config/difftool.adoc index 4f7d40ce242b78..1b8d48381357aa 100644 --- a/Documentation/config/difftool.adoc +++ b/Documentation/config/difftool.adoc @@ -1,43 +1,43 @@ -diff.tool:: +`diff.tool`:: Controls which diff tool is used by linkgit:git-difftool[1]. This variable overrides the value configured in `merge.tool`. The list below shows the valid built-in values. Any other value is treated as a custom diff tool and requires - that a corresponding difftool..cmd variable is defined. + that a corresponding `difftool..cmd` variable is defined. -diff.guitool:: +`diff.guitool`:: Controls which diff tool is used by linkgit:git-difftool[1] when - the -g/--gui flag is specified. This variable overrides the value + the `-g`/`--gui` flag is specified. This variable overrides the value configured in `merge.guitool`. The list below shows the valid built-in values. Any other value is treated as a custom diff tool - and requires that a corresponding difftool..cmd variable + and requires that a corresponding `difftool..cmd` variable is defined. include::{build_dir}/mergetools-diff.adoc[] -difftool..cmd:: +`difftool..cmd`:: Specify the command to invoke the specified diff tool. The specified command is evaluated in shell with the following - variables available: 'LOCAL' is set to the name of the temporary - file containing the contents of the diff pre-image and 'REMOTE' + variables available: `LOCAL` is set to the name of the temporary + file containing the contents of the diff pre-image and `REMOTE` is set to the name of the temporary file containing the contents of the diff post-image. + See the `--tool=` option in linkgit:git-difftool[1] for more details. -difftool..path:: +`difftool..path`:: Override the path for the given tool. This is useful in case your tool is not in the PATH. -difftool.trustExitCode:: +`difftool.trustExitCode`:: Exit difftool if the invoked diff tool returns a non-zero exit status. + See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details. -difftool.prompt:: +`difftool.prompt`:: Prompt before each invocation of the diff tool. -difftool.guiDefault:: +`difftool.guiDefault`:: Set `true` to use the `diff.guitool` by default (equivalent to specifying the `--gui` argument), or `auto` to select `diff.guitool` or `diff.tool` depending on the presence of a `DISPLAY` environment variable value. The diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc index 532456644b770e..be6678bb5b5585 100644 --- a/Documentation/config/extensions.adoc +++ b/Documentation/config/extensions.adoc @@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the `core.repositoryFormatVersion` setting. refStorage::: - Specify the ref storage format to use. The acceptable values are: + Specify the ref storage format and a corresponding payload. The value + can be either a format name or a URI: + -- +* A format name alone (e.g., `reftable` or `files`). + +* A URI format `://` explicitly specifies both the + format and payload (e.g., `reftable:///foo/bar`). + +Supported format names are: + include::../ref-storage-format.adoc[] + +The payload is passed directly to the reference backend. For the files and +reftable backends, this must be a filesystem path where the references will +be stored. Defaulting to the commondir when no payload is provided. Relative +paths are resolved relative to the `$GIT_DIR`. Future backends may support +other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo. -- + Note that this setting should only be set by linkgit:git-init[1] or @@ -73,6 +87,35 @@ relativeWorktrees::: repaired with either the `--relative-paths` option or with the `worktree.useRelativePaths` config set to `true`. +submodulePathConfig::: + This extension is for the minority of users who: ++ +-- +* Encounter errors like `refusing to create ... in another submodule's git dir` + due to a number of reasons, like case-insensitive filesystem conflicts when + creating modules named `foo` and `Foo`. +* Require more flexible submodule layouts, for example due to nested names like + `foo`, `foo/bar` and `foo/baz` not supported by the default gitdir mechanism + which uses `.git/modules/` locations, causing further conflicts. +-- ++ +When `extensions.submodulePathConfig` is enabled, the `submodule..gitdir` +config becomes the single source of truth for all submodule gitdir paths and is +automatically set for all new submodules both during clone and init operations. ++ +Git will error out if a module does not have a corresponding +`submodule..gitdir` set. ++ +Existing (pre-extension) submodules need to be migrated by adding the missing +config entries. This can be done manually, e.g. for each submodule: +`git config submodule..gitdir .git/modules/`, or via the +`git submodule--helper migrate-gitdir-configs` command which iterates over all +submodules and attempts to migrate them. ++ +The extension can be enabled automatically for new repositories by setting +`init.defaultSubmodulePathConfig` to `true`, for example by running +`git config --global init.defaultSubmodulePathConfig true`. + worktreeConfig::: If enabled, then worktrees will load config settings from the `$GIT_DIR/config.worktree` file in addition to the diff --git a/Documentation/config/fetch.adoc b/Documentation/config/fetch.adoc index cd40db0cad1c36..04ac90912d3a58 100644 --- a/Documentation/config/fetch.adoc +++ b/Documentation/config/fetch.adoc @@ -76,7 +76,7 @@ default is `skipping`. Unknown values will cause `git fetch` to error out. + -See also the `--negotiate-only` and `--negotiation-tip` options to +See also the `--negotiate-only` and `--negotiation-restrict` options to linkgit:git-fetch[1]. `fetch.showForcedUpdates`:: diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc index ab0710e86a3e2c..95d19134b26ea0 100644 --- a/Documentation/config/format.adoc +++ b/Documentation/config/format.adoc @@ -101,6 +101,11 @@ format.coverLetter:: generate a cover-letter only when there's more than one patch. Default is false. +format.commitListFormat:: + When the `--commit-list-format` option is not given, `format-patch` + uses the value of this variable to decide how to format the entry of + each commit. Defaults to `shortlog`. + format.outputDirectory:: Set a custom directory to store the resulting files instead of the current working directory. All directory components will be created. diff --git a/Documentation/config/fsmonitor--daemon.adoc b/Documentation/config/fsmonitor--daemon.adoc index 671f9b94628446..6f8386e29150ff 100644 --- a/Documentation/config/fsmonitor--daemon.adoc +++ b/Documentation/config/fsmonitor--daemon.adoc @@ -4,8 +4,8 @@ fsmonitor.allowRemote:: behavior. Only respected when `core.fsmonitor` is set to `true`. fsmonitor.socketDir:: - This Mac OS-specific option, if set, specifies the directory in + This Mac OS and Linux-specific option, if set, specifies the directory in which to create the Unix domain socket used for communication between the fsmonitor daemon and various Git commands. The directory must - reside on a native Mac OS filesystem. Only respected when `core.fsmonitor` + reside on a native filesystem. Only respected when `core.fsmonitor` is set to `true`. diff --git a/Documentation/config/grep.adoc b/Documentation/config/grep.adoc index 10041f27b0c8e2..83d4b76dd351e1 100644 --- a/Documentation/config/grep.adoc +++ b/Documentation/config/grep.adoc @@ -1,28 +1,28 @@ -grep.lineNumber:: - If set to true, enable `-n` option by default. +`grep.lineNumber`:: + If set to `true`, enable `-n` option by default. -grep.column:: - If set to true, enable the `--column` option by default. +`grep.column`:: + If set to `true`, enable the `--column` option by default. -grep.patternType:: - Set the default matching behavior. Using a value of 'basic', 'extended', - 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`, +`grep.patternType`:: + Set the default matching behavior. Using a value of `basic`, `extended`, + `fixed`, or `perl` will enable the `--basic-regexp`, `--extended-regexp`, `--fixed-strings`, or `--perl-regexp` option accordingly, while the - value 'default' will use the `grep.extendedRegexp` option to choose - between 'basic' and 'extended'. + value `default` will use the `grep.extendedRegexp` option to choose + between `basic` and `extended`. -grep.extendedRegexp:: - If set to true, enable `--extended-regexp` option by default. This +`grep.extendedRegexp`:: + If set to `true`, enable `--extended-regexp` option by default. This option is ignored when the `grep.patternType` option is set to a value - other than 'default'. + other than `default`. -grep.threads:: +`grep.threads`:: Number of grep worker threads to use. If unset (or set to 0), Git will use as many threads as the number of logical cores available. -grep.fullName:: - If set to true, enable `--full-name` option by default. +`grep.fullName`:: + If set to `true`, enable `--full-name` option by default. -grep.fallbackToNoIndex:: - If set to true, fall back to `git grep --no-index` if `git grep` - is executed outside of a git repository. Defaults to false. +`grep.fallbackToNoIndex`:: + If set to `true`, fall back to `git grep --no-index` if `git grep` + is executed outside of a git repository. Defaults to `false`. diff --git a/Documentation/config/gui.adoc b/Documentation/config/gui.adoc index 171be774d243fd..1565c0af197b9c 100644 --- a/Documentation/config/gui.adoc +++ b/Documentation/config/gui.adoc @@ -55,3 +55,8 @@ gui.blamehistoryctx:: linkgit:gitk[1] for the selected commit, when the `Show History Context` menu item is invoked from 'git gui blame'. If this variable is set to zero, the whole history is shown. + +gui.GCWarning:: + Determines whether linkgit:git-gui[1] should prompt for garbage + collection when git detects a large number of loose objects in + the repository. The default value is "true". diff --git a/Documentation/config/hook.adoc b/Documentation/config/hook.adoc new file mode 100644 index 00000000000000..083dc60a1325f2 --- /dev/null +++ b/Documentation/config/hook.adoc @@ -0,0 +1,107 @@ +ifdef::git-hook[] +:see-git-hook: +endif::git-hook[] +ifndef::git-hook[] +:see-git-hook: See linkgit:git-hook[1]. +endif::git-hook[] + +hook..command:: + The command to execute for `hook.`. `` + is a unique name that identifies this hook. The hook events that + trigger the command are configured with `hook..event`. + The value can be an executable path or a shell oneliner. If more than + one value is specified for the same ``, only the last + value parsed is used. {see-git-hook} + +hook..event:: + The hook events that trigger `hook.`. The value is the + name of a hook event, like "pre-commit" or "update". (See + linkgit:githooks[5] for a complete list of hook events.) On the + specified event, the associated `hook..command` is executed. + This is a multi-valued key. To run `hook.` on multiple + events, specify the key more than once. An empty value resets + the list of events, clearing any previously defined events for + `hook.`. {see-git-hook} ++ +The `` must not be the same as a known hook event name +(e.g. do not use `hook.pre-commit.event`). Using a known event name as +a friendly-name is a fatal error because it creates an ambiguity with +`hook..enabled` and `hook..jobs`. For unknown event names, +a warning is issued when `` matches the event value. + +hook..enabled:: + Whether the hook `hook.` is enabled. Defaults to `true`. + Set to `false` to disable the hook without removing its + configuration. This is particularly useful when a hook is defined + in a system or global config file and needs to be disabled for a + specific repository. {see-git-hook} + +hook..parallel:: + Whether the hook `hook.` may run in parallel with other hooks + for the same event. Defaults to `false`. Set to `true` only when the + hook script is safe to run concurrently with other hooks for the same + event. If any hook for an event does not have this set to `true`, + all hooks for that event run sequentially regardless of `hook.jobs`. + Only configured (named) hooks need to declare this. Traditional hooks + found in the hooks directory do not need to, and run in parallel when + the effective job count is greater than 1. {see-git-hook} + +hook..enabled:: + Switch to enable or disable all hooks for the `` hook event. + When set to `false`, no hooks fire for that event, regardless of any + per-hook `hook..enabled` settings. Defaults to `true`. + {see-git-hook} ++ +Note on naming: `` must be the event name (e.g. `pre-commit`), +not a hook friendly-name. Since using a known event name as a +friendly-name is disallowed (see `hook..event` above), +there is no ambiguity between event-level and per-hook `.enabled` +settings for known events. For unknown events, if a friendly-name +matches the event name despite the warning, `.enabled` is treated +as per-hook only. + +hook..jobs:: + Specifies how many hooks can be run simultaneously for the `` + hook event (e.g. `hook.post-receive.jobs = 4`). Overrides `hook.jobs` + for this specific event. The same parallelism restrictions apply: this + setting has no effect unless all configured hooks for the event have + `hook..parallel` set to `true`. Set to `-1` to use the + number of available CPU cores. Must be a positive integer or `-1`; + zero is rejected with a warning. {see-git-hook} ++ +Note on naming: although this key resembles `hook..*` +(a per-hook setting), `` must be the event name, not a hook +friendly name. The key component is stored literally and looked up by +event name at runtime with no translation between the two namespaces. +A key like `hook.my-hook.jobs` is stored under `"my-hook"` but the +lookup at runtime uses the event name (e.g. `"post-receive"`), so +`hook.my-hook.jobs` is silently ignored even when `my-hook` is +registered for that event. Use `hook.post-receive.jobs` or any other +valid event name when setting `hook..jobs`. + +hook.jobs:: + Specifies how many hooks can be run simultaneously during parallelized + hook execution. If unspecified, defaults to 1 (serial execution). + Set to `-1` to use the number of available CPU cores. + Can be overridden on a per-event basis with `hook..jobs`. + Some hooks always run sequentially regardless of this setting because + they operate on shared data and cannot safely be parallelized: ++ +-- +`applypatch-msg`;; +`prepare-commit-msg`;; +`commit-msg`;; + Receive a commit message file and may rewrite it in place. +`pre-commit`;; +`post-checkout`;; +`push-to-checkout`;; +`post-commit`;; + Access the working tree, index, or repository state. +-- ++ +This setting has no effect unless all configured hooks for the event have +`hook..parallel` set to `true`. ++ +For `pre-push` hooks, which normally keep stdout and stderr separate, +setting this to a value greater than 1 (or passing `-j`) will merge stdout +into stderr to allow correct de-interleaving of parallel output. diff --git a/Documentation/config/http.adoc b/Documentation/config/http.adoc index 9da5c298cc1d5e..792a71b41350d4 100644 --- a/Documentation/config/http.adoc +++ b/Documentation/config/http.adoc @@ -59,7 +59,18 @@ http.emptyAuth:: Attempt authentication without seeking a username or password. This can be used to attempt GSS-Negotiate authentication without specifying a username in the URL, as libcurl normally requires a username for - authentication. + authentication. Possible values are: ++ +-- +* `auto` (default) - Send empty credentials only if the server's 401 response + advertises an authentication mechanism that requires them (such as + GSS-Negotiate); otherwise fall back to prompting via the credential helper. +* `true` - Always send empty credentials on the very first request, before + receiving any 401 response from the server. +* `false` - Never send empty credentials. Mechanisms that require + empty credentials or an explicit username, such as GSS-Negotiate, will not + work. +-- http.proactiveAuth:: Attempt authentication without first making an unauthenticated attempt and @@ -315,6 +326,32 @@ http.keepAliveCount:: unset, curl's default value is used. Can be overridden by the `GIT_HTTP_KEEPALIVE_COUNT` environment variable. +http.retryAfter:: + Default wait time in seconds before retrying when a server returns + HTTP 429 (Too Many Requests) without a Retry-After header. + Defaults to 0 (retry immediately). When a Retry-After header is + present, its value takes precedence over this setting; however, + automatic use of the server-provided `Retry-After` header requires + libcurl 7.66.0 or later. On older versions, configure this setting + manually to control the retry delay. Can be overridden by the + `GIT_HTTP_RETRY_AFTER` environment variable. + See also `http.maxRetries` and `http.maxRetryTime`. + +http.maxRetries:: + Maximum number of times to retry after receiving HTTP 429 (Too Many + Requests) responses. Set to 0 (the default) to disable retries. + Can be overridden by the `GIT_HTTP_MAX_RETRIES` environment variable. + See also `http.retryAfter` and `http.maxRetryTime`. + +http.maxRetryTime:: + Maximum time in seconds to wait for a single retry attempt when + handling HTTP 429 (Too Many Requests) responses. If the server + requests a delay (via Retry-After header) or if `http.retryAfter` + is configured with a value that exceeds this maximum, Git will fail + immediately rather than waiting. Default is 300 seconds (5 minutes). + Can be overridden by the `GIT_HTTP_MAX_RETRY_TIME` environment + variable. See also `http.retryAfter` and `http.maxRetries`. + http.noEPSV:: A boolean which disables using of EPSV ftp command by curl. This can be helpful with some "poor" ftp servers which don't diff --git a/Documentation/config/imap.adoc b/Documentation/config/imap.adoc index 4682a6bd039755..cb8f5e2700ae13 100644 --- a/Documentation/config/imap.adoc +++ b/Documentation/config/imap.adoc @@ -1,44 +1,44 @@ -imap.folder:: +`imap.folder`:: The folder to drop the mails into, which is typically the Drafts folder. For example: `INBOX.Drafts`, `INBOX/Drafts` or `[Gmail]/Drafts`. The IMAP folder to interact with MUST be specified; the value of this configuration variable is used as the fallback default value when the `--folder` option is not given. -imap.tunnel:: +`imap.tunnel`:: Command used to set up a tunnel to the IMAP server through which commands will be piped instead of using a direct network connection - to the server. Required when imap.host is not set. + to the server. Required when `imap.host` is not set. -imap.host:: +`imap.host`:: A URL identifying the server. Use an `imap://` prefix for non-secure connections and an `imaps://` prefix for secure connections. - Ignored when imap.tunnel is set, but required otherwise. + Ignored when `imap.tunnel` is set, but required otherwise. -imap.user:: +`imap.user`:: The username to use when logging in to the server. -imap.pass:: +`imap.pass`:: The password to use when logging in to the server. -imap.port:: +`imap.port`:: An integer port number to connect to on the server. - Defaults to 143 for imap:// hosts and 993 for imaps:// hosts. - Ignored when imap.tunnel is set. + Defaults to 143 for `imap://` hosts and 993 for `imaps://` hosts. + Ignored when `imap.tunnel` is set. -imap.sslverify:: +`imap.sslverify`:: A boolean to enable/disable verification of the server certificate used by the SSL/TLS connection. Default is `true`. Ignored when - imap.tunnel is set. + `imap.tunnel` is set. -imap.preformattedHTML:: +`imap.preformattedHTML`:: A boolean to enable/disable the use of html encoding when sending - a patch. An html encoded patch will be bracketed with 
+	a patch.  An html encoded patch will be bracketed with `
`
 	and have a content type of text/html.  Ironically, enabling this
 	option causes Thunderbird to send the patch as a plain/text,
 	format=fixed email.  Default is `false`.
 
-imap.authMethod::
+`imap.authMethod`::
 	Specify the authentication method for authenticating with the IMAP server.
 	If Git was built with the NO_CURL option, or if your curl version is older
 	than 7.34.0, or if you're running git-imap-send with the `--no-curl`
diff --git a/Documentation/config/init.adoc b/Documentation/config/init.adoc
index e45b2a812151dc..7b4abdaf8ba29b 100644
--- a/Documentation/config/init.adoc
+++ b/Documentation/config/init.adoc
@@ -18,3 +18,9 @@ endif::[]
 	See `--ref-format=` in linkgit:git-init[1]. Both the command line
 	option and the `GIT_DEFAULT_REF_FORMAT` environment variable take
 	precedence over this config.
+
+init.defaultSubmodulePathConfig::
+	A boolean that specifies if `git init` and `git clone` should
+	automatically set `extensions.submodulePathConfig` to `true`. This
+	allows all new repositories to automatically use the submodule path
+	extension. Defaults to `false` when unset.
diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc
index d0c38f03fabd60..b578856dde1dd4 100644
--- a/Documentation/config/maintenance.adoc
+++ b/Documentation/config/maintenance.adoc
@@ -30,8 +30,7 @@ The possible strategies are:
 +
 * `none`: This strategy implies no tasks are run at all. This is the default
   strategy for scheduled maintenance.
-* `gc`: This strategy runs the `gc` task. This is the default strategy for
-  manual maintenance.
+* `gc`: This strategy runs the `gc` task.
 * `geometric`: This strategy performs geometric repacking of packfiles and
   keeps auxiliary data structures up-to-date. The strategy expires data in the
   reflog and removes worktrees that cannot be located anymore. When the
@@ -40,7 +39,8 @@ The possible strategies are:
   are already part of a cruft pack will be expired.
 +
 This repacking strategy is a full replacement for the `gc` strategy and is
-recommended for large repositories.
+recommended for large repositories. This is the default strategy for manual
+maintenance.
 * `incremental`: This setting optimizes for performing small maintenance
   activities that do not delete any data. This does not schedule the `gc`
   task, but runs the `prefetch` and `commit-graph` tasks hourly, the
diff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc
index 7064f5a462cb56..7afdcad92b3934 100644
--- a/Documentation/config/mergetool.adoc
+++ b/Documentation/config/mergetool.adoc
@@ -52,13 +52,13 @@
 	if `merge.tool` is configured as __), Git will consult
 	`mergetool..layout` to determine the tool's layout. If the
 	variant-specific configuration is not available, `vimdiff` ' s is used as
-	fallback.  If that too is not available, a default layout with 4 windows
-	will be used.  To configure the layout, see the 'BACKEND SPECIFIC HINTS'
+	fallback. If that too is not available, a default layout with 4 windows
+	will be used.
 ifdef::git-mergetool[]
-	section.
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section.
 endif::[]
 ifndef::git-mergetool[]
-	section in linkgit:git-mergetool[1].
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section in linkgit:git-mergetool[1].
 endif::[]
 
 `mergetool.hideResolved`::
diff --git a/Documentation/config/pack.adoc b/Documentation/config/pack.adoc
index 75402d5579d4b2..22384c2d2f0773 100644
--- a/Documentation/config/pack.adoc
+++ b/Documentation/config/pack.adoc
@@ -160,12 +160,13 @@ pack.usePathWalk::
 	processes. See linkgit:git-pack-objects[1] for full details.
 
 pack.preferBitmapTips::
+	Specifies a ref hierarchy (e.g., "refs/heads/"); can be
+	given multiple times to specify more than one hierarchy.
 	When selecting which commits will receive bitmaps, prefer a
-	commit at the tip of any reference that is a suffix of any value
-	of this configuration over any other commits in the "selection
-	window".
+	commit at the tip of a reference that is contained in any of
+	the configured hierarchies.
 +
-Note that setting this configuration to `refs/foo` does not mean that
+Note that setting this configuration to `refs/foo/` does not mean that
 the commits at the tips of `refs/foo/bar` and `refs/foo/baz` will
 necessarily be selected. This is because commits are selected for
 bitmaps from within a series of windows of variable length.
diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc
index 93e5e0d9b55eb4..39af63dcb87a32 100644
--- a/Documentation/config/promisor.adoc
+++ b/Documentation/config/promisor.adoc
@@ -63,11 +63,13 @@ If one of these field names (e.g., "token") is being checked for an
 advertised promisor remote (e.g., "foo"), three conditions must be met
 for the check of this specific field to pass:
 +
+--
 1. The corresponding local configuration (e.g., `remote.foo.token`)
    must be set.
 2. The server must advertise the "token" field for remote "foo".
 3. The value of the locally configured `remote.foo.token` must exactly
    match the value advertised by the server for the "token" field.
+--
 +
 If any of these conditions is not met for any field name listed in
 `promisor.checkFields`, the advertised remote "foo" is rejected.
@@ -89,3 +91,36 @@ variable. The fields are checked only if the
 `promisor.acceptFromServer` config variable is not set to "None". If
 set to "None", this config variable has no effect. See
 linkgit:gitprotocol-v2[5].
+
+promisor.storeFields::
+	A comma or space separated list of additional remote related
+	field names. If a client accepts an advertised remote, the
+	client will store the values associated with these field names
+	taken from the remote advertisement into its configuration,
+	and then reload its remote configuration. Currently,
+	"partialCloneFilter" and "token" are the only supported field
+	names.
++
+For example if a server advertises "partialCloneFilter=blob:limit=20k"
+for remote "foo", and that remote is accepted, then "blob:limit=20k"
+will be stored for the "remote.foo.partialCloneFilter" configuration
+variable.
++
+If the new field value from an advertised remote is the same as the
+existing field value for that remote on the client side, then no
+change is made to the client configuration though.
++
+When a new value is stored, a message is printed to standard error to
+let users know about this.
++
+Note that for security reasons, if the remote is not already
+configured on the client side, nothing will be stored for that
+remote. In any case, no new remote will be created and no URL will be
+stored.
++
+Before storing a partial clone filter, it's parsed to check it's
+valid. If it's not, a warning is emitted and it's not stored.
++
+Before storing a token, a check is performed to ensure it contains no
+control character. If the check fails, a warning is emitted and it's
+not stored.
diff --git a/Documentation/config/push.adoc b/Documentation/config/push.adoc
index d9112b22609b51..28132eedfee6c0 100644
--- a/Documentation/config/push.adoc
+++ b/Documentation/config/push.adoc
@@ -41,9 +41,10 @@ this is a deprecated synonym for `upstream`.
 `simple`;;
 push the current branch with the same name on the remote.
 +
-If you are working on a centralized workflow (pushing to the same repository you
-pull from, which is typically `origin`), then you need to configure an upstream
-branch with the same name.
+This mode requires that the remote repository to be pushed to is
+known.  When pushing back to the same remote you pull from, the
+current branch must also have an upstream tracking branch with the
+same name.
 +
 This mode is the default since Git 2.0, and is the safest option suited for
 beginners.
diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc
index 91e46f66f5dd1c..eb9c8a3c488448 100644
--- a/Documentation/config/remote.adoc
+++ b/Documentation/config/remote.adoc
@@ -107,6 +107,55 @@ priority configuration file (e.g. `.git/config` in a repository) to clear
 the values inherited from a lower priority configuration files (e.g.
 `$HOME/.gitconfig`).
 
+remote..negotiationRestrict::
+	When negotiating with this remote during `git fetch`, restrict the
+	commits advertised as "have" lines to only those reachable from refs
+	matching the given patterns.  This multi-valued config option behaves
+	like `--negotiation-restrict` on the command line.
++
+Each value is either an exact ref name (e.g. `refs/heads/release`) or a
+glob pattern (e.g. `refs/heads/release/*`).  The pattern syntax is the
+same as for `--negotiation-restrict`.
++
+These config values are used as defaults for the `--negotiation-restrict`
+command-line option.  If `--negotiation-restrict` (or its synonym
+`--negotiation-tip`) is specified on the command line, then the config
+values are not used.
++
+These values also influence negotiation during `git push` if
+`push.negotiate` is enabled.
++
+Blank values signal to ignore all previous values, allowing a reset of
+the list from broader config scenarios.
+
+remote..negotiationInclude::
+	When negotiating with this remote during `git fetch`, the client
+	advertises a list of commits that exist locally.  In repos with
+	many references, this list of "haves" can be truncated. Depending
+	on data shape, dropping certain references may be expensive. This
+	multi-valued config option specifies references, commit hashes,
+	or ref pattern globs whose tips should always be sent as "have"
+	commits during fetch negotiation with this remote.
++
+Each value is either an exact ref name (e.g. `refs/heads/release`), a
+commit hash, or a glob pattern (e.g. `refs/heads/release/*`).  The
+pattern syntax is the same as for `--negotiation-include`.
++
+These config values are used as defaults for the `--negotiation-include`
+command-line option.  If `--negotiation-include` is specified on the
+command line, then the config values are not used.
++
+This option is additive with the normal negotiation process: the
+negotiation algorithm still runs and advertises its own selected commits,
+but the refs matching `remote..negotiationInclude` are sent
+unconditionally on top of those heuristically selected commits.
++
+These values also influence negotiation during `git push` if
+`push.negotiate` is enabled.
++
+Blank values signal to ignore all previous values, allowing a reset of
+the list from broader config scenarios.
+
 remote..followRemoteHEAD::
 	How linkgit:git-fetch[1] should handle updates to `remotes//HEAD`
 	when fetching using the configured refspecs of a remote.
diff --git a/Documentation/config/repack.adoc b/Documentation/config/repack.adoc
index e9e78dcb198292..4c22a499f6216c 100644
--- a/Documentation/config/repack.adoc
+++ b/Documentation/config/repack.adoc
@@ -46,3 +46,21 @@ repack.midxMustContainCruft::
 	`--write-midx`. When false, cruft packs are only included in the MIDX
 	when necessary (e.g., because they might be required to form a
 	reachability closure with MIDX bitmaps). Defaults to true.
+
+repack.midxSplitFactor::
+	The factor used in the geometric merging condition when
+	compacting incremental MIDX layers during `git repack` when
+	invoked with the `--write-midx=incremental` option.
++
+Adjacent layers are merged when the accumulated object count of the
+newer layer exceeds `1/` of the object count of the next deeper
+layer. Must be at least 2. Defaults to 2.
+
+repack.midxNewLayerThreshold::
+	The minimum number of packs in the tip MIDX layer before those
+	packs are considered as candidates for geometric repacking
+	during `git repack --write-midx=incremental`.
++
+When the tip layer has fewer packs than this threshold, those packs are
+excluded from the geometric repack entirely, and are thus left
+unmodified. Must be at least 1. Defaults to 8.
diff --git a/Documentation/config/safe.adoc b/Documentation/config/safe.adoc
index 2d45c98b12d951..99fbfc06188c52 100644
--- a/Documentation/config/safe.adoc
+++ b/Documentation/config/safe.adoc
@@ -2,10 +2,14 @@ safe.bareRepository::
 	Specifies which bare repositories Git will work with. The currently
 	supported values are:
 +
-* `all`: Git works with all bare repositories. This is the default.
+--
+* `all`: Git works with all bare repositories. This is the default in
+  Git 2.x.
 * `explicit`: Git only works with bare repositories specified via
   the top-level `--git-dir` command-line option, or the `GIT_DIR`
-  environment variable (see linkgit:git[1]).
+  environment variable (see linkgit:git[1]). This will be the default
+  in Git 3.0.
+--
 +
 If you do not use bare repositories in your workflow, then it may be
 beneficial to set `safe.bareRepository` to `explicit` in your global
@@ -13,6 +17,10 @@ config. This will protect you from attacks that involve cloning a
 repository that contains a bare repository and running a Git command
 within that directory.
 +
+If you use bare repositories regularly and want to preserve the current
+behavior after upgrading to Git 3.0, set `safe.bareRepository` to `all`
+in your global or system config.
++
 This config setting is only respected in protected configuration (see
 <>). This prevents untrusted repositories from tampering with
 this value.
diff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc
index 90164c734d2660..1d700559b4a4c3 100644
--- a/Documentation/config/sendemail.adoc
+++ b/Documentation/config/sendemail.adoc
@@ -12,6 +12,22 @@ sendemail.smtpSSLCertPath::
 	Path to ca-certificates (either a directory or a single file).
 	Set it to an empty string to disable certificate verification.
 
+sendemail.smtpSSLClientCert::
+	Path to the client certificate file to present if requested by the
+	server. This is required when the server is set up to verify client
+	certificates. If the corresponding private key is not included in the
+	file, it must be supplied using `sendemail.smtpSSLClientKey` or the
+	`--smtp-ssl-client-key` option.
+
+sendemail.smtpSSLClientKey::
+	Path to the client private key file that corresponds to the client
+	certificate. To avoid misconfiguration, this configuration must be used
+	in conjunction with `sendemail.smtpSSLClientCert` or the
+	`--smtp-ssl-client-cert` option. If the client key is included in the
+	client certificate, the choice of private key depends on the format of
+	the certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more
+	details.
+
 sendemail..*::
 	Identity-specific versions of the `sendemail.*` parameters
 	found below, taking precedence over those when this
diff --git a/Documentation/config/sideband.adoc b/Documentation/config/sideband.adoc
new file mode 100644
index 00000000000000..f5b159e15fd834
--- /dev/null
+++ b/Documentation/config/sideband.adoc
@@ -0,0 +1,27 @@
+sideband.allowControlCharacters::
+	By default, control characters that are delivered via the sideband
+	are masked, except ANSI color sequences. This prevents potentially
+	unwanted ANSI escape sequences from being sent to the terminal. Use
+	this config setting to override this behavior (the value can be
+	a comma-separated list of the following keywords):
++
+--
+	`color`::
+		Allow ANSI color sequences, line feeds and horizontal tabs,
+		but mask all other control characters. This is the default.
+	`cursor`::
+		Allow control sequences that move the cursor. This is
+		disabled by default.
+	`erase`::
+		Allow control sequences that erase characters. This is
+		disabled by default.
+	`false`::
+		Mask all control characters other than line feeds and
+		horizontal tabs.
+	`true`::
+		Allow all control characters to be sent to the terminal.
+--
+
+sideband..*::
+	Apply the `sideband.*` option selectively to specific URLs. The
+	same URL matching logic applies as for `http..*` settings.
diff --git a/Documentation/config/status.adoc b/Documentation/config/status.adoc
index 8caf90f51c19a3..b5dd85b761f6f9 100644
--- a/Documentation/config/status.adoc
+++ b/Documentation/config/status.adoc
@@ -17,6 +17,31 @@ status.aheadBehind::
 	`--no-ahead-behind` by default in linkgit:git-status[1] for
 	non-porcelain status formats.  Defaults to true.
 
+status.compareBranches::
+	A space-separated list of branch comparison specifiers to use in
+	linkgit:git-status[1]. Currently, only `@{upstream}` and `@{push}`
+	are supported. They are interpreted as `branch@{upstream}` and
+	`branch@{push}` for the current branch.
++
+If not set, the default behavior is equivalent to `@{upstream}`, which
+compares against the configured upstream tracking branch.
++
+The entries are shown in the order they appear in the configuration.
+Duplicate entries that resolve to the same ref are suppressed after
+their first occurrence, so `@{push} @{upstream} @{push}` shows at
+most two comparisons.  When `@{upstream}` and `@{push}` resolve to
+the same remote-tracking branch, only one comparison is shown.
++
+Example:
++
+----
+[status]
+	compareBranches = @{upstream} @{push}
+----
++
+This would show comparisons against both the configured upstream and push
+tracking branches for the current branch.
+
 status.displayCommentPrefix::
 	If set to true, linkgit:git-status[1] will insert a comment
 	prefix before each output line (starting with
diff --git a/Documentation/config/submodule.adoc b/Documentation/config/submodule.adoc
index 0672d9911724d1..4c424017b4821e 100644
--- a/Documentation/config/submodule.adoc
+++ b/Documentation/config/submodule.adoc
@@ -32,15 +32,16 @@ submodule..fetchRecurseSubmodules::
 
 submodule..ignore::
 	Defines under what circumstances "git status" and the diff family show
-	a submodule as modified. When set to "all", it will never be considered
-	modified (but it will nonetheless show up in the output of status and
-	commit when it has been staged), "dirty" will ignore all changes
-	to the submodule's work tree and
+	a submodule as modified.
+	When set to "all" will never consider the submodule modified. It can
+	nevertheless be staged using the option --force and it will then show up
+	in the output of status.
+	When set to "dirty" will ignore all changes to the submodule's work tree and
 	takes only differences between the HEAD of the submodule and the commit
 	recorded in the superproject into account. "untracked" will additionally
 	let submodules with modified tracked files in their work tree show up.
-	Using "none" (the default when this option is not set) also shows
-	submodules that have untracked files in their work tree as changed.
+	When set to "none" (default) it also shows submodules as changed if they have
+	untracked files in their work tree.
 	This setting overrides any setting made in .gitmodules for this submodule,
 	both settings can be overridden on the command line by using the
 	"--ignore-submodules" option. The 'git submodule' commands are not
@@ -52,6 +53,13 @@ submodule..active::
 	submodule.active config option. See linkgit:gitsubmodules[7] for
 	details.
 
+submodule..gitdir::
+	This sets the gitdir path for submodule . This configuration is
+	respected when `extensions.submodulePathConfig` is enabled, otherwise it
+	has no effect. When enabled, this config becomes the single source of
+	truth for submodule gitdir paths and Git will error if it is missing.
+	See linkgit:git-config[1] for details.
+
 submodule.active::
 	A repeated field which contains a pathspec used to match against a
 	submodule's path to determine if the submodule is of interest to git
diff --git a/Documentation/config/trailer.adoc b/Documentation/config/trailer.adoc
index 60bc221c88b801..1bc70192d3a547 100644
--- a/Documentation/config/trailer.adoc
+++ b/Documentation/config/trailer.adoc
@@ -1,21 +1,21 @@
-trailer.separators::
+`trailer.separators`::
 	This option tells which characters are recognized as trailer
-	separators. By default only ':' is recognized as a trailer
-	separator, except that '=' is always accepted on the command
+	separators. By default only `:` is recognized as a trailer
+	separator, except that `=` is always accepted on the command
 	line for compatibility with other git commands.
 +
 The first character given by this option will be the default character
 used when another separator is not specified in the config for this
 trailer.
 +
-For example, if the value for this option is "%=$", then only lines
-using the format '' with  containing '%', '='
-or '$' and then spaces will be considered trailers. And '%' will be
+For example, if the value for this option is `%=$`, then only lines
+using the format __ with __ containing `%`, `=`
+or `$` and then spaces will be considered trailers. And `%` will be
 the default separator used, so by default trailers will appear like:
-'% ' (one percent sign and one space will appear between
+`% ` (one percent sign and one space will appear between
 the key and the value).
 
-trailer.where::
+`trailer.where`::
 	This option tells where a new trailer will be added.
 +
 This can be `end`, which is the default, `start`, `after` or `before`.
@@ -27,41 +27,41 @@ If it is `start`, then each new trailer will appear at the start,
 instead of the end, of the existing trailers.
 +
 If it is `after`, then each new trailer will appear just after the
-last trailer with the same .
+last trailer with the same __.
 +
 If it is `before`, then each new trailer will appear just before the
-first trailer with the same .
+first trailer with the same __.
 
-trailer.ifexists::
+`trailer.ifexists`::
 	This option makes it possible to choose what action will be
 	performed when there is already at least one trailer with the
-	same  in the input.
+	same __ in the input.
 +
 The valid values for this option are: `addIfDifferentNeighbor` (this
 is the default), `addIfDifferent`, `add`, `replace` or `doNothing`.
 +
 With `addIfDifferentNeighbor`, a new trailer will be added only if no
-trailer with the same (, ) pair is above or below the line
+trailer with the same (__, __) pair is above or below the line
 where the new trailer will be added.
 +
 With `addIfDifferent`, a new trailer will be added only if no trailer
-with the same (, ) pair is already in the input.
+with the same (__, __) pair is already in the input.
 +
 With `add`, a new trailer will be added, even if some trailers with
-the same (, ) pair are already in the input.
+the same (__, __) pair are already in the input.
 +
-With `replace`, an existing trailer with the same  will be
+With `replace`, an existing trailer with the same __ will be
 deleted and the new trailer will be added. The deleted trailer will be
-the closest one (with the same ) to the place where the new one
+the closest one (with the same __) to the place where the new one
 will be added.
 +
 With `doNothing`, nothing will be done; that is no new trailer will be
-added if there is already one with the same  in the input.
+added if there is already one with the same __ in the input.
 
-trailer.ifmissing::
+`trailer.ifmissing`::
 	This option makes it possible to choose what action will be
 	performed when there is not yet any trailer with the same
-	 in the input.
+	__ in the input.
 +
 The valid values for this option are: `add` (this is the default) and
 `doNothing`.
@@ -70,67 +70,68 @@ With `add`, a new trailer will be added.
 +
 With `doNothing`, nothing will be done.
 
-trailer..key::
-	Defines a  for the . The  must be a
-	prefix (case does not matter) of the . For example, in `git
-	config trailer.ack.key "Acked-by"` the "Acked-by" is the  and
-	the "ack" is the . This configuration allows the shorter
+`trailer..key`::
+	Defines a __ for the __. The __ must be a
+	prefix (case does not matter) of the __. For example, in `git
+	config trailer.ack.key "Acked-by"` the `Acked-by` is the __ and
+	the `ack` is the __. This configuration allows the shorter
 	`--trailer "ack:..."` invocation on the command line using the "ack"
-	 instead of the longer `--trailer "Acked-by:..."`.
+	`` instead of the longer `--trailer "Acked-by:..."`.
 +
-At the end of the , a separator can appear and then some
-space characters. By default the only valid separator is ':',
+At the end of the __, a separator can appear and then some
+space characters. By default the only valid separator is `:`,
 but this can be changed using the `trailer.separators` config
 variable.
 +
 If there is a separator in the key, then it overrides the default
 separator when adding the trailer.
 
-trailer..where::
-	This option takes the same values as the 'trailer.where'
+`trailer..where`::
+	This option takes the same values as the `trailer.where`
 	configuration variable and it overrides what is specified by
-	that option for trailers with the specified .
+	that option for trailers with the specified __.
 
-trailer..ifexists::
-	This option takes the same values as the 'trailer.ifexists'
+`trailer..ifexists`::
+	This option takes the same values as the `trailer.ifexists`
 	configuration variable and it overrides what is specified by
-	that option for trailers with the specified .
+	that option for trailers with the specified __.
 
-trailer..ifmissing::
-	This option takes the same values as the 'trailer.ifmissing'
+`trailer..ifmissing`::
+	This option takes the same values as the `trailer.ifmissing`
 	configuration variable and it overrides what is specified by
-	that option for trailers with the specified .
+	that option for trailers with the specified __.
 
-trailer..command::
-	Deprecated in favor of 'trailer..cmd'.
-	This option behaves in the same way as 'trailer..cmd', except
+`trailer..command`::
+	Deprecated in favor of `trailer..cmd`.
+	This option behaves in the same way as `trailer..cmd`, except
 	that it doesn't pass anything as argument to the specified command.
-	Instead the first occurrence of substring $ARG is replaced by the
-	 that would be passed as argument.
+	Instead the first occurrence of substring `$ARG` is replaced by the
+	__ that would be passed as argument.
 +
-Note that $ARG in the user's command is
-only replaced once and that the original way of replacing $ARG is not safe.
+Note that `$ARG` in the user's command is
+only replaced once and that the original way of replacing `$ARG` is not safe.
 +
-When both 'trailer..cmd' and 'trailer..command' are given
-for the same , 'trailer..cmd' is used and
-'trailer..command' is ignored.
+When both `trailer..cmd` and `trailer..command` are given
+for the same __, `trailer..cmd` is used and
+`trailer..command` is ignored.
 
-trailer..cmd::
+`trailer..cmd`::
 	This option can be used to specify a shell command that will be called
-	once to automatically add a trailer with the specified , and then
-	called each time a '--trailer =' argument is specified to
-	modify the  of the trailer that this option would produce.
+	once to automatically add a trailer with the specified __, and then
+	called each time a `--trailer =` argument is specified to
+	modify the __ of the trailer that this option would produce.
 +
 When the specified command is first called to add a trailer
-with the specified , the behavior is as if a special
-'--trailer =' argument was added at the beginning
-of the "git interpret-trailers" command, where 
-is taken to be the standard output of the command with any
-leading and trailing whitespace trimmed off.
+with the specified __, the behavior is as if a special
+`--trailer =` argument was added at the beginning
+of linkgit:git-interpret-trailers[1], where __ is taken to be the
+standard output of the command with any leading and trailing whitespace
+trimmed off.
 +
-If some '--trailer =' arguments are also passed
+If some `--trailer =` arguments are also passed
 on the command line, the command is called again once for each
-of these arguments with the same . And the  part
+of these arguments with the same __. And the __ part
 of these arguments, if any, will be passed to the command as its
-first argument. This way the command can produce a  computed
-from the  passed in the '--trailer =' argument.
+first argument. This way the command can produce a __ computed
+from the __ passed in the `--trailer =`
+argument.
diff --git a/Documentation/date-formats.adoc b/Documentation/date-formats.adoc
index e24517c496fce4..330424b2baccda 100644
--- a/Documentation/date-formats.adoc
+++ b/Documentation/date-formats.adoc
@@ -9,6 +9,11 @@ Git internal format::
 	`` is the number of seconds since the UNIX epoch.
 	`` is a positive or negative offset from UTC.
 	For example CET (which is 1 hour ahead of UTC) is `+0100`.
++
+It is safer to prepend the `` with `@` (e.g.,
+`@0 +0000`), which forces Git to interpret it as a raw timestamp. This
+is required for values less than 100,000,000 (which have fewer than 9
+digits) to avoid confusion with other date formats like `YYYYMMDD`.
 
 RFC 2822::
 	The standard date format as described by RFC 2822, for example
diff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc
index e161260358fff5..b9ace2aa4b3092 100644
--- a/Documentation/diff-context-options.adoc
+++ b/Documentation/diff-context-options.adoc
@@ -1,7 +1,9 @@
 `-U`::
 `--unified=`::
-	Generate diffs with __ lines of context. Defaults to `diff.context`
-	or 3 if the config option is unset.
+	Generate diffs with __ lines of context. The number of context
+	lines defaults to `diff.context` or 3 if the configuration variable
+	is unset. (`-U` without `` is silently accepted as a synonym for
+	`-p` due to a historical accident).
 
 `--inter-hunk-context=`::
 	Show the context between diff hunks, up to the specified __
diff --git a/Documentation/diff-format.adoc b/Documentation/diff-format.adoc
index 9f7e9882418349..ef5df140fe5814 100644
--- a/Documentation/diff-format.adoc
+++ b/Documentation/diff-format.adoc
@@ -19,9 +19,9 @@ compared differs:
 `git-diff-files [...]`::
         compares the index and the files on the filesystem.
 
-The `git-diff-tree` command begins its output by printing the hash of
-what is being compared. After that, all the commands print one output
-line per changed file.
+All the commands print one output line per changed file,
+except `git diff-files` in the case of an unmerged file, which prints
+both an "unmerged" and an "in-place edit" line.
 
 An output line is formatted this way:
 
@@ -37,13 +37,13 @@ unmerged       :000000 000000 0000000 0000000 U file6
 That is, from the left to the right:
 
 . a colon.
-. mode for "src"; 000000 if creation or unmerged.
+. mode for "src"; 000000 if creation, or if "src" is from the index and is unmerged.
 . a space.
-. mode for "dst"; 000000 if deletion or unmerged.
+. mode for "dst"; 000000 if deletion, or if "dst" is from the index and is unmerged.
 . a space.
-. sha1 for "src"; 0\{40\} if creation or unmerged.
+. sha1 for "src"; 0\{40\} if creation, or if "src" is from the index and is unmerged.
 . a space.
-. sha1 for "dst"; 0\{40\} if deletion, unmerged or "work tree out of sync with the index".
+. sha1 for "dst"; 0\{40\} if deletion, if "dst" is from the index and is unmerged, or if "dst" is from the work tree and is out of sync with the index.
 . a space.
 . status, followed by optional "score" number.
 . a tab or a NUL when `-z` option is used.
diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc
index 9cdad6f72a0c7d..c8242e24627eef 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -127,8 +127,10 @@ endif::git-log[]
 
 `-U`::
 `--unified=`::
-	Generate diffs with __ lines of context instead of
-	the usual three.
+	Generate diffs with __ lines of context. The number of context
+	lines defaults to `diff.context` or 3 if the configuration variable
+	is unset. (`-U` without `` is silently accepted as a synonym for
+	`-p` due to a historical accident).
 ifndef::git-format-patch[]
 	Implies `--patch`.
 endif::git-format-patch[]
@@ -455,6 +457,14 @@ endif::git-diff[]
 +
 Note that despite the name of the first mode, color is used to
 highlight the changed parts in all modes if enabled.
++
+The `--word-diff` option operates by taking the same line-by-line
+diff that is produced without the option and computing
+word-by-word changes within each hunk.  This may produce a
+larger diff than a dedicated word-diff tool would.  If Git
+acquires a different implementation in the future, the output
+may change.  Note that this is similar to the `--diff-algorithm`
+option, which may also change the output.
 
 `--word-diff-regex=`::
 	Use __ to decide what a word is, instead of considering
@@ -859,10 +869,18 @@ endif::git-format-patch[]
 	Do not show any source or destination prefix.
 
 `--default-prefix`::
+ifdef::git-format-patch[]
+	Use the default source and destination prefixes ("a/" and "b/").
+	This overrides configuration variables such as `format.noprefix`,
+	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
+	(see linkgit:git-config[1]).
+endif::git-format-patch[]
+ifndef::git-format-patch[]
 	Use the default source and destination prefixes ("a/" and "b/").
 	This overrides configuration variables such as `diff.noprefix`,
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).
+endif::git-format-patch[]
 
 `--line-prefix=`::
 	Prepend an additional __ to every line of output.
diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc
index fcba46ee9e5d61..035f780e583cee 100644
--- a/Documentation/fetch-options.adoc
+++ b/Documentation/fetch-options.adoc
@@ -1,6 +1,6 @@
 `--all`::
 `--no-all`::
-	Fetch all remotes, except for the ones that has the
+	Fetch all remotes, except for the ones that have the
 	`remote..skipFetchAll` configuration variable set.
 	This overrides the configuration variable `fetch.all`.
 
@@ -49,6 +49,7 @@ the current repository has the same history as the source repository.
 	`.git/shallow`. This option updates `.git/shallow` and accepts such
 	refs.
 
+`--negotiation-restrict=(|)`::
 `--negotiation-tip=(|)`::
 	By default, Git will report, to the server, commits reachable
 	from all local refs to find common commits in an attempt to
@@ -58,6 +59,9 @@ the current repository has the same history as the source repository.
 	local ref is likely to have commits in common with the
 	upstream ref being fetched.
 +
+`--negotiation-restrict` is the preferred name for this option;
+`--negotiation-tip` is accepted as a synonym.
++
 This option may be specified more than once; if so, Git will report
 commits reachable from any of the given commits.
 +
@@ -69,9 +73,32 @@ See also the `fetch.negotiationAlgorithm` and `push.negotiate`
 configuration variables documented in linkgit:git-config[1], and the
 `--negotiate-only` option below.
 
+`--negotiation-include=(|)`::
+	Ensure that the commits at the given tips are always sent as "have"
+	lines during fetch negotiation, regardless of what the negotiation
+	algorithm selects.  This is useful to guarantee that common
+	history reachable from specific refs is always considered, even
+	when `--negotiation-restrict` restricts the set of tips or when
+	the negotiation algorithm would otherwise skip them.
++
+This option may be specified more than once; if so, each commit is sent
+unconditionally.
++
+The argument may be an exact ref name (e.g. `refs/heads/release`), an
+object hash, or a glob pattern (e.g. `refs/heads/release/{asterisk}`).
+The pattern syntax is the same as for `--negotiation-restrict`.
++
+If `--negotiation-restrict` is used, the have set is first restricted by
+that option and then increased to include the tips specified by
+`--negotiation-include`.
++
+If this option is not specified on the command line, then any
+`remote..negotiationInclude` config values for the current remote
+are used instead.
+
 `--negotiate-only`::
 	Do not fetch anything from the server, and instead print the
-	ancestors of the provided `--negotiation-tip=` arguments,
+	ancestors of the provided `--negotiation-restrict=` arguments,
 	which we have in common with the server.
 +
 This is incompatible with `--recurse-submodules=(yes|on-demand)`.
@@ -88,6 +115,25 @@ linkgit:git-config[1].
 This is incompatible with `--recurse-submodules=(yes|on-demand)` and takes
 precedence over the `fetch.output` config option.
 
+`--filter=`::
+	Use the partial clone feature and request that the server sends
+	a subset of reachable objects according to a given object filter.
+	When using `--filter`, the supplied __ is used for
+	the partial fetch.
++
+If `--filter=auto` is used, the filter specification is determined
+automatically by combining the filter specifications advertised by
+the server for the promisor remotes that the client accepts (see
+linkgit:gitprotocol-v2[5] and the `promisor.acceptFromServer`
+configuration option in linkgit:git-config[1]).
++
+For details on all other available filter specifications, see the
+`--filter=` option in linkgit:git-rev-list[1].
++
+For example, `--filter=blob:none` will filter out all blobs (file
+contents) until needed by Git. Also, `--filter=blob:limit=` will
+filter out all blobs of size at least __.
+
 ifndef::git-pull[]
 `--write-fetch-head`::
 `--no-write-fetch-head`::
@@ -234,6 +280,8 @@ endif::git-pull[]
 `--jobs=`::
 	Parallelize all forms of fetching up to __ jobs at a time.
 +
+A value of 0 will use some reasonable default.
++
 If the `--multiple` option was specified, the different remotes will be fetched
 in parallel. If multiple submodules are fetched, they will be fetched in
 parallel. To control them independently, use the config settings
diff --git a/Documentation/for-each-ref-options.adoc b/Documentation/for-each-ref-options.adoc
index f13efb5f2556cf..54e2fa95c2911e 100644
--- a/Documentation/for-each-ref-options.adoc
+++ b/Documentation/for-each-ref-options.adoc
@@ -30,8 +30,8 @@ TAB %(refname)`.
 
 `--color[=]`::
 	Respect any colors specified in the `--format` option. The
-	_` is absent, behave as if `always` was given).
+	__ field must be one of `always`, `never`, or `auto` (if
+	__ is absent, behave as if `always` was given).
 
 `--shell`::
 `--perl`::
diff --git a/Documentation/format-patch-caveats.adoc b/Documentation/format-patch-caveats.adoc
new file mode 100644
index 00000000000000..133e4757e7946c
--- /dev/null
+++ b/Documentation/format-patch-caveats.adoc
@@ -0,0 +1,33 @@
+The output from linkgit:git-format-patch[1] can lead to a different
+commit message when applied with linkgit:git-am[1]. The patch that is
+applied may also be different from the one that was generated, or patch
+application may fail outright.
+ifdef::git-am[]
+See the <> section above for the syntactic rules.
+endif::git-am[]
+
+ifndef::git-am[]
+include::format-patch-end-of-commit-message.adoc[]
+endif::git-am[]
+
+Note that this is especially problematic for unindented diffs that occur
+in the commit message; the diff in the commit message might get applied
+along with the patch section, or the patch application machinery might
+trip up because the patch target doesn't apply. This could for example
+be caused by a diff in a Markdown code block.
+
+The solution for this is to indent the diff or other text that could
+cause problems.
+
+This loss of fidelity might be simple to notice if you are applying
+patches directly from a mailbox. However, changes originating from Git
+could be applied in bulk, in which case this would be much harder to
+notice. This could for example be a Linux distribution which uses patch
+files to apply changes on top of the commits from the upstream
+repositories. This goes to show that this behavior does not only impact
+email workflows.
+
+Given these limitations, one might be tempted to use a general-purpose
+utility like `patch`(1) instead. However, `patch`(1) will not only look for
+unindented diffs (like linkgit:git-am[1]) but will try to apply indented
+diffs as well.
diff --git a/Documentation/format-patch-end-of-commit-message.adoc b/Documentation/format-patch-end-of-commit-message.adoc
new file mode 100644
index 00000000000000..a1a624d2ac5bc2
--- /dev/null
+++ b/Documentation/format-patch-end-of-commit-message.adoc
@@ -0,0 +1,8 @@
+Any line that is of the form:
+
+* three-dashes and end-of-line, or
+* a line that begins with `diff -`, or
+* a line that begins with `Index: `
+
+is taken as the beginning of a patch, and the commit log message
+is terminated before the first occurrence of such a line.
diff --git a/Documentation/fsck-msgids.adoc b/Documentation/fsck-msgids.adoc
index acac9683af83f4..6a4db3a9916ea6 100644
--- a/Documentation/fsck-msgids.adoc
+++ b/Documentation/fsck-msgids.adoc
@@ -13,6 +13,9 @@
 `badGpgsig`::
 	(ERROR) A tag contains a bad (truncated) signature (e.g., `gpgsig`) header.
 
+`badHeadTarget`::
+	(ERROR) The `HEAD` ref is a symref that does not refer to a branch.
+
 `badHeaderContinuation`::
 	(ERROR) A continuation header (such as for `gpgsig`) is unexpectedly truncated.
 
@@ -41,6 +44,9 @@
 `badRefName`::
 	(ERROR) A ref has an invalid format.
 
+`badRefOid`::
+	(ERROR) A ref points to an invalid object ID.
+
 `badReferentName`::
 	(ERROR) The referent name of a symref is invalid.
 
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
index 6192daeb0371cf..941135dc637d90 100644
--- a/Documentation/git-add.adoc
+++ b/Documentation/git-add.adoc
@@ -75,7 +75,10 @@ in linkgit:gitglossary[7].
 
 `-f`::
 `--force`::
-	Allow adding otherwise ignored files.
+	Allow adding otherwise ignored files. The option is also used when
+	`submodule..ignore=all` is set, but you want to stage an
+	update of the submodule. The `path` to the submodule must be explicitly
+	specified.
 
 `--sparse`::
 	Allow updating index entries outside of the sparse-checkout cone.
diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
index b23b4fba2013c2..28adf4cf656651 100644
--- a/Documentation/git-am.adoc
+++ b/Documentation/git-am.adoc
@@ -8,17 +8,17 @@ git-am - Apply a series of patches from a mailbox
 
 SYNOPSIS
 --------
-[verse]
-'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--no-verify]
+[synopsis]
+git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify]
 	 [--[no-]3way] [--interactive] [--committer-date-is-author-date]
 	 [--ignore-date] [--ignore-space-change | --ignore-whitespace]
 	 [--whitespace=] [-C] [-p] [--directory=]
 	 [--exclude=] [--include=] [--reject] [-q | --quiet]
-	 [--[no-]scissors] [-S[]] [--patch-format=]
+	 [--[no-]scissors] [-S[]] [--patch-format=]
 	 [--quoted-cr=]
 	 [--empty=(stop|drop|keep)]
 	 [( | )...]
-'git am' (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)
+git am (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)
 
 DESCRIPTION
 -----------
@@ -30,44 +30,45 @@ history without merges.
 
 OPTIONS
 -------
-(|)...::
+`(|)...`::
 	The list of mailbox files to read patches from. If you do not
 	supply this argument, the command reads from the standard input.
 	If you supply directories, they will be treated as Maildirs.
 
--s::
---signoff::
-	Add a `Signed-off-by` trailer to the commit message, using
-	the committer identity of yourself.
-	See the signoff option in linkgit:git-commit[1] for more information.
+`-s`::
+`--signoff`::
+	Add a `Signed-off-by` trailer to the commit message (see
+	linkgit:git-interpret-trailers[1]), using the committer identity
+	of yourself.  See the signoff option in linkgit:git-commit[1]
+	for more information.
 
--k::
---keep::
-	Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
+`-k`::
+`--keep`::
+	Pass `-k` flag to linkgit:git-mailinfo[1].
 
---keep-non-patch::
-	Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
+`--keep-non-patch`::
+	Pass `-b` flag to linkgit:git-mailinfo[1].
 
---keep-cr::
---no-keep-cr::
-	With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1])
+`--keep-cr`::
+`--no-keep-cr`::
+	With `--keep-cr`, call linkgit:git-mailsplit[1]
 	with the same option, to prevent it from stripping CR at the end of
 	lines. `am.keepcr` configuration variable can be used to specify the
 	default behaviour.  `--no-keep-cr` is useful to override `am.keepcr`.
 
--c::
---scissors::
+`-c`::
+`--scissors`::
 	Remove everything in body before a scissors line (see
 	linkgit:git-mailinfo[1]). Can be activated by default using
 	the `mailinfo.scissors` configuration variable.
 
---no-scissors::
+`--no-scissors`::
 	Ignore scissors lines (see linkgit:git-mailinfo[1]).
 
---quoted-cr=::
-	This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]).
+`--quoted-cr=`::
+	This flag will be passed down to linkgit:git-mailinfo[1].
 
---empty=(drop|keep|stop)::
+`--empty=(drop|keep|stop)`::
 	How to handle an e-mail message lacking a patch:
 +
 --
@@ -81,24 +82,24 @@ OPTIONS
 	session. This is the default behavior.
 --
 
--m::
---message-id::
-	Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]),
-	so that the Message-ID header is added to the commit message.
+`-m`::
+`--message-id`::
+	Pass the `-m` flag to linkgit:git-mailinfo[1],
+	so that the `Message-ID` header is added to the commit message.
 	The `am.messageid` configuration variable can be used to specify
 	the default behaviour.
 
---no-message-id::
+`--no-message-id`::
 	Do not add the Message-ID header to the commit message.
-	`no-message-id` is useful to override `am.messageid`.
+	`--no-message-id` is useful to override `am.messageid`.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Be quiet. Only print error messages.
 
--u::
---utf8::
-	Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
+`-u`::
+`--utf8`::
+	Pass `-u` flag to linkgit:git-mailinfo[1].
 	The proposed commit log message taken from the e-mail
 	is re-coded into UTF-8 encoding (configuration variable
 	`i18n.commitEncoding` can be used to specify the project's
@@ -107,85 +108,93 @@ OPTIONS
 This was optional in prior versions of git, but now it is the
 default.   You can use `--no-utf8` to override this.
 
---no-utf8::
-	Pass `-n` flag to 'git mailinfo' (see
-	linkgit:git-mailinfo[1]).
+`--no-utf8`::
+	Pass `-n` flag to linkgit:git-mailinfo[1].
 
--3::
---3way::
---no-3way::
+`-3`::
+`--3way`::
+`--no-3way`::
 	When the patch does not apply cleanly, fall back on
 	3-way merge if the patch records the identity of blobs
 	it is supposed to apply to and we have those blobs
 	available locally. `--no-3way` can be used to override
-	am.threeWay configuration variable. For more information,
-	see am.threeWay in linkgit:git-config[1].
+	`am.threeWay` configuration variable. For more information,
+	see `am.threeWay` in linkgit:git-config[1].
 
 include::rerere-options.adoc[]
 
---ignore-space-change::
---ignore-whitespace::
---whitespace=::
--C::
--p::
---directory=::
---exclude=::
---include=::
---reject::
-	These flags are passed to the 'git apply' (see linkgit:git-apply[1])
-	program that applies
-	the patch.
+`--ignore-space-change`::
+`--ignore-whitespace`::
+`--whitespace=`::
+`-C`::
+`-p`::
+`--directory=`::
+`--exclude=`::
+`--include=`::
+`--reject`::
+	These flags are passed to the linkgit:git-apply[1] program that
+	applies the patch.
 +
-Valid  for the `--whitespace` option are:
+Valid __ for the `--whitespace` option are:
 `nowarn`, `warn`, `fix`, `error`, and `error-all`.
 
---patch-format::
+`--patch-format`::
 	By default the command will try to detect the patch format
 	automatically. This option allows the user to bypass the automatic
 	detection and specify the patch format that the patch(es) should be
 	interpreted as. Valid formats are mbox, mboxrd,
 	stgit, stgit-series, and hg.
 
--i::
---interactive::
+`-i`::
+`--interactive`::
 	Run interactively.
 
--n::
---no-verify::
-	By default, the pre-applypatch and applypatch-msg hooks are run.
-	When any of `--no-verify` or `-n` is given, these are bypassed.
-	See also linkgit:githooks[5].
+`--verify`::
+`-n`::
+`--no-verify`::
+	Run the `pre-applypatch` and `applypatch-msg` hooks. This is the
+	default. Skip these hooks with `-n` or `--no-verify`. See also
+	linkgit:githooks[5].
++
+Note that `post-applypatch` cannot be skipped.
 
---committer-date-is-author-date::
+`--committer-date-is-author-date`::
 	By default the command records the date from the e-mail
 	message as the commit author date, and uses the time of
 	commit creation as the committer date. This allows the
 	user to lie about the committer date by using the same
 	value as the author date.
-
---ignore-date::
++
+WARNING: The history walking machinery assumes that commits have
+non-decreasing commit timestamps. You should consider if you really need
+to use this option. Then you should only use this option to override the
+committer date when applying commits on top of a base which commit is
+older (in terms of the commit date) than the oldest patch you are
+applying.
+
+`--ignore-date`::
 	By default the command records the date from the e-mail
 	message as the commit author date, and uses the time of
 	commit creation as the committer date. This allows the
 	user to lie about the author date by using the same
 	value as the committer date.
 
---skip::
+`--skip`::
 	Skip the current patch.  This is only meaningful when
 	restarting an aborted patch.
 
--S[]::
---gpg-sign[=]::
---no-gpg-sign::
-	GPG-sign commits. The `keyid` argument is optional and
+`-S[]`::
+`--gpg-sign[=]`::
+`--no-gpg-sign`::
+	GPG-sign commits. The __ is optional and
 	defaults to the committer identity; if specified, it must be
 	stuck to the option without a space. `--no-gpg-sign` is useful to
 	countermand both `commit.gpgSign` configuration variable, and
 	earlier `--gpg-sign`.
 
---continue::
--r::
---resolved::
+`--continue`::
+`-r`::
+`--resolved`::
 	After a patch failure (e.g. attempting to apply
 	conflicting patch), the user has applied it by hand and
 	the index file stores the result of the application.
@@ -193,39 +202,41 @@ Valid  for the `--whitespace` option are:
 	extracted from the e-mail message and the current index
 	file, and continue.
 
---resolvemsg=::
-	When a patch failure occurs,  will be printed
+`--resolvemsg=`::
+	When a patch failure occurs, __ will be printed
 	to the screen before exiting.  This overrides the
 	standard message informing you to use `--continue`
 	or `--skip` to handle the failure.  This is solely
-	for internal use between 'git rebase' and 'git am'.
+	for internal use between linkgit:git-rebase[1] and
+	linkgit:git-am[1].
 
---abort::
+`--abort`::
 	Restore the original branch and abort the patching operation.
 	Revert the contents of files involved in the am operation to their
 	pre-am state.
 
---quit::
-	Abort the patching operation but keep HEAD and the index
+`--quit`::
+	Abort the patching operation but keep `HEAD` and the index
 	untouched.
 
---retry::
+`--retry`::
 	Try to apply the last conflicting patch again. This is generally
 	only useful for passing extra options to the retry attempt
 	(e.g., `--3way`), since otherwise you'll just see the same
 	failure again.
 
---show-current-patch[=(diff|raw)]::
-	Show the message at which `git am` has stopped due to
+`--show-current-patch[=(diff|raw)]`::
+	Show the message at which linkgit:git-am[1] has stopped due to
 	conflicts.  If `raw` is specified, show the raw contents of
 	the e-mail message; if `diff`, show the diff portion only.
 	Defaults to `raw`.
 
---allow-empty::
+`--allow-empty`::
 	After a patch failure on an input e-mail message lacking a patch,
 	create an empty commit with the contents of the e-mail message
 	as its log message.
 
+[[discussion]]
 DISCUSSION
 ----------
 
@@ -245,16 +256,13 @@ where the patch begins.  Excess whitespace at the end of each
 line is automatically stripped.
 
 The patch is expected to be inline, directly following the
-message.  Any line that is of the form:
-
-* three-dashes and end-of-line, or
-* a line that begins with "diff -", or
-* a line that begins with "Index: "
+message.
+include::format-patch-end-of-commit-message.adoc[]
 
-is taken as the beginning of a patch, and the commit log message
-is terminated before the first occurrence of such a line.
+This means that the contents of the commit message can inadvertently
+interrupt the processing (see the <> section below).
 
-When initially invoking `git am`, you give it the names of the mailboxes
+When initially invoking linkgit:git-am[1], you give it the names of the mailboxes
 to process.  Upon seeing the first patch that does not apply, it
 aborts in the middle.  You can recover from this in one of two ways:
 
@@ -270,11 +278,18 @@ operation is finished, so if you decide to start over from scratch,
 run `git am --abort` before running the command with mailbox
 names.
 
-Before any patches are applied, ORIG_HEAD is set to the tip of the
+Before any patches are applied, `ORIG_HEAD` is set to the tip of the
 current branch.  This is useful if you have problems with multiple
-commits, like running 'git am' on the wrong branch or an error in the
-commits that is more easily fixed by changing the mailbox (e.g.
-errors in the "From:" lines).
+commits, like running linkgit:git-am[1] on the wrong branch or an error
+in the commits that is more easily fixed by changing the mailbox (e.g.
+errors in the `From:` lines).
+
+[[caveats]]
+CAVEATS
+-------
+
+:git-am: 1
+include::format-patch-caveats.adoc[]
 
 HOOKS
 -----
@@ -282,6 +297,8 @@ This command can run `applypatch-msg`, `pre-applypatch`,
 and `post-applypatch` hooks.  See linkgit:githooks[5] for more
 information.
 
+See the `--verify`/`-n`/`--no-verify` options.
+
 CONFIGURATION
 -------------
 
diff --git a/Documentation/git-apply.adoc b/Documentation/git-apply.adoc
index 6c71ee69da977d..3f22dac1ce8edd 100644
--- a/Documentation/git-apply.adoc
+++ b/Documentation/git-apply.adoc
@@ -8,8 +8,8 @@ git-apply - Apply a patch to files and/or to the index
 
 SYNOPSIS
 --------
-[verse]
-'git apply' [--stat] [--numstat] [--summary] [--check]
+[synopsis]
+git apply [--stat] [--numstat] [--summary] [--check]
 	  [--index | --intent-to-add] [--3way] [--ours | --theirs | --union]
 	  [--apply] [--no-add] [--build-fake-ancestor=] [-R | --reverse]
 	  [--allow-binary-replacement | --binary] [--reject] [-z]
@@ -35,33 +35,33 @@ linkgit:git-format-patch[1] and/or received by email.
 
 OPTIONS
 -------
-...::
-	The files to read the patch from.  '-' can be used to read
+`...`::
+	The files to read the patch from.  `-` can be used to read
 	from the standard input.
 
---stat::
+`--stat`::
 	Instead of applying the patch, output diffstat for the
 	input.  Turns off "apply".
 
---numstat::
+`--numstat`::
 	Similar to `--stat`, but shows the number of added and
 	deleted lines in decimal notation and the pathname without
 	abbreviation, to make it more machine friendly.  For
 	binary files, outputs two `-` instead of saying
 	`0 0`.  Turns off "apply".
 
---summary::
+`--summary`::
 	Instead of applying the patch, output a condensed
 	summary of information obtained from git diff extended
 	headers, such as creations, renames, and mode changes.
 	Turns off "apply".
 
---check::
+`--check`::
 	Instead of applying the patch, see if the patch is
 	applicable to the current working tree and/or the index
 	file and detects errors.  Turns off "apply".
 
---index::
+`--index`::
 	Apply the patch to both the index and the working tree (or
 	merely check that it would apply cleanly to both if `--check` is
 	in effect). Note that `--index` expects index entries and
@@ -70,13 +70,13 @@ OPTIONS
 	raise an error if they are not, even if the patch would apply
 	cleanly to both the index and the working tree in isolation.
 
---cached::
+`--cached`::
 	Apply the patch to just the index, without touching the working
 	tree. If `--check` is in effect, merely check that it would
 	apply cleanly to the index entry.
 
--N::
---intent-to-add::
+`-N`::
+`--intent-to-add`::
 	When applying the patch only to the working tree, mark new
 	files to be added to the index later (see `--intent-to-add`
 	option in linkgit:git-add[1]). This option is ignored if
@@ -84,8 +84,8 @@ OPTIONS
 	repository. Note that `--index` could be implied by other options
 	such as `--3way`.
 
--3::
---3way::
+`-3`::
+`--3way`::
 	Attempt 3-way merge if the patch records the identity of blobs it is supposed
 	to apply to and we have those blobs available locally, possibly leaving the
 	conflict markers in the files in the working tree for the user to
@@ -94,14 +94,14 @@ OPTIONS
 	When used with the `--cached` option, any conflicts are left at higher stages
 	in the cache.
 
---ours::
---theirs::
---union::
+`--ours`::
+`--theirs`::
+`--union`::
 	Instead of leaving conflicts in the file, resolve conflicts favouring
-	our (or their or both) side of the lines. Requires --3way.
+	our (or their or both) side of the lines. Requires `--3way`.
 
---build-fake-ancestor=::
-	Newer 'git diff' output has embedded 'index information'
+`--build-fake-ancestor=`::
+	Newer `git diff` output has embedded 'index information'
 	for each blob to help identify the original version that
 	the patch applies to.  When this flag is given, and if
 	the original versions of the blobs are available locally,
@@ -110,18 +110,18 @@ OPTIONS
 When a pure mode change is encountered (which has no index information),
 the information is read from the current index instead.
 
--R::
---reverse::
+`-R`::
+`--reverse`::
 	Apply the patch in reverse.
 
---reject::
-	For atomicity, 'git apply' by default fails the whole patch and
+`--reject`::
+	For atomicity, `git apply` by default fails the whole patch and
 	does not touch the working tree when some of the hunks
 	do not apply.  This option makes it apply
 	the parts of the patch that are applicable, and leave the
-	rejected hunks in corresponding *.rej files.
+	rejected hunks in corresponding `*.rej` files.
 
--z::
+`-z`::
 	When `--numstat` has been given, do not munge pathnames,
 	but use a NUL-terminated machine-readable format.
 +
@@ -129,20 +129,20 @@ Without this option, pathnames with "unusual" characters are quoted as
 explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
--p::
-	Remove  leading path components (separated by slashes) from
+`-p`::
+	Remove __ leading path components (separated by slashes) from
 	traditional diff paths. E.g., with `-p2`, a patch against
 	`a/dir/file` will be applied directly to `file`. The default is
 	1.
 
--C::
-	Ensure at least  lines of surrounding context match before
+`-C`::
+	Ensure at least __ lines of surrounding context match before
 	and after each change.  When fewer lines of surrounding
 	context exist they all must match.  By default no context is
 	ever ignored.
 
---unidiff-zero::
-	By default, 'git apply' expects that the patch being
+`--unidiff-zero`::
+	By default, `git apply` expects that the patch being
 	applied is a unified diff with at least one line of context.
 	This provides good safety measures, but breaks down when
 	applying a diff generated with `--unified=0`. To bypass these
@@ -151,34 +151,34 @@ linkgit:git-config[1]).
 Note, for the reasons stated above, the usage of context-free patches is
 discouraged.
 
---apply::
+`--apply`::
 	If you use any of the options marked "Turns off
-	'apply'" above, 'git apply' reads and outputs the
+	'apply'" above, `git apply` reads and outputs the
 	requested information without actually applying the
 	patch.  Give this flag after those flags to also apply
 	the patch.
 
---no-add::
+`--no-add`::
 	When applying a patch, ignore additions made by the
 	patch.  This can be used to extract the common part between
-	two files by first running 'diff' on them and applying
+	two files by first running `diff` on them and applying
 	the result with this option, which would apply the
 	deletion part but not the addition part.
 
---allow-binary-replacement::
---binary::
+`--allow-binary-replacement`::
+`--binary`::
 	Historically we did not allow binary patch application
 	without an explicit permission from the user, and this
 	flag was the way to do so.  Currently, we always allow binary
 	patch application, so this is a no-op.
 
---exclude=::
-	Don't apply changes to files matching the given path pattern. This can
+`--exclude=`::
+	Don't apply changes to files matching __. This can
 	be useful when importing patchsets, where you want to exclude certain
 	files or directories.
 
---include=::
-	Apply changes to files matching the given path pattern. This can
+`--include=`::
+	Apply changes to files matching the __. This can
 	be useful when importing patchsets, where you want to include certain
 	files or directories.
 +
@@ -188,15 +188,15 @@ patch to each path is used.  A patch to a path that does not match any
 include/exclude pattern is used by default if there is no include pattern
 on the command line, and ignored if there is any include pattern.
 
---ignore-space-change::
---ignore-whitespace::
+`--ignore-space-change`::
+`--ignore-whitespace`::
 	When applying a patch, ignore changes in whitespace in context
 	lines if necessary.
 	Context lines will preserve their whitespace, and they will not
 	undergo whitespace fixing regardless of the value of the
 	`--whitespace` option. New lines will still be fixed, though.
 
---whitespace=::
+`--whitespace=`::
 	When applying a patch, detect a new or modified line that has
 	whitespace errors.  What are considered whitespace errors is
 	controlled by `core.whitespace` configuration.  By default,
@@ -209,7 +209,7 @@ By default, the command outputs warning messages but applies the patch.
 When `git-apply` is used for statistics and not applying a
 patch, it defaults to `nowarn`.
 +
-You can use different `` values to control this
+You can use different __ values to control this
 behavior:
 +
 * `nowarn` turns off the trailing whitespace warning.
@@ -223,48 +223,48 @@ behavior:
   to apply the patch.
 * `error-all` is similar to `error` but shows all errors.
 
---inaccurate-eof::
-	Under certain circumstances, some versions of 'diff' do not correctly
+`--inaccurate-eof`::
+	Under certain circumstances, some versions of `diff` do not correctly
 	detect a missing new-line at the end of the file. As a result, patches
-	created by such 'diff' programs do not record incomplete lines
+	created by such `diff` programs do not record incomplete lines
 	correctly. This option adds support for applying such patches by
 	working around this bug.
 
--v::
---verbose::
+`-v`::
+`--verbose`::
 	Report progress to stderr. By default, only a message about the
 	current patch being applied will be printed. This option will cause
 	additional information to be reported.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Suppress stderr output. Messages about patch status and progress
 	will not be printed.
 
---recount::
+`--recount`::
 	Do not trust the line counts in the hunk headers, but infer them
 	by inspecting the patch (e.g. after editing the patch without
 	adjusting the hunk headers appropriately).
 
---directory=::
-	Prepend  to all filenames.  If a "-p" argument was also passed,
+`--directory=`::
+	Prepend __ to all filenames.  If a `-p` argument was also passed,
 	it is applied before prepending the new root.
 +
 For example, a patch that talks about updating `a/git-gui.sh` to `b/git-gui.sh`
 can be applied to the file in the working tree `modules/git-gui/git-gui.sh` by
 running `git apply --directory=modules/git-gui`.
 
---unsafe-paths::
+`--unsafe-paths`::
 	By default, a patch that affects outside the working area
 	(either a Git controlled working tree, or the current working
-	directory when "git apply" is used as a replacement of GNU
-	patch) is rejected as a mistake (or a mischief).
+	directory when `git apply` is used as a replacement of GNU
+	`patch`) is rejected as a mistake (or a mischief).
 +
-When `git apply` is used as a "better GNU patch", the user can pass
+When `git apply` is used as a "better GNU `patch`", the user can pass
 the `--unsafe-paths` option to override this safety check.  This option
 has no effect when `--index` or `--cached` is in use.
 
---allow-empty::
+`--allow-empty`::
 	Don't return an error for patches containing no diff. This includes
 	empty patches and patches with commit text only.
 
@@ -273,11 +273,12 @@ CONFIGURATION
 
 include::includes/cmd-config-section-all.adoc[]
 
+:git-apply: 1
 include::config/apply.adoc[]
 
 SUBMODULES
 ----------
-If the patch contains any changes to submodules then 'git apply'
+If the patch contains any changes to submodules then `git apply`
 treats these changes as follows.
 
 If `--index` is specified (explicitly or implicitly), then the submodule
diff --git a/Documentation/git-archive.adoc b/Documentation/git-archive.adoc
index a0e3fe7996e57b..086bade6d8d8a2 100644
--- a/Documentation/git-archive.adoc
+++ b/Documentation/git-archive.adoc
@@ -54,6 +54,11 @@ OPTIONS
 	Prepend / to paths in the archive.  Can be repeated; its
 	rightmost value is used for all tracked files.  See below which
 	value gets used by `--add-file`.
++
+The  is used as given and is not normalized. It may
+include leading slashes or parent directory components (e.g.,
+`../`). Some archive consumers may treat such paths as
+potentially unsafe and adjust or warn during extraction.
 
 -o ::
 --output=::
diff --git a/Documentation/git-backfill.adoc b/Documentation/git-backfill.adoc
index b8394dcf22b6e1..82d6a1969d0542 100644
--- a/Documentation/git-backfill.adoc
+++ b/Documentation/git-backfill.adoc
@@ -9,7 +9,7 @@ git-backfill - Download missing objects in a partial clone
 SYNOPSIS
 --------
 [synopsis]
-git backfill [--min-batch-size=] [--[no-]sparse]
+git backfill [--min-batch-size=] [--[no-]sparse] [--[no-]include-edges] []
 
 DESCRIPTION
 -----------
@@ -43,7 +43,7 @@ smaller network calls than downloading the entire repository at clone
 time.
 
 By default, `git backfill` downloads all blobs reachable from the `HEAD`
-commit. This set can be restricted or expanded using various options.
+commit. This set can be restricted or expanded using various options below.
 
 THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR MAY CHANGE IN THE FUTURE.
 
@@ -63,9 +63,32 @@ OPTIONS
 	current sparse-checkout. If the sparse-checkout feature is enabled,
 	then `--sparse` is assumed and can be disabled with `--no-sparse`.
 
+`--include-edges`::
+`--no-include-edges`::
+	Include blobs from boundary commits in the backfill.  Useful in
+	preparation for commands like `git log -p A..B` or `git replay
+	--onto TARGET A..B`, where A..B normally excludes A but you need
+	the blobs from A as well.  `--include-edges` is the default.
+
+``::
+	Backfill only blobs reachable from commits in the specified
+	revision range.  When no __ is specified, it
+	defaults to `HEAD` (i.e. the whole history leading to the
+	current commit).  For a complete list of ways to spell
+	__, see the "Specifying Ranges" section of
+	linkgit:gitrevisions[7].
++
+You may also use commit-limiting options understood by
+linkgit:git-rev-list[1] such as `--first-parent`, `--since`, or pathspecs.
++
+Most `--filter=` options don't work with the purpose of
+`git backfill`, but the `sparse:` filter is integrated to provide a
+focused set of paths to download, distinct from the `--sparse` option.
+
 SEE ALSO
 --------
-linkgit:git-clone[1].
+linkgit:git-clone[1],
+linkgit:git-rev-list[1]
 
 GIT
 ---
diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc
index b0078dda0eb050..d2115b29905f41 100644
--- a/Documentation/git-bisect.adoc
+++ b/Documentation/git-bisect.adoc
@@ -8,20 +8,20 @@ git-bisect - Use binary search to find the commit that introduced a bug
 
 SYNOPSIS
 --------
-[verse]
-'git bisect' start [--term-(bad|new)= --term-(good|old)=]
-		   [--no-checkout] [--first-parent] [ [...]] [--] [...]
-'git bisect' (bad|new|) []
-'git bisect' (good|old|) [...]
-'git bisect' terms [--term-(good|old) | --term-(bad|new)]
-'git bisect' skip [(|)...]
-'git bisect' next
-'git bisect' reset []
-'git bisect' (visualize|view)
-'git bisect' replay 
-'git bisect' log
-'git bisect' run  [...]
-'git bisect' help
+[synopsis]
+git bisect start [--term-(bad|new)= --term-(good|old)=]
+		 [--no-checkout] [--first-parent] [ [...]] [--] [...]
+git bisect (bad|new|) []
+git bisect (good|old|) [...]
+git bisect terms [--term-(good|old) | --term-(bad|new)]
+git bisect skip [(|)...]
+git bisect next
+git bisect reset []
+git bisect (visualize|view)
+git bisect replay 
+git bisect log
+git bisect run  [...]
+git bisect help
 
 DESCRIPTION
 -----------
@@ -94,11 +94,10 @@ Bisect reset
 ~~~~~~~~~~~~
 
 After a bisect session, to clean up the bisection state and return to
-the original HEAD, issue the following command:
+the original `HEAD`, issue the following command:
 
-------------------------------------------------
-$ git bisect reset
-------------------------------------------------
+[synopsis]
+git bisect reset
 
 By default, this will return your tree to the commit that was checked
 out before `git bisect start`.  (A new `git bisect start` will also do
@@ -107,9 +106,9 @@ that, as it cleans up the old bisection state.)
 With an optional argument, you can return to a different commit
 instead:
 
-------------------------------------------------
-$ git bisect reset 
-------------------------------------------------
+[synopsis]
+git bisect reset 
+
 
 For example, `git bisect reset bisect/bad` will check out the first
 bad revision, while `git bisect reset HEAD` will leave you on the
@@ -143,23 +142,20 @@ To use "old" and "new" instead of "good" and bad, you must run `git
 bisect start` without commits as argument and then run the following
 commands to add the commits:
 
-------------------------------------------------
+[synopsis]
 git bisect old []
-------------------------------------------------
 
 to indicate that a commit was before the sought change, or
 
-------------------------------------------------
+[synopsis]
 git bisect new [...]
-------------------------------------------------
 
 to indicate that it was after.
 
 To get a reminder of the currently used terms, use
 
-------------------------------------------------
+[synopsis]
 git bisect terms
-------------------------------------------------
 
 You can get just the old term with `git bisect terms --term-old`
 or `git bisect terms --term-good`; `git bisect terms --term-new`
@@ -171,21 +167,20 @@ If you would like to use your own terms instead of "bad"/"good" or
 subcommands like `reset`, `start`, ...) by starting the
 bisection using
 
-------------------------------------------------
+[synopsis]
 git bisect start --term-old  --term-new 
-------------------------------------------------
 
 For example, if you are looking for a commit that introduced a
 performance regression, you might use
 
 ------------------------------------------------
-git bisect start --term-old fast --term-new slow
+$ git bisect start --term-old fast --term-new slow
 ------------------------------------------------
 
 Or if you are looking for the commit that fixed a bug, you might use
 
 ------------------------------------------------
-git bisect start --term-new fixed --term-old broken
+$ git bisect start --term-new fixed --term-old broken
 ------------------------------------------------
 
 Then, use `git bisect ` and `git bisect ` instead
@@ -194,7 +189,7 @@ of `git bisect good` and `git bisect bad` to mark commits.
 Bisect visualize/view
 ~~~~~~~~~~~~~~~~~~~~~
 
-To see the currently remaining suspects in 'gitk', issue the following
+To see the currently remaining suspects in `gitk`, issue the following
 command during the bisection process (the subcommand `view` can be used
 as an alternative to `visualize`):
 
@@ -203,12 +198,13 @@ $ git bisect visualize
 ------------
 
 Git detects a graphical environment through various environment variables:
-`DISPLAY`, which is set in X Window System environments on Unix systems.
-`SESSIONNAME`, which is set under Cygwin in interactive desktop sessions.
-`MSYSTEM`, which is set under Msys2 and Git for Windows.
-`SECURITYSESSIONID`, which may be set on macOS in interactive desktop sessions.
 
-If none of these environment variables is set, 'git log' is used instead.
+`DISPLAY`:: which is set in X Window System environments on Unix systems.
+`SESSIONNAME`:: which is set under Cygwin in interactive desktop sessions.
+`MSYSTEM`:: which is set under Msys2 and Git for Windows.
+`SECURITYSESSIONID`:: which may be set on macOS in interactive desktop sessions.
+
+If none of these environment variables is set, `git log` is used instead.
 You can also give command-line options such as `-p` and `--stat`.
 
 ------------
@@ -332,18 +328,17 @@ Bisect run
 If you have a script that can tell if the current source code is good
 or bad, you can bisect by issuing the command:
 
-------------
-$ git bisect run my_script arguments
-------------
+[synopsis]
+git bisect run  [...]
 
-Note that the script (`my_script` in the above example) should exit
+Note that __ run with __  should exit
 with code 0 if the current source code is good/old, and exit with a
 code between 1 and 127 (inclusive), except 125, if the current source
 code is bad/new.
 
 Any other exit code will abort the bisect process. It should be noted
-that a program that terminates via `exit(-1)` leaves $? = 255, (see the
-exit(3) manual page), as the value is chopped with `& 0377`.
+that a program that terminates via `exit(-1)` leaves `$?` = 255, (see the
+`exit`(3) manual page), as the value is chopped with `& 0377`.
 
 The special exit code 125 should be used when the current source code
 cannot be tested. If the script exits with this code, the current
@@ -355,12 +350,12 @@ details do not matter, as they are normal errors in the script, as far as
 `bisect run` is concerned).
 
 You may often find that during a bisect session you want to have
-temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a
+temporary modifications (e.g. `s/#define DEBUG 0/#define DEBUG 1/` in a
 header file, or "revision that does not have this commit needs this
 patch applied to work around another problem this bisection is not
 interested in") applied to the revision being tested.
 
-To cope with such a situation, after the inner 'git bisect' finds the
+To cope with such a situation, after the inner `git bisect` finds the
 next revision to test, the script can apply the patch
 before compiling, run the real test, and afterwards decide if the
 revision (possibly with the needed patch) passed the test and then
@@ -370,20 +365,18 @@ determine the eventual outcome of the bisect session.
 
 OPTIONS
 -------
---no-checkout::
-+
-Do not checkout the new working tree at each iteration of the bisection
-process. Instead just update the reference named `BISECT_HEAD` to make
-it point to the commit that should be tested.
+`--no-checkout`::
+	Do not checkout the new working tree at each iteration of the bisection
+	process. Instead just update the reference named `BISECT_HEAD` to make
+	it point to the commit that should be tested.
 +
 This option may be useful when the test you would perform in each step
 does not require a checked out tree.
 +
 If the repository is bare, `--no-checkout` is assumed.
 
---first-parent::
-+
-Follow only the first parent commit upon seeing a merge commit.
+`--first-parent`::
+	Follow only the first parent commit upon seeing a merge commit.
 +
 In detecting regressions introduced through the merging of a branch, the merge
 commit will be identified as introduction of the bug and its ancestors will be
@@ -395,7 +388,7 @@ branch contained broken or non-buildable commits, but the merge itself was OK.
 EXAMPLES
 --------
 
-* Automatically bisect a broken build between v1.2 and HEAD:
+* Automatically bisect a broken build between v1.2 and `HEAD`:
 +
 ------------
 $ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
@@ -403,7 +396,7 @@ $ git bisect run make                # "make" builds the app
 $ git bisect reset                   # quit the bisect session
 ------------
 
-* Automatically bisect a test failure between origin and HEAD:
+* Automatically bisect a test failure between origin and `HEAD`:
 +
 ------------
 $ git bisect start HEAD origin --    # HEAD is bad, origin is good
@@ -430,7 +423,7 @@ and `exit 1` otherwise.
 +
 It is safer if both `test.sh` and `check_test_case.sh` are
 outside the repository to prevent interactions between the bisect,
-make and test processes and the scripts.
+`make` and test processes and the scripts.
 
 * Automatically bisect with temporary modifications (hot-fix):
 +
@@ -491,9 +484,9 @@ $ git bisect run sh -c '
 $ git bisect reset                   # quit the bisect session
 ------------
 +
-In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that
+In this case, when `git bisect run` finishes, `bisect/bad` will refer to a commit that
 has at least one parent whose reachable graph is fully traversable in the sense
-required by 'git pack objects'.
+required by `git pack-objects`.
 
 * Look for a fix instead of a regression in the code
 +
diff --git a/Documentation/git-blame.adoc b/Documentation/git-blame.adoc
index adcbb6f5dc97a3..8808009e87eb1d 100644
--- a/Documentation/git-blame.adoc
+++ b/Documentation/git-blame.adoc
@@ -7,12 +7,12 @@ git-blame - Show what revision and author last modified each line of a file
 
 SYNOPSIS
 --------
-[verse]
-'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
-	    [-L ] [-S ] [-M] [-C] [-C] [-C] [--since=]
-	    [--ignore-rev ] [--ignore-revs-file ]
-	    [--color-lines] [--color-by-age] [--progress] [--abbrev=]
-	    [ --contents  ] [ | --reverse ..] [--] 
+[synopsis]
+git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
+	  [-L ] [-S ] [-M] [-C] [-C] [-C] [--since=]
+	  [--ignore-rev ] [--ignore-revs-file ]
+	  [--color-lines] [--color-by-age] [--progress] [--abbrev=]
+	  [ --contents  ] [ | --reverse ..] [--] 
 
 DESCRIPTION
 -----------
@@ -30,7 +30,7 @@ lines that were copied and pasted from another file, etc., see the
 `-C` and `-M` options.
 
 The report does not tell you anything about lines which have been deleted or
-replaced; you need to use a tool such as 'git diff' or the "pickaxe"
+replaced; you need to use a tool such as `git diff` or the "pickaxe"
 interface briefly mentioned in the following paragraph.
 
 Apart from supporting file annotation, Git also supports searching the
@@ -50,47 +50,47 @@ OPTIONS
 -------
 include::blame-options.adoc[]
 
--c::
+`-c`::
 	Use the same output mode as linkgit:git-annotate[1] (Default: off).
 
---score-debug::
+`--score-debug`::
 	Include debugging information related to the movement of
 	lines between files (see `-C`) and lines moved within a
 	file (see `-M`).  The first number listed is the score.
 	This is the number of alphanumeric characters detected
 	as having been moved between or within files.  This must be above
-	a certain threshold for 'git blame' to consider those lines
+	a certain threshold for `git blame` to consider those lines
 	of code to have been moved.
 
--f::
---show-name::
+`-f`::
+`--show-name`::
 	Show the filename in the original commit.  By default
 	the filename is shown if there is any line that came from a
 	file with a different name, due to rename detection.
 
--n::
---show-number::
+`-n`::
+`--show-number`::
 	Show the line number in the original commit (Default: off).
 
--s::
+`-s`::
 	Suppress the author name and timestamp from the output.
 
--e::
---show-email::
+`-e`::
+`--show-email`::
 	Show the author email instead of the author name (Default: off).
 	This can also be controlled via the `blame.showEmail` config
 	option.
 
--w::
+`-w`::
 	Ignore whitespace when comparing the parent's version and
 	the child's to find where the lines came from.
 
 include::diff-algorithm-option.adoc[]
 
---abbrev=::
-	Instead of using the default 7+1 hexadecimal digits as the
-	abbreviated object name, use +1 digits, where  is at
-	least  but ensures the commit object names are unique.
+`--abbrev=`::
+	Instead of using the default _7+1_ hexadecimal digits as the
+	abbreviated object name, use _+1_ digits, where __ is at
+	least __ but ensures the commit object names are unique.
 	Note that 1 column
 	is used for a caret to mark the boundary commit.
 
@@ -124,21 +124,21 @@ header at the minimum has the first line which has:
 This header line is followed by the following information
 at least once for each commit:
 
-- the author name ("author"), email ("author-mail"), time
-  ("author-time"), and time zone ("author-tz"); similarly
+- the author name (`author`), email (`author-mail`), time
+  (`author-time`), and time zone (`author-tz`); similarly
   for committer.
 - the filename in the commit that the line is attributed to.
-- the first line of the commit log message ("summary").
+- the first line of the commit log message (`summary`).
 
 The contents of the actual line are output after the above
-header, prefixed by a TAB. This is to allow adding more
+header, prefixed by a _TAB_. This is to allow adding more
 header elements later.
 
 The porcelain format generally suppresses commit information that has
 already been seen. For example, two lines that are blamed to the same
 commit will both be shown, but the details for that commit will be shown
 only once. Information which is specific to individual lines will not be
-grouped together, like revs to be marked 'ignored' or 'unblamable'. This
+grouped together, like revs to be marked `ignored` or `unblamable`. This
 is more efficient, but may require more state be kept by the reader. The
 `--line-porcelain` option can be used to output full commit information
 for each line, allowing simpler (but less efficient) usage like:
@@ -152,7 +152,7 @@ for each line, allowing simpler (but less efficient) usage like:
 SPECIFYING RANGES
 -----------------
 
-Unlike 'git blame' and 'git annotate' in older versions of git, the extent
+Unlike `git blame` and `git annotate` in older versions of git, the extent
 of the annotation can be limited to both line ranges and revision
 ranges. The `-L` option, which limits annotation to a range of lines, may be
 specified multiple times.
@@ -173,7 +173,7 @@ which limits the annotation to the body of the `hello` subroutine.
 
 When you are not interested in changes older than version
 v2.6.18, or changes older than 3 weeks, you can use revision
-range specifiers similar to 'git rev-list':
+range specifiers similar to `git rev-list`:
 
 	git blame v2.6.18.. -- foo
 	git blame --since=3.weeks -- foo
@@ -212,8 +212,9 @@ does not contain the actual lines from the file that is being
 annotated.
 
 . Each blame entry always starts with a line of:
-
-	<40-byte-hex-sha1>   
++
+[synopsis]
+<40-byte-hex-sha1>   
 +
 Line numbers count from 1.
 
@@ -224,16 +225,17 @@ Line numbers count from 1.
 
 . Unlike the Porcelain format, the filename information is always
   given and terminates the entry:
-
-	"filename" 
++
+[synopsis]
+filename 
 +
 and thus it is really quite easy to parse for some line- and word-oriented
 parser (which should be quite natural for most scripting languages).
 +
 [NOTE]
 For people who do parsing: to make it more robust, just ignore any
-lines between the first and last one ("" and "filename" lines)
-where you do not recognize the tag words (or care about that particular
+lines between the first and last one (_<40-byte-hex-sha1>_ and `filename`
+lines) where you do not recognize the tag words (or care about that particular
 one) at the beginning of the "extended information" lines. That way, if
 there is ever added information (like the commit encoding or extended
 commit commentary), a blame viewer will not care.
diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc
index c139f55a168d61..86b9181599317e 100644
--- a/Documentation/git-cat-file.adoc
+++ b/Documentation/git-cat-file.adoc
@@ -174,6 +174,11 @@ flush::
 	since the beginning or since the last flush was issued. When `--buffer`
 	is used, no output will come until a `flush` is issued. When `--buffer`
 	is not used, commands are flushed each time without issuing `flush`.
+
+`mailmap ()`::
+	Enable or disable mailmap for subsequent commands. The ``
+	argument accepts the same boolean values as linkgit:git-config[1].
+	The mailmap data is read upon the first use and only once.
 --
 +
 
diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc
index 6f281b298efac1..a8b3b8c2e238bf 100644
--- a/Documentation/git-checkout.adoc
+++ b/Documentation/git-checkout.adoc
@@ -251,20 +251,19 @@ working tree, by copying them from elsewhere, extracting a tarball, etc.
 	are different between the current branch and the branch to
 	which you are switching, the command refuses to switch
 	branches in order to preserve your modifications in context.
-	However, with this option, a three-way merge between the current
-	branch, your working tree contents, and the new branch
-	is done, and you will be on the new branch.
-+
-When a merge conflict happens, the index entries for conflicting
-paths are left unmerged, and you need to resolve the conflicts
-and mark the resolved paths with `git add` (or `git rm` if the merge
-should result in deletion of the path).
+	With this option, the conflicting local changes are
+	automatically stashed before the switch and reapplied
+	afterwards.  If the local changes do not overlap with the
+	differences between branches, the switch proceeds without
+	stashing.  If reapplying the stash results in conflicts, the
+	entry is saved to the stash list.  Resolve the conflicts
+	and run `git stash drop` when done, or clear the working
+	tree (e.g. with `git reset --hard`) before running `git stash
+	pop` later to re-apply your changes.
 +
 When checking out paths from the index, this option lets you recreate
 the conflicted merge in the specified paths.  This option cannot be
 used when checking out paths from a tree-ish.
-+
-When switching branches with `--merge`, staged changes may be lost.
 
 `--conflict=