diff --git a/.b4-config b/.b4-config new file mode 100644 index 00000000000000..fd4fb56b6d5678 --- /dev/null +++ b/.b4-config @@ -0,0 +1,6 @@ +# Note that these are default values that you can tweak via the typical +# git-config(1) machinery. You thus shouldn't ever have to change this file. +# See also https://b4.docs.kernel.org/en/latest/config.html. +[b4] +send-same-thread = shallow +prep-cover-template = ./.b4-cover-template diff --git a/.b4-cover-template b/.b4-cover-template new file mode 100644 index 00000000000000..ab864933b5c846 --- /dev/null +++ b/.b4-cover-template @@ -0,0 +1,11 @@ +${cover} + +--- +${shortlog} + +${diffstat} + +${range_diff} +--- +base-commit: ${base_commit} +${prerequisites} diff --git a/.gitattributes b/.gitattributes index 556322be01b4a8..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 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 3435baeca29a55..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: 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 6f3d94e3a60cdd..85cfedf5b0e0a4 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,14 +140,14 @@ 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}} + 1)) 10 @@ -157,7 +157,7 @@ jobs: run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v5 + uses: actions/upload-artifact@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}} @@ -244,7 +244,7 @@ jobs: run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v5 + uses: actions/upload-artifact@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,13 +286,13 @@ 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 @@ -305,7 +305,7 @@ jobs: 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 @@ -420,7 +420,9 @@ jobs: CI_JOB_IMAGE: ${{matrix.vector.image}} CUSTOM_PATH: /custom runs-on: ubuntu-latest - container: ${{matrix.vector.image}} + container: + image: ${{ matrix.vector.image }} + options: ${{ github.repository_visibility == 'private' && '--pids-limit 16384 --ulimit nproc=16384:16384 --ulimit nofile=32768:32768' || '' }} steps: - name: prepare libc6 for actions if: matrix.vector.jobname == 'linux32' @@ -439,7 +441,7 @@ 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 . @@ -449,7 +451,7 @@ jobs: 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 +466,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 +482,7 @@ jobs: group: rust-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-rust-checks.sh sparse: @@ -494,7 +496,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 +512,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 24635cf2d6f4a3..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 @@ -182,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 83ec786c5a49d0..1c4d04da9dcd4c 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,15 +86,10 @@ test:osx: stage: test needs: [ ] tags: - - saas-macos-medium-m1 + - saas-macos-large-m2pro variables: - TEST_OUTPUT_DIRECTORY: "/Volumes/RAMDisk" + TEST_OUTPUT_DIRECTORY: "/tmp/test-output" before_script: - # Create a 4GB RAM disk that we use to store test output on. This small hack - # significantly speeds up tests by more than a factor of 2 because the - # macOS runners use network-attached storage as disks, which is _really_ - # slow with the many small writes that our tests do. - - sudo diskutil apfs create $(hdiutil attach -nomount ram://8192000) RAMDisk - ./ci/install-dependencies.sh script: - ./ci/run-build-and-tests.sh @@ -104,10 +106,10 @@ test:osx: image: macos-15-xcode-16 CC: clang - jobname: osx-reftable - image: macos-15-xcode-16 + image: macos-26-xcode-26 CC: clang - jobname: osx-meson - image: macos-15-xcode-16 + image: macos-26-xcode-26 CC: clang artifacts: paths: @@ -145,6 +147,9 @@ test:mingw64: needs: - job: "build:mingw64" artifacts: true + variables: + # Windows runners don't have enough RAM to run EXPENSIVE tests. + GIT_TEST_LONG: false before_script: - *windows_before_script - git-sdk/usr/bin/bash.exe -l -c 'tar xf artifacts/artifacts.tar.gz' @@ -161,11 +166,16 @@ test:mingw64: 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: @@ -188,6 +198,9 @@ test:msvc-meson: script: - | & "C:/Program Files/Git/usr/bin/bash.exe" -l -c 'ci/run-test-slice-meson.sh build $CI_NODE_INDEX $CI_NODE_TOTAL' + variables: + # Windows runners don't have enough RAM to run EXPENSIVE tests. + GIT_TEST_LONG: false after_script: - | if ($env:CI_JOB_STATUS -ne "success") { diff --git a/.mailmap b/.mailmap index c2e3939beb286d..f8ede075ea172f 100644 --- a/.mailmap +++ b/.mailmap @@ -277,6 +277,7 @@ Sven Verdoolaege SZEDER Gábor Tao Qingyun <845767657@qq.com> Tay Ray Chuan +Taylor Blau Ted Percival Theodore Ts'o Thomas Ackermann 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 af59c43f42c8e6..73bb939359c72e 100644 --- a/Documentation/BreakingChanges.adoc +++ b/Documentation/BreakingChanges.adoc @@ -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 2aafcec40dc0c2..c06f5d3071968c 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -693,6 +693,12 @@ For C programs: 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/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index b9fdefce0224c9..4832e5bad59bf1 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -790,7 +790,7 @@ We can note a few things: v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of three patches in the second iteration. Each iteration is sent with a new cover letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the - previous iteration (more on that below). + first iteration (more on that below). NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without _i_/_n_ numbering (in the above thread overview, no single-patch topic appears, @@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not be merged. ---- -At this point the tutorial diverges, in order to demonstrate two +At this point the tutorial diverges, in order to demonstrate three different methods of formatting your patchset and getting it reviewed. The first method to be covered is GitGitGadget, which is useful for those @@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some setup which can change depending on your system and will not be covered in this tutorial. +The third method to be covered is `b4`, which builds on top of `git +format-patch` and `git send-email`. This method is the recommended way to +submit patches via mail as it automates a lot of the bookkeeping required by +`git send-email`. + Regardless of which method you choose, your engagement with reviewers will be -the same; the review process will be covered after the sections on GitGitGadget -and `git send-email`. +the same; the review process will be covered after the sections on GitGitGadget, +`git send-email` and `b4`. [[howto-ggg]] == Sending Patches via GitGitGadget @@ -1214,7 +1219,7 @@ between your last version and now, if it's something significant. You do not need the exact same body in your second cover letter; focus on explaining to reviewers the changes you've made that may not be as visible. -You will also need to go and find the Message-ID of your previous cover letter. +You will also need to go and find the Message-ID of your first cover letter. You can either note it when you send the first series, from the output of `git send-email`, or you can look it up on the https://lore.kernel.org/git[mailing list]. Find your cover letter in the @@ -1227,8 +1232,8 @@ Message-ID: Your Message-ID is ``. This example will be used below as well; make sure to replace it with the correct Message-ID for your -**previous cover letter** - that is, if you're sending v2, use the Message-ID -from v1; if you're sending v3, use the Message-ID from v2. +**first cover letter** - that is, for any subsequent version that you send, +always use the Message-ID from v1. While you're looking at the email, you should also note who is CC'd, as it's common practice in the mailing list to keep all CCs on a thread. You can add @@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644 2.21.0.392.gf8f6787159e-goog ---- +[[howto-b4]] +== Sending Patches with `b4` + +`b4` is a tool that builds on top of `git format-patch` and `git send-email`. +It automates much of the bookkeeping involved in sending a patch series to a +mailing-list-based project. + +Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference. + +[[prep-b4]] +=== Preparing a Patch Series + +`b4` tracks your patch series as a branch. To start tracking the `psuh` branch +you have been working on, run: + +---- +$ b4 prep --enroll master +---- + +This enrolls the current branch, using `master` as the base of the topic. `b4` +manages the cover letter as part of the branch, so you can edit it at any time +with: + +---- +$ b4 prep --edit-cover +---- + +The cover letter not only tracks the content of the top-level mail, but also +the set of recipients. You can add recipients by adding `To:` and `Cc:` +trailer lines. + +[[send-b4]] +=== Sending the Patches + +Before sending the series out for real, you can inspect what `b4` would send by +passing `--dry-run`: + +---- +$ b4 send --dry-run +---- + +Once you are happy with the result, send the series with: + +---- +$ b4 send +---- + +[[v2-b4]] +=== Sending v2 + +When you are ready to send a new iteration of your series, refine your +patches as usual using linkgit:git-rebase[1]. Note that you typically want to +rebase on top of the cover letter. You can configure an alias to enable easy +rebases going forward: + +--- +$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"' +$ git b4-rebase -i +--- + +Before sending out the new version you should also update the cover letter with +`b4 prep --edit-cover` to note the relevant changes compared to the previous +version. You can inspect the changes between the two versions with `b4 prep +--compare-to=v1`. + +Same as with the first version, you can use `b4 send` to send out the second +version. `b4` automatically bumps the version to `v2`, generates the range-diff +against the previous iteration, and threads the new series as a reply to the +cover letter of the first version. + +[[configure-b4]] +=== Configure b4 + +`b4` can be configured via linkgit:git-config[1]. In addition to that, projects +can have their own set of defaults in `.b4-config` in the root tree, which also +uses Git's config format. The user's configuration always takes precedence over +the per-project defaults. + +Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation] +for more information on the available options. + [[now-what]] == My Patch Got Emailed - Now What? @@ -1330,6 +1416,28 @@ previous one" patches over 2 days), reviewers would strongly prefer if a single polished version came 2 days later instead, and that version with fewer mistakes were the only one they would need to review. +This consideration applies not only when going from the initial patch to v2, +but also to later iterations of the same series. There is no fixed rule for how +long to wait before sending a new version. A useful default is to send at most +one new version of the same patch series per day. This gives multiple reviewers +time to comment, gives reviewers across time zones a fair chance to +participate, lets you batch feedback together, and gives you time to think +through the comments you received. Knowing that you should not immediately send +another version also encourages you to review the patches more carefully before +sending them, catch small mistakes such as typos and off-by-one errors +yourself, and let reviewers spend more of their attention on design, +algorithms, and other substantial issues. + +The right timing depends on the topic and the feedback. Larger series usually +need more review time. If the only comments so far are minor, such as typo +fixes, it often makes sense to wait a little longer in case deeper reviews are +still coming. If the comments call for substantial rework, do not rush out an +updated version before you have reviewed the larger changes carefully. Instead, +reply to the review that prompted the rewrite, say that you are preparing a +substantial rework, and mention which parts of the current series will become +obsolete so reviewers can avoid spending time on them until the updated series +is ready. + [[reviewing]] === Responding to Reviews @@ -1337,11 +1445,13 @@ fewer mistakes were the only one they would need to review. After a few days, you will hopefully receive a reply to your patchset with some comments. Woohoo! Now you can get back to work. -It's good manners to reply to each comment, notifying the reviewer that you have -made the change suggested, feel the original is better, or that the comment -inspired you to do something a new way which is superior to both the original -and the suggested change. This way reviewers don't need to inspect your v2 to -figure out whether you implemented their comment or not. +It's good manners to reply to each comment in the mailing list discussion +instead of letting the next version of your patch be your only response. Tell +the reviewer whether you plan to make the suggested change, keep the original, +or pursue a different approach. This way reviewers can respond to your reasoning +before you spend time preparing a version they may not agree with, and later do +not need to inspect your v2 to figure out whether you implemented their comment +or not. Reviewers may ask you about what you wrote in the patchset, either in the proposed commit log message or in the changes themselves. You 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..f5643534dcc19c --- /dev/null +++ b/Documentation/RelNotes/2.55.0.adoc @@ -0,0 +1,460 @@ +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. We had a regression in this + update that broke https:// proxies, but that has been caught and + 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/RelNotes/2.56.0.adoc b/Documentation/RelNotes/2.56.0.adoc new file mode 100644 index 00000000000000..b2d2c8a674a7d6 --- /dev/null +++ b/Documentation/RelNotes/2.56.0.adoc @@ -0,0 +1,217 @@ +Git v2.56 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * Advice shown by "git status" when the local branch is behind or has + diverged from its push branch has been updated to suggest "git pull + ". + + * The handling of promisor-remote protocol capability has been updated + to allow the other side to add to the list of promisor remotes via the + 'promisor.acceptFromServerURL' configuration variable. + + * The 'ort' merge backend has been hardened against corrupt trees by + ensuring it aborts under appropriate error conditions. + + * The `fetch.followRemoteHEAD` configuration variable has been added to + provide a default for the per-remote `remote..followRemoteHEAD` + setting. + + * "git log --follow" has been updated to better handle non-linear + history, in which the path being tracked gets renamed differently in + multiple history lines. + + * The "git repo info" command has been taught new keys to output both + absolute and relative paths for "gitdir" and "commondir", supported by + a new path-formatting helper extracted from "git rev-parse". + + * When 'git push origin/main' or 'git branch origin main' is run, the + command is now recognized as a potential typo, and advice has been + added to offer a typo fix. + + * The 'git refs' toolbox has been extended with new 'create', 'delete', + 'update', and 'rename' subcommands to create, delete, update, and + rename references, respectively. + + * The experimental 'git history' command has been taught a new 'drop' + subcommand to remove a commit, with its descendants replayed onto its + parent. + + * The alignment of commit object name abbreviations in 'git blame' + output has been optimized to reserve a column for marks (caret, + question mark, or asterisk) only when such marks are actually shown. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * The refactoring of 'setup.c' has been continued to drop remaining + global state (`git_work_tree_cfg`, `is_bare_repository_cfg`), updating + `is_bare_repository()` to no longer implicitly rely on + `the_repository`. + + * Project-specific configuration for b4 has been introduced, and the + documentation has been updated to recommend using it as a + streamlined method for submitting patches. + + * The default format path of git cat-file --batch has been optimized + to use strbuf_add_oid_hex() and strbuf_add_uint() instead of + strbuf_addf(), yielding a noticeable speedup. + + * Commands that list branches and tags (like git branch and git tag) + have been optimized to pass the namespace prefix when initializing + their ref iterator, avoiding a loose-ref scaling regression in + repositories with many unrelated loose references. + + * The packed object source has been refactored into a proper struct + odb_source. + + * The global configuration variables protect_hfs and protect_ntfs have + been migrated into struct repo_config_values to tie them to + per-repository configuration state. + + * The trailer sections in SubmittingPatches have been updated to + encourage use of standard trailers. + + * The documentation in SubmittingPatches has been updated to clarify how + patch contributors should respond to design and viability critiques, + and how the resolution of such critiques should be recorded in the + final commit messages. + + * The pack-objects command has been updated to support reachability + bitmaps and delta-islands concurrently with the `--path-walk` option, + allowing faster packaging by falling back to path-walk when bitmaps + cannot fully satisfy the request. + + * Documentation on community contribution guidelines has been updated to + encourage replying to review comments before rerolling, and to advise + a default limit of at most one reroll per day to give reviewers across + different time zones enough time to participate. + + * The lazy priority queue optimization pattern (deferring actual removal + in 'prio_queue_get()' to allow get+put fusion) has been folded + directly into 'prio_queue' itself, speeding up commit traversal + workflows and simplifying callers. + + * The 'reprepare()' callback for object database sources has been + generalized into a 'prepare()' callback with an optional flush cache + flag, and a new 'odb_prepare()' wrapper has been introduced to allow + pre-opening object database sources. + + * The 'whence' field in 'struct object_info' has been removed. The + backend-specific object information retrieval has been refactored into + an opt-in 'struct object_info_source' structure. + + * A racy build failure under Meson has been corrected by ensuring that + the generated header file 'hook-list.h' is built before compiling + files in 'builtin_sources' that depend on it. + + +Fixes since v2.55 +----------------- + + * A regression in the error diagnosis code for invalid .git files has + been fixed, avoiding a potential NULL-pointer crash when reporting + that a .git file does not point to a valid repository. + (merge 54a441bcea jk/setup-gitfile-diag-fix later to maint). + + * Support for hashing loose or packed objects larger than 4GB on Windows + and other LLP64 platforms has been improved by converting object header + buffers and data-handling functions from 'unsigned long' to 'size_t'. + (merge d99e13d0be po/hash-object-size-t later to maint). + + * The display of the rebase todo list in "git status" has been + improved to correctly abbreviate object IDs for more commands and + avoid misinterpreting refs as object IDs. + (merge 6f34e5f9e3 pw/status-rebase-todo later to maint). + + * Reference backend configuration has been updated to load lazily to + avoid recursive calls during repository initialization when 'onbranch' + configuration conditions are evaluated. This has also fixed a memory + leak and allowed the unused `chdir_notify_reparent()` machinery to be + dropped. + (merge d6522d01df ps/refs-onbranch-fixes later to maint). + + * The connectivity check has been refactored to search for promisor + objects in a generic way using the object database interface, + rather than iterating packfiles directly. This allows connectivity + checks to work properly in repositories that do not use packfiles. + (merge 66ee9cb930 ps/connected-generic-promisor-checks later to maint). + + * A test checking interactions between git rebase --quit and + autostash in t3420-rebase-autostash.sh has been corrected to use + test_path_is_missing instead of ! grep on a file that shouldn't + exist in the conflicted state. + (merge eaad121fef sg/t3420-do-not-grep-in-missing-file later to maint). + + * The GPG and SSH signature parsing code has been corrected to strip + carriage return characters only when they immediately precede line + feeds, instead of unconditionally stripping all carriage returns. + (merge 5dea8b690b ad/gpg-strip-cr-before-lf later to maint). + + * A memory leak in the 'reftable_writer_new()' initialization function + has been fixed by delaying the allocation of 'struct reftable_writer' + until after input options are validated. + (merge c6fb3b9c3e jk/reftable-leakfix later to maint). + + * A memory leak in the '--base' handling of 'git format-patch' has been + plugged, and the leak reporting of the test suite when running under a + TAP harness has been improved. + (merge 973a0373ff jk/format-patch-leakfix later to maint). + + * A write file stream resource leak has been fixed as part of a code + cleanup. + (merge ebb4d2ffa3 jc/history-message-prep-fix later to maint). + + * Various memory leaks in the Bloom-filter code paths that are exposed + when running tests with the 'GIT_TEST_COMMIT_GRAPH_CHANGED_PATHS=1' + environment variable have been plugged. + (merge 459088ec2e jk/bloom-leak-fixes later to maint). + + * The wincred credential helper has been updated to avoid memory + corruption when erasing credentials and to prevent silent + credential loss when storing OAuth tokens, by correcting buffer + allocations and arguments passed to safe-CRT APIs. + (merge f635ab9ab4 js/wincred-fixes later to maint). + + * Various code paths that initialize a cryptographic hash context but + bail out or finish without calling 'git_hash_final()' have been taught + to call 'git_hash_discard()' to release allocated resources, fixing + memory leaks when Git is built with non-default backends like + 'OpenSSL' or 'libgcrypt'. + (merge 600588d2aa jk/hash-algo-leak-fixes later to maint). + + * Various resource leaks, invalid file descriptor closures, and process + handle ownership issues flagged by Coverity have been fixed. + (merge 9184231173 js/coverity-fixes later to maint). + + * Dockerized CI jobs running in private GitHub repositories have been + adjusted to use explicit process and file limits, preventing resource + exhaustion errors on private runners. + (merge bad766fbac js/ci-dockerized-pid-limit later to maint). + + * Various test scripts have been updated to clean up large temporary + files and repositories, reducing peak disk usage during testing. + Also, expensive tests have been disabled on platforms that lack + sufficient resources (like 32-bit platforms and Windows CI runners), + and the long test suite has been enabled in GitLab CI. + (merge 84248444ad ps/t-fixes-for-git-test-long later to maint). + + * The UTF-8 precomposition wrapper on macOS has been updated to use a + flexible array member to represent the name of a directory entry, + preventing fortified libc checks from failing when the name is + reallocated to be larger than 'NAME_MAX' bytes. + (merge 1eb281159f ih/precompose-flex-array later to maint). + + * The 'git_hash_*()' wrappers have been updated to be used consistently + across the codebase instead of direct calls to members of 'struct + git_hash_algo', and 'git_hash_discard()' has been made idempotent to + simplify cleanups. + (merge 9e396aa553 jk/git-hash-cleanups later to maint). + + * The sideband demultiplexer has been updated to recognize ANSI SGR + escape sequences that use colon-separated subfields (e.g., for + 256-color or true-color codes). + (merge 3792b2aea4 mm/sideband-ansi-sgr-colon-fix later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d570184ec84998..d2d82eb543279d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -48,13 +48,41 @@ 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. + respond to them with "Reply-All" on the mailing list, instead of + letting an updated patch series be your only response. Tell + reviewers which suggestions you plan to use, which ones you disagree + with, and when a comment leads you to consider a different approach. + Use these replies and any follow-up discussion as input when + preparing an updated set of patches. ++ +Be particularly mindful of critiques regarding the high-level design +or viability of your proposal (e.g., questioning if the feature is +worth implementing, or if the chosen approach is appropriate). Defend +your design decisions on the list first and work with reviewers and +other members to improve the design before revising the implementation. +This will avoid wasting effort on an implementation before its design is +solid. ++ +Make sure that any new version explains and justifies those design +decisions more clearly, in the cover letter and in the revised commit +messages. Aim to make the reviewers say "it is now clear why we may +want to do this with the updated version". ++ +Topics with unresolved fundamental design critiques will not be +considered ready for merging. + 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. +input, gives reviewers in different time zones a fair chance to comment, +and avoids unnecessary churn from many rapid iterations. Waiting also +encourages you to polish each version before sending it, so reviewers +can focus on substantial issues rather than typos or other small +mistakes. ++ +As a rough default, avoid sending more than one new version of the same +series per day, while considering the size of the series and the depth +of review. . These early update iterations are expected to be full replacements, not incremental updates on top of what you posted already. If you @@ -92,7 +120,7 @@ input and avoids unnecessary churn from many rapid iterations. 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 @@ -237,6 +265,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 @@ -322,6 +351,10 @@ The body should provide a meaningful commit message, which: . alternate solutions considered but discarded, if any. +. records the resolution of design or viability concerns raised by the + community during the review, if any, ensuring the historical record + explains why the chosen approach was accepted over alternatives. + [[present-tense]] The problem statement that describes the status quo is written in the present tense. Write "The code does X when it is given input Y", @@ -374,7 +407,7 @@ or, on an older version of Git without support for --pretty=reference: .... [[sign-off]] -=== Certify your work by adding your `Signed-off-by` trailer +=== Certify your work by adding your `Signed-off-by:` trailer To improve tracking of who did what, we ask you to certify that you wrote the patch or have the right to pass it on under the same license @@ -411,7 +444,7 @@ d. I understand and agree that this project and the contribution this project or the open source license(s) involved. ____ -you add a "Signed-off-by" trailer to your commit, that looks like +you add a `Signed-off-by:` trailer to your commit, that looks like this: .... @@ -421,19 +454,23 @@ this: This line can be added by Git if you run the git-commit command with the -s option. -Notice that you can place your own `Signed-off-by` trailer when +Notice that you can place your own `Signed-off-by:` trailer when forwarding somebody else's patch with the above rules for D-C-O. Indeed you are encouraged to do so. Do not forget to place an in-body "From: " line at the beginning to properly attribute the change to its true author (see (2) above). +Place this `Signed-off-by:` trailer at the end, after trailers added by +others and after other trailers added by you; see +<> below ("chronological order"). + This procedure originally came from the Linux kernel project, so our rule is quite similar to theirs, but what exactly it means to sign-off your patch differs from project to project, so it may be different from that of the project you are accustomed to. [[real-name]] -Please use a known identity in the `Signed-off-by` trailer, since we cannot +Please use a known identity in the `Signed-off-by:` trailer, since we cannot accept anonymous contributions. It is common, but not required, to use some form of your real name. We realize that some contributors are not comfortable doing so or prefer to contribute under a pseudonym or preferred name and we can accept @@ -444,7 +481,15 @@ The goal of this policy is to allow us to have sufficient information to contact you if questions arise about your contribution. [[commit-trailers]] -If you like, you can put extra trailers at the end: +=== Commit trailers +It is polite to credit people who have helped with your work to a +substantial enough degree. This project uses commit trailers for that, +where the credited person is written out like a Git author, i.e. with +both their name and their email address. Note that the threshold to +credit someone is a judgement call, and crediting someone for simple +review work is certainly not necessary. + +These are the common trailers in use: . `Reported-by:` is used to credit someone who found the bug that the patch attempts to fix. @@ -457,6 +502,10 @@ If you like, you can put extra trailers at the end: and found it to have the desired effect. . `Co-authored-by:` is used to indicate that people exchanged drafts of a patch before submitting it. +. `Based-on-patch-by:` is used when someone else authored parts of the + patch that you are submitting. This might be relevant if someone sent + a patch to the mailing list with their sign-off. (Be mindful and ask + them to sign off on it if they did not.) . `Helped-by:` is used to credit someone who suggested ideas for changes without providing the precise changes in patch form. . `Mentored-by:` is used to credit someone with helping develop a @@ -468,8 +517,42 @@ While you can also create your own trailer if the situation warrants it, we encourage you to instead use one of the common trailers in this project highlighted above. +Other projects might regularly refer to other kinds of data, like +`Fixes:` and `Link:` in the Linux Kernel project, but these ones in +particular are not used in this project. + 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". +`Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`. + +As mentioned under <> above, trailers are added in +chronological order; one person might sign-off on a patch and send it to +someone else, who then in turn adds her own sign-off. Further, any +trailers that you add beyond your sign-off should come before that +sign-off. That makes it clear what trailers which person added. + +[[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) @@ -562,8 +645,8 @@ when the maintainer did not heavily participate in the discussion and instead left the review to trusted others. Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and -`Tested-by:` lines as necessary to credit people who helped your -patch, and "cc:" them when sending such a final version for inclusion. +`Tested-by:` (see <>), and "cc:" them +when sending such a final version for inclusion. ==== `format-patch` and `send-email` @@ -573,8 +656,10 @@ your existing e-mail client (often optimized for "multipart/*" MIME type e-mails) might render your patches unusable. NOTE: Here we outline the procedure using `format-patch` and -`send-email`, but you can instead use GitGitGadget to send in your -patches (see link:MyFirstContribution.html[MyFirstContribution]). +`send-email`, but you can instead use GitGitGadget or `b4` to send in +your patches (see link:MyFirstContribution.html[MyFirstContribution]). +Contributors are encouraged to use `b4`, which automates much of the +bookkeeping that is otherwise done by hand. People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for @@ -588,10 +673,13 @@ grouped into their own e-mail thread to help readers find all parts of the series. To that end, send them as replies to either an additional "cover letter" message (see below), the first patch, or the respective preceding patch. Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on -how to submit updated versions of a patch series. +how to submit updated versions of a patch series. Before sending another +version, make sure you have answered meaningful review comments in the existing +discussion. Also give reviewers enough time to comment before sending another +version. If your log message (including your name on the -`Signed-off-by` trailer) is not writable in ASCII, make sure that +`Signed-off-by:` trailer) is not writable in ASCII, make sure that you send off a message in the correct encoding. WARNING: Be wary of your MUAs word-wrap @@ -611,7 +699,7 @@ previously sent. The `git format-patch` command follows the best current practice to format the body of an e-mail message. At the beginning of the patch should come your commit message, ending with the -`Signed-off-by` trailers, and a line that consists of three dashes, +`Signed-off-by:` trailers, and a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit @@ -817,6 +905,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 31b883a72c5739..93c63b284a9669 100644 --- a/Documentation/asciidoc.conf.in +++ b/Documentation/asciidoc.conf.in @@ -84,6 +84,9 @@ 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[] @@ -93,6 +96,9 @@ 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/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/advice.adoc b/Documentation/config/advice.adoc index 257db58918179a..81f80a92745123 100644 --- a/Documentation/config/advice.adoc +++ b/Documentation/config/advice.adoc @@ -48,6 +48,10 @@ all advice messages. to create a local branch after the fact. diverging:: Shown when a fast-forward is not possible. + fetchRemoteHEADWarn:: + Shown when linkgit:git-fetch[1] reveals that a remote `HEAD` + differs from what is set locally and the user has opted into + receiving a warning in this situation. fetchShowForcedUpdates:: Shown when linkgit:git-fetch[1] takes a long time to calculate forced updates after ref updates, or to warn @@ -90,6 +94,11 @@ all advice messages. Shown when linkgit:git-push[1] rejects a forced update of a branch when its remote-tracking ref has updates that we do not have locally. + pushRepoLooksLikeRef:: + Shown when the repository given to linkgit:git-push[1] is not + a configured remote but looks like a `/` ref, + suggesting that the remote and branch be given as separate + arguments. pushUnqualifiedRefname:: Shown when linkgit:git-push[1] gives up trying to guess based on the source and destination refs what diff --git a/Documentation/config/am.adoc b/Documentation/config/am.adoc index e9561e12d7467e..250e6b5047365d 100644 --- a/Documentation/config/am.adoc +++ b/Documentation/config/am.adoc @@ -1,11 +1,11 @@ -am.keepcr:: +`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. -am.threeWay:: +`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 @@ -13,7 +13,7 @@ am.threeWay:: have those blobs available locally (equivalent to giving the `--3way` option from the command line). Defaults to `false`. -am.messageId:: +`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` 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/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/fetch.adoc b/Documentation/config/fetch.adoc index cd40db0cad1c36..00435e9a16d9f9 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`:: @@ -126,3 +126,22 @@ the new bundle URI. The creation token values are chosen by the provider serving the specific bundle URI. If you modify the URI at `fetch.bundleURI`, then be sure to remove the value for the `fetch.bundleCreationToken` value before fetching. + +`fetch.followRemoteHEAD`:: + When fetching using a default refspec, this setting determines how to handle + differences between a fetched remote's `HEAD` and the local + `remotes//HEAD` symbolic-ref. Its value is one of ++ +-- +`create`;; + Create `remotes//HEAD` if a ref exists on the remote, but not locally. + An existing symbolic-ref will not be touched. This is the default value. +`warn`;; + Display a warning if the remote advertises a different `HEAD` than what is + set locally. Behaves like "create" if the local symbolic-ref doesn't exist. +`always`;; + Silently update `remotes//HEAD` whenever the remote advertises a new + value. +`never`;; + Never create or modify the `remotes//HEAD` symbolic-ref. +-- diff --git a/Documentation/config/format.adoc b/Documentation/config/format.adoc index dbd186290b501f..95d19134b26ea0 100644 --- a/Documentation/config/format.adoc +++ b/Documentation/config/format.adoc @@ -102,7 +102,7 @@ format.coverLetter:: Default is false. format.commitListFormat:: - When the `--cover-letter-format` option is not given, `format-patch` + 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`. 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/hook.adoc b/Documentation/config/hook.adoc index 9e78f264396ca5..083dc60a1325f2 100644 --- a/Documentation/config/hook.adoc +++ b/Documentation/config/hook.adoc @@ -1,10 +1,17 @@ +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 linkgit:git-hook[1]. + value parsed is used. {see-git-hook} hook..event:: The hook events that trigger `hook.`. The value is the @@ -14,11 +21,87 @@ hook..event:: 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 linkgit:git-hook[1]. + `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 linkgit:git-hook[1]. + 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 849c89f36c5ad8..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 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/log.adoc b/Documentation/config/log.adoc
index f20cc25cd7c3bf..757a7be196ab38 100644
--- a/Documentation/config/log.adoc
+++ b/Documentation/config/log.adoc
@@ -53,8 +53,7 @@ This is the same as the `--decorate` option of the `git log`.
 `log.follow`::
 	If `true`, `git log` will act as if the `--follow` option was used when
 	a single  is given.  This has the same limitations as `--follow`,
-	i.e. it cannot be used to follow multiple files and does not work well
-	on non-linear history.
+	i.e. it cannot be used to follow multiple files.
 
 `log.graphColors`::
 	A list of colors, separated by commas, that can be used to draw
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/promisor.adoc b/Documentation/config/promisor.adoc
index b0fa43b8393a53..c1f3d766a64cc0 100644
--- a/Documentation/config/promisor.adoc
+++ b/Documentation/config/promisor.adoc
@@ -32,24 +32,136 @@ variable is set to "true", and the "name" and "url" fields are always
 advertised regardless of this setting.
 
 promisor.acceptFromServer::
-	If set to "all", a client will accept all the promisor remotes
-	a server might advertise using the "promisor-remote"
-	capability. If set to "knownName" the client will accept
-	promisor remotes which are already configured on the client
-	and have the same name as those advertised by the client. This
-	is not very secure, but could be used in a corporate setup
-	where servers and clients are trusted to not switch name and
-	URLs. If set to "knownUrl", the client will accept promisor
-	remotes which have both the same name and the same URL
-	configured on the client as the name and URL advertised by the
-	server. This is more secure than "all" or "knownName", so it
-	should be used if possible instead of those options. Default
-	is "none", which means no promisor remote advertised by a
-	server will be accepted. By accepting a promisor remote, the
-	client agrees that the server might omit objects that are
-	lazily fetchable from this promisor remote from its responses
-	to "fetch" and "clone" requests from the client. Name and URL
-	comparisons are case sensitive. See linkgit:gitprotocol-v2[5].
+	Controls which promisor remotes advertised by a server (using the
+	"promisor-remote" protocol capability) a client will accept. By
+	accepting a promisor remote, the client agrees that the server
+	might omit objects that are lazily fetchable from this promisor
+	remote from its responses to "fetch" and "clone" requests.
++
+Note that this option does not cause new remotes to be automatically
+created in the client's configuration. It only allows remotes which
+are somehow already configured to be trusted for the current
+operation, or their fields to be updated (if `promisor.storeFields` is
+set and the remote already exists locally). To allow Git to
+automatically create and persist new remotes from server
+advertisements, use `promisor.acceptFromServerUrl`.
++
+The available options are:
++
+* `none` (default): No promisor remote advertised by a server will be
+  accepted.
++
+* `knownUrl`: The client will accept promisor remotes that are already
+  configured on the client and have both the same name and the same URL
+  as advertised by the server. This is more secure than `all` or
+  `knownName`, and should be used if possible instead of those options.
++
+* `knownName`: The client will accept promisor remotes that are already
+  configured on the client and have the same name as those advertised
+  by the server. This is not very secure, but could be used in a corporate
+  setup where servers and clients are trusted to not switch names and URLs.
++
+* `all`: The client will accept all the promisor remotes a server might
+  advertise. This is the least secure option and should only be used in
+  fully trusted environments.
++
+Name and URL comparisons are case-sensitive. See linkgit:gitprotocol-v2[5]
+for protocol details.
+
+promisor.acceptFromServerUrl::
+	A glob pattern to specify which server-advertised URLs a
+	client is allowed to act on. When a URL matches, the client
+	will accept the advertised remote as a promisor remote, may
+	automatically create a new remote configuration for it and may
+	automatically accept field updates (such as authentication
+	tokens) from the server, even if `promisor.acceptFromServer`
+	is set to `none` (the default).
++
+This option can appear multiple times in config files. An advertised
+URL will be accepted if it matches _ANY_ glob pattern specified by
+this option in _ANY_ config file read by Git.
++
+When both `promisor.acceptFromServer` and `promisor.acceptFromServerUrl`
+are set, `promisor.acceptFromServerUrl` is consulted first and takes
+precedence: if a matching pattern leads to acceptance (either by
+auto-configuring an unknown remote or by accepting field updates for
+a known remote whose URL matches both the local configuration and the
+allowlist), the advertised remote is accepted regardless of the
+`promisor.acceptFromServer` setting. If no pattern in
+`promisor.acceptFromServerUrl` triggers acceptance, the decision is
+left to `promisor.acceptFromServer`.
++
+Note however that, even when an advertised URL matches a pattern in
+`promisor.acceptFromServerUrl`, an already-existing remote on the
+client whose name matches the advertised name but whose configured URL
+differs from the advertised one will _NOT_ be accepted through
+`promisor.acceptFromServerUrl`. This prevents a server from silently
+re-pointing an existing client-side remote at a different URL. (Such a
+remote may still be accepted through `promisor.acceptFromServer=all`
+or `=knownName`, which have their own, looser semantics; see the
+documentation of that option.)
++
+Be _VERY_ careful with these patterns: `*` matches any sequence of
+characters within the 'host' and 'path' parts of a URL (but cannot
+cross part boundaries). An overly broad pattern is a major security
+risk, as a matching URL allows a server to auto-configure new remotes
+and to update fields (such as authentication tokens) on known remotes
+without further confirmation. To minimize security risks, follow these
+guidelines:
++
+--
+1. Start with a secure protocol scheme, like `https://` or `ssh://`.
++
+2. Only allow domain names or paths where you control and trust _ALL_
+   the content. Be especially careful with shared hosting platforms
+   like `github.com` or `gitlab.com`. A broad pattern like
+   `https://gitlab.com/*` is dangerous because it trusts every
+   repository on the entire platform. Always restrict such patterns to
+   your specific organization or namespace (e.g.,
+   `https://gitlab.com/your-org/*`).
++
+3. Never use globs at the end of domain names. For example,
+   `https://cdn.your-org.com/*` might be safe, but
+   `https://cdn.your-org.com*/*` is a major security risk because
+   the latter matches `https://cdn.your-org.com.hacker.net/repo`.
++
+4. Be careful using globs at the beginning of domain names. While the
+   code ensures a `*` in the host cannot cross into the path, a
+   pattern like `https://*.example.com/*` will still match any
+   subdomain. This is extremely dangerous on shared hosting platforms
+   (e.g., `https://*.github.io/*` trusts every user's site on the
+   entire platform).
+--
++
+Before matching, both the advertised URL and the pattern are
+normalized: the scheme and host are lowercased, percent-encoded
+characters are decoded where possible, and path segments like `..`
+are resolved. The port must also match exactly (e.g.,
+`https://example.com:8080/*` will not match a URL advertised on
+port 9999). The username and password components of the URL are
+ignored during matching. Note that embedding credentials in URLs is
+discouraged. Passing authentication tokens via the `token` field of
+the `promisor-remote` capability is strongly preferred.
++
+The glob pattern can optionally be prefixed with a remote name and an
+equals sign (e.g., `cdn=https://cdn.example.com/*`). If such a prefix
+is provided, accepted remotes will be saved under that name. If no
+such prefix is provided, a safe remote name will be automatically
+generated by sanitizing the URL and prefixing it with
+`promisor-auto-`.
++
+If a remote with the chosen name already exists but points to a
+different URL, Git will append a numeric suffix (e.g., `-1`, `-2`) to
+the name to prevent overwriting existing configurations. You should
+make sure that this doesn't happen often though, as remotes will be
+rejected if the numeric suffix increases too much. In all cases, the
+original name advertised by the server is recorded in the
+`remote..advertisedAs` configuration variable for tracing and
+debugging purposes.
++
+For the security implications of accepting a promisor remote, see the
+documentation of `promisor.acceptFromServer`. For details on the
+protocol, see linkgit:gitprotocol-v2[5].
 
 promisor.checkFields::
 	A comma or space separated list of additional remote related
@@ -63,11 +175,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.
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..3a20d0f7524e72 100644
--- a/Documentation/config/remote.adoc
+++ b/Documentation/config/remote.adoc
@@ -91,6 +91,15 @@ remote..promisor::
 	When set to true, this remote will be used to fetch promisor
 	objects.
 
+remote..advertisedAs::
+	When a promisor remote is automatically configured using
+	information advertised by a server through the
+	`promisor-remote` protocol capability (see
+	`promisor.acceptFromServerUrl`), the server's originally
+	advertised name is saved in this variable. This is for
+	information, tracing and debugging purposes. Users should not
+	typically modify or create such configuration entries.
+
 remote..partialclonefilter::
 	The filter that will be applied when fetching from this	promisor remote.
 	Changing or clearing this value will only affect fetches for new commits.
@@ -107,16 +116,62 @@ 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.
-	The default value is "create", which will create `remotes//HEAD`
-	if it exists on the remote, but not locally; this will not touch an
-	already existing local reference. Setting it to "warn" will print
-	a message if the remote has a different value than the local one;
-	in case there is no local reference, it behaves like "create".
-	A variant on "warn" is "warn-if-not-$branch", which behaves like
-	"warn", but if `HEAD` on the remote is `$branch` it will be silent.
-	Setting it to "always" will silently update `remotes//HEAD` to
-	the value on the remote.  Finally, setting it to "never" will never
-	change or create the local reference.
+	When fetching this remote using its default refspec, this setting determines
+	how to handle differences between the remote's `HEAD` and the local
+	`remotes//HEAD` symbolic-ref.  Overrides the value of
+	`fetch.followRemoteHEAD`.  See `fetch.followRemoteHEAD` for a description of
+	accepted values.
++
+In addition to the values supported by `fetch.followRemoteHEAD`, this setting
+may also take on the value "warn-if-not-`$branch`", which behaves like "warn",
+but ignores the warning if the remote's `HEAD` is `remotes//$branch`.
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/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/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-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 8a63b5e164114a..c8242e24627eef 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -457,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
diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc
index 81a9d7f9bbc11d..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)`.
diff --git a/Documentation/format-patch-caveats.adoc b/Documentation/format-patch-caveats.adoc
index 807a65b885b09a..133e4757e7946c 100644
--- a/Documentation/format-patch-caveats.adoc
+++ b/Documentation/format-patch-caveats.adoc
@@ -28,6 +28,6 @@ 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
+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
index ec1ef79f5e3308..a1a624d2ac5bc2 100644
--- a/Documentation/format-patch-end-of-commit-message.adoc
+++ b/Documentation/format-patch-end-of-commit-message.adoc
@@ -1,8 +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: "
+* 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/git-am.adoc b/Documentation/git-am.adoc
index ac65852918f3ee..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,45 +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::
+`-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::
+`-k`::
+`--keep`::
 	Pass `-k` flag to linkgit:git-mailinfo[1].
 
---keep-non-patch::
+`--keep-non-patch`::
 	Pass `-b` flag to linkgit:git-mailinfo[1].
 
---keep-cr::
---no-keep-cr::
+`--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=::
+`--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:
 +
 --
@@ -82,23 +82,23 @@ OPTIONS
 	session. This is the default behavior.
 --
 
--m::
---message-id::
+`-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`.
 
--q::
---quiet::
+`-q`::
+`--quiet`::
 	Be quiet. Only print error messages.
 
--u::
---utf8::
+`-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
@@ -108,57 +108,57 @@ 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::
+`--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::
+`--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.
 
---verify::
--n::
---no-verify::
+`--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
@@ -172,29 +172,29 @@ 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::
+`--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.
@@ -202,36 +202,36 @@ applying.
 	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 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-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.
@@ -278,11 +278,11 @@ 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 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).
+errors in the `From:` lines).
 
 [[caveats]]
 CAVEATS
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-backfill.adoc b/Documentation/git-backfill.adoc
index 246ab417c24a10..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,7 +63,27 @@ OPTIONS
 	current sparse-checkout. If the sparse-checkout feature is enabled,
 	then `--sparse` is assumed and can be disabled with `--no-sparse`.
 
-You may also specify the commit limiting options from linkgit:git-rev-list[1].
+`--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
 --------
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 8808009e87eb1d..2b74e455997c8c 100644
--- a/Documentation/git-blame.adoc
+++ b/Documentation/git-blame.adoc
@@ -88,11 +88,12 @@ include::blame-options.adoc[]
 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.
-	Note that 1 column
-	is used for a caret to mark the boundary commit.
+	Instead of using the default _7_ hexadecimal digits as the
+	abbreviated object name, use at least __ digits, but ensure
+	the commit object names are unique.
+	If commits marked with caret (boundary), question mark (ignored)
+	or asterisk (unblamable) are shown, extend unmarked object names
+	to align them.
 
 
 THE DEFAULT FORMAT
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 43ccf47cf6de28..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=