Git 2.33.5

Signed-off-by: Taylor Blau <me@ttaylorr.com>

.github/workflows/check-whitespace.yml

@@ -1,9 +1,8 @@
 name: check-whitespace
 
-# Get the repository with all commits to ensure that we can analyze
-# all of the commits contributed via the Pull Request.
+# Get the repo with the commits(+1) in the series.
 # Process `git log --check` output to extract just the check errors.
-# Exit with failure upon white-space issues.
+# Add a comment to the pull request with the check errors.
 
 on:
   pull_request:

.github/workflows/l10n.yml

@@ -1,105 +0,0 @@
-name: git-l10n
-
-on: [push, pull_request_target]
-
-jobs:
-  git-po-helper:
-    if: >-
-      endsWith(github.repository, '/git-po') ||
-      contains(github.head_ref, 'l10n') ||
-      contains(github.ref, 'l10n')
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-    steps:
-      - name: Setup base and head objects
-        id: setup-tips
-        run: |
-          if test "${{ github.event_name }}" = "pull_request_target"
-          then
-            base=${{ github.event.pull_request.base.sha }}
-            head=${{ github.event.pull_request.head.sha }}
-          else
-            base=${{ github.event.before }}
-            head=${{ github.event.after }}
-          fi
-          echo "::set-output name=base::$base"
-          echo "::set-output name=head::$head"
-      - name: Run partial clone
-        run: |
-          git -c init.defaultBranch=master init --bare .
-          git remote add \
-            --mirror=fetch \
-            origin \
-            https://github.com/${{ github.repository }}
-          # Fetch tips that may be unreachable from github.ref:
-          # - For a forced push, "$base" may be unreachable.
-          # - For a "pull_request_target" event, "$head" may be unreachable.
-          args=
-          for commit in \
-            ${{ steps.setup-tips.outputs.base }} \
-            ${{ steps.setup-tips.outputs.head }}
-          do
-            case $commit in
-            *[^0]*)
-              args="$args $commit"
-              ;;
-            *)
-              # Should not fetch ZERO-OID.
-              ;;
-            esac
-          done
-          git -c protocol.version=2 fetch \
-            --progress \
-            --no-tags \
-            --no-write-fetch-head \
-            --filter=blob:none \
-            origin \
-            ${{ github.ref }} \
-            $args
-      - uses: actions/setup-go@v2
-        with:
-          go-version: '>=1.16'
-      - name: Install git-po-helper
-        run: go install github.com/git-l10n/git-po-helper@main
-      - name: Install other dependencies
-        run: |
-          sudo apt-get update -q &&
-          sudo apt-get install -q -y gettext
-      - name: Run git-po-helper
-        id: check-commits
-        run: |
-          exit_code=0
-          git-po-helper check-commits \
-            --github-action-event="${{ github.event_name }}" -- \
-            ${{ steps.setup-tips.outputs.base }}..${{ steps.setup-tips.outputs.head }} \
-            >git-po-helper.out 2>&1 || exit_code=$?
-          if test $exit_code -ne 0 || grep -q WARNING git-po-helper.out
-          then
-            # Remove ANSI colors which are proper for console logs but not
-            # proper for PR comment.
-            echo "COMMENT_BODY<<EOF" >>$GITHUB_ENV
-            perl -pe 's/\e\[[0-9;]*m//g; s/\bEOF$//g' git-po-helper.out >>$GITHUB_ENV
-            echo "EOF" >>$GITHUB_ENV
-          fi
-          cat git-po-helper.out
-          exit $exit_code
-      - name: Create comment in pull request for report
-        uses: mshick/add-pr-comment@v1
-        if: >-
-          always() &&
-          github.event_name == 'pull_request_target' &&
-          env.COMMENT_BODY != ''
-        with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-          repo-token-user-login: 'github-actions[bot]'
-          message: >
-            ${{ steps.check-commits.outcome == 'failure' && 'Errors and warnings' || 'Warnings' }}
-            found by [git-po-helper](https://github.com/git-l10n/git-po-helper#readme) in workflow
-            [#${{ github.run_number }}](${{ env.GITHUB_SERVER_URL }}/${{ github.repository }}/actions/runs/${{ github.run_id }}):
-
-            ```
-
-            ${{ env.COMMENT_BODY }}
-
-            ```

.github/workflows/main.yml

@@ -1,4 +1,4 @@
-name: CI
+name: CI/PR
 
 on: [push, pull_request]
 
@@ -7,7 +7,6 @@ env:
 
 jobs:
   ci-config:
-    name: config
     runs-on: ubuntu-latest
     outputs:
       enabled: ${{ steps.check-ref.outputs.enabled }}${{ steps.skip-if-redundant.outputs.enabled }}
@@ -78,7 +77,6 @@ jobs:
             }
 
   windows-build:
-    name: win build
     needs: ci-config
     if: needs.ci-config.outputs.enabled == 'yes'
     runs-on: windows-latest
@@ -90,7 +88,7 @@ jobs:
       env:
         HOME: ${{runner.workspace}}
         NO_PERL: 1
-      run: . /etc/profile && ci/make-test-artifacts.sh artifacts
+      run: ci/make-test-artifacts.sh artifacts
     - name: zip up tracked files
       run: git archive -o artifacts/tracked.tar.gz HEAD
     - name: upload tracked files and build artifacts
@@ -99,7 +97,6 @@ jobs:
         name: windows-artifacts
         path: artifacts
   windows-test:
-    name: win test
     runs-on: windows-latest
     needs: [windows-build]
     strategy:
@@ -118,7 +115,7 @@ jobs:
     - uses: git-for-windows/setup-git-for-windows-sdk@v1
     - name: test
       shell: bash
-      run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10
+      run: ci/run-test-slice.sh ${{matrix.nr}} 10
     - name: ci/print-test-failures.sh
       if: failure()
       shell: bash
@@ -130,7 +127,6 @@ jobs:
         name: failed-tests-windows
         path: ${{env.FAILED_TEST_ARTIFACTS}}
   vs-build:
-    name: win+VS build
     needs: ci-config
     if: needs.ci-config.outputs.enabled == 'yes'
     env:
@@ -182,7 +178,6 @@ jobs:
         name: vs-artifacts
         path: artifacts
   vs-test:
-    name: win+VS test
     runs-on: windows-latest
     needs: vs-build
     strategy:
@@ -203,7 +198,8 @@ jobs:
       shell: bash
       env:
         NO_SVN_TESTS: 1
-      run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10
+        GIT_TEST_SKIP_REBASE_P: 1
+      run: ci/run-test-slice.sh ${{matrix.nr}} 10
     - name: ci/print-test-failures.sh
       if: failure()
       shell: bash
@@ -215,7 +211,6 @@ jobs:
         name: failed-tests-windows
         path: ${{env.FAILED_TEST_ARTIFACTS}}
   regular:
-    name: ${{matrix.vector.jobname}} (${{matrix.vector.pool}})
     needs: ci-config
     if: needs.ci-config.outputs.enabled == 'yes'
     strategy:
@@ -225,37 +220,21 @@ jobs:
           - jobname: linux-clang
             cc: clang
             pool: ubuntu-latest
-          - jobname: linux-sha256
-            cc: clang
-            os: ubuntu
-            pool: ubuntu-latest
           - jobname: linux-gcc
             cc: gcc
-            cc_package: gcc-8
-            pool: ubuntu-latest
-          - jobname: linux-TEST-vars
-            cc: gcc
-            os: ubuntu
-            cc_package: gcc-8
             pool: ubuntu-latest
           - jobname: osx-clang
             cc: clang
             pool: macos-latest
           - jobname: osx-gcc
             cc: gcc
-            cc_package: gcc-9
             pool: macos-latest
           - jobname: linux-gcc-default
             cc: gcc
             pool: ubuntu-latest
-          - jobname: linux-leaks
-            cc: gcc
-            pool: ubuntu-latest
     env:
       CC: ${{matrix.vector.cc}}
-      CC_PACKAGE: ${{matrix.vector.cc_package}}
       jobname: ${{matrix.vector.jobname}}
-      runs_on_pool: ${{matrix.vector.pool}}
     runs-on: ${{matrix.vector.pool}}
     steps:
     - uses: actions/checkout@v2
@@ -270,7 +249,6 @@ jobs:
         name: failed-tests-${{matrix.vector.jobname}}
         path: ${{env.FAILED_TEST_ARTIFACTS}}
   dockerized:
-    name: ${{matrix.vector.jobname}} (${{matrix.vector.image}})
     needs: ci-config
     if: needs.ci-config.outputs.enabled == 'yes'
     strategy:
@@ -279,8 +257,7 @@ jobs:
         vector:
         - jobname: linux-musl
           image: alpine
-        - jobname: linux32
-          os: ubuntu32
+        - jobname: Linux32
           image: daald/ubuntu32:xenial
         - jobname: pedantic
           image: fedora
@@ -310,7 +287,6 @@ jobs:
     - uses: actions/checkout@v2
     - run: ci/install-dependencies.sh
     - run: ci/run-static-analysis.sh
-    - run: ci/check-directional-formatting.bash
   sparse:
     needs: ci-config
     if: needs.ci-config.outputs.enabled == 'yes'
@@ -332,7 +308,6 @@ jobs:
       run: ci/install-dependencies.sh
     - run: make sparse
   documentation:
-    name: documentation
     needs: ci-config
     if: needs.ci-config.outputs.enabled == 'yes'
     env:

.gitignore

@@ -125,6 +125,7 @@
 /git-range-diff
 /git-read-tree
 /git-rebase
+/git-rebase--preserve-merges
 /git-receive-pack
 /git-reflog
 /git-remote
@@ -189,7 +190,6 @@
 /gitweb/static/gitweb.min.*
 /config-list.h
 /command-list.h
-/hook-list.h
 *.tar.gz
 *.dsc
 *.deb
@@ -224,7 +224,6 @@
 *.lib
 *.res
 *.sln
-*.sp
 *.suo
 *.ncb
 *.vcproj

.travis.yml

@@ -0,0 +1,60 @@
+language: c
+
+cache:
+  directories:
+    - $HOME/travis-cache
+
+os:
+  - linux
+  - osx
+
+osx_image: xcode10.1
+
+compiler:
+  - clang
+  - gcc
+
+matrix:
+  include:
+    - env: jobname=linux-gcc-default
+      os: linux
+      compiler:
+      addons:
+      before_install:
+    - env: jobname=linux-gcc-4.8
+      os: linux
+      dist: trusty
+      compiler:
+    - env: jobname=Linux32
+      os: linux
+      compiler:
+      addons:
+      services:
+        - docker
+      before_install:
+      script: ci/run-docker.sh
+    - env: jobname=linux-musl
+      os: linux
+      compiler:
+      addons:
+      services:
+        - docker
+      before_install:
+      script: ci/run-docker.sh
+    - env: jobname=StaticAnalysis
+      os: linux
+      compiler:
+      script: ci/run-static-analysis.sh
+      after_failure:
+    - env: jobname=Documentation
+      os: linux
+      compiler:
+      script: ci/test-documentation.sh
+      after_failure:
+
+before_install: ci/install-dependencies.sh
+script: ci/run-build-and-tests.sh
+after_failure: ci/print-test-failures.sh
+
+notifications:
+  email: false

Documentation/.gitignore

@@ -14,5 +14,4 @@ manpage-base-url.xsl
 SubmittingPatches.txt
 tmp-doc-diff/
 GIT-ASCIIDOCFLAGS
-/.build/
 /GIT-EXCLUDED-PROGRAMS

Documentation/CodingGuidelines

@@ -499,33 +499,6 @@ For Python scripts:
  - Where required libraries do not restrict us to Python 2, we try to
    also be compatible with Python 3.1 and later.
 
-
-Program Output
-
- We make a distinction between a Git command's primary output and
- output which is merely chatty feedback (for instance, status
- messages, running transcript, or progress display), as well as error
- messages. Roughly speaking, a Git command's primary output is that
- which one might want to capture to a file or send down a pipe; its
- chatty output should not interfere with these use-cases.
-
- As such, primary output should be sent to the standard output stream
- (stdout), and chatty output should be sent to the standard error
- stream (stderr). Examples of commands which produce primary output
- include `git log`, `git show`, and `git branch --list` which generate
- output on the stdout stream.
-
- Not all Git commands have primary output; this is often true of
- commands whose main function is to perform an action. Some action
- commands are silent, whereas others are chatty. An example of a
- chatty action commands is `git clone` with its "Cloning into
- '<path>'..." and "Checking connectivity..." status messages which it
- sends to the stderr stream.
-
- Error messages from Git commands should always be sent to the stderr
- stream.
-
-
 Error Messages
 
  - Do not end error messages with a full stop.

Documentation/Makefile

@@ -90,7 +90,6 @@ SP_ARTICLES += $(API_DOCS)
 TECH_DOCS += MyFirstContribution
 TECH_DOCS += MyFirstObjectWalk
 TECH_DOCS += SubmittingPatches
-TECH_DOCS += technical/bundle-format
 TECH_DOCS += technical/hash-function-transition
 TECH_DOCS += technical/http-protocol
 TECH_DOCS += technical/index-format
@@ -226,7 +225,6 @@ endif
 
 ifneq ($(findstring $(MAKEFLAGS),s),s)
 ifndef V
-	QUIET		= @
 	QUIET_ASCIIDOC	= @echo '   ' ASCIIDOC $@;
 	QUIET_XMLTO	= @echo '   ' XMLTO $@;
 	QUIET_DB2TEXI	= @echo '   ' DB2TEXI $@;
@@ -234,15 +232,11 @@ ifndef V
 	QUIET_DBLATEX	= @echo '   ' DBLATEX $@;
 	QUIET_XSLTPROC	= @echo '   ' XSLTPROC $@;
 	QUIET_GEN	= @echo '   ' GEN $@;
+	QUIET_LINT	= @echo '   ' LINT $@;
 	QUIET_STDERR	= 2> /dev/null
 	QUIET_SUBDIR0	= +@subdir=
 	QUIET_SUBDIR1	= ;$(NO_SUBDIR) echo '   ' SUBDIR $$subdir; \
 			  $(MAKE) $(PRINT_DIR) -C $$subdir
-
-	QUIET_LINT_GITLINK	= @echo '   ' LINT GITLINK $<;
-	QUIET_LINT_MANSEC	= @echo '   ' LINT MAN SEC $<;
-	QUIET_LINT_MANEND	= @echo '   ' LINT MAN END $<;
-
 	export V
 endif
 endif
@@ -290,7 +284,7 @@ install-html: html
 ../GIT-VERSION-FILE: FORCE
 	$(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE
 
-ifneq ($(filter-out lint-docs clean,$(MAKECMDGOALS)),)
+ifneq ($(MAKECMDGOALS),clean)
 -include ../GIT-VERSION-FILE
 endif
 
@@ -349,7 +343,6 @@ GIT-ASCIIDOCFLAGS: FORCE
             fi
 
 clean:
-	$(RM) -rf .build/
 	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
 	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
 	$(RM) *.pdf
@@ -463,61 +456,14 @@ quick-install-html: require-htmlrepo
 print-man1:
 	@for i in $(MAN1_TXT); do echo $$i; done
 
-## Lint: Common
-.build:
-	$(QUIET)mkdir $@
-.build/lint-docs: | .build
-	$(QUIET)mkdir $@
-
-## Lint: gitlink
-.build/lint-docs/gitlink: | .build/lint-docs
-	$(QUIET)mkdir $@
-.build/lint-docs/gitlink/howto: | .build/lint-docs/gitlink
-	$(QUIET)mkdir $@
-.build/lint-docs/gitlink/config: | .build/lint-docs/gitlink
-	$(QUIET)mkdir $@
-LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
-$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink
-$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/howto
-$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/config
-$(LINT_DOCS_GITLINK): lint-gitlink.perl
-$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
-	$(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \
-		$< \
+lint-docs::
+	$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \
 		$(HOWTO_TXT) $(DOC_DEP_TXT) \
 		--section=1 $(MAN1_TXT) \
 		--section=5 $(MAN5_TXT) \
-		--section=7 $(MAN7_TXT) >$@
-.PHONY: lint-docs-gitlink
-lint-docs-gitlink: $(LINT_DOCS_GITLINK)
-
-## Lint: man-end-blurb
-.build/lint-docs/man-end-blurb: | .build/lint-docs
-	$(QUIET)mkdir $@
-LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
-$(LINT_DOCS_MAN_END_BLURB): | .build/lint-docs/man-end-blurb
-$(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl
-$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt
-	$(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@
-.PHONY: lint-docs-man-end-blurb
-lint-docs-man-end-blurb: $(LINT_DOCS_MAN_END_BLURB)
-
-## Lint: man-section-order
-.build/lint-docs/man-section-order: | .build/lint-docs
-	$(QUIET)mkdir $@
-LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
-$(LINT_DOCS_MAN_SECTION_ORDER): | .build/lint-docs/man-section-order
-$(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl
-$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt
-	$(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@
-.PHONY: lint-docs-man-section-order
-lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER)
-
-## Lint: list of targets above
-.PHONY: lint-docs
-lint-docs: lint-docs-gitlink
-lint-docs: lint-docs-man-end-blurb
-lint-docs: lint-docs-man-section-order
+		--section=7 $(MAN7_TXT); \
+	$(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT); \
+	$(PERL_PATH) lint-man-section-order.perl $(MAN_TXT);
 
 ifeq ($(wildcard po/Makefile),po/Makefile)
 doc-l10n install-l10n::

Documentation/MyFirstContribution.txt

@@ -905,34 +905,19 @@ Sending emails with Git is a two-part process; before you can prepare the emails
 themselves, you'll need to prepare the patches. Luckily, this is pretty simple:
 
 ----
-$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh
+$ git format-patch --cover-letter -o psuh/ master..psuh
 ----
 
- . The `--cover-letter` option tells `format-patch` to create a
-   cover letter template for you. You will need to fill in the
-   template before you're ready to send - but for now, the template
-   will be next to your other patches.
+The `--cover-letter` parameter tells `format-patch` to create a cover letter
+template for you. You will need to fill in the template before you're ready
+to send - but for now, the template will be next to your other patches.
 
- . The `-o psuh/` option tells `format-patch` to place the patch
-   files into a directory. This is useful because `git send-email`
-   can take a directory and send out all the patches from there.
+The `-o psuh/` parameter tells `format-patch` to place the patch files into a
+directory. This is useful because `git send-email` can take a directory and
+send out all the patches from there.
 
- . The `--base=auto` option tells the command to record the "base
-   commit", on which the recipient is expected to apply the patch
-   series.  The `auto` value will cause `format-patch` to compute
-   the base commit automatically, which is the merge base of tip
-   commit of the remote-tracking branch and the specified revision
-   range.
-
- . The `psuh@{u}..psuh` option tells `format-patch` to generate
-   patches for the commits you created on the `psuh` branch since it
-   forked from its upstream (which is `origin/master` if you
-   followed the example in the "Set up your workspace" section).  If
-   you are already on the `psuh` branch, you can just say `@{u}`,
-   which means "commits on the current branch since it forked from
-   its upstream", which is the same thing.
-
-The command will make one patch file per commit. After you
+`master..psuh` tells `format-patch` to generate patches for the difference
+between `master` and `psuh`. It will make one patch file per commit. After you
 run, you can go have a look at each of the patches with your favorite text
 editor and make sure everything looks alright; however, it's not recommended to
 make code fixups via the patch file. It's a better idea to make the change the
@@ -1044,42 +1029,22 @@ kidding - be patient!)
 [[v2-git-send-email]]
 === Sending v2
 
-This section will focus on how to send a v2 of your patchset. To learn what
-should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
-information on how to handle comments from reviewers.
+Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
+handle comments from reviewers. Continue this section when your topic branch is
+shaped the way you want it to look for your patchset v2.
 
-We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
-mark the tip of our v1 branch for easy reference:
+When you're ready with the next iteration of your patch, the process is fairly
+similar.
+
+First, generate your v2 patches again:
 
 ----
-$ git checkout psuh
-$ git branch psuh-v1
+$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
 ----
 
-Refine your patch series by using `git rebase -i` to adjust commits based upon
-reviewer comments. Once the patch series is ready for submission, generate your
-patches again, but with some new flags:
-
-----
-$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
-----
-
-The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
-range-diff between `psuh-v1` and `psuh` in the cover letter (see
-linkgit:git-range-diff[1]). This helps tell reviewers about the differences
-between your v1 and v2 patches.
-
-The `-v2` parameter tells `format-patch` to output your patches
-as version "2". For instance, you may notice that your v2 patches are
-all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format
-your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]",
-and your range-diff will be prefaced with "Range-diff against v1".
-
-Afer you run this command, `format-patch` will output the patches to the `psuh/`
-directory, alongside the v1 patches. Using a single directory makes it easy to
-refer to the old v1 patches while proofreading the v2 patches, but you will need
-to be careful to send out only the v2 patches. We will use a pattern like
-"psuh/v2-*.patch" (not "psuh/*.patch", which would match v1 and v2 patches).
+This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
+to the `psuh/` directory. You may notice that they are sitting alongside the v1
+patches; that's fine, but be careful when you are ready to send them.
 
 Edit your cover letter again. Now is a good time to mention what's different
 between your last version and now, if it's something significant. You do not
@@ -1117,7 +1082,7 @@ to the command:
 ----
 $ git send-email --to=target@example.com
 		 --in-reply-to="<foo.12345.author@example.com>"
-		 psuh/v2-*.patch
+		 psuh/v2*
 ----
 
 [[single-patch]]

Documentation/MyFirstObjectWalk.txt

@@ -58,19 +58,14 @@ running, enable trace output by setting the environment variable `GIT_TRACE`.
 
 Add usage text and `-h` handling, like all subcommands should consistently do
 (our test suite will notice and complain if you fail to do so).
-We'll need to include the `parse-options.h` header.
 
 ----
-#include "parse-options.h"
-
-...
-
 int cmd_walken(int argc, const char **argv, const char *prefix)
 {
 	const char * const walken_usage[] = {
 		N_("git walken"),
 		NULL,
-	};
+	}
 	struct option options[] = {
 		OPT_END()
 	};
@@ -200,14 +195,9 @@ Similarly to the default values, we don't have anything to do here yet
 ourselves; however, we should call `git_default_config()` if we aren't calling
 any other existing config callbacks.
 
-Add a new function to `builtin/walken.c`.
-We'll also need to include the `config.h` header:
+Add a new function to `builtin/walken.c`:
 
 ----
-#include "config.h"
-
-...
-
 static int git_walken_config(const char *var, const char *value, void *cb)
 {
 	/*
@@ -239,14 +229,8 @@ typically done by calling `repo_init_revisions()` with the repository you intend
 to target, as well as the `prefix` argument of `cmd_walken` and your `rev_info`
 struct.
 
-Add the `struct rev_info` and the `repo_init_revisions()` call.
-We'll also need to include the `revision.h` header:
-
+Add the `struct rev_info` and the `repo_init_revisions()` call:
 ----
-#include "revision.h"
-
-...
-
 int cmd_walken(int argc, const char **argv, const char *prefix)
 {
 	/* This can go wherever you like in your declarations.*/
@@ -640,14 +624,9 @@ static void walken_object_walk(struct rev_info *rev)
 ----
 
 Let's start by calling just the unfiltered walk and reporting our counts.
-Complete your implementation of `walken_object_walk()`.
-We'll also need to include the `list-objects.h` header.
+Complete your implementation of `walken_object_walk()`:
 
 ----
-#include "list-objects.h"
-
-...
-
 	traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL);
 
 	printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count,
@@ -718,7 +697,7 @@ First, we'll need to `#include "list-objects-filter-options.h"` and set up the
 ----
 static void walken_object_walk(struct rev_info *rev)
 {
-	struct list_objects_filter_options filter_options = { 0 };
+	struct list_objects_filter_options filter_options = {};
 
 	...
 ----

Documentation/RelNotes/2.30.5.txt

@@ -0,0 +1,12 @@
+Git v2.30.5 Release Notes
+=========================
+
+This release contains minor fix-ups for the changes that went into
+Git 2.30.3 and 2.30.4, addressing CVE-2022-29187.
+
+ * The safety check that verifies a safe ownership of the Git
+   worktree is now extended to also cover the ownership of the Git
+   directory (and the `.git` file, if there is any).
+
+Carlo Marcelo Arenas Belón (1):
+      setup: tighten ownership checks post CVE-2022-24765

Documentation/RelNotes/2.30.6.txt

@@ -0,0 +1,60 @@
+Git v2.30.6 Release Notes
+=========================
+
+This release addresses the security issues CVE-2022-39253 and
+CVE-2022-39260.
+
+Fixes since v2.30.5
+-------------------
+
+ * CVE-2022-39253:
+   When relying on the `--local` clone optimization, Git dereferences
+   symbolic links in the source repository before creating hardlinks
+   (or copies) of the dereferenced link in the destination repository.
+   This can lead to surprising behavior where arbitrary files are
+   present in a repository's `$GIT_DIR` when cloning from a malicious
+   repository.
+
+   Git will no longer dereference symbolic links via the `--local`
+   clone mechanism, and will instead refuse to clone repositories that
+   have symbolic links present in the `$GIT_DIR/objects` directory.
+
+   Additionally, the value of `protocol.file.allow` is changed to be
+   "user" by default.
+
+ * CVE-2022-39260:
+   An overly-long command string given to `git shell` can result in
+   overflow in `split_cmdline()`, leading to arbitrary heap writes and
+   remote code execution when `git shell` is exposed and the directory
+   `$HOME/git-shell-commands` exists.
+
+   `git shell` is taught to refuse interactive commands that are
+   longer than 4MiB in size. `split_cmdline()` is hardened to reject
+   inputs larger than 2GiB.
+
+Credit for finding CVE-2022-39253 goes to Cory Snider of Mirantis. The
+fix was authored by Taylor Blau, with help from Johannes Schindelin.
+
+Credit for finding CVE-2022-39260 goes to Kevin Backhouse of GitHub.
+The fix was authored by Kevin Backhouse, Jeff King, and Taylor Blau.
+
+
+Jeff King (2):
+      shell: add basic tests
+      shell: limit size of interactive commands
+
+Kevin Backhouse (1):
+      alias.c: reject too-long cmdline strings in split_cmdline()
+
+Taylor Blau (11):
+      builtin/clone.c: disallow `--local` clones with symlinks
+      t/lib-submodule-update.sh: allow local submodules
+      t/t1NNN: allow local submodules
+      t/2NNNN: allow local submodules
+      t/t3NNN: allow local submodules
+      t/t4NNN: allow local submodules
+      t/t5NNN: allow local submodules
+      t/t6NNN: allow local submodules
+      t/t7NNN: allow local submodules
+      t/t9NNN: allow local submodules
+      transport: make `protocol.file.allow` be "user" by default

Documentation/RelNotes/2.31.4.txt

@@ -0,0 +1,6 @@
+Git v2.31.4 Release Notes
+=========================
+
+This release merges up the fixes that appear in v2.30.5 to address
+the security issue CVE-2022-29187; see the release notes for that
+version for details.

Documentation/RelNotes/2.31.5.txt

@@ -0,0 +1,5 @@
+Git v2.31.5 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.

Documentation/RelNotes/2.32.3.txt

@@ -0,0 +1,6 @@
+Git v2.32.3 Release Notes
+=========================
+
+This release merges up the fixes that appear in v2.30.5 and
+v2.31.4 to address the security issue CVE-2022-29187; see the
+release notes for these versions for details.

Documentation/RelNotes/2.32.4.txt

@@ -0,0 +1,5 @@
+Git v2.32.4 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.

Documentation/RelNotes/2.33.4.txt

@@ -0,0 +1,6 @@
+Git v2.33.4 Release Notes
+=========================
+
+This release merges up the fixes that appear in v2.30.5, v2.31.4
+and v2.32.3 to address the security issue CVE-2022-29187; see
+the release notes for these versions for details.

Documentation/RelNotes/2.33.5.txt

@@ -0,0 +1,5 @@
+Git v2.33.5 Release Notes
+=========================
+
+This release merges the security fix that appears in v2.30.6; see
+the release notes for that version for details.

Documentation/RelNotes/2.34.0.txt

@@ -1,438 +0,0 @@
-Git 2.34 Release Notes
-======================
-
-Updates since Git 2.33
-----------------------
-
-Backward compatibility notes
-
- * The "--preserve-merges" option of "git rebase" has been removed.
-
-
-UI, Workflows & Features
-
- * Pathname expansion (like "~username/") learned a way to specify a
-   location relative to Git installation (e.g. its $sharedir which is
-   $(prefix)/share), with "%(prefix)".
-
- * The `ort` strategy is used instead of `recursive` as the default
-   merge strategy.
-
- * The userdiff pattern for "java" language has been updated.
-
- * "git rebase" by default skips changes that are equivalent to
-   commits that are already in the history the branch is rebased onto;
-   give messages when this happens to let the users be aware of
-   skipped commits, and also teach them how to tell "rebase" to keep
-   duplicated changes.
-
- * The advice message that "git cherry-pick" gives when it asks
-   conflicted replay of a commit to be resolved by the end user has
-   been updated.
-
- * After "git clone --recurse-submodules", all submodules are cloned
-   but they are not by default recursed into by other commands.  With
-   submodule.stickyRecursiveClone configuration set, submodule.recurse
-   configuration is set to true in a repository created by "clone"
-   with "--recurse-submodules" option.
-
- * The logic for auto-correction of misspelt subcommands learned to go
-   interactive when the help.autocorrect configuration variable is set
-   to 'prompt'.
-
- * "git maintenance" scheduler learned to use systemd timers as a
-   possible backend.
-
- * "git diff --submodule=diff" showed failure from run_command() when
-   trying to run diff inside a submodule, when the user manually
-   removes the submodule directory.
-
- * "git bundle unbundle" learned to show progress display.
-
- * In cone mode, the sparse-index code path learned to remove ignored
-   files (like build artifacts) outside the sparse cone, allowing the
-   entire directory outside the sparse cone to be removed, which is
-   especially useful when the sparse patterns change.
-
- * Taking advantage of the CGI interface, http-backend has been
-   updated to enable protocol v2 automatically when the other side
-   asks for it.
-
- * The credential-cache helper has been adjusted to Windows.
-
- * The error in "git help no-such-git-command" is handled better.
-
- * The unicode character width table (used for output alignment) has
-   been updated.
-
- * The ref iteration code used to optionally allow dangling refs to be
-   shown, which has been tightened up.
-
- * "git add", "git mv", and "git rm" have been adjusted to avoid
-   updating paths outside of the sparse-checkout definition unless
-   the user specifies a "--sparse" option.
-
- * "git repack" has been taught to generate multi-pack reachability
-   bitmaps.
-
- * "git fsck" has been taught to report mismatch between expected and
-   actual types of an object better.
-
- * In addition to GnuPG, ssh public crypto can be used for object and
-   push-cert signing.  Note that this feature cannot be used with
-   ssh-keygen from OpenSSH 8.7, whose support for it is broken.  Avoid
-   using it unless you update to OpenSSH 8.8.
-
- * "git log --grep=string --author=name" learns to highlight hits just
-   like "git grep string" does.
-
-
-
-Performance, Internal Implementation, Development Support etc.
-
- * "git bisect" spawned "git show-branch" only to pretty-print the
-   title of the commit after checking out the next version to be
-   tested; this has been rewritten in C.
-
- * "git add" can work better with the sparse index.
-
- * Support for ancient versions of cURL library (pre 7.19.4) has been
-   dropped.
-
- * A handful of tests that assumed implementation details of files
-   backend for refs have been cleaned up.
-
- * trace2 logs learned to show parent process name to see in what
-   context Git was invoked.
-
- * Loading of ref tips to prepare for common ancestry negotiation in
-   "git fetch-pack" has been optimized by taking advantage of the
-   commit graph when available.
-
- * Remind developers that the userdiff patterns should be kept simple
-   and permissive, assuming that the contents they apply are always
-   syntactically correct.
-
- * The current implementation of GIT_TEST_FAIL_PREREQS is broken in
-   that checking for the lack of a prerequisite would not work.  Avoid
-   the use of "if ! test_have_prereq X" in a test script.
-
- * The revision traversal API has been optimized by taking advantage
-   of the commit-graph, when available, to determine if a commit is
-   reachable from any of the existing refs.
-
- * "git fetch --quiet" optimization to avoid useless computation of
-   info that will never be displayed.
-
- * Callers from older advice_config[] based API has been updated to
-   use the newer advice_if_enabled() and advice_enabled() API.
-
- * Teach "test_pause" and "debug" helpers to allow using the HOME and
-   TERM environment variables the user usually uses.
-
- * "make INSTALL_STRIP=-s install" allows the installation step to use
-   "install -s" to strip the binaries as they get installed.
-
- * Code that handles large number of refs in the "git fetch" code
-   path has been optimized.
-
- * The reachability bitmap file used to be generated only for a single
-   pack, but now we've learned to generate bitmaps for history that
-   span across multiple packfiles.
-
- * The code to make "git grep" recurse into submodules has been
-   updated to migrate away from the "add submodule's object store as
-   an alternate object store" mechanism (which is suboptimal).
-
- * The tracing of process ancestry information has been enhanced.
-
- * Reduce number of write(2) system calls while sending the
-   ref advertisement.
-
- * Update the build procedure to use the "-pedantic" build when
-   DEVELOPER makefile macro is in effect.
-
- * Large part of "git submodule add" gets rewritten in C.
-
- * The run-command API has been updated so that the callers can easily
-   ask the file descriptors open for packfiles to be closed immediately
-   before spawning commands that may trigger auto-gc.
-
- * An oddball OPTION_ARGUMENT feature has been removed from the
-   parse-options API.
-
- * The mergesort implementation used to sort linked list has been
-   optimized.
-
- * Remove external declaration of functions that no longer exist.
-
- * "git multi-pack-index write --bitmap" learns to propagate the
-   hashcache from original bitmap to resulting bitmap.
-
- * CI learns to run the leak sanitizer builds.
-
- * "git grep --recurse-submodules" takes trees and blobs from the
-   submodule repository, but the textconv settings when processing a
-   blob from the submodule is not taken from the submodule repository.
-   A test is added to demonstrate the issue, without fixing it.
-
- * Teach "git help -c" into helping the command line completion of
-   configuration variables.
-
- * When "git cmd -h" shows more than one line of usage text (e.g.
-   the cmd subcommand may take sub-sub-command), parse-options API
-   learned to align these lines, even across i18n/l10n.
-
- * Prevent "make sparse" from running for the source files that
-   haven't been modified.
-
- * The code path to write a new version of .midx multi-pack index files
-   has learned to release the mmaped memory holding the current
-   version of .midx before removing them from the disk, as some
-   platforms do not allow removal of a file that still has mapping.
-
- * A new feature has been added to abort early in the test framework.
-
-
-Fixes since v2.33
------------------
-
- * Input validation of "git pack-objects --stdin-packs" has been
-   corrected.
-
- * Bugfix for common ancestor negotiation recently introduced in "git
-   push" code path.
-
- * "git pull" had various corner cases that were not well thought out
-   around its --rebase backend, e.g. "git pull --ff-only" did not stop
-   but went ahead and rebased when the history on other side is not a
-   descendant of our history.  The series tries to fix them up.
-
- * "git apply" miscounted the bytes and failed to read to the end of
-   binary hunks.
-
- * "git range-diff" code clean-up.
-
- * "git commit --fixup" now works with "--edit" again, after it was
-   broken in v2.32.
-
- * Use upload-artifacts v1 (instead of v2) for 32-bit linux, as the
-   new version has a blocker bug for that architecture.
-
- * Checking out all the paths from HEAD during the last conflicted
-   step in "git rebase" and continuing would cause the step to be
-   skipped (which is expected), but leaves MERGE_MSG file behind in
-   $GIT_DIR and confuses the next "git commit", which has been
-   corrected.
-
- * Various bugs in "git rebase -r" have been fixed.
-
- * mmap() imitation used to call xmalloc() that dies upon malloc()
-   failure, which has been corrected to just return an error to the
-   caller to be handled.
-
- * "git diff --relative" segfaulted and/or produced incorrect result
-   when there are unmerged paths.
-
- * The delayed checkout code path in "git checkout" etc. were chatty
-   even when --quiet and/or --no-progress options were given.
-
- * "git branch -D <branch>" used to refuse to remove a broken branch
-   ref that points at a missing commit, which has been corrected.
-
- * Build update for Apple clang.
-
- * The parser for the "--nl" option of "git column" has been
-   corrected.
-
- * "git upload-pack" which runs on the other side of "git fetch"
-   forgot to take the ref namespaces into account when handling
-   want-ref requests.
-
- * The sparse-index support can corrupt the index structure by storing
-   a stale and/or uninitialized data, which has been corrected.
-
- * Buggy tests could damage repositories outside the throw-away test
-   area we created.  We now by default export GIT_CEILING_DIRECTORIES
-   to limit the damage from such a stray test.
-
- * Even when running "git send-email" without its own threaded
-   discussion support, a threading related header in one message is
-   carried over to the subsequent message to result in an unwanted
-   threading, which has been corrected.
-
- * The output from "git fast-export", when its anonymization feature
-   is in use, showed an annotated tag incorrectly.
-
- * Recent "diff -m" changes broke "gitk", which has been corrected.
-
- * The "git apply -3" code path learned not to bother the lower level
-   merge machinery when the three-way merge can be trivially resolved
-   without the content level merge.  This fixes a regression caused by
-   recent "-3way first and fall back to direct application" change.
-
- * The code that optionally creates the *.rev reverse index file has
-   been optimized to avoid needless computation when it is not writing
-   the file out.
-
- * "git range-diff -I... <range> <range>" segfaulted, which has been
-   corrected.
-
- * The order in which various files that make up a single (conceptual)
-   packfile has been reevaluated and straightened up.  This matters in
-   correctness, as an incomplete set of files must not be shown to a
-   running Git.
-
- * The "mode" word is useless in a call to open(2) that does not
-   create a new file.  Such a call in the files backend of the ref
-   subsystem has been cleaned up.
-
- * "git update-ref --stdin" failed to flush its output as needed,
-   which potentially led the conversation to a deadlock.
-
- * When "git am --abort" fails to abort correctly, it still exited
-   with exit status of 0, which has been corrected.
-
- * Correct nr and alloc members of strvec struct to be of type size_t.
-
- * "git stash", where the tentative change involves changing a
-   directory to a file (or vice versa), was confused, which has been
-   corrected.
-
- * "git clone" from a repository whose HEAD is unborn into a bare
-   repository didn't follow the branch name the other side used, which
-   is corrected.
-
- * "git cvsserver" had a long-standing bug in its authentication code,
-   which has finally been corrected (it is unclear and is a separate
-   question if anybody is seriously using it, though).
-
- * "git difftool --dir-diff" mishandled symbolic links.
-
- * Sensitive data in the HTTP trace were supposed to be redacted, but
-   we failed to do so in HTTP/2 requests.
-
- * "make clean" has been updated to remove leftover .depend/
-   directories, even when it is not told to use them to compute header
-   dependencies.
-
- * Protocol v0 clients can get stuck parsing a malformed feature line.
-
- * A few kinds of changes "git status" can show were not documented.
-   (merge d2a534c515 ja/doc-status-types-and-copies later to maint).
-
- * The mergesort implementation used to sort linked list has been
-   optimized.
-   (merge c90cfc225b rs/mergesort later to maint).
-
- * An editor session launched during a Git operation (e.g. during 'git
-   commit') can leave the terminal in a funny state.  The code path
-   has updated to save the terminal state before, and restore it
-   after, it spawns an editor.
-   (merge 3d411afabc cm/save-restore-terminal later to maint).
-
- * "git cat-file --batch" with the "--batch-all-objects" option is
-   supposed to iterate over all the objects found in a repository, but
-   it used to translate these object names using the replace mechanism,
-   which defeats the point of enumerating all objects in the repository.
-   This has been corrected.
-   (merge bf972896d7 jk/cat-file-batch-all-wo-replace later to maint).
-
- * Recent sparse-index work broke safety against attempts to add paths
-   with trailing slashes to the index, which has been corrected.
-   (merge c8ad9d04c6 rs/make-verify-path-really-verify-again later to maint).
-
- * The "--color-lines" and "--color-by-age" options of "git blame"
-   have been missing, which are now documented.
-   (merge 8c32856133 bs/doc-blame-color-lines later to maint).
-
- * The PATH used in CI job may be too wide and let incompatible dlls
-   to be grabbed, which can cause the build&test to fail.  Tighten it.
-   (merge 7491ef6198 js/windows-ci-path-fix later to maint).
-
- * Avoid performance measurements from getting ruined by gc and other
-   housekeeping pauses interfering in the middle.
-   (merge be79131a53 rs/disable-gc-during-perf-tests later to maint).
-
- * Stop "git add --dry-run" from creating new blob and tree objects.
-   (merge e578d0311d rs/add-dry-run-without-objects later to maint).
-
- * "git commit" gave duplicated error message when the object store
-   was unwritable, which has been corrected.
-   (merge 4ef91a2d79 ab/fix-commit-error-message-upon-unwritable-object-store later to maint).
-
- * Recent sparse-index addition, namely any use of index_name_pos(),
-   can expand sparse index entries and breaks any code that walks
-   cache-tree or existing index entries.  One such instance of such a
-   breakage has been corrected.
-
- * The xxdiff difftool backend can exit with status 128, which the
-   difftool-helper that launches the backend takes as a significant
-   failure, when it is not significant at all.  Work it around.
-   (merge 571f4348dd da/mergetools-special-case-xxdiff-exit-128 later to maint).
-
- * Improve test framework around unwritable directories.
-   (merge 5d22e18965 ab/test-cleanly-recreate-trash-directory later to maint).
-
- * "git push" client talking to an HTTP server did not diagnose the
-   lack of the final status report from the other side correctly,
-   which has been corrected.
-   (merge c5c3486f38 jk/http-push-status-fix later to maint).
-
- * Update "git archive" documentation and give explicit mention on the
-   compression level for both zip and tar.gz format.
-   (merge c4b208c309 bs/archive-doc-compression-level later to maint).
-
- * Drop "git sparse-checkout" from the list of common commands.
-   (merge 6a9a50a8af sg/sparse-index-not-that-common-a-command later to maint).
-
- * "git branch -c/-m new old" was not described to copy config, which
-   has been corrected.
-   (merge 8252ec300e jc/branch-copy-doc later to maint).
-
- * Squelch over-eager warning message added during this cycle.
-
- * Fix long-standing shell syntax error in the completion script.
-   (merge 46b0585286 re/completion-fix-test-equality later to maint).
-
- * Teach "git commit-graph" command not to allow using replace objects
-   at all, as we do not use the commit-graph at runtime when we see
-   object replacement.
-   (merge 095d112f8c ab/ignore-replace-while-working-on-commit-graph later to maint).
-
- * "git pull --no-verify" did not affect the underlying "git merge".
-   (merge 47bfdfb3fd ar/fix-git-pull-no-verify later to maint).
-
- * One CI task based on Fedora image noticed a not-quite-kosher
-   construct recently, which has been corrected.
-
- * "git pull --ff-only" and "git pull --rebase --ff-only" should make
-   it a no-op to attempt pulling from a remote that is behind us, but
-   instead the command errored out by saying it was impossible to
-   fast-forward, which may technically be true, but not a useful thing
-   to diagnose as an error.  This has been corrected.
-   (merge 361cb52383 jc/fix-pull-ff-only-when-already-up-to-date later to maint).
-
- * The way Cygwin emulates a unix-domain socket, on top of which the
-   simple-ipc mechanism is implemented, can race with the program on
-   the other side that wants to use the socket, and briefly make it
-   appear as a regular file before lstat(2) starts reporting it as a
-   socket.  We now have a workaround on the side that connects to a
-   unix domain socket.
-
- * Other code cleanup, docfix, build fix, etc.
-   (merge f188160be9 ab/bundle-remove-verbose-option later to maint).
-   (merge 8c6b4332b4 rs/close-pack-leakfix later to maint).
-   (merge 51b04c05b7 bs/difftool-msg-tweak later to maint).
-   (merge dd20e4a6db ab/make-compdb-fix later to maint).
-   (merge 6ffb990dc4 os/status-docfix later to maint).
-   (merge 100c2da2d3 rs/p3400-lose-tac later to maint).
-   (merge 76f3b69896 tb/aggregate-ignore-leading-whitespaces later to maint).
-   (merge 6e4fd8bfcd tz/doc-link-to-bundle-format-fix later to maint).
-   (merge f6c013dfa1 jc/doc-commit-header-continuation-line later to maint).
-   (merge ec9a37d69b ab/pkt-line-cleanup later to maint).
-   (merge 8650c6298c ab/fix-make-lint-docs later to maint).
-   (merge 1c720357ce ab/test-lib-diff-cleanup later to maint).
-   (merge 6b615dbece ks/submodule-add-message-fix later to maint).
-   (merge 203eb8381a jc/doc-format-patch-clarify-auto-base later to maint).
-   (merge 559664c792 ab/test-lib later to maint).

Documentation/RelNotes/2.34.1.txt

@@ -1,23 +0,0 @@
-Git v2.34.1 Release Notes
-=========================
-
-This release is primarily to fix a handful of regressions in Git 2.34.
-
-Fixes since v2.34
------------------
-
- * "git grep" looking in a blob that has non-UTF8 payload was
-   completely broken when linked with certain versions of PCREv2
-   library in the latest release.
-
- * "git pull" with any strategy when the other side is behind us
-   should succeed as it is a no-op, but doesn't.
-
- * An earlier change in 2.34.0 caused JGit application (that abused
-   GIT_EDITOR mechanism when invoking "git config") to get stuck with
-   a SIGTTOU signal; it has been reverted.
-
- * An earlier change that broke .gitignore matching has been reverted.
-
- * SubmittingPatches document gained a syntactically incorrect mark-up,
-   which has been corrected.

Documentation/RelNotes/2.34.2.txt

@@ -1,6 +0,0 @@
-Git v2.34.2 Release Notes
-=========================
-
-This release merges up the fixes that appear in v2.30.3, v2.31.2,
-v2.32.1 and v2.33.2 to address the security issue CVE-2022-24765;
-see the release notes for these versions for details.

Documentation/RelNotes/2.34.3.txt

@@ -1,4 +0,0 @@
-Git Documentation/RelNotes/2.34.3.txt Release Notes
-=========================
-
-This release merges up the fixes that appear in v2.34.3.

Documentation/RelNotes/2.35.0.txt

@@ -1,412 +0,0 @@
-Git 2.35 Release Notes
-======================
-
-Updates since Git 2.34
-----------------------
-
-Backward compatibility warts
-
- * "_" is now treated as any other URL-valid characters in an URL when
-   matching the per-URL configuration variable names.
-
- * The color palette used by "git grep" has been updated to match that
-   of GNU grep.
-
-
-Note to those who build from the source
-
- * You may need to define NO_UNCOMPRESS2 Makefile macro if you build
-   with zlib older than 1.2.9.
-
- * If your compiler cannot grok C99, the build will fail.  See the
-   instruction at the beginning of git-compat-util.h if this happens
-   to you.
-
-
-UI, Workflows & Features
-
- * "git status --porcelain=v2" now show the number of stash entries
-   with --show-stash like the normal output does.
-
- * "git stash" learned the "--staged" option to stash away what has
-   been added to the index (and nothing else).
-
- * "git var GIT_DEFAULT_BRANCH" is a way to see what name is used for
-   the newly created branch if "git init" is run.
-
- * Various operating modes of "git reset" have been made to work
-   better with the sparse index.
-
- * "git submodule deinit" for a submodule whose .git metadata
-   directory is embedded in its working tree refused to work, until
-   the submodule gets converted to use the "absorbed" form where the
-   metadata directory is stored in superproject, and a gitfile at the
-   top-level of the working tree of the submodule points at it.  The
-   command is taught to convert such submodules to the absorbed form
-   as needed.
-
- * The completion script (in contrib/) learns that the "--date"
-   option of commands from the "git log" family takes "human" and
-   "auto" as valid values.
-
- * "Zealous diff3" style of merge conflict presentation has been added.
-
- * The "git log --format=%(describe)" placeholder has been extended to
-   allow passing selected command-line options to the underlying "git
-   describe" command.
-
- * "default" and "reset" have been added to our color palette.
-
- * The cryptographic signing using ssh keys can specify literal keys
-   for keytypes whose name do not begin with the "ssh-" prefix by
-   using the "key::" prefix mechanism (e.g. "key::ecdsa-sha2-nistp256").
-
- * "git fetch" without the "--update-head-ok" option ought to protect
-   a checked out branch from getting updated, to prevent the working
-   tree that checks it out to go out of sync.  The code was written
-   before the use of "git worktree" got widespread, and only checked
-   the branch that was checked out in the current worktree, which has
-   been updated.
-
- * "git name-rev" has been tweaked to give output that is shorter and
-   easier to understand.
-
- * "git apply" has been taught to ignore a message without a patch
-   with the "--allow-empty" option.  It also learned to honor the
-   "--quiet" option given from the command line.
-
- * The "init" and "set" subcommands in "git sparse-checkout" have been
-   unified for a better user experience and performance.
-
- * Many git commands that deal with working tree files try to remove a
-   directory that becomes empty (i.e. "git switch" from a branch that
-   has the directory to another branch that does not would attempt
-   remove all files in the directory and the directory itself).  This
-   drops users into an unfamiliar situation if the command was run in
-   a subdirectory that becomes subject to removal due to the command.
-   The commands have been taught to keep an empty directory if it is
-   the directory they were started in to avoid surprising users.
-
- * "git am" learns "--empty=(stop|drop|keep)" option to tweak what is
-   done to a piece of e-mail without a patch in it.
-
- * The default merge message prepared by "git merge" records the name
-   of the current branch; the name can be overridden with a new option
-   to allow users to pretend a merge is made on a different branch.
-
- * The way "git p4" shows file sizes in its output has been updated to
-   use human-readable units.
-
- * "git -c branch.autosetupmerge=inherit branch new old" makes "new"
-   to have the same upstream as the "old" branch, instead of marking
-   "old" itself as its upstream.
-
-
-Performance, Internal Implementation, Development Support etc.
-
- * The use of errno as a means to carry the nature of error in the ref
-   API implementation has been reworked and reduced.
-
- * Teach and encourage first-time contributors to this project to
-   state the base commit when they submit their topic.
-
- * The command line completion for "git send-email" options have been
-   tweaked to make it easier to keep it in sync with the command itself.
-
- * Ensure that the sparseness of the in-core index matches the
-   index.sparse configuration specified by the repository immediately
-   after the on-disk index file is read.
-
- * Code clean-up to eventually allow information on remotes defined
-   for an arbitrary repository to be read.
-
- * Build optimization.
-
- * Tighten code for testing pack-bitmap.
-
- * Weather balloon to break people with compilers that do not support
-   C99.
-
- * The "reftable" backend for the refs API, without integrating into
-   the refs subsystem, has been added.
-
- * More tests are marked as leak-free.
-
- * The test framework learns to list unsatisfied test prerequisites,
-   and optionally error out when prerequisites that are expected to be
-   satisfied are not.
-
- * The default setting for trace2 event nesting was too low to cause
-   test failures, which is worked around by bumping it up in the test
-   framework.
-
- * Drop support for TravisCI and update test workflows at GitHub.
-
- * Many tests that used to need GIT_TEST_DEFAULT_INITIAL_BRANCH_NAME
-   mechanism to force "git" to use 'master' as the default name for
-   the initial branch no longer need it; the use of the mechanism from
-   them have been removed.
-
- * Allow running our tests while disabling fsync.
-
- * Document the parameters given to the reflog entry iterator callback
-   functions.
-   (merge e6e94f34b2 jc/reflog-iterator-callback-doc later to maint).
-
- * The test helper for refs subsystem learned to write bogus and/or
-   nonexistent object name to refs to simulate error situations we
-   want to test Git in.
-
- * "diff --histogram" optimization.
-
- * Weather balloon to find compilers that do not grok variable
-   declaration in the for() loop.
-
- * diff and blame commands have been taught to work better with sparse
-   index.
-
- * The chainlint test script linter in the test suite has been updated.
-
- * The DEVELOPER=yes build uses -std=gnu99 now.
-
- * "git format-patch" uses a single rev_info instance and then exits.
-   Mark the structure with UNLEAK() macro to squelch leak sanitizer.
-
- * New interface into the tmp-objdir API to help in-core use of the
-   quarantine feature.
-
- * Broken &&-chains in the test scripts have been corrected.
-
- * The RCS keyword substitution in "git p4" used to be done assuming
-   that the contents are UTF-8 text, which can trigger decoding
-   errors.  We now treat the contents as a bytestring for robustness
-   and correctness.
-
- * The conditions to choose different definitions of the FLEX_ARRAY
-   macro for vendor compilers has been simplified to make it easier to
-   maintain.
-
- * Correctness and performance update to "diff --color-moved" feature.
-
- * "git upload-pack" (the other side of "git fetch") used a 8kB buffer
-   but most of its payload came on 64kB "packets".  The buffer size
-   has been enlarged so that such a packet fits.
-
- * "git fetch" and "git pull" are now declared sparse-index clean.
-   Also "git ls-files" learns the "--sparse" option to help debugging.
-
- * Similar message templates have been consolidated so that
-   translators need to work on fewer number of messages.
-
-
-Fixes since v2.34
------------------
-
- * "git grep" looking in a blob that has non-UTF8 payload was
-   completely broken when linked with certain versions of PCREv2
-   library in the latest release.
-
- * Other code cleanup, docfix, build fix, etc.
-
- * "git pull" with any strategy when the other side is behind us
-   should succeed as it is a no-op, but doesn't.
-
- * An earlier change in 2.34.0 caused JGit application (that abused
-   GIT_EDITOR mechanism when invoking "git config") to get stuck with
-   a SIGTTOU signal; it has been reverted.
-
- * An earlier change that broke .gitignore matching has been reverted.
-
- * Things like "git -c branch.sort=bogus branch new HEAD", i.e. the
-   operation modes of the "git branch" command that do not need the
-   sort key information, no longer errors out by seeing a bogus sort
-   key.
-   (merge 98e7ab6d42 jc/fix-ref-sorting-parse later to maint).
-
- * The compatibility implementation for unsetenv(3) were written to
-   mimic ancient, non-POSIX, variant seen in an old glibc; it has been
-   changed to return an integer to match the more modern era.
-   (merge a38989bd5b jc/unsetenv-returns-an-int later to maint).
-
- * The clean/smudge conversion code path has been prepared to better
-   work on platforms where ulong is narrower than size_t.
-   (merge 596b5e77c9 mc/clean-smudge-with-llp64 later to maint).
-
- * Redact the path part of packfile URI that appears in the trace output.
-   (merge 0ba558ffb1 if/redact-packfile-uri later to maint).
-
- * CI has been taught to catch some Unicode directional formatting
-   sequence that can be used in certain mischief.
-   (merge 0e7696c64d js/ci-no-directional-formatting later to maint).
-
- * The "--date=format:<strftime>" gained a workaround for the lack of
-   system support for a non-local timezone to handle "%s" placeholder.
-   (merge 9b591b9403 jk/strbuf-addftime-seconds-since-epoch later to maint).
-
- * The "merge" subcommand of "git jump" (in contrib/) silently ignored
-   pathspec and other parameters.
-   (merge 67ba13e5a4 jk/jump-merge-with-pathspec later to maint).
-
- * The code to decode the length of packed object size has been
-   corrected.
-   (merge 34de5b8eac jt/pack-header-lshift-overflow later to maint).
-
- * The advice message given by "git pull" when the user hasn't made a
-   choice between merge and rebase still said that the merge is the
-   default, which no longer is the case.  This has been corrected.
-   (merge 71076d0edd ah/advice-pull-has-no-preference-between-rebase-and-merge later to maint).
-
- * "git fetch", when received a bad packfile, can fail with SIGPIPE.
-   This wasn't wrong per-se, but we now detect the situation and fail
-   in a more predictable way.
-   (merge 2a4aed42ec jk/fetch-pack-avoid-sigpipe-to-index-pack later to maint).
-
- * The function to cull a child process and determine the exit status
-   had two separate code paths for normal callers and callers in a
-   signal handler, and the latter did not yield correct value when the
-   child has caught a signal.  The handling of the exit status has
-   been unified for these two code paths.  An existing test with
-   flakiness has also been corrected.
-   (merge 5263e22cba jk/t7006-sigpipe-tests-fix later to maint).
-
- * When a non-existent program is given as the pager, we tried to
-   reuse an uninitialized child_process structure and crashed, which
-   has been fixed.
-   (merge f917f57f40 em/missing-pager later to maint).
-
- * The single-key-input mode in "git add -p" had some code to handle
-   keys that generate a sequence of input via ReadKey(), which did not
-   handle end-of-file correctly, which has been fixed.
-   (merge fc8a8126df cb/add-p-single-key-fix later to maint).
-
- * "git rebase -x" added an unnecessary 'exec' instructions before
-   'noop', which has been corrected.
-   (merge cc9dcdee61 en/rebase-x-fix later to maint).
-
- * When the "git push" command is killed while the receiving end is
-   trying to report what happened to the ref update proposals, the
-   latter used to die, due to SIGPIPE.  The code now ignores SIGPIPE
-   to increase our chances to run the post-receive hook after it
-   happens.
-   (merge d34182b9e3 rj/receive-pack-avoid-sigpipe-during-status-reporting later to maint).
-
- * "git worktree add" showed "Preparing worktree" message to the
-   standard output stream, but when it failed, the message from die()
-   went to the standard error stream.  Depending on the order the
-   stdio streams are flushed at the program end, this resulted in
-   confusing output.  It has been corrected by sending all the chatty
-   messages to the standard error stream.
-   (merge b50252484f es/worktree-chatty-to-stderr later to maint).
-
- * Coding guideline document has been updated to clarify what goes to
-   standard error in our system.
-   (merge e258eb4800 es/doc-stdout-vs-stderr later to maint).
-
- * The sparse-index/sparse-checkout feature had a bug in its use of
-   the matching code to determine which path is in or outside the
-   sparse checkout patterns.
-   (merge 8c5de0d265 ds/sparse-deep-pattern-checkout-fix later to maint).
-
- * "git rebase -x" by mistake started exporting the GIT_DIR and
-   GIT_WORK_TREE environment variables when the command was rewritten
-   in C, which has been corrected.
-   (merge 434e0636db en/rebase-x-wo-git-dir-env later to maint).
-
- * When "git log" implicitly enabled the "decoration" processing
-   without being explicitly asked with "--decorate" option, it failed
-   to read and honor the settings given by the "--decorate-refs"
-   option.
-
- * "git fetch --set-upstream" did not check if there is a current
-   branch, leading to a segfault when it is run on a detached HEAD,
-   which has been corrected.
-   (merge 17baeaf82d ab/fetch-set-upstream-while-detached later to maint).
-
- * Among some code paths that ask an yes/no question, only one place
-   gave a prompt that looked different from the others, which has been
-   updated to match what the others create.
-   (merge 0fc8ed154c km/help-prompt-fix later to maint).
-
- * "git log --invert-grep --author=<name>" used to exclude commits
-   written by the given author, but now "--invert-grep" only affects
-   the matches made by the "--grep=<pattern>" option.
-   (merge 794c000267 rs/log-invert-grep-with-headers later to maint).
-
- * "git grep --perl-regexp" failed to match UTF-8 characters with
-   wildcard when the pattern consists only of ASCII letters, which has
-   been corrected.
-   (merge 32e3e8bc55 rs/pcre2-utf later to maint).
-
- * Certain sparse-checkout patterns that are valid in non-cone mode
-   led to segfault in cone mode, which has been corrected.
-
- * Use of certain "git rev-list" options with "git fast-export"
-   created nonsense results (the worst two of which being "--reverse"
-   and "--invert-grep --grep=<foo>").  The use of "--first-parent" is
-   made to behave a bit more sensible than before.
-   (merge 726a228dfb ws/fast-export-with-revision-options later to maint).
-
- * Perf tests were run with end-user's shell, but it has been
-   corrected to use the shell specified by $TEST_SHELL_PATH.
-   (merge 9ccab75608 ja/perf-use-specified-shell later to maint).
-
- * Fix dependency rules to generate hook-list.h header file.
-   (merge d3fd1a6667 ab/makefile-hook-list-dependency-fix later to maint).
-
- * "git stash" by default triggers its "push" action, but its
-   implementation also made "git stash -h" to show short help only for
-   "git stash push", which has been corrected.
-   (merge ca7990cea5 ab/do-not-limit-stash-help-to-push later to maint).
-
- * "git apply --3way" bypasses the attempt to do a three-way
-   application in more cases to address the regression caused by the
-   recent change to use direct application as a fallback.
-   (merge 34d607032c jz/apply-3-corner-cases later to maint).
-
- * Fix performance-releated bug in "git subtree" (in contrib/).
-   (merge 3ce8888fb4 jl/subtree-check-parents-argument-passing-fix later to maint).
-
- * Extend the guidance to choose the base commit to build your work
-   on, and hint/nudge contributors to read others' changes.
-   (merge fdfae830f8 jc/doc-submitting-patches-choice-of-base later to maint).
-
- * A corner case bug in the ort merge strategy has been corrected.
-   (merge d30126c20d en/merge-ort-renorm-with-rename-delete-conflict-fix later to maint).
-
- * "git stash apply" forgot to attempt restoring untracked files when
-   it failed to restore changes to tracked ones.
-   (merge 71cade5a0b en/stash-df-fix later to maint).
-
- * Calling dynamically loaded functions on Windows has been corrected.
-   (merge 4a9b204920 ma/windows-dynload-fix later to maint).
-
- * Some lockfile code called free() in signal-death code path, which
-   has been corrected.
-   (merge 58d4d7f1c5 ps/lockfile-cleanup-fix later to maint).
-
- * Other code cleanup, docfix, build fix, etc.
-   (merge 74db416c9c cw/protocol-v2-doc-fix later to maint).
-   (merge f9b2b6684d ja/doc-cleanup later to maint).
-   (merge 7d1b866778 jc/fix-first-object-walk later to maint).
-   (merge 538ac74604 js/trace2-avoid-recursive-errors later to maint).
-   (merge 152923b132 jk/t5319-midx-corruption-test-deflake later to maint).
-   (merge 9081a421a6 ab/checkout-branch-info-leakfix later to maint).
-   (merge 42c456ff81 rs/mergesort later to maint).
-   (merge ad506e6780 tl/midx-docfix later to maint).
-   (merge bf5b83fd8a hk/ci-checkwhitespace-commentfix later to maint).
-   (merge 49f1eb3b34 jk/refs-g11-workaround later to maint).
-   (merge 7d3fc7df70 jt/midx-doc-fix later to maint).
-   (merge 7b089120d9 hn/create-reflog-simplify later to maint).
-   (merge 9e12400da8 cb/mingw-gmtime-r later to maint).
-   (merge 0bf0de6cc7 tb/pack-revindex-on-disk-cleanup later to maint).
-   (merge 2c68f577fc ew/cbtree-remove-unused-and-broken-cb-unlink later to maint).
-   (merge eafd6e7e55 ab/die-with-bug later to maint).
-   (merge 91028f7659 jc/grep-patterntype-default-doc later to maint).
-   (merge 47ca93d071 ds/repack-fixlets later to maint).
-   (merge e6a9bc0c60 rs/t4202-invert-grep-test-fix later to maint).
-   (merge deb5407a42 gh/gpg-doc-markup-fix later to maint).
-   (merge 999bba3e0b rs/daemon-plug-leak later to maint).
-   (merge 786eb1ba39 js/l10n-mention-ngettext-early-in-readme later to maint).
-   (merge 2f12b31b74 ab/makefile-msgfmt-wo-stats later to maint).
-   (merge 0517f591ca fs/gpg-unknown-key-test-fix later to maint).
-   (merge 97d6fb5a1f ma/header-dup-cleanup later to maint).

Documentation/RelNotes/2.35.1.txt

@@ -1,6 +0,0 @@
-Git v2.35.1 Release Notes
-=========================
-
-Git 2.35 shipped with a regression that broke use of "rebase" and
-"stash" in a secondary worktree.  This maintenance release ought to
-fix it.

Documentation/RelNotes/2.35.2.txt

@@ -1,7 +0,0 @@
-Git v2.35.2 Release Notes
-=========================
-
-This release merges up the fixes that appear in v2.30.3,
-v2.31.2, v2.32.1, v2.33.2 and v2.34.2 to address the security
-issue CVE-2022-24765; see the release notes for these versions
-for details.

Documentation/RelNotes/2.35.3.txt

@@ -1,4 +0,0 @@
-Git Documentation/RelNotes/2.35.3.txt Release Notes
-=========================
-
-This release merges up the fixes that appear in v2.35.3.

Documentation/SubmittingPatches

@@ -19,10 +19,8 @@ change is relevant to.
   base your work on the tip of the topic.
 
 * A new feature should be based on `master` in general. If the new
-  feature depends on other topics that are in `next`, but not in
-  `master`, fork a branch from the tip of `master`, merge these topics
-  to the branch, and work on that branch.  You can remind yourself of
-  how you prepared the base with `git log --first-parent master..`.
+  feature depends on a topic that is in `seen`, but not in `master`,
+  base your work on the tip of that topic.
 
 * Corrections and enhancements to a topic not yet in `master` should
   be based on the tip of that topic. If the topic has not been merged
@@ -30,10 +28,10 @@ change is relevant to.
   into the series.
 
 * In the exceptional case that a new feature depends on several topics
-  not in `master`, start working on `next` or `seen` privately and
-  send out patches only for discussion. Once your new feature starts
-  to stabilize, you would have to rebase it (see the "depends on other
-  topics" above).
+  not in `master`, start working on `next` or `seen` privately and send
+  out patches for discussion. Before the final merge, you may have to
+  wait until some of the dependent topics graduate to `master`, and
+  rebase your work.
 
 * Some parts of the system have dedicated maintainers with their own
   repositories (see the section "Subsystems" below).  Changes to
@@ -73,13 +71,8 @@ Make sure that you have tests for the bug you are fixing.  See
 [[tests]]
 When adding a new feature, make sure that you have new tests to show
 the feature triggers the new behavior when it should, and to show the
-feature does not trigger when it shouldn't.  After any code change,
-make sure that the entire test suite passes.  When fixing a bug, make
-sure you have new tests that break if somebody else breaks what you
-fixed by accident to avoid regression.  Also, try merging your work to
-'next' and 'seen' and make sure the tests still pass; topics by others
-that are still in flight may have unexpected interactions with what
-you are trying to do in your topic.
+feature does not trigger when it shouldn't.  After any code change, make
+sure that the entire test suite passes.
 
 Pushing to a fork of https://github.com/git/git will use their CI
 integration to test your changes on Linux, Mac and Windows. See the
@@ -151,21 +144,8 @@ without external resources. Instead of giving a URL to a mailing list
 archive, summarize the relevant points of the discussion.
 
 [[commit-reference]]
-
-There are a few reasons why you may want to refer to another commit in
-the "more stable" part of the history (i.e. on branches like `maint`,
-`master`, and `next`):
-
-. A commit that introduced the root cause of a bug you are fixing.
-
-. A commit that introduced a feature that you are enhancing.
-
-. A commit that conflicts with your work when you made a trial merge
-  of your work into `next` and `seen` for testing.
-
-When you reference a commit on a more stable branch (like `master`,
-`maint` and `next`), use the format "abbreviated hash (subject,
-date)", like this:
+If you want to reference a previous commit in the history of a stable
+branch, use the format "abbreviated hash (subject, date)", like this:
 
 ....
 	Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30)
@@ -279,11 +259,9 @@ Please make sure your patch does not add commented out debugging code,
 or include any extra files which do not relate to what your patch
 is trying to achieve. Make sure to review
 your patch after generating it, to ensure accuracy.  Before
-sending out, please make sure it cleanly applies to the base you
-have chosen in the "Decide what to base your work on" section,
-and unless it targets the `master` branch (which is the default),
-mark your patches as such.
-
+sending out, please make sure it cleanly applies to the `master`
+branch head.  If you are preparing a work based on "next" branch,
+that is fine, but please mark it as such.
 
 [[send-patches]]
 === Sending your patches.
@@ -387,10 +365,7 @@ Security mailing list{security-ml-ref}.
 Send your patch with "To:" set to the mailing list, with "cc:" listing
 people who are involved in the area you are touching (the `git
 contacts` command in `contrib/contacts/` can help to
-identify them), to solicit comments and reviews.  Also, when you made
-trial merges of your topic to `next` and `seen`, you may have noticed
-work by others conflicting with your changes.  There is a good possibility
-that these people may know the area you are touching well.
+identify them), to solicit comments and reviews.
 
 :current-maintainer: footnote:[The current maintainer: gitster@pobox.com]
 :git-ml: footnote:[The mailing list: git@vger.kernel.org]
@@ -473,7 +448,7 @@ their trees themselves.
   entitled "What's cooking in git.git" and "What's in git.git" giving
   the status of various proposed changes.
 
-== GitHub CI[[GHCI]]
+== GitHub CI[[GHCI]]]
 
 With an account at GitHub, you can use GitHub CI to test your changes
 on Linux, Mac and Windows. See
@@ -488,7 +463,7 @@ Follow these steps for the initial setup:
 
 After the initial setup, CI will run whenever you push new changes
 to your fork of Git on GitHub.  You can monitor the test state of all your
-branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
+branches here: https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml
 
 If a branch did not pass all test cases then it is marked with a red
 cross. In that case you can click on the failing job and navigate to

Documentation/blame-options.txt

@@ -136,16 +136,5 @@ take effect.
 	option.  An empty file name, `""`, will clear the list of revs from
 	previously processed files.
 
---color-lines::
-	Color line annotations in the default format differently if they come from
-	the same commit as the preceding line. This makes it easier to distinguish
-	code blocks introduced by different commits. The color defaults to cyan and
-	can be adjusted using the `color.blame.repeatedLines` config option.
-
---color-by-age::
-	Color line annotations depending on the age of the line in the default format.
-	The `color.blame.highlightRecent` config option controls what color is used for
-	each range of age.
-
 -h::
 	Show help message.

Documentation/config.txt

@@ -262,19 +262,11 @@ color::
        colors (at most two, one for foreground and one for background)
        and attributes (as many as you want), separated by spaces.
 +
-The basic colors accepted are `normal`, `black`, `red`, `green`,
-`yellow`, `blue`, `magenta`, `cyan`, `white` and `default`.  The first
-color given is the foreground; the second is the background.  All the
-basic colors except `normal` and `default` have a bright variant that can
-be specified by prefixing the color with `bright`, like `brightred`.
-+
-The color `normal` makes no change to the color. It is the same as an
-empty string, but can be used as the foreground color when specifying a
-background color alone (for example, "normal red").
-+
-The color `default` explicitly resets the color to the terminal default,
-for example to specify a cleared background. Although it varies between
-terminals, this is usually not the same as setting to "white black".
+The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`,
+`blue`, `magenta`, `cyan` and `white`.  The first color given is the
+foreground; the second is the background.  All the basic colors except
+`normal` have a bright variant that can be specified by prefixing the
+color with `bright`, like `brightred`.
 +
 Colors may also be given as numbers between 0 and 255; these use ANSI
 256-color mode (but note that not all terminals may support this).  If
@@ -288,11 +280,6 @@ The position of any attributes with respect to the colors
 be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`,
 `no-ul`, etc).
 +
-The pseudo-attribute `reset` resets all colors and attributes before
-applying the specified coloring. For example, `reset green` will result
-in a green foreground and default background without any active
-attributes.
-+
 An empty color string produces no color effect at all. This can be used
 to avoid coloring specific elements without disabling color entirely.
 +
@@ -311,15 +298,6 @@ pathname::
 	tilde expansion happens to such a string: `~/`
 	is expanded to the value of `$HOME`, and `~user/` to the
 	specified user's home directory.
-+
-If a path starts with `%(prefix)/`, the remainder is interpreted as a
-path relative to Git's "runtime prefix", i.e. relative to the location
-where Git itself was installed. For example, `%(prefix)/bin/` refers to
-the directory in which the Git executable itself lives. If Git was
-compiled without runtime prefix support, the compiled-in prefix will be
-substituted instead. In the unlikely event that a literal path needs to
-be specified that should _not_ be expanded, it needs to be prefixed by
-`./`, like so: `./%(prefix)/bin`.
 
 
 Variables

Documentation/config/advice.txt

@@ -44,9 +44,6 @@ advice.*::
 		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.
-	skippedCherryPicks::
-		Shown when linkgit:git-rebase[1] skips a commit that has already
-		been cherry-picked onto the upstream branch.
 	statusAheadBehind::
 		Shown when linkgit:git-status[1] computes the ahead/behind
 		counts for a local ref compared to its remote tracking ref,

Documentation/config/branch.txt

@@ -7,8 +7,7 @@ branch.autoSetupMerge::
 	automatic setup is done; `true` -- automatic setup is done when the
 	starting point is a remote-tracking branch; `always` --
 	automatic setup is done when the starting point is either a
-	local branch or remote-tracking branch; `inherit` -- if the starting point
-	has a tracking configuration, it is copied to the new
+	local branch or remote-tracking
 	branch. This option defaults to true.
 
 branch.autoSetupRebase::
@@ -86,6 +85,10 @@ When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase'
 so that the local merge commits are included in the rebase (see
 linkgit:git-rebase[1] for details).
 +
+When `preserve` (or just 'p', deprecated in favor of `merges`), also pass
+`--preserve-merges` along to 'git rebase' so that locally committed merge
+commits will not be flattened by running 'git pull'.
++
 When the value is `interactive` (or just 'i'), the rebase is run in interactive
 mode.
 +

Documentation/config/color.txt

@@ -9,27 +9,26 @@ color.advice.hint::
 	Use customized color for hints.
 
 color.blame.highlightRecent::
-	Specify the line annotation color for `git blame --color-by-age`
-	depending upon the age of the line.
+	This can be used to color the metadata of a blame line depending
+	on age of the line.
 +
-This setting should be set to a comma-separated list of color and
-date settings, starting and ending with a color, the dates should be
-set from oldest to newest. The metadata will be colored with the
-specified colors if the line was introduced before the given
-timestamp, overwriting older timestamped colors.
+This setting should be set to a comma-separated list of color and date settings,
+starting and ending with a color, the dates should be set from oldest to newest.
+The metadata will be colored given the colors if the line was introduced
+before the given timestamp, overwriting older timestamped colors.
 +
-Instead of an absolute timestamp relative timestamps work as well,
-e.g. `2.weeks.ago` is valid to address anything older than 2 weeks.
+Instead of an absolute timestamp relative timestamps work as well, e.g.
+2.weeks.ago is valid to address anything older than 2 weeks.
 +
-It defaults to `blue,12 month ago,white,1 month ago,red`, which
-colors everything older than one year blue, recent changes between
-one month and one year old are kept white, and lines introduced
-within the last month are colored red.
+It defaults to 'blue,12 month ago,white,1 month ago,red', which colors
+everything older than one year blue, recent changes between one month and
+one year old are kept white, and lines introduced within the last month are
+colored red.
 
 color.blame.repeatedLines::
-	Use the specified color to colorize line annotations for
-	`git blame --color-lines`, if they come from the same commit as the
-	preceding line. Defaults to cyan.
+	Use the customized color for the part of git-blame output that
+	is repeated meta information per line (such as commit id,
+	author name, date and timezone). Defaults to cyan.
 
 color.branch::
 	A boolean to enable/disable color in the output of
@@ -105,12 +104,9 @@ color.grep.<slot>::
 `matchContext`;;
 	matching text in context lines
 `matchSelected`;;
-	matching text in selected lines. Also, used to customize the following
-	linkgit:git-log[1] subcommands: `--grep`, `--author` and `--committer`.
+	matching text in selected lines
 `selected`;;
-	non-matching text in selected lines. Also, used to customize the
-	following linkgit:git-log[1] subcommands: `--grep`, `--author` and
-	`--committer`.
+	non-matching text in selected lines
 `separator`;;
 	separators between fields on a line (`:`, `-`, and `=`)
 	and between hunks (`--`)

Documentation/config/gpg.txt

@@ -11,13 +11,13 @@ gpg.program::
 
 gpg.format::
 	Specifies which key format to use when signing with `--gpg-sign`.
-	Default is "openpgp". Other possible values are "x509", "ssh".
+	Default is "openpgp" and another possible value is "x509".
 
 gpg.<format>.program::
 	Use this to customize the program used for the signing format you
 	chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still
 	be used as a legacy synonym for `gpg.openpgp.program`. The default
-	value for `gpg.x509.program` is "gpgsm" and `gpg.ssh.program` is "ssh-keygen".
+	value for `gpg.x509.program` is "gpgsm".
 
 gpg.minTrustLevel::
 	Specifies a minimum trust level for signature verification.  If
@@ -33,47 +33,3 @@ gpg.minTrustLevel::
 * `marginal`
 * `fully`
 * `ultimate`
-
-gpg.ssh.defaultKeyCommand::
-	This command that will be run when user.signingkey is not set and a ssh
-	signature is requested. On successful exit a valid ssh public key is
-	expected in the	first line of its output. To automatically use the first
-	available key from your ssh-agent set this to "ssh-add -L".
-
-gpg.ssh.allowedSignersFile::
-	A file containing ssh public keys which you are willing to trust.
-	The file consists of one or more lines of principals followed by an ssh
-	public key.
-	e.g.: `user1@example.com,user2@example.com ssh-rsa AAAAX1...`
-	See ssh-keygen(1) "ALLOWED SIGNERS" for details.
-	The principal is only used to identify the key and is available when
-	verifying a signature.
-+
-SSH has no concept of trust levels like gpg does. To be able to differentiate
-between valid signatures and trusted signatures the trust level of a signature
-verification is set to `fully` when the public key is present in the allowedSignersFile.
-Otherwise the trust level is `undefined` and git verify-commit/tag will fail.
-+
-This file can be set to a location outside of the repository and every developer
-maintains their own trust store. A central repository server could generate this
-file automatically from ssh keys with push access to verify the code against.
-In a corporate setting this file is probably generated at a global location
-from automation that already handles developer ssh keys.
-+
-A repository that only allows signed commits can store the file
-in the repository itself using a path relative to the top-level of the working tree.
-This way only committers with an already valid key can add or change keys in the keyring.
-+
-Since OpensSSH 8.8 this file allows specifying a key lifetime using valid-after &
-valid-before options. Git will mark signatures as valid if the signing key was
-valid at the time of the signatures creation. This allows users to change a
-signing key without invalidating all previously made signatures.
-+
-Using a SSH CA key with the cert-authority option
-(see ssh-keygen(1) "CERTIFICATES") is also valid.
-
-gpg.ssh.revocationFile::
-	Either a SSH KRL or a list of revoked public keys (without the principal prefix).
-	See ssh-keygen(1) for details.
-	If a public key is found in this file then it will always be treated
-	as having trust level "never" and signatures will show as invalid.

Documentation/config/grep.txt

@@ -8,8 +8,7 @@ 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 return to the default matching behavior.
 
 grep.extendedRegexp::
 	If set to true, enable `--extended-regexp` option by default. This

Documentation/config/help.txt

@@ -9,15 +9,13 @@ help.format::
 
 help.autoCorrect::
 	If git detects typos and can identify exactly one valid command similar
-	to the error, git will try to suggest the correct command or even
-	run the suggestion automatically. Possible config values are:
-	 - 0 (default): show the suggested command.
-	 - positive number: run the suggested command after specified
-deciseconds (0.1 sec).
-	 - "immediate": run the suggested command immediately.
-	 - "prompt": show the suggestion and prompt for confirmation to run
-the command.
-	 - "never": don't run or show any suggested command.
+	to the error, git will automatically run the intended command after
+	waiting a duration of time defined by this configuration value in
+	deciseconds (0.1 sec).  If this value is 0, the suggested corrections
+	will be shown, but not executed. If it is a negative integer, or
+	"immediate", the suggested command
+	is run immediately. If "never", suggestions are not shown at all. The
+	default value is zero.
 
 help.htmlPath::
 	Specify the path where the HTML documentation resides. File system paths

Documentation/config/merge.txt

@@ -4,14 +4,7 @@ merge.conflictStyle::
 	shows a `<<<<<<<` conflict marker, changes made by one side,
 	a `=======` marker, changes made by the other side, and then
 	a `>>>>>>>` marker.  An alternate style, "diff3", adds a `|||||||`
-	marker and the original text before the `=======` marker.  The
-	"merge" style tends to produce smaller conflict regions than diff3,
-	both because of the exclusion of the original text, and because
-	when a subset of lines match on the two sides they are just pulled
-	out of the conflict region.  Another alternate style, "zdiff3", is
-	similar to diff3 but removes matching lines on the two sides from
-	the conflict region when those matching lines appear near either
-	the beginning or end of a conflict region.
+	marker and the original text before the `=======` marker.
 
 merge.defaultToUpstream::
 	If merge is called without any commit argument, merge the upstream

Documentation/config/pack.txt

@@ -159,10 +159,6 @@ pack.writeBitmapHashCache::
 	between an older, bitmapped pack and objects that have been
 	pushed since the last gc). The downside is that it consumes 4
 	bytes per object of disk space. Defaults to true.
-+
-When writing a multi-pack reachability bitmap, no new namehashes are
-computed; instead, any namehashes stored in an existing bitmap are
-permuted into their appropriate location when writing a new bitmap.
 
 pack.writeReverseIndex::
 	When true, git will write a corresponding .rev file (see:

Documentation/config/protocol.txt

@@ -1,10 +1,10 @@
 protocol.allow::
 	If set, provide a user defined default policy for all protocols which
 	don't explicitly have a policy (`protocol.<name>.allow`).  By default,
-	if unset, known-safe protocols (http, https, git, ssh, file) have a
+	if unset, known-safe protocols (http, https, git, ssh) have a
 	default policy of `always`, known-dangerous protocols (ext) have a
-	default policy of `never`, and all other protocols have a default
-	policy of `user`.  Supported policies:
+	default policy of `never`, and all other protocols (including file)
+	have a default policy of `user`.  Supported policies:
 +
 --
 

Documentation/config/pull.txt

@@ -18,6 +18,10 @@ When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase'
 so that the local merge commits are included in the rebase (see
 linkgit:git-rebase[1] for details).
 +
+When `preserve` (or just 'p', deprecated in favor of `merges`), also pass
+`--preserve-merges` along to 'git rebase' so that locally committed merge
+commits will not be flattened by running 'git pull'.
++
 When the value is `interactive` (or just 'i'), the rebase is run in interactive
 mode.
 +

Documentation/config/safe.txt

@@ -26,3 +26,17 @@ directory was listed in the `safe.directory` list. If `safe.directory=*`
 is set in system config and you want to re-enable this protection, then
 initialize your list with an empty value before listing the repositories
 that you deem safe.
++
+As explained, Git only allows you to access repositories owned by
+yourself, i.e. the user who is running Git, by default.  When Git
+is running as 'root' in a non Windows platform that provides sudo,
+however, git checks the SUDO_UID environment variable that sudo creates
+and will allow access to the uid recorded as its value in addition to
+the id from 'root'.
+This is to make it easy to perform a common sequence during installation
+"make && sudo make install".  A git process running under 'sudo' runs as
+'root' but the 'sudo' command exports the environment variable to record
+which id the original user has.
+If that is not what you would prefer and want git to only trust
+repositories that are owned by root instead, then you can remove
+the `SUDO_UID` variable from root's environment before invoking git.

Documentation/config/user.txt

@@ -36,13 +36,3 @@ user.signingKey::
 	commit, you can override the default selection with this variable.
 	This option is passed unchanged to gpg's --local-user parameter,
 	so you may specify a key using any method that gpg supports.
-	If gpg.format is set to `ssh` this can contain the path to either
-	your private ssh key or the public key when ssh-agent is used.
-	Alternatively it can contain a public key prefixed with `key::`
-	directly (e.g.: "key::ssh-rsa XXXXXX identifier"). The private key
-	needs to be available via ssh-agent. If not set git will call
-	gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the
-	first key available. For backward compatibility, a raw key which
-	begins with "ssh-", such as "ssh-rsa XXXXXX identifier", is treated
-	as "key::ssh-rsa XXXXXX identifier", but this form is deprecated;
-	use the `key::` form instead.

Documentation/date-formats.txt

@@ -5,9 +5,9 @@ The `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` environment variables
 support the following date formats:
 
 Git internal format::
-	It is `<unix-timestamp> <time-zone-offset>`, where
-	`<unix-timestamp>` is the number of seconds since the UNIX epoch.
-	`<time-zone-offset>` is a positive or negative offset from UTC.
+	It is `<unix timestamp> <time zone offset>`, where `<unix
+	timestamp>` is the number of seconds since the UNIX epoch.
+	`<time zone offset>` is a positive or negative offset from UTC.
 	For example CET (which is 1 hour ahead of UTC) is `+0100`.
 
 RFC 2822::

Documentation/diff-format.txt

@@ -59,7 +59,7 @@ Possible status letters are:
 - D: deletion of a file
 - M: modification of the contents or mode of a file
 - R: renaming of a file
-- T: change in the type of the file (regular file, symbolic link or submodule)
+- T: change in the type of the file
 - U: file is unmerged (you must complete the merge before it can
   be committed)
 - X: "unknown" change type (most probably a bug, please report it)

Documentation/git-add.txt

@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
-	  [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--sparse]
+	  [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]
 	  [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize]
 	  [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]]
 	  [--] [<pathspec>...]
@@ -79,13 +79,6 @@ in linkgit:gitglossary[7].
 --force::
 	Allow adding otherwise ignored files.
 
---sparse::
-	Allow updating index entries outside of the sparse-checkout cone.
-	Normally, `git add` refuses to update index entries whose paths do
-	not fit within the sparse-checkout cone, since those files might
-	be removed from the working tree without warning. See
-	linkgit:git-sparse-checkout[1] for more details.
-
 -i::
 --interactive::
 	Add modified contents in the working tree interactively to

Documentation/git-am.txt

@@ -16,9 +16,8 @@ SYNOPSIS
 	 [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
 	 [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>]
 	 [--quoted-cr=<action>]
-	 [--empty=(stop|drop|keep)]
 	 [(<mbox> | <Maildir>)...]
-'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)] | --allow-empty)
+'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)])
 
 DESCRIPTION
 -----------
@@ -64,14 +63,6 @@ OPTIONS
 --quoted-cr=<action>::
 	This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]).
 
---empty=(stop|drop|keep)::
-	By default, or when the option is set to 'stop', the command
-	errors out on an input e-mail message lacking a patch
-	and stops into the middle of the current am session. When this
-	option is set to 'drop', skip such an e-mail message instead.
-	When this option is set to 'keep', create an empty commit,
-	recording the contents of the e-mail message as its log.
-
 -m::
 --message-id::
 	Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]),
@@ -200,11 +191,6 @@ default.   You can use `--no-utf8` to override this.
 	the e-mail message; if `diff`, show the diff portion only.
 	Defaults to `raw`.
 
---allow-empty::
-	After a patch failure on an input e-mail message lacking a patch,
-	create an empty commit with the contents of the e-mail message
-	as its log message.
-
 DISCUSSION
 ----------
 

Documentation/git-apply.txt

@@ -16,7 +16,7 @@ SYNOPSIS
 	  [--ignore-space-change | --ignore-whitespace]
 	  [--whitespace=(nowarn|warn|fix|error|error-all)]
 	  [--exclude=<path>] [--include=<path>] [--directory=<root>]
-	  [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>...]
+	  [--verbose] [--unsafe-paths] [<patch>...]
 
 DESCRIPTION
 -----------
@@ -228,11 +228,6 @@ behavior:
 	current patch being applied will be printed. This option will cause
 	additional information to be reported.
 
--q::
---quiet::
-	Suppress stderr output. Messages about patch status and progress
-	will not be printed.
-
 --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
@@ -256,10 +251,6 @@ 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::
-	Don't return error for patches containing no diff. This includes
-	empty patches and patches with commit text only.
-
 CONFIGURATION
 -------------
 

Documentation/git-archimport.txt

@@ -9,14 +9,14 @@ git-archimport - Import a GNU Arch repository into Git
 SYNOPSIS
 --------
 [verse]
-'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D <depth>] [-t <tempdir>]
-	       <archive>/<branch>[:<git-branch>]...
+'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]
+               <archive/branch>[:<git-branch>] ...
 
 DESCRIPTION
 -----------
 Imports a project from one or more GNU Arch repositories.
 It will follow branches
-and repositories within the namespaces defined by the <archive>/<branch>
+and repositories within the namespaces defined by the <archive/branch>
 parameters supplied. If it cannot find the remote branch a merge comes from
 it will just import it as a regular commit. If it can find it, it will mark it
 as a merge whenever possible (see discussion below).
@@ -27,7 +27,7 @@ import new branches within the provided roots.
 
 It expects to be dealing with one project only. If it sees
 branches that have different roots, it will refuse to run. In that case,
-edit your <archive>/<branch> parameters to define clearly the scope of the
+edit your <archive/branch> parameters to define clearly the scope of the
 import.
 
 'git archimport' uses `tla` extensively in the background to access the
@@ -42,7 +42,7 @@ incremental imports.
 
 While 'git archimport' will try to create sensible branch names for the
 archives that it imports, it is also possible to specify Git branch names
-manually.  To do so, write a Git branch name after each <archive>/<branch>
+manually.  To do so, write a Git branch name after each <archive/branch>
 parameter, separated by a colon.  This way, you can shorten the Arch
 branch names and convert Arch jargon to Git jargon, for example mapping a
 "PROJECT{litdd}devo{litdd}VERSION" branch to "master".
@@ -104,8 +104,8 @@ OPTIONS
 	Override the default tempdir.
 
 
-<archive>/<branch>::
-	<archive>/<branch> identifier in a format that `tla log` understands.
+<archive/branch>::
+	Archive/branch identifier in a format that `tla log` understands.
 
 
 GIT

Documentation/git-archive.txt

@@ -93,19 +93,12 @@ BACKEND EXTRA OPTIONS
 
 zip
 ~~~
--<digit>::
-	Specify compression level.  Larger values allow the command
-	to spend more time to compress to smaller size.  Supported
-	values are from `-0` (store-only) to `-9` (best ratio).
-	Default is `-6` if not given.
+-0::
+	Store the files instead of deflating them.
+-9::
+	Highest and slowest compression level.  You can specify any
+	number from 1 to 9 to adjust compression speed and ratio.
 
-tar
-~~~
--<number>::
-	Specify compression level. The value will be passed to the
-	compression command configured in `tar.<format>.command`. See
-	manual page of the configured command for the list of supported
-	levels and the default level if this option isn't specified.
 
 CONFIGURATION
 -------------

Documentation/git-blame.txt

@@ -11,8 +11,8 @@ SYNOPSIS
 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
 	    [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
 	    [--ignore-rev <rev>] [--ignore-revs-file <file>]
-	    [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>]
-	    [<rev> | --contents <file> | --reverse <rev>..<rev>] [--] <file>
+	    [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>]
+	    [--] <file>
 
 DESCRIPTION
 -----------
@@ -93,19 +93,6 @@ include::blame-options.txt[]
 	is used for a caret to mark the boundary commit.
 
 
-THE DEFAULT FORMAT
-------------------
-
-When neither `--porcelain` nor `--incremental` option is specified,
-`git blame` will output annotation for each line with:
-
-- abbreviated object name for the commit the line came from;
-- author ident (by default author name and date, unless `-s` or `-e`
-  is specified); and
-- line number
-
-before the line contents.
-
 THE PORCELAIN FORMAT
 --------------------
 

Documentation/git-branch.txt

@@ -16,7 +16,7 @@ SYNOPSIS
 	[--points-at <object>] [--format=<format>]
 	[(-r | --remotes) | (-a | --all)]
 	[--list] [<pattern>...]
-'git branch' [--track[=(direct|inherit)] | --no-track] [-f] <branchname> [<start-point>]
+'git branch' [--track | --no-track] [-f] <branchname> [<start-point>]
 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
 'git branch' --unset-upstream [<branchname>]
 'git branch' (-m | -M) [<oldbranch>] <newbranch>
@@ -125,14 +125,14 @@ OPTIONS
 
 -m::
 --move::
-	Move/rename a branch, together with its config and reflog.
+	Move/rename a branch and the corresponding reflog.
 
 -M::
 	Shortcut for `--move --force`.
 
 -c::
 --copy::
-	Copy a branch, together with its config and reflog.
+	Copy a branch and the corresponding reflog.
 
 -C::
 	Shortcut for `--copy --force`.
@@ -206,34 +206,24 @@ This option is only applicable in non-verbose mode.
 	Display the full sha1s in the output listing rather than abbreviating them.
 
 -t::
---track[=(direct|inherit)]::
+--track::
 	When creating a new branch, set up `branch.<name>.remote` and
-	`branch.<name>.merge` configuration entries to set "upstream" tracking
-	configuration for the new branch. This
+	`branch.<name>.merge` configuration entries to mark the
+	start-point branch as "upstream" from the new branch. This
 	configuration will tell git to show the relationship between the
 	two branches in `git status` and `git branch -v`. Furthermore,
 	it directs `git pull` without arguments to pull from the
 	upstream when the new branch is checked out.
 +
-The exact upstream branch is chosen depending on the optional argument:
-`-t`, `--track`, or `--track=direct` means to use the start-point branch
-itself as the upstream; `--track=inherit` means to copy the upstream
-configuration of the start-point branch.
-+
-`--track=direct` is the default when the start point is a remote-tracking branch.
+This behavior is the default when the start point is a remote-tracking branch.
 Set the branch.autoSetupMerge configuration variable to `false` if you
 want `git switch`, `git checkout` and `git branch` to always behave as if `--no-track`
 were given. Set it to `always` if you want this behavior when the
-start-point is either a local or remote-tracking branch. Set it to
-`inherit` if you want to copy the tracking configuration from the
-branch point.
-+
-See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on
-how the `branch.<name>.remote` and `branch.<name>.merge` options are used.
+start-point is either a local or remote-tracking branch.
 
 --no-track::
 	Do not set up "upstream" configuration, even if the
-	branch.autoSetupMerge configuration variable is set.
+	branch.autoSetupMerge configuration variable is true.
 
 --set-upstream::
 	As this option had confusing syntax, it is no longer supported.

Documentation/git-bundle.txt

@@ -13,7 +13,7 @@ SYNOPSIS
 		    [--version=<version>] <file> <git-rev-list-args>
 'git bundle' verify [-q | --quiet] <file>
 'git bundle' list-heads <file> [<refname>...]
-'git bundle' unbundle [--progress] <file> [<refname>...]
+'git bundle' unbundle <file> [<refname>...]
 
 DESCRIPTION
 -----------
@@ -51,10 +51,10 @@ using the `--thin` option to linkgit:git-pack-objects[1], and
 unbundled using the `--fix-thin` option to linkgit:git-index-pack[1].
 
 There is no option to create a "thick pack" when using revision
-exclusions, and users should not be concerned about the difference. By
-using "thin packs", bundles created using exclusions are smaller in
+exclusions, users should not be concerned about the difference. By
+using "thin packs" bundles created using exclusions are smaller in
 size. That they're "thin" under the hood is merely noted here as a
-curiosity, and as a reference to other documentation.
+curiosity, and as a reference to other documentation
 
 See link:technical/bundle-format.html[the `bundle-format`
 documentation] for more details and the discussion of "thin pack" in
@@ -144,7 +144,7 @@ unbundle <file>::
 SPECIFYING REFERENCES
 ---------------------
 
-Revisions must be accompanied by reference names to be packaged in a
+Revisions must accompanied by reference names to be packaged in a
 bundle.
 
 More than one reference may be packaged, and more than one set of prerequisite objects can

Documentation/git-cat-file.txt

@@ -94,10 +94,8 @@ OPTIONS
 	Instead of reading a list of objects on stdin, perform the
 	requested batch operation on all objects in the repository and
 	any alternate object stores (not just reachable objects).
-	Requires `--batch` or `--batch-check` be specified. By default,
-	the objects are visited in order sorted by their hashes; see
-	also `--unordered` below. Objects are presented as-is, without
-	respecting the "replace" mechanism of linkgit:git-replace[1].
+	Requires `--batch` or `--batch-check` be specified. Note that
+	the objects are visited in order sorted by their hashes.
 
 --buffer::
 	Normally batch output is flushed after each object is output, so

Documentation/git-checkout.txt

@@ -11,7 +11,7 @@ SYNOPSIS
 'git checkout' [-q] [-f] [-m] [<branch>]
 'git checkout' [-q] [-f] [-m] --detach [<branch>]
 'git checkout' [-q] [-f] [-m] [--detach] <commit>
-'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
+'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...
 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
 'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
@@ -43,7 +43,7 @@ You could omit `<branch>`, in which case the command degenerates to
 rather expensive side-effects to show only the tracking information,
 if exists, for the current branch.
 
-'git checkout' -b|-B <new-branch> [<start-point>]::
+'git checkout' -b|-B <new_branch> [<start point>]::
 
 	Specifying `-b` causes a new branch to be created as if
 	linkgit:git-branch[1] were called and then checked out.  In
@@ -52,11 +52,11 @@ if exists, for the current branch.
 	`--track` without `-b` implies branch creation; see the
 	description of `--track` below.
 +
-If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it
+If `-B` is given, `<new_branch>` is created if it doesn't exist; otherwise, it
 is reset. This is the transactional equivalent of
 +
 ------------
-$ git branch -f <branch> [<start-point>]
+$ git branch -f <branch> [<start point>]
 $ git checkout <branch>
 ------------
 +
@@ -118,9 +118,8 @@ OPTIONS
 -f::
 --force::
 	When switching branches, proceed even if the index or the
-	working tree differs from `HEAD`, and even if there are untracked
-	files in the way.  This is used to throw away local changes and
-	any untracked files or directories that are in the way.
+	working tree differs from `HEAD`.  This is used to throw away
+	local changes.
 +
 When checking out paths from the index, do not fail upon unmerged
 entries; instead, unmerged entries are ignored.
@@ -145,18 +144,18 @@ as `ours` (i.e. "our shared canonical history"), while what you did
 on your side branch as `theirs` (i.e. "one contributor's work on top
 of it").
 
--b <new-branch>::
-	Create a new branch named `<new-branch>` and start it at
-	`<start-point>`; see linkgit:git-branch[1] for details.
+-b <new_branch>::
+	Create a new branch named `<new_branch>` and start it at
+	`<start_point>`; see linkgit:git-branch[1] for details.
 
--B <new-branch>::
-	Creates the branch `<new-branch>` and start it at `<start-point>`;
-	if it already exists, then reset it to `<start-point>`. This is
+-B <new_branch>::
+	Creates the branch `<new_branch>` and start it at `<start_point>`;
+	if it already exists, then reset it to `<start_point>`. This is
 	equivalent to running "git branch" with "-f"; see
 	linkgit:git-branch[1] for details.
 
 -t::
---track[=(direct|inherit)]::
+--track::
 	When creating a new branch, set up "upstream" configuration. See
 	"--track" in linkgit:git-branch[1] for details.
 +
@@ -210,16 +209,16 @@ variable.
 	`<commit>` is not a branch name.  See the "DETACHED HEAD" section
 	below for details.
 
---orphan <new-branch>::
-	Create a new 'orphan' branch, named `<new-branch>`, started from
-	`<start-point>` and switch to it.  The first commit made on this
+--orphan <new_branch>::
+	Create a new 'orphan' branch, named `<new_branch>`, started from
+	`<start_point>` and switch to it.  The first commit made on this
 	new branch will have no parents and it will be the root of a new
 	history totally disconnected from all the other branches and
 	commits.
 +
 The index and the working tree are adjusted as if you had previously run
-`git checkout <start-point>`.  This allows you to start a new history
-that records a set of paths similar to `<start-point>` by easily running
+`git checkout <start_point>`.  This allows you to start a new history
+that records a set of paths similar to `<start_point>` by easily running
 `git commit -a` to make the root commit.
 +
 This can be useful when you want to publish the tree from a commit
@@ -229,7 +228,7 @@ whose full history contains proprietary or otherwise encumbered bits of
 code.
 +
 If you want to start a disconnected history that records a set of paths
-that is totally different from the one of `<start-point>`, then you should
+that is totally different from the one of `<start_point>`, then you should
 clear the index and the working tree right after creating the orphan
 branch by running `git rm -rf .` from the top level of the working tree.
 Afterwards you will be ready to prepare your new files, repopulating the
@@ -266,7 +265,8 @@ When switching branches with `--merge`, staged changes may be lost.
 	The same as `--merge` option above, but changes the way the
 	conflicting hunks are presented, overriding the
 	`merge.conflictStyle` configuration variable.  Possible values are
-	"merge" (default), "diff3", and "zdiff3".
+	"merge" (default) and "diff3" (in addition to what is shown by
+	"merge" style, shows the original contents).
 
 -p::
 --patch::
@@ -340,10 +340,10 @@ As a special case, you may use `A...B` as a shortcut for the
 merge base of `A` and `B` if there is exactly one merge base. You can
 leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
 
-<new-branch>::
+<new_branch>::
 	Name for the new branch.
 
-<start-point>::
+<start_point>::
 	The name of a commit at which to start the new branch; see
 	linkgit:git-branch[1] for details. Defaults to `HEAD`.
 +

Documentation/git-cherry-pick.txt

@@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits
 SYNOPSIS
 --------
 [verse]
-'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]
+'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
 		  [-S[<keyid>]] <commit>...
 'git cherry-pick' (--continue | --skip | --abort | --quit)
 
@@ -81,8 +81,8 @@ OPTIONS
 	described above, and `-r` was to disable it.  Now the
 	default is not to do `-x` so this option is a no-op.
 
--m <parent-number>::
---mainline <parent-number>::
+-m parent-number::
+--mainline parent-number::
 	Usually you cannot cherry-pick a merge because you do not know which
 	side of the merge should be considered the mainline.  This
 	option specifies the parent number (starting from 1) of

Documentation/git-clone.txt

@@ -9,10 +9,10 @@ git-clone - Clone a repository into a new directory
 SYNOPSIS
 --------
 [verse]
-'git clone' [--template=<template-directory>]
+'git clone' [--template=<template_directory>]
 	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
 	  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
-	  [--dissociate] [--separate-git-dir <git-dir>]
+	  [--dissociate] [--separate-git-dir <git dir>]
 	  [--depth <depth>] [--[no-]single-branch] [--no-tags]
 	  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
 	  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
@@ -167,10 +167,10 @@ objects from the source repository into a pack in the cloned repository.
 	configuration variables are created.
 
 --sparse::
-	Employ a sparse-checkout, with only files in the toplevel
-	directory initially being present.  The
-	linkgit:git-sparse-checkout[1] command can be used to grow the
-	working directory as needed.
+	Initialize the sparse-checkout file so the working
+	directory starts with only the files in the root
+	of the repository. The sparse-checkout file can be
+	modified to grow the working directory as needed.
 
 --filter=<filter-spec>::
 	Use the partial clone feature and request that the server sends
@@ -211,7 +211,7 @@ objects from the source repository into a pack in the cloned repository.
 	via ssh, this specifies a non-default path for the command
 	run on the other end.
 
---template=<template-directory>::
+--template=<template_directory>::
 	Specify the directory from which templates will be used;
 	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
 
@@ -294,7 +294,7 @@ or `--mirror` is given)
 	superproject's recorded SHA-1. Equivalent to passing `--remote` to
 	`git submodule update`.
 
---separate-git-dir=<git-dir>::
+--separate-git-dir=<git dir>::
 	Instead of placing the cloned repository where it is supposed
 	to be, place the cloned repository at the specified directory,
 	then make a filesystem-agnostic Git symbolic link to there.

Documentation/git-commit.txt

@@ -212,9 +212,8 @@ include::signoff-option.txt[]
 	each trailer would appear, and other details.
 
 -n::
---[no-]verify::
-	By default, the pre-commit and commit-msg hooks are run.
-	When any of `--no-verify` or `-n` is given, these are bypassed.
+--no-verify::
+	This option bypasses the pre-commit and commit-msg hooks.
 	See also linkgit:githooks[5].
 
 --allow-empty::

Documentation/git-config.txt

@@ -9,20 +9,20 @@ git-config - Get and set repository or global options
 SYNOPSIS
 --------
 [verse]
-'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
-'git config' [<file-option>] [--type=<type>] --add <name> <value>
-'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]
-'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>
-'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]
-'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]
-'git config' [<file-option>] --rename-section <old-name> <new-name>
-'git config' [<file-option>] --remove-section <name>
+'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]]
+'git config' [<file-option>] [--type=<type>] --add name value
+'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern]
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern]
+'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL
+'git config' [<file-option>] [--fixed-value] --unset name [value-pattern]
+'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern]
+'git config' [<file-option>] --rename-section old_name new_name
+'git config' [<file-option>] --remove-section name
 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list
-'git config' [<file-option>] --get-color <name> [<default>]
-'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]
+'git config' [<file-option>] --get-color name [default]
+'git config' [<file-option>] --get-colorbool name [stdout-is-tty]
 'git config' [<file-option>] -e | --edit
 
 DESCRIPTION
@@ -102,9 +102,9 @@ OPTIONS
 	in which section and variable names are lowercased, but subsection
 	names are not.
 
---get-urlmatch <name> <URL>::
+--get-urlmatch name URL::
 	When given a two-part name section.key, the value for
-	section.<URL>.key whose <URL> part matches the best to the
+	section.<url>.key whose <url> part matches the best to the
 	given URL is returned (if no such key exists, the value for
 	section.key is used as a fallback).  When given just the
 	section as name, do so for all the keys in the section and
@@ -145,8 +145,8 @@ See also <<FILES>>.
 	read from or written to if `extensions.worktreeConfig` is
 	present. If not it's the same as `--local`.
 
--f <config-file>::
---file <config-file>::
+-f config-file::
+--file config-file::
 	For writing options: write to the specified file rather than the
 	repository `.git/config`.
 +
@@ -155,7 +155,7 @@ available files.
 +
 See also <<FILES>>.
 
---blob <blob>::
+--blob blob::
 	Similar to `--file` but use the given blob instead of a file. E.g.
 	you can use 'master:.gitmodules' to read values from the file
 	'.gitmodules' in the master branch. See "SPECIFYING REVISIONS"
@@ -246,18 +246,18 @@ Valid `<type>`'s include:
 	all queried config options with the scope of that value
 	(local, global, system, command).
 
---get-colorbool <name> [<stdout-is-tty>]::
+--get-colorbool name [stdout-is-tty]::
 
-	Find the color setting for `<name>` (e.g. `color.diff`) and output
-	"true" or "false".  `<stdout-is-tty>` should be either "true" or
+	Find the color setting for `name` (e.g. `color.diff`) and output
+	"true" or "false".  `stdout-is-tty` should be either "true" or
 	"false", and is taken into account when configuration says
-	"auto".  If `<stdout-is-tty>` is missing, then checks the standard
+	"auto".  If `stdout-is-tty` is missing, then checks the standard
 	output of the command itself, and exits with status 0 if color
 	is to be used, or exits with status 1 otherwise.
 	When the color setting for `name` is undefined, the command uses
 	`color.ui` as fallback.
 
---get-color <name> [<default>]::
+--get-color name [default]::
 
 	Find the color configured for `name` (e.g. `color.diff.new`) and
 	output it as the ANSI color escape sequence to the standard

Documentation/git-credential.txt

@@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials
 SYNOPSIS
 --------
 ------------------
-'git credential' (fill|approve|reject)
+git credential <fill|approve|reject>
 ------------------
 
 DESCRIPTION

Documentation/git-cvsexportcommit.txt

@@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout
 SYNOPSIS
 --------
 [verse]
-'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>]
-	[-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id>
+'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot]
+	[-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID
 
 
 DESCRIPTION

Documentation/git-cvsimport.txt

@@ -11,9 +11,9 @@ SYNOPSIS
 [verse]
 'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]
 	      [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]
-	      [-C <git-repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]
-	      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commit-limit>]
-	      [-r <remote>] [-R] [<CVS-module>]
+	      [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]
+	      [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]
+	      [-r <remote>] [-R] [<CVS_module>]
 
 
 DESCRIPTION
@@ -59,7 +59,7 @@ OPTIONS
 	from `CVS/Root`. If no such file exists, it checks for the
 	`CVSROOT` environment variable.
 
-<CVS-module>::
+<CVS_module>::
 	The CVS module you want to import. Relative to <CVSROOT>.
 	If not given, 'git cvsimport' tries to read it from
 	`CVS/Repository`.

Documentation/git-diff-files.txt

@@ -9,7 +9,7 @@ git-diff-files - Compares files in the working tree and the index
 SYNOPSIS
 --------
 [verse]
-'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common-diff-options>] [<path>...]
+'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...]
 
 DESCRIPTION
 -----------

Documentation/git-diff-index.txt

@@ -9,7 +9,7 @@ git-diff-index - Compare a tree to the working tree or index
 SYNOPSIS
 --------
 [verse]
-'git diff-index' [-m] [--cached] [--merge-base] [<common-diff-options>] <tree-ish> [<path>...]
+'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...]
 
 DESCRIPTION
 -----------

Documentation/git-diff-tree.txt

@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]
 	      [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base]
-	      [<common-diff-options>] <tree-ish> [<tree-ish>] [<path>...]
+	      [<common diff options>] <tree-ish> [<tree-ish>] [<path>...]
 
 DESCRIPTION
 -----------

Documentation/git-fmt-merge-msg.txt

@@ -9,7 +9,7 @@ git-fmt-merge-msg - Produce a merge commit message
 SYNOPSIS
 --------
 [verse]
-'git fmt-merge-msg' [-m <message>] [--into-name <branch>] [--log[=<n>] | --no-log]
+'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log]
 'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -F <file>
 
 DESCRIPTION
@@ -44,10 +44,6 @@ OPTIONS
 	Use <message> instead of the branch names for the first line
 	of the log message.  For use with `--log`.
 
---into-name <branch>::
-	Prepare the merge message as if merging to the branch `<branch>`,
-	instead of the name of the real branch to which the merge is made.
-
 -F <file>::
 --file <file>::
 	Take the list of merged objects from <file> instead of

Documentation/git-for-each-ref.txt

@@ -235,15 +235,6 @@ and `date` to extract the named component.  For email fields (`authoremail`,
 without angle brackets, and `:localpart` to get the part before the `@` symbol
 out of the trimmed email.
 
-The raw data in an object is `raw`.
-
-raw:size::
-	The raw data size of the object.
-
-Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`,
-because such language may not support arbitrary binary data in their string
-variable type.
-
 The message in a commit or a tag object is `contents`, from which
 `contents:<part>` can be used to extract various parts out of:
 

Documentation/git-format-patch.txt

@@ -18,7 +18,7 @@ SYNOPSIS
 		   [-n | --numbered | -N | --no-numbered]
 		   [--start-number <n>] [--numbered-files]
 		   [--in-reply-to=<message id>] [--suffix=.<sfx>]
-		   [--ignore-if-in-upstream] [--always]
+		   [--ignore-if-in-upstream]
 		   [--cover-from-description=<mode>]
 		   [--rfc] [--subject-prefix=<subject prefix>]
 		   [(--reroll-count|-v) <n>]
@@ -192,10 +192,6 @@ will want to ensure that threading is disabled for `git send-email`.
 	patches being generated, and any patch that matches is
 	ignored.
 
---always::
-	Include patches for commits that do not introduce any change,
-	which are omitted by default.
-
 --cover-from-description=<mode>::
 	Controls which parts of the cover letter will be automatically
 	populated using the branch's description.
@@ -693,10 +689,10 @@ You can also use `git format-patch --base=P -3 C` to generate patches
 for A, B and C, and the identifiers for P, X, Y, Z are appended at the
 end of the first message.
 
-If set `--base=auto` in cmdline, it will automatically compute
-the base commit as the merge base of tip commit of the remote-tracking
+If set `--base=auto` in cmdline, it will track base commit automatically,
+the base commit will be the merge base of tip commit of the remote-tracking
 branch and revision-range specified in cmdline.
-For a local branch, you need to make it to track a remote branch by `git branch
+For a local branch, you need to track a remote branch by `git branch
 --set-upstream-to` before using this option.
 
 EXAMPLES

Documentation/git-fsck.txt

@@ -12,7 +12,7 @@ SYNOPSIS
 'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
 	 [--[no-]full] [--strict] [--verbose] [--lost-found]
 	 [--[no-]dangling] [--[no-]progress] [--connectivity-only]
-	 [--[no-]name-objects] [<object>...]
+	 [--[no-]name-objects] [<object>*]
 
 DESCRIPTION
 -----------

Documentation/git-gui.txt

@@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git
 SYNOPSIS
 --------
 [verse]
-'git gui' [<command>] [<arguments>]
+'git gui' [<command>] [arguments]
 
 DESCRIPTION
 -----------

Documentation/git-help.txt

@@ -8,15 +8,13 @@ git-help - Display help information about Git
 SYNOPSIS
 --------
 [verse]
-'git help' [-a|--all [--[no-]verbose]]
-	   [[-i|--info] [-m|--man] [-w|--web]] [<command>|<guide>]
-'git help' [-g|--guides]
-'git help' [-c|--config]
+'git help' [-a|--all [--[no-]verbose]] [-g|--guides]
+	   [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]
 
 DESCRIPTION
 -----------
 
-With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
+With no options and no COMMAND or GUIDE given, the synopsis of the 'git'
 command and a list of the most commonly used Git commands are printed
 on the standard output.
 
@@ -33,7 +31,7 @@ variables.
 
 If an alias is given, git shows the definition of the alias on
 standard output. To get the manual page for the aliased command, use
-`git <command> --help`.
+`git COMMAND --help`.
 
 Note that `git --help ...` is identical to `git help ...` because the
 former is internally converted into the latter.
@@ -60,7 +58,8 @@ OPTIONS
 
 -g::
 --guides::
-	Prints a list of the Git concept guides on the standard output.
+	Prints a list of the Git concept guides on the standard output. This
+	option overrides any given command or guide name.
 
 -i::
 --info::

Documentation/git-http-backend.txt

@@ -16,9 +16,7 @@ A simple CGI program to serve the contents of a Git repository to Git
 clients accessing the repository over http:// and https:// protocols.
 The program supports clients fetching using both the smart HTTP protocol
 and the backwards-compatible dumb HTTP protocol, as well as clients
-pushing using the smart HTTP protocol. It also supports Git's
-more-efficient "v2" protocol if properly configured; see the
-discussion of `GIT_PROTOCOL` in the ENVIRONMENT section below.
+pushing using the smart HTTP protocol.
 
 It verifies that the directory has the magic file
 "git-daemon-export-ok", and it will refuse to export any Git directory
@@ -79,18 +77,6 @@ Apache 2.x::
 SetEnv GIT_PROJECT_ROOT /var/www/git
 SetEnv GIT_HTTP_EXPORT_ALL
 ScriptAlias /git/ /usr/libexec/git-core/git-http-backend/
-
-# This is not strictly necessary using Apache and a modern version of
-# git-http-backend, as the webserver will pass along the header in the
-# environment as HTTP_GIT_PROTOCOL, and http-backend will copy that into
-# GIT_PROTOCOL. But you may need this line (or something similar if you
-# are using a different webserver), or if you want to support older Git
-# versions that did not do that copying.
-#
-# Having the webserver set up GIT_PROTOCOL is perfectly fine even with
-# modern versions (and will take precedence over HTTP_GIT_PROTOCOL,
-# which means it can be used to override the client's request).
-SetEnvIf Git-Protocol ".*" GIT_PROTOCOL=$0
 ----------------------------------------------------------------
 +
 To enable anonymous read access but authenticated write access,
@@ -278,16 +264,6 @@ a repository with an extremely large number of refs.  The value can be
 specified with a unit (e.g., `100M` for 100 megabytes). The default is
 10 megabytes.
 
-Clients may probe for optional protocol capabilities (like the v2
-protocol) using the `Git-Protocol` HTTP header. In order to support
-these, the contents of that header must appear in the `GIT_PROTOCOL`
-environment variable. Most webservers will pass this header to the CGI
-via the `HTTP_GIT_PROTOCOL` variable, and `git-http-backend` will
-automatically copy that to `GIT_PROTOCOL`. However, some webservers may
-be more selective about which headers they'll pass, in which case they
-need to be configured explicitly (see the mention of `Git-Protocol` in
-the Apache config from the earlier EXAMPLES section).
-
 The backend process sets GIT_COMMITTER_NAME to '$REMOTE_USER' and
 GIT_COMMITTER_EMAIL to '$\{REMOTE_USER}@http.$\{REMOTE_ADDR\}',
 ensuring that any reflogs created by 'git-receive-pack' contain some

Documentation/git-http-fetch.txt

@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP
 SYNOPSIS
 --------
 [verse]
-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <URL>
+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>
 
 DESCRIPTION
 -----------

Documentation/git-http-push.txt

@@ -9,7 +9,7 @@ git-http-push - Push objects over HTTP/DAV to another repository
 SYNOPSIS
 --------
 [verse]
-'git http-push' [--all] [--dry-run] [--force] [--verbose] <URL> <ref> [<ref>...]
+'git http-push' [--all] [--dry-run] [--force] [--verbose] <url> <ref> [<ref>...]
 
 DESCRIPTION
 -----------
@@ -63,15 +63,16 @@ of such patterns separated by a colon ":" (this means that a ref name
 cannot have a colon in it).  A single pattern '<name>' is just a
 shorthand for '<name>:<name>'.
 
-Each pattern pair '<src>:<dst>' consists of the source side (before
-the colon) and the destination side (after the colon).  The ref to be
-pushed is determined by finding a match that matches the source side,
-and where it is pushed is determined by using the destination side.
+Each pattern pair consists of the source side (before the colon)
+and the destination side (after the colon).  The ref to be
+pushed is determined by finding a match that matches the source
+side, and where it is pushed is determined by using the
+destination side.
 
- - It is an error if '<src>' does not match exactly one of the
+ - It is an error if <src> does not match exactly one of the
    local refs.
 
- - If '<dst>' does not match any remote ref, either
+ - If <dst> does not match any remote ref, either
 
    * it has to start with "refs/"; <dst> is used as the
      destination literally in this case.

Documentation/git-index-pack.txt

@@ -82,12 +82,6 @@ OPTIONS
 --strict::
 	Die, if the pack contains broken objects or links.
 
---progress-title::
-	For internal use only.
-+
-Set the title of the progress bar. The title is "Receiving objects" by
-default and "Indexing objects" when `--stdin` is specified.
-
 --check-self-contained-and-connected::
 	Die if the pack contains broken links. For internal use only.
 

Documentation/git-init-db.txt

@@ -9,7 +9,7 @@ git-init-db - Creates an empty Git repository
 SYNOPSIS
 --------
 [verse]
-'git init-db' [-q | --quiet] [--bare] [--template=<template-directory>] [--separate-git-dir <git-dir>] [--shared[=<permissions>]]
+'git init-db' [-q | --quiet] [--bare] [--template=<template_directory>] [--separate-git-dir <git dir>] [--shared[=<permissions>]]
 
 
 DESCRIPTION

Documentation/git-init.txt

@@ -9,10 +9,10 @@ git-init - Create an empty Git repository or reinitialize an existing one
 SYNOPSIS
 --------
 [verse]
-'git init' [-q | --quiet] [--bare] [--template=<template-directory>]
-	  [--separate-git-dir <git-dir>] [--object-format=<format>]
+'git init' [-q | --quiet] [--bare] [--template=<template_directory>]
+	  [--separate-git-dir <git dir>] [--object-format=<format>]
 	  [-b <branch-name> | --initial-branch=<branch-name>]
-	  [--shared[=<permissions>]] [<directory>]
+	  [--shared[=<permissions>]] [directory]
 
 
 DESCRIPTION
@@ -57,12 +57,12 @@ values are 'sha1' and (if enabled) 'sha256'.  'sha1' is the default.
 +
 include::object-format-disclaimer.txt[]
 
---template=<template-directory>::
+--template=<template_directory>::
 
 Specify the directory from which templates will be used.  (See the "TEMPLATE
 DIRECTORY" section below.)
 
---separate-git-dir=<git-dir>::
+--separate-git-dir=<git dir>::
 
 Instead of initializing the repository as a directory to either `$GIT_DIR` or
 `./.git/`, create a text file there containing the path to the actual
@@ -79,7 +79,7 @@ repository.  If not specified, fall back to the default name (currently
 `master`, but this is subject to change in the future; the name can be
 customized via the `init.defaultBranch` configuration variable).
 
---shared[=(false|true|umask|group|all|world|everybody|<perm>)]::
+--shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
 
 Specify that the Git repository is to be shared amongst several users.  This
 allows users belonging to the same group to push into that
@@ -110,16 +110,13 @@ the repository permissions.
 
 Same as 'group', but make the repository readable by all users.
 
-'<perm>'::
+'0xxx'::
 
-'<perm>' is a 3-digit octal number prefixed with `0` and each file
-will have mode '<perm>'. '<perm>' will override users' umask(2)
-value (and not only loosen permissions as 'group' and 'all'
-does). '0640' will create a repository which is group-readable, but
-not group-writable or accessible to others. '0660' will create a repo
-that is readable and writable to the current user and group, but
-inaccessible to others (directories and executable files get their
-`x` bit from the `r` bit for corresponding classes of users).
+'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will
+override users' umask(2) value (and not only loosen permissions as 'group' and
+'all' does). '0640' will create a repository which is group-readable, but not
+group-writable or accessible to others. '0660' will create a repo that is
+readable and writable to the current user and group, but inaccessible to others.
 --
 
 By default, the configuration flag `receive.denyNonFastForwards` is enabled

Documentation/git-log.txt

@@ -9,7 +9,7 @@ git-log - Show commit logs
 SYNOPSIS
 --------
 [verse]
-'git log' [<options>] [<revision-range>] [[--] <path>...]
+'git log' [<options>] [<revision range>] [[--] <path>...]
 
 DESCRIPTION
 -----------
@@ -81,13 +81,13 @@ produced by `--stat`, etc.
 
 include::line-range-options.txt[]
 
-<revision-range>::
+<revision range>::
 	Show only commits in the specified revision range.  When no
-	<revision-range> is specified, it defaults to `HEAD` (i.e. the
+	<revision range> is specified, it defaults to `HEAD` (i.e. the
 	whole history leading to the current commit).  `origin..HEAD`
 	specifies all the commits reachable from the current commit
 	(i.e. `HEAD`), but not from `origin`. For a complete list of
-	ways to spell <revision-range>, see the 'Specifying Ranges'
+	ways to spell <revision range>, see the 'Specifying Ranges'
 	section of linkgit:gitrevisions[7].
 
 [--] <path>...::

Documentation/git-ls-files.txt

@@ -10,9 +10,9 @@ SYNOPSIS
 --------
 [verse]
 'git ls-files' [-z] [-t] [-v] [-f]
-		[-c|--cached] [-d|--deleted] [-o|--others] [-i|--|ignored]
-		[-s|--stage] [-u|--unmerged] [-k|--|killed] [-m|--modified]
-		[--directory [--no-empty-directory]] [--eol]
+		(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
+		(-[c|d|o|i|s|u|k|m])*
+		[--eol]
 		[--deduplicate]
 		[-x <pattern>|--exclude=<pattern>]
 		[-X <file>|--exclude-from=<file>]
@@ -187,11 +187,6 @@ Both the <eolinfo> in the index ("i/<eolinfo>")
 and in the working tree ("w/<eolinfo>") are shown for regular files,
 followed by the  ("attr/<eolattr>").
 
---sparse::
-	If the index is sparse, show the sparse directories without expanding
-	to the contained files. Sparse directories will be shown with a
-	trailing slash, such as "x/" for a sparse directory "x".
-
 \--::
 	Do not interpret any more arguments as options.
 

Documentation/git-maintenance.txt

@@ -179,17 +179,6 @@ OPTIONS
 	`maintenance.<task>.enabled` configured as `true` are considered.
 	See the 'TASKS' section for the list of accepted `<task>` values.
 
---scheduler=auto|crontab|systemd-timer|launchctl|schtasks::
-	When combined with the `start` subcommand, specify the scheduler
-	for running the hourly, daily and weekly executions of
-	`git maintenance run`.
-	Possible values for `<scheduler>` are `auto`, `crontab`
-	(POSIX), `systemd-timer` (Linux), `launchctl` (macOS), and
-	`schtasks` (Windows). When `auto` is specified, the
-	appropriate platform-specific scheduler is used; on Linux,
-	`systemd-timer` is used if available, otherwise
-	`crontab`. Default is `auto`.
-
 
 TROUBLESHOOTING
 ---------------
@@ -288,52 +277,6 @@ schedule to ensure you are executing the correct binaries in your
 schedule.
 
 
-BACKGROUND MAINTENANCE ON LINUX SYSTEMD SYSTEMS
------------------------------------------------
-
-While Linux supports `cron`, depending on the distribution, `cron` may
-be an optional package not necessarily installed. On modern Linux
-distributions, systemd timers are superseding it.
-
-If user systemd timers are available, they will be used as a replacement
-of `cron`.
-
-In this case, `git maintenance start` will create user systemd timer units
-and start the timers. The current list of user-scheduled tasks can be found
-by running `systemctl --user list-timers`. The timers written by `git
-maintenance start` are similar to this:
-
------------------------------------------------------------------------
-$ systemctl --user list-timers
-NEXT                         LEFT          LAST                         PASSED     UNIT                         ACTIVATES
-Thu 2021-04-29 19:00:00 CEST 42min left    Thu 2021-04-29 18:00:11 CEST 17min ago  git-maintenance@hourly.timer git-maintenance@hourly.service
-Fri 2021-04-30 00:00:00 CEST 5h 42min left Thu 2021-04-29 00:00:11 CEST 18h ago    git-maintenance@daily.timer  git-maintenance@daily.service
-Mon 2021-05-03 00:00:00 CEST 3 days left   Mon 2021-04-26 00:00:11 CEST 3 days ago git-maintenance@weekly.timer git-maintenance@weekly.service
------------------------------------------------------------------------
-
-One timer is registered for each `--schedule=<frequency>` option.
-
-The definition of the systemd units can be inspected in the following files:
-
------------------------------------------------------------------------
-~/.config/systemd/user/git-maintenance@.timer
-~/.config/systemd/user/git-maintenance@.service
-~/.config/systemd/user/timers.target.wants/git-maintenance@hourly.timer
-~/.config/systemd/user/timers.target.wants/git-maintenance@daily.timer
-~/.config/systemd/user/timers.target.wants/git-maintenance@weekly.timer
------------------------------------------------------------------------
-
-`git maintenance start` will overwrite these files and start the timer
-again with `systemctl --user`, so any customization should be done by
-creating a drop-in file, i.e. a `.conf` suffixed file in the
-`~/.config/systemd/user/git-maintenance@.service.d` directory.
-
-`git maintenance stop` will stop the user systemd timers and delete
-the above mentioned files.
-
-For more details, see `systemd.timer(5)`.
-
-
 BACKGROUND MAINTENANCE ON MACOS SYSTEMS
 ---------------------------------------
 

Documentation/git-merge-file.txt

@@ -70,9 +70,6 @@ OPTIONS
 --diff3::
 	Show conflicts in "diff3" style.
 
---zdiff3::
-	Show conflicts in "zdiff3" style.
-
 --ours::
 --theirs::
 --union::

Documentation/git-merge-index.txt

@@ -9,7 +9,7 @@ git-merge-index - Run a merge for files needing merging
 SYNOPSIS
 --------
 [verse]
-'git merge-index' [-o] [-q] <merge-program> (-a | ( [--] <file>...) )
+'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*)
 
 DESCRIPTION
 -----------

Documentation/git-merge.txt

@@ -12,8 +12,7 @@ SYNOPSIS
 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
 	[--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
 	[--[no-]allow-unrelated-histories]
-	[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>]
-	[--into-name <branch>] [<commit>...]
+	[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...]
 'git merge' (--continue | --abort | --quit)
 
 DESCRIPTION
@@ -77,11 +76,6 @@ The 'git fmt-merge-msg' command can be
 used to give a good default for automated 'git merge'
 invocations. The automated message can include the branch description.
 
---into-name <branch>::
-	Prepare the default merge message as if merging to the branch
-	`<branch>`, instead of the name of the real branch to which
-	the merge is made.
-
 -F <file>::
 --file=<file>::
 	Read the commit message to be used for the merge commit (in
@@ -246,8 +240,7 @@ from the RCS suite to present such a conflicted hunk, like this:
 
 ------------
 Here are lines that are either unchanged from the common
-ancestor, or cleanly resolved because only one side changed,
-or cleanly resolved because both sides changed the same way.
+ancestor, or cleanly resolved because only one side changed.
 <<<<<<< yours:sample.txt
 Conflict resolution is hard;
 let's go shopping.
@@ -268,37 +261,16 @@ side wants to say it is hard and you'd prefer to go shopping, while the
 other side wants to claim it is easy.
 
 An alternative style can be used by setting the "merge.conflictStyle"
-configuration variable to either "diff3" or "zdiff3".  In "diff3"
-style, the above conflict may look like this:
+configuration variable to "diff3".  In "diff3" style, the above conflict
+may look like this:
 
 ------------
 Here are lines that are either unchanged from the common
-ancestor, or cleanly resolved because only one side changed,
-<<<<<<< yours:sample.txt
-or cleanly resolved because both sides changed the same way.
-Conflict resolution is hard;
-let's go shopping.
-||||||| base:sample.txt
-or cleanly resolved because both sides changed identically.
-Conflict resolution is hard.
-=======
-or cleanly resolved because both sides changed the same way.
-Git makes conflict resolution easy.
->>>>>>> theirs:sample.txt
-And here is another line that is cleanly resolved or unmodified.
-------------
-
-while in "zdiff3" style, it may look like this:
-
-------------
-Here are lines that are either unchanged from the common
-ancestor, or cleanly resolved because only one side changed,
-or cleanly resolved because both sides changed the same way.
+ancestor, or cleanly resolved because only one side changed.
 <<<<<<< yours:sample.txt
 Conflict resolution is hard;
 let's go shopping.
-||||||| base:sample.txt
-or cleanly resolved because both sides changed identically.
+|||||||
 Conflict resolution is hard.
 =======
 Git makes conflict resolution easy.

Documentation/git-multi-pack-index.txt

@@ -9,7 +9,8 @@ git-multi-pack-index - Write and verify multi-pack-indexes
 SYNOPSIS
 --------
 [verse]
-'git multi-pack-index' [--object-dir=<dir>] [--[no-]bitmap] <sub-command>
+'git multi-pack-index' [--object-dir=<dir>] [--[no-]progress]
+	[--preferred-pack=<pack>] <subcommand>
 
 DESCRIPTION
 -----------
@@ -22,13 +23,10 @@ OPTIONS
 	Use given directory for the location of Git objects. We check
 	`<dir>/packs/multi-pack-index` for the current MIDX file, and
 	`<dir>/packs` for the pack-files to index.
-+
-`<dir>` must be an alternate of the current repository.
 
 --[no-]progress::
 	Turn progress on/off explicitly. If neither is specified, progress is
-	shown if standard error is connected to a terminal. Supported by
-	sub-commands `write`, `verify`, `expire`, and `repack.
+	shown if standard error is connected to a terminal.
 
 The following subcommands are available:
 
@@ -39,31 +37,9 @@ write::
 --
 	--preferred-pack=<pack>::
 		Optionally specify the tie-breaking pack used when
-		multiple packs contain the same object. `<pack>` must
-		contain at least one object. If not given, ties are
-		broken in favor of the pack with the lowest mtime.
-
-	--[no-]bitmap::
-		Control whether or not a multi-pack bitmap is written.
-
-	--stdin-packs::
-		Write a multi-pack index containing only the set of
-		line-delimited pack index basenames provided over stdin.
-
-	--refs-snapshot=<path>::
-		With `--bitmap`, optionally specify a file which
-		contains a "refs snapshot" taken prior to repacking.
-+
-A reference snapshot is composed of line-delimited OIDs corresponding to
-the reference tips, usually taken by `git repack` prior to generating a
-new pack. A line may optionally start with a `+` character to indicate
-that the reference which corresponds to that OID is "preferred" (see
-linkgit:git-config[1]'s `pack.preferBitmapTips`.)
-+
-The file given at `<path>` is expected to be readable, and can contain
-duplicates. (If a given OID is given more than once, it is marked as
-preferred if at least one instance of it begins with the special `+`
-marker).
+		multiple packs contain the same object. If not given,
+		ties are broken in favor of the pack with the lowest
+		mtime.
 --
 
 verify::
@@ -99,26 +75,19 @@ associated `.keep` file will not be selected for the batch to repack.
 EXAMPLES
 --------
 
-* Write a MIDX file for the packfiles in the current `.git` directory.
+* Write a MIDX file for the packfiles in the current .git folder.
 +
 -----------------------------------------------
 $ git multi-pack-index write
 -----------------------------------------------
 
-* Write a MIDX file for the packfiles in the current `.git` directory with a
-corresponding bitmap.
-+
--------------------------------------------------------------
-$ git multi-pack-index write --preferred-pack=<pack> --bitmap
--------------------------------------------------------------
-
 * Write a MIDX file for the packfiles in an alternate object store.
 +
 -----------------------------------------------
 $ git multi-pack-index --object-dir <alt> write
 -----------------------------------------------
 
-* Verify the MIDX file for the packfiles in the current `.git` directory.
+* Verify the MIDX file for the packfiles in the current .git folder.
 +
 -----------------------------------------------
 $ git multi-pack-index verify

Documentation/git-p4.txt

@@ -9,10 +9,10 @@ git-p4 - Import from and submit to Perforce repositories
 SYNOPSIS
 --------
 [verse]
-'git p4 clone' [<sync-options>] [<clone-options>] <p4-depot-path>...
-'git p4 sync' [<sync-options>] [<p4-depot-path>...]
+'git p4 clone' [<sync options>] [<clone options>] <p4 depot path>...
+'git p4 sync' [<sync options>] [<p4 depot path>...]
 'git p4 rebase'
-'git p4 submit' [<submit-options>] [<master-branch-name>]
+'git p4 submit' [<submit options>] [<master branch name>]
 
 
 DESCRIPTION
@@ -361,7 +361,7 @@ These options can be used to modify 'git p4 submit' behavior.
 	p4/master.  See the "Sync options" section above for more
 	information.
 
---commit (<sha1>|<sha1>..<sha1>)::
+--commit <sha1>|<sha1..sha1>::
     Submit only the specified commit or range of commits, instead of the full
     list of changes that are in the current Git branch.
 

Documentation/git-pack-objects.txt

@@ -13,8 +13,8 @@ SYNOPSIS
 	[--no-reuse-delta] [--delta-base-offset] [--non-empty]
 	[--local] [--incremental] [--window=<n>] [--depth=<n>]
 	[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]
-	[--stdout [--filter=<filter-spec>] | <base-name>]
-	[--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list>
+	[--stdout [--filter=<filter-spec>] | base-name]
+	[--shallow] [--keep-true-parents] [--[no-]sparse] < object-list
 
 
 DESCRIPTION

Documentation/git-pack-redundant.txt

@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files
 SYNOPSIS
 --------
 [verse]
-'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
+'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >
 
 DESCRIPTION
 -----------

Documentation/git-pull.txt

@@ -105,7 +105,7 @@ Options related to merging
 include::merge-options.txt[]
 
 -r::
---rebase[=false|true|merges|interactive]::
+--rebase[=false|true|merges|preserve|interactive]::
 	When true, rebase the current branch on top of the upstream
 	branch after fetching. If there is a remote-tracking branch
 	corresponding to the upstream branch and the upstream branch
@@ -116,6 +116,10 @@ When set to `merges`, rebase using `git rebase --rebase-merges` so that
 the local merge commits are included in the rebase (see
 linkgit:git-rebase[1] for details).
 +
+When set to `preserve` (deprecated in favor of `merges`), rebase with the
+`--preserve-merges` option passed to `git rebase` so that locally created
+merge commits will not be flattened.
++
 When false, merge the upstream branch into the current branch.
 +
 When `interactive`, enable the interactive mode of rebase.

Documentation/git-read-tree.txt

@@ -10,7 +10,8 @@ SYNOPSIS
 --------
 [verse]
 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
-		[-u | -i]] [--index-output=<file>] [--no-sparse-checkout]
+		[-u [--exclude-per-directory=<gitignore>] | -i]]
+		[--index-output=<file>] [--no-sparse-checkout]
 		(--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
 
 
@@ -38,9 +39,8 @@ OPTIONS
 
 --reset::
 	Same as -m, except that unmerged entries are discarded instead
-	of failing.  When used with `-u`, updates leading to loss of
-	working tree changes or untracked files or directories will not
-	abort the operation.
+	of failing. When used with `-u`, updates leading to loss of
+	working tree changes will not abort the operation.
 
 -u::
 	After a successful merge, update the files in the work
@@ -88,6 +88,21 @@ OPTIONS
 	The command will refuse to overwrite entries that already
 	existed in the original index file.
 
+--exclude-per-directory=<gitignore>::
+	When running the command with `-u` and `-m` options, the
+	merge result may need to overwrite paths that are not
+	tracked in the current branch.  The command usually
+	refuses to proceed with the merge to avoid losing such a
+	path.  However this safety valve sometimes gets in the
+	way.  For example, it often happens that the other
+	branch added a file that used to be a generated file in
+	your branch, and the safety valve triggers when you try
+	to switch to that branch after you ran `make` but before
+	running `make clean` to remove the generated file.  This
+	option tells the command to read per-directory exclude
+	file (usually '.gitignore') and allows such an untracked
+	but explicitly ignored file to be overwritten.
+
 --index-output=<file>::
 	Instead of writing the results out to `$GIT_INDEX_FILE`,
 	write the resulting index in the named file.  While the

Documentation/git-rebase.txt

@@ -79,10 +79,9 @@ remain the checked-out branch.
 
 If the upstream branch already contains a change you have made (e.g.,
 because you mailed a patch which was applied upstream), then that commit
-will be skipped and warnings will be issued (if the `merge` backend is
-used).  For example, running `git rebase master` on the following
-history (in which `A'` and `A` introduce the same set of changes, but
-have different committer information):
+will be skipped. For example, running `git rebase master` on the
+following history (in which `A'` and `A` introduce the same set of changes,
+but have different committer information):
 
 ------------
           A---B---C topic
@@ -313,10 +312,7 @@ See also INCOMPATIBLE OPTIONS below.
 By default (or if `--no-reapply-cherry-picks` is given), these commits
 will be automatically dropped.  Because this necessitates reading all
 upstream commits, this can be expensive in repos with a large number
-of upstream commits that need to be read.  When using the `merge`
-backend, warnings will be issued for each dropped commit (unless
-`--quiet` is given). Advice will also be issued unless
-`advice.skippedCherryPicks` is set to false (see linkgit:git-config[1]).
+of upstream commits that need to be read.
 +
 `--reapply-cherry-picks` allows rebase to forgo reading all upstream
 commits, potentially improving performance.
@@ -356,8 +352,8 @@ See also INCOMPATIBLE OPTIONS below.
 
 -s <strategy>::
 --strategy=<strategy>::
-	Use the given merge strategy, instead of the default `ort`.
-	This implies `--merge`.
+	Use the given merge strategy, instead of the default
+	`recursive`.  This implies `--merge`.
 +
 Because 'git rebase' replays each commit from the working branch
 on top of the <upstream> branch using the given strategy, using
@@ -370,7 +366,7 @@ See also INCOMPATIBLE OPTIONS below.
 --strategy-option=<strategy-option>::
 	Pass the <strategy-option> through to the merge strategy.
 	This implies `--merge` and, if no strategy has been
-	specified, `-s ort`.  Note the reversal of 'ours' and
+	specified, `-s recursive`.  Note the reversal of 'ours' and
 	'theirs' as noted above for the `-m` option.
 +
 See also INCOMPATIBLE OPTIONS below.
@@ -446,8 +442,7 @@ When --fork-point is active, 'fork_point' will be used instead of
 ends up being empty, the <upstream> will be used as a fallback.
 +
 If <upstream> is given on the command line, then the default is
-`--no-fork-point`, otherwise the default is `--fork-point`. See also
-`rebase.forkpoint` in linkgit:git-config[1].
+`--no-fork-point`, otherwise the default is `--fork-point`.
 +
 If your branch was based on <upstream> but <upstream> was rewound and
 your branch contains commits which were dropped, this option can be used
@@ -527,12 +522,29 @@ i.e. commits that would be excluded by linkgit:git-log[1]'s
 the `rebase-cousins` mode is turned on, such commits are instead rebased
 onto `<upstream>` (or `<onto>`, if specified).
 +
+The `--rebase-merges` mode is similar in spirit to the deprecated
+`--preserve-merges` but works with interactive rebases,
+where commits can be reordered, inserted and dropped at will.
++
 It is currently only possible to recreate the merge commits using the
-`ort` merge strategy; different merge strategies can be used only via
+`recursive` merge strategy; different merge strategies can be used only via
 explicit `exec git merge -s <strategy> [...]` commands.
 +
 See also REBASING MERGES and INCOMPATIBLE OPTIONS below.
 
+-p::
+--preserve-merges::
+	[DEPRECATED: use `--rebase-merges` instead] Recreate merge commits
+	instead of flattening the history by replaying commits a merge commit
+	introduces. Merge conflict resolutions or manual amendments to merge
+	commits are not preserved.
++
+This uses the `--interactive` machinery internally, but combining it
+with the `--interactive` option explicitly is generally not a good
+idea unless you know what you are doing (see BUGS below).
++
+See also INCOMPATIBLE OPTIONS below.
+
 -x <cmd>::
 --exec <cmd>::
 	Append "exec <cmd>" after each line creating a commit in the
@@ -564,6 +576,9 @@ See also INCOMPATIBLE OPTIONS below.
 	the root commit(s) on a branch.  When used with --onto, it
 	will skip changes already contained in <newbase> (instead of
 	<upstream>) whereas without --onto it will operate on every change.
+	When used together with both --onto and --preserve-merges,
+	'all' root commits will be rewritten to have <newbase> as parent
+	instead.
 +
 See also INCOMPATIBLE OPTIONS below.
 
@@ -625,6 +640,7 @@ are incompatible with the following options:
  * --allow-empty-message
  * --[no-]autosquash
  * --rebase-merges
+ * --preserve-merges
  * --interactive
  * --exec
  * --no-keep-empty
@@ -635,6 +651,13 @@ are incompatible with the following options:
 
 In addition, the following pairs of options are incompatible:
 
+ * --preserve-merges and --interactive
+ * --preserve-merges and --signoff
+ * --preserve-merges and --rebase-merges
+ * --preserve-merges and --empty=
+ * --preserve-merges and --ignore-whitespace
+ * --preserve-merges and --committer-date-is-author-date
+ * --preserve-merges and --ignore-date
  * --keep-base and --onto
  * --keep-base and --root
  * --fork-point and --root
@@ -714,9 +737,9 @@ information about the rebased commits and their parents (and instead
 generates new fake commits based off limited information in the
 generated patches), those commits cannot be identified; instead it has
 to fall back to a commit summary.  Also, when merge.conflictStyle is
-set to diff3 or zdiff3, the apply backend will use "constructed merge
-base" to label the content from the merge base, and thus provide no
-information about the merge base commit whatsoever.
+set to diff3, the apply backend will use "constructed merge base" to
+label the content from the merge base, and thus provide no information
+about the merge base commit whatsoever.
 
 The merge backend works with the full commits on both sides of history
 and thus has no such limitations.
@@ -1193,16 +1216,16 @@ successful merge so that the user can edit the message.
 If a `merge` command fails for any reason other than merge conflicts (i.e.
 when the merge operation did not even start), it is rescheduled immediately.
 
-By default, the `merge` command will use the `ort` merge strategy for
-regular merges, and `octopus` for octopus merges.  One can specify a
-default strategy for all merges using the `--strategy` argument when
-invoking rebase, or can override specific merges in the interactive
-list of commands by using an `exec` command to call `git merge`
-explicitly with a `--strategy` argument.  Note that when calling `git
-merge` explicitly like this, you can make use of the fact that the
-labels are worktree-local refs (the ref `refs/rewritten/onto` would
-correspond to the label `onto`, for example) in order to refer to the
-branches you want to merge.
+By default, the `merge` command will use the `recursive` merge
+strategy for regular merges, and `octopus` for octopus merges.  One
+can specify a default strategy for all merges using the `--strategy`
+argument when invoking rebase, or can override specific merges in the
+interactive list of commands by using an `exec` command to call `git
+merge` explicitly with a `--strategy` argument.  Note that when
+calling `git merge` explicitly like this, you can make use of the fact
+that the labels are worktree-local refs (the ref `refs/rewritten/onto`
+would correspond to the label `onto`, for example) in order to refer
+to the branches you want to merge.
 
 Note: the first command (`label onto`) labels the revision onto which
 the commits are rebased; The name `onto` is just a convention, as a nod
@@ -1252,6 +1275,29 @@ CONFIGURATION
 include::config/rebase.txt[]
 include::config/sequencer.txt[]
 
+BUGS
+----
+The todo list presented by the deprecated `--preserve-merges --interactive`
+does not represent the topology of the revision graph (use `--rebase-merges`
+instead).  Editing commits and rewording their commit messages should work
+fine, but attempts to reorder commits tend to produce counterintuitive results.
+Use `--rebase-merges` in such scenarios instead.
+
+For example, an attempt to rearrange
+------------
+1 --- 2 --- 3 --- 4 --- 5
+------------
+to
+------------
+1 --- 2 --- 4 --- 3 --- 5
+------------
+by moving the "pick 4" line will result in the following history:
+------------
+	3
+       /
+1 --- 2 --- 4 --- 5
+------------
+
 GIT
 ---
 Part of the linkgit:git[1] suite

Documentation/git-receive-pack.txt

@@ -41,11 +41,6 @@ OPTIONS
 <directory>::
 	The repository to sync into.
 
---http-backend-info-refs::
-	Used by linkgit:git-http-backend[1] to serve up
-	`$GIT_URL/info/refs?service=git-receive-pack` requests. See
-	`--http-backend-info-refs` in linkgit:git-upload-pack[1].
-
 PRE-RECEIVE HOOK
 ----------------
 Before any ref is updated, if $GIT_DIR/hooks/pre-receive file exists

Documentation/git-reflog.txt

@@ -17,12 +17,12 @@ The command takes various subcommands, and different options
 depending on the subcommand:
 
 [verse]
-'git reflog' ['show'] [<log-options>] [<ref>]
+'git reflog' ['show'] [log-options] [<ref>]
 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
 	[--rewrite] [--updateref] [--stale-fix]
 	[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
 'git reflog delete' [--rewrite] [--updateref]
-	[--dry-run | -n] [--verbose] <ref>@\{<specifier>\}...
+	[--dry-run | -n] [--verbose] ref@\{specifier\}...
 'git reflog exists' <ref>
 
 Reference logs, or "reflogs", record when the tips of branches and

Documentation/git-remote.txt

@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git remote' [-v | --verbose]
-'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <URL>
+'git remote add' [-t <branch>] [-m <master>] [-f] [--[no-]tags] [--mirror=(fetch|push)] <name> <url>
 'git remote rename' <old> <new>
 'git remote remove' <name>
 'git remote set-head' <name> (-a | --auto | -d | --delete | <branch>)
@@ -18,7 +18,7 @@ SYNOPSIS
 'git remote get-url' [--push] [--all] <name>
 'git remote set-url' [--push] <name> <newurl> [<oldurl>]
 'git remote set-url --add' [--push] <name> <newurl>
-'git remote set-url --delete' [--push] <name> <URL>
+'git remote set-url --delete' [--push] <name> <url>
 'git remote' [-v | --verbose] 'show' [-n] <name>...
 'git remote prune' [-n | --dry-run] <name>...
 'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...]
@@ -47,7 +47,7 @@ subcommands are available to perform operations on the remotes.
 'add'::
 
 Add a remote named <name> for the repository at
-<URL>.  The command `git fetch <name>` can then be used to create and
+<url>.  The command `git fetch <name>` can then be used to create and
 update remote-tracking branches <name>/<branch>.
 +
 With `-f` option, `git fetch <name>` is run immediately after
@@ -152,7 +152,7 @@ With `--push`, push URLs are manipulated instead of fetch URLs.
 With `--add`, instead of changing existing URLs, new URL is added.
 +
 With `--delete`, instead of changing existing URLs, all URLs matching
-regex <URL> are deleted for remote <name>.  Trying to delete all
+regex <url> are deleted for remote <name>.  Trying to delete all
 non-push URLs is an error.
 +
 Note that the push URL and the fetch URL, even though they can

Documentation/git-repack.txt

@@ -9,7 +9,7 @@ git-repack - Pack unpacked objects in a repository
 SYNOPSIS
 --------
 [verse]
-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx]
+'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>]
 
 DESCRIPTION
 -----------
@@ -76,9 +76,8 @@ to the new separate pack will be written.
 	linkgit:git-pack-objects[1].
 
 -q::
---quiet::
-	Show no progress over the standard error stream and pass the `-q`
-	option to 'git pack-objects'. See linkgit:git-pack-objects[1].
+	Pass the `-q` option to 'git pack-objects'. See
+	linkgit:git-pack-objects[1].
 
 -n::
 	Do not update the server information with
@@ -129,11 +128,10 @@ depth is 4095.
 -b::
 --write-bitmap-index::
 	Write a reachability bitmap index as part of the repack. This
-	only makes sense when used with `-a`, `-A` or `-m`, as the bitmaps
+	only makes sense when used with `-a` or `-A`, as the bitmaps
 	must be able to refer to all reachable objects. This option
-	overrides the setting of `repack.writeBitmaps`. This option
-	has no effect if multiple packfiles are created, unless writing a
-	MIDX (in which case a multi-pack bitmap is created).
+	overrides the setting of `repack.writeBitmaps`.  This option
+	has no effect if multiple packfiles are created.
 
 --pack-kept-objects::
 	Include objects in `.keep` files when repacking.  Note that we
@@ -191,15 +189,6 @@ this "roll-up", without respect to their reachability. This is subject
 to change in the future. This option (implying a drastically different
 repack mode) is not guaranteed to work with all other combinations of
 option to `git repack`.
-+
-When writing a multi-pack bitmap, `git repack` selects the largest resulting
-pack as the preferred pack for object selection by the MIDX (see
-linkgit:git-multi-pack-index[1]).
-
--m::
---write-midx::
-	Write a multi-pack index (see linkgit:git-multi-pack-index[1])
-	containing the non-redundant packs.
 
 CONFIGURATION
 -------------

Documentation/git-request-pull.txt

@@ -8,7 +8,7 @@ git-request-pull - Generates a summary of pending changes
 SYNOPSIS
 --------
 [verse]
-'git request-pull' [-p] <start> <URL> [<end>]
+'git request-pull' [-p] <start> <url> [<end>]
 
 DESCRIPTION
 -----------
@@ -21,7 +21,7 @@ the changes and indicates from where they can be pulled.
 The upstream project is expected to have the commit named by
 `<start>` and the output asks it to integrate the changes you made
 since that commit, up to the commit named by `<end>`, by visiting
-the repository named by `<URL>`.
+the repository named by `<url>`.
 
 
 OPTIONS
@@ -33,14 +33,14 @@ OPTIONS
 	Commit to start at.  This names a commit that is already in
 	the upstream history.
 
-<URL>::
+<url>::
 	The repository URL to be pulled from.
 
 <end>::
 	Commit to end at (defaults to HEAD).  This names the commit
 	at the tip of the history you are asking to be pulled.
 +
-When the repository named by `<URL>` has the commit at a tip of a
+When the repository named by `<url>` has the commit at a tip of a
 ref that is different from the ref you have locally, you can use the
 `<local>:<remote>` syntax, to have its local name, a colon `:`, and
 its remote name.

Documentation/git-reset.txt

@@ -69,8 +69,7 @@ linkgit:git-add[1]).
 
 --hard::
 	Resets the index and working tree. Any changes to tracked files in the
-	working tree since `<commit>` are discarded.  Any untracked files or
-	directories in the way of writing any tracked files are simply deleted.
+	working tree since `<commit>` are discarded.
 
 --merge::
 	Resets the index and updates the files in the working tree that are

Documentation/git-restore.txt

@@ -92,7 +92,8 @@ in linkgit:git-checkout[1] for details.
 	The same as `--merge` option above, but changes the way the
 	conflicting hunks are presented, overriding the
 	`merge.conflictStyle` configuration variable.  Possible values
-	are "merge" (default), "diff3", and "zdiff3".
+	are "merge" (default) and "diff3" (in addition to what is
+	shown by "merge" style, shows the original contents).
 
 --ignore-unmerged::
 	When restoring files on the working tree from the index, do

Documentation/git-rm.txt

@@ -72,12 +72,6 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
 --ignore-unmatch::
 	Exit with a zero status even if no files matched.
 
---sparse::
-	Allow updating index entries outside of the sparse-checkout cone.
-	Normally, `git rm` refuses to update index entries whose paths do
-	not fit within the sparse-checkout cone. See
-	linkgit:git-sparse-checkout[1] for more.
-
 -q::
 --quiet::
 	`git rm` normally outputs one line (in the form of an `rm` command)

Documentation/git-send-email.txt

@@ -9,8 +9,7 @@ git-send-email - Send a collection of patches as emails
 SYNOPSIS
 --------
 [verse]
-'git send-email' [<options>] <file|directory>...
-'git send-email' [<options>] <format-patch options>
+'git send-email' [<options>] <file|directory|rev-list options>...
 'git send-email' --dump-aliases
 
 
@@ -20,8 +19,7 @@ Takes the patches given on the command line and emails them out.
 Patches can be specified as files, directories (which will send all
 files in the directory), or directly as a revision list.  In the
 last case, any format accepted by linkgit:git-format-patch[1] can
-be passed to git send-email, as well as options understood by
-linkgit:git-format-patch[1].
+be passed to git send-email.
 
 The header of the email is configurable via command-line options.  If not
 specified on the command line, the user will be prompted with a ReadLine

Documentation/git-send-pack.txt

@@ -9,10 +9,10 @@ git-send-pack - Push objects over Git protocol to another repository
 SYNOPSIS
 --------
 [verse]
-'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
+'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>]
 		[--verbose] [--thin] [--atomic]
 		[--[no-]signed|--signed=(true|false|if-asked)]
-		[<host>:]<directory> (--all | <ref>...)
+		[<host>:]<directory> [<ref>...]
 
 DESCRIPTION
 -----------

Documentation/git-shortlog.txt

@@ -8,7 +8,7 @@ git-shortlog - Summarize 'git log' output
 SYNOPSIS
 --------
 [verse]
-'git shortlog' [<options>] [<revision-range>] [[--] <path>...]
+'git shortlog' [<options>] [<revision range>] [[--] <path>...]
 git log --pretty=short | 'git shortlog' [<options>]
 
 DESCRIPTION
@@ -89,13 +89,13 @@ counts both authors and co-authors.
 If width is `0` (zero) then indent the lines of the output without wrapping
 them.
 
-<revision-range>::
+<revision range>::
 	Show only commits in the specified revision range.  When no
-	<revision-range> is specified, it defaults to `HEAD` (i.e. the
+	<revision range> is specified, it defaults to `HEAD` (i.e. the
 	whole history leading to the current commit).  `origin..HEAD`
 	specifies all the commits reachable from the current commit
 	(i.e. `HEAD`), but not from `origin`. For a complete list of
-	ways to spell <revision-range>, see the "Specifying Ranges"
+	ways to spell <revision range>, see the "Specifying Ranges"
 	section of linkgit:gitrevisions[7].
 
 [--] <path>...::

Documentation/git-sparse-checkout.txt

@@ -11,7 +11,7 @@ given by a list of patterns.
 SYNOPSIS
 --------
 [verse]
-'git sparse-checkout <subcommand> [<options>]'
+'git sparse-checkout <subcommand> [options]'
 
 
 DESCRIPTION
@@ -30,36 +30,28 @@ COMMANDS
 'list'::
 	Describe the patterns in the sparse-checkout file.
 
-'set'::
-	Enable the necessary config settings
-	(extensions.worktreeConfig, core.sparseCheckout,
-	core.sparseCheckoutCone) if they are not already enabled, and
-	write a set of patterns to the sparse-checkout file from the
-	list of arguments following the 'set' subcommand. Update the
-	working directory to match the new patterns.
+'init'::
+	Enable the `core.sparseCheckout` setting. If the
+	sparse-checkout file does not exist, then populate it with
+	patterns that match every file in the root directory and
+	no other directories, then will remove all directories tracked
+	by Git. Add patterns to the sparse-checkout file to
+	repopulate the working directory.
 +
-When the `--stdin` option is provided, the patterns are read from
-standard in as a newline-delimited list instead of from the arguments.
+To avoid interfering with other worktrees, it first enables the
+`extensions.worktreeConfig` setting and makes sure to set the
+`core.sparseCheckout` setting in the worktree-specific config file.
 +
-When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
-input list is considered a list of directories instead of
-sparse-checkout patterns.  This allows for better performance with a
-limited set of patterns (see 'CONE PATTERN SET' below).  Note that the
-set command will write patterns to the sparse-checkout file to include
-all files contained in those directories (recursively) as well as
-files that are siblings of ancestor directories. The input format
-matches the output of `git ls-tree --name-only`.  This includes
-interpreting pathnames that begin with a double quote (") as C-style
-quoted strings.  This may become the default in the future; --no-cone
-can be passed to request non-cone mode.
+When `--cone` is provided, the `core.sparseCheckoutCone` setting is
+also set, allowing for better performance with a limited set of
+patterns (see 'CONE PATTERN SET' below).
 +
-Use the `--[no-]sparse-index` option to use a sparse index (the
-default is to not use it).  A sparse index reduces the size of the
-index to be more closely aligned with your sparse-checkout
-definition. This can have significant performance advantages for
-commands such as `git status` or `git add`.  This feature is still
-experimental. Some commands might be slower with a sparse index until
-they are properly integrated with the feature.
+Use the `--[no-]sparse-index` option to toggle the use of the sparse
+index format. This reduces the size of the index to be more closely
+aligned with your sparse-checkout definition. This can have significant
+performance advantages for commands such as `git status` or `git add`.
+This feature is still experimental. Some commands might be slower with
+a sparse index until they are properly integrated with the feature.
 +
 **WARNING:** Using a sparse index requires modifying the index in a way
 that is not completely understood by external tools. If you have trouble
@@ -68,6 +60,23 @@ to rewrite your index to not be sparse. Older versions of Git will not
 understand the sparse directory entries index extension and may fail to
 interact with your repository until it is disabled.
 
+'set'::
+	Write a set of patterns to the sparse-checkout file, as given as
+	a list of arguments following the 'set' subcommand. Update the
+	working directory to match the new patterns. Enable the
+	core.sparseCheckout config setting if it is not already enabled.
++
+When the `--stdin` option is provided, the patterns are read from
+standard in as a newline-delimited list instead of from the arguments.
++
+When `core.sparseCheckoutCone` is enabled, the input list is considered a
+list of directories instead of sparse-checkout patterns. The command writes
+patterns to the sparse-checkout file to include all files contained in those
+directories (recursively) as well as files that are siblings of ancestor
+directories. The input format matches the output of `git ls-tree --name-only`.
+This includes interpreting pathnames that begin with a double quote (") as
+C-style quoted strings.
+
 'add'::
 	Update the sparse-checkout file to include additional patterns.
 	By default, these patterns are read from the command-line arguments,
@@ -84,35 +93,12 @@ interact with your repository until it is disabled.
 	cases, it can make sense to run `git sparse-checkout reapply` later
 	after cleaning up affected paths (e.g. resolving conflicts, undoing
 	or committing changes, etc.).
-+
-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
-flags, with the same meaning as the flags from the `set` command, in order
-to change which sparsity mode you are using without needing to also respecify
-all sparsity paths.
 
 'disable'::
 	Disable the `core.sparseCheckout` config setting, and restore the
-	working directory to include all files.
-
-'init'::
-	Deprecated command that behaves like `set` with no specified paths.
-	May be removed in the future.
-+
-Historically, `set` did not handle all the necessary config settings,
-which meant that both `init` and `set` had to be called.  Invoking
-both meant the `init` step would first remove nearly all tracked files
-(and in cone mode, ignored files too), then the `set` step would add
-many of the tracked files (but not ignored files) back.  In addition
-to the lost files, the performance and UI of this combination was
-poor.
-+
-Also, historically, `init` would not actually initialize the
-sparse-checkout file if it already existed.  This meant it was
-possible to return to a sparse-checkout without remembering which
-paths to pass to a subsequent 'set' or 'add' command.  However,
-`--cone` and `--sparse-index` options would not be remembered across
-the disable command, so the easy restore of calling a plain `init`
-decreased in utility.
+	working directory to include all files. Leaves the sparse-checkout
+	file intact so a later 'git sparse-checkout init' command may
+	return the working directory to the same state.
 
 SPARSE CHECKOUT
 ---------------
@@ -121,7 +107,7 @@ SPARSE CHECKOUT
 It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell
 Git whether a file in the working directory is worth looking at. If
 the skip-worktree bit is set, then the file is ignored in the working
-directory. Git will avoid populating the contents of those files, which
+directory. Git will not populate the contents of those files, which
 makes a sparse checkout helpful when working in a repository with many
 files, but only a few are important to the current user.
 
@@ -131,8 +117,10 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
-To enable the sparse-checkout feature, run `git sparse-checkout set` to
-set the patterns you want to use.
+To enable the sparse-checkout feature, run `git sparse-checkout init` to
+initialize a simple sparse-checkout file and enable the `core.sparseCheckout`
+config setting. Then, run `git sparse-checkout set` to modify the patterns in
+the sparse-checkout file.
 
 To repopulate the working directory with all files, use the
 `git sparse-checkout disable` command.
@@ -222,16 +210,6 @@ case-insensitive check. This corrects for case mismatched filenames in the
 'git sparse-checkout set' command to reflect the expected cone in the working
 directory.
 
-When changing the sparse-checkout patterns in cone mode, Git will inspect each
-tracked directory that is not within the sparse-checkout cone to see if it
-contains any untracked files. If all of those files are ignored due to the
-`.gitignore` patterns, then the directory will be deleted. If any of the
-untracked files within that directory is not ignored, then no deletions will
-occur within that directory and a warning message will appear. If these files
-are important, then reset your sparse-checkout definition so they are included,
-use `git add` and `git commit` to store them, then remove any remaining files
-manually to ensure Git can behave optimally.
-
 
 SUBMODULES
 ----------