diff --git a/.github/workflows/check-whitespace.yml b/.github/workflows/check-whitespace.yml index f1483059c7..8c4358d805 100644 --- a/.github/workflows/check-whitespace.yml +++ b/.github/workflows/check-whitespace.yml @@ -12,15 +12,9 @@ jobs: check-whitespace: runs-on: ubuntu-latest steps: - - name: Set commit count - shell: bash - run: echo "COMMIT_DEPTH=$((1+$COMMITS))" >>$GITHUB_ENV - env: - COMMITS: ${{ github.event.pull_request.commits }} - - uses: actions/checkout@v2 with: - fetch-depth: ${{ env.COMMIT_DEPTH }} + fetch-depth: 0 - name: git log --check id: check_out @@ -47,25 +41,9 @@ jobs: echo "${dash} ${etc}" ;; esac - done <<< $(git log --check --pretty=format:"---% h% s" -${{github.event.pull_request.commits}}) + done <<< $(git log --check --pretty=format:"---% h% s" ${{github.event.pull_request.base.sha}}..) if test -n "${log}" then - echo "::set-output name=checkout::"${log}"" exit 2 fi - - - name: Add Check Output as Comment - uses: actions/github-script@v3 - id: add-comment - env: - log: ${{ steps.check_out.outputs.checkout }} - with: - script: | - await github.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: `Whitespace errors found in workflow ${{ github.workflow }}:\n\n\`\`\`\n${process.env.log.replace(/\\n/g, "\n")}\n\`\`\`` - }) - if: ${{ failure() }} diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 73856bafc9..47876a4f02 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -81,44 +81,21 @@ jobs: if: needs.ci-config.outputs.enabled == 'yes' runs-on: windows-latest steps: - - uses: actions/checkout@v1 - - name: download git-sdk-64-minimal - shell: bash - run: | - ## Get artifact - urlbase=https://dev.azure.com/git-for-windows/git/_apis/build/builds - id=$(curl "$urlbase?definitions=22&statusFilter=completed&resultFilter=succeeded&\$top=1" | - jq -r ".value[] | .id") - download_url="$(curl "$urlbase/$id/artifacts" | - jq -r '.value[] | select(.name == "git-sdk-64-minimal").resource.downloadUrl')" - curl --connect-timeout 10 --retry 5 --retry-delay 0 --retry-max-time 240 \ - -o artifacts.zip "$download_url" - - ## Unzip and remove the artifact - unzip artifacts.zip - rm artifacts.zip + - uses: actions/checkout@v2 + - uses: git-for-windows/setup-git-for-windows-sdk@v1 - name: build - shell: powershell + shell: bash env: HOME: ${{runner.workspace}} - MSYSTEM: MINGW64 NO_PERL: 1 - run: | - & .\git-sdk-64-minimal\usr\bin\bash.exe -lc @" - printf '%s\n' /git-sdk-64-minimal/ >>.git/info/exclude - - ci/make-test-artifacts.sh artifacts - "@ - - name: upload build artifacts - uses: actions/upload-artifact@v1 + 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 + uses: actions/upload-artifact@v2 with: name: windows-artifacts path: artifacts - - name: upload git-sdk-64-minimal - uses: actions/upload-artifact@v1 - with: - name: git-sdk-64-minimal - path: git-sdk-64-minimal windows-test: runs-on: windows-latest needs: [windows-build] @@ -127,37 +104,25 @@ jobs: matrix: nr: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] steps: - - uses: actions/checkout@v1 - - name: download build artifacts - uses: actions/download-artifact@v1 + - name: download tracked files and build artifacts + uses: actions/download-artifact@v2 with: name: windows-artifacts path: ${{github.workspace}} - - name: extract build artifacts + - name: extract tracked files and build artifacts shell: bash - run: tar xf artifacts.tar.gz - - name: download git-sdk-64-minimal - uses: actions/download-artifact@v1 - with: - name: git-sdk-64-minimal - path: ${{github.workspace}}/git-sdk-64-minimal/ + run: tar xf artifacts.tar.gz && tar xf tracked.tar.gz + - uses: git-for-windows/setup-git-for-windows-sdk@v1 - name: test - shell: powershell - run: | - & .\git-sdk-64-minimal\usr\bin\bash.exe -lc @" - # Let Git ignore the SDK - printf '%s\n' /git-sdk-64-minimal/ >>.git/info/exclude - - ci/run-test-slice.sh ${{matrix.nr}} 10 - "@ + shell: bash + run: ci/run-test-slice.sh ${{matrix.nr}} 10 - name: ci/print-test-failures.sh if: failure() - shell: powershell - run: | - & .\git-sdk-64-minimal\usr\bin\bash.exe -lc ci/print-test-failures.sh + shell: bash + run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v1 + uses: actions/upload-artifact@v2 with: name: failed-tests-windows path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -165,27 +130,12 @@ jobs: needs: ci-config if: needs.ci-config.outputs.enabled == 'yes' env: - MSYSTEM: MINGW64 NO_PERL: 1 GIT_CONFIG_PARAMETERS: "'user.name=CI' 'user.email=ci@git'" runs-on: windows-latest steps: - - uses: actions/checkout@v1 - - name: download git-sdk-64-minimal - shell: bash - run: | - ## Get artifact - urlbase=https://dev.azure.com/git-for-windows/git/_apis/build/builds - id=$(curl "$urlbase?definitions=22&statusFilter=completed&resultFilter=succeeded&\$top=1" | - jq -r ".value[] | .id") - download_url="$(curl "$urlbase/$id/artifacts" | - jq -r '.value[] | select(.name == "git-sdk-64-minimal").resource.downloadUrl')" - curl --connect-timeout 10 --retry 5 --retry-delay 0 --retry-max-time 240 \ - -o artifacts.zip "$download_url" - - ## Unzip and remove the artifact - unzip artifacts.zip - rm artifacts.zip + - uses: actions/checkout@v2 + - uses: git-for-windows/setup-git-for-windows-sdk@v1 - name: initialize vcpkg uses: actions/checkout@v2 with: @@ -203,75 +153,60 @@ jobs: - name: add msbuild to PATH uses: microsoft/setup-msbuild@v1 - name: copy dlls to root - shell: powershell - run: | - & compat\vcbuild\vcpkg_copy_dlls.bat release - if (!$?) { exit(1) } + shell: cmd + run: compat\vcbuild\vcpkg_copy_dlls.bat release - name: generate Visual Studio solution shell: bash run: | cmake `pwd`/contrib/buildsystems/ -DCMAKE_PREFIX_PATH=`pwd`/compat/vcbuild/vcpkg/installed/x64-windows \ - -DMSGFMT_EXE=`pwd`/git-sdk-64-minimal/mingw64/bin/msgfmt.exe -DPERL_TESTS=OFF -DPYTHON_TESTS=OFF -DCURL_NO_CURL_CMAKE=ON + -DNO_GETTEXT=YesPlease -DPERL_TESTS=OFF -DPYTHON_TESTS=OFF -DCURL_NO_CURL_CMAKE=ON - name: MSBuild run: msbuild git.sln -property:Configuration=Release -property:Platform=x64 -maxCpuCount:4 -property:PlatformToolset=v142 - name: bundle artifact tar - shell: powershell + shell: bash env: MSVC: 1 VCPKG_ROOT: ${{github.workspace}}\compat\vcbuild\vcpkg run: | - & git-sdk-64-minimal\usr\bin\bash.exe -lc @" - mkdir -p artifacts && - eval \"`$(make -n artifacts-tar INCLUDE_DLLS_IN_ARTIFACTS=YesPlease ARTIFACTS_DIRECTORY=artifacts 2>&1 | grep ^tar)\" - "@ - - name: upload build artifacts - uses: actions/upload-artifact@v1 + mkdir -p artifacts && + eval "$(make -n artifacts-tar INCLUDE_DLLS_IN_ARTIFACTS=YesPlease ARTIFACTS_DIRECTORY=artifacts NO_GETTEXT=YesPlease 2>&1 | grep ^tar)" + - name: zip up tracked files + run: git archive -o artifacts/tracked.tar.gz HEAD + - name: upload tracked files and build artifacts + uses: actions/upload-artifact@v2 with: name: vs-artifacts path: artifacts vs-test: runs-on: windows-latest - needs: [vs-build, windows-build] + needs: vs-build strategy: fail-fast: false matrix: nr: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] steps: - - uses: actions/checkout@v1 - - name: download git-sdk-64-minimal - uses: actions/download-artifact@v1 - with: - name: git-sdk-64-minimal - path: ${{github.workspace}}/git-sdk-64-minimal/ - - name: download build artifacts - uses: actions/download-artifact@v1 + - uses: git-for-windows/setup-git-for-windows-sdk@v1 + - name: download tracked files and build artifacts + uses: actions/download-artifact@v2 with: name: vs-artifacts path: ${{github.workspace}} - - name: extract build artifacts + - name: extract tracked files and build artifacts shell: bash - run: tar xf artifacts.tar.gz + run: tar xf artifacts.tar.gz && tar xf tracked.tar.gz - name: test - shell: powershell + shell: bash env: - MSYSTEM: MINGW64 NO_SVN_TESTS: 1 GIT_TEST_SKIP_REBASE_P: 1 - run: | - & .\git-sdk-64-minimal\usr\bin\bash.exe -lc @" - # Let Git ignore the SDK and the test-cache - printf '%s\n' /git-sdk-64-minimal/ /test-cache/ >>.git/info/exclude - - 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: powershell - run: | - & .\git-sdk-64-minimal\usr\bin\bash.exe -lc ci/print-test-failures.sh + shell: bash + run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v1 + uses: actions/upload-artifact@v2 with: name: failed-tests-windows path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -302,14 +237,14 @@ jobs: jobname: ${{matrix.vector.jobname}} runs-on: ${{matrix.vector.pool}} steps: - - uses: actions/checkout@v1 + - uses: actions/checkout@v2 - run: ci/install-dependencies.sh - run: ci/run-build-and-tests.sh - run: ci/print-test-failures.sh if: failure() - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v1 + uses: actions/upload-artifact@v2 with: name: failed-tests-${{matrix.vector.jobname}} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -336,7 +271,7 @@ jobs: if: failure() - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v1 + uses: actions/upload-artifact@v2 with: name: failed-tests-${{matrix.vector.jobname}} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -347,9 +282,29 @@ jobs: jobname: StaticAnalysis runs-on: ubuntu-18.04 steps: - - uses: actions/checkout@v1 + - uses: actions/checkout@v2 - run: ci/install-dependencies.sh - run: ci/run-static-analysis.sh + sparse: + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + env: + jobname: sparse + runs-on: ubuntu-20.04 + steps: + - name: Download a current `sparse` package + # Ubuntu's `sparse` version is too old for us + uses: git-for-windows/get-azure-pipelines-artifact@v0 + with: + repository: git/git + definitionId: 10 + artifact: sparse-20.04 + - name: Install the current `sparse` package + run: sudo dpkg -i sparse-20.04/sparse_*.deb + - uses: actions/checkout@v2 + - name: Install other dependencies + run: ci/install-dependencies.sh + - run: make sparse documentation: needs: ci-config if: needs.ci-config.outputs.enabled == 'yes' @@ -357,6 +312,6 @@ jobs: jobname: Documentation runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 + - uses: actions/checkout@v2 - run: ci/install-dependencies.sh - run: ci/test-documentation.sh diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index e3af089ecf..711cb9171e 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -551,6 +551,51 @@ Writing Documentation: documentation, please see the documentation-related advice in the Documentation/SubmittingPatches file). + In order to ensure the documentation is inclusive, avoid assuming + that an unspecified example person is male or female, and think + twice before using "he", "him", "she", or "her". Here are some + tips to avoid use of gendered pronouns: + + - Prefer succinctness and matter-of-factly describing functionality + in the abstract. E.g. + + --short:: Emit output in the short-format. + + and avoid something like these overly verbose alternatives: + + --short:: Use this to emit output in the short-format. + --short:: You can use this to get output in the short-format. + --short:: A user who prefers shorter output could.... + --short:: Should a person and/or program want shorter output, he + she/they/it can... + + This practice often eliminates the need to involve human actors in + your description, but it is a good practice regardless of the + avoidance of gendered pronouns. + + - When it becomes awkward to stick to this style, prefer "you" when + addressing the the hypothetical user, and possibly "we" when + discussing how the program might react to the user. E.g. + + You can use this option instead of --xyz, but we might remove + support for it in future versions. + + while keeping in mind that you can probably be less verbose, e.g. + + Use this instead of --xyz. This option might be removed in future + versions. + + - If you still need to refer to an example person that is + third-person singular, you may resort to "singular they" to avoid + "he/she/him/her", e.g. + + A contributor asks their upstream to pull from them. + + Note that this sounds ungrammatical and unnatural to those who + learned that "they" is only used for third-person plural, e.g. + those who learn English as a second language in some parts of the + world. + Every user-visible change should be reflected in the documentation. The same general rule as for code applies -- imitate the existing conventions. diff --git a/Documentation/Makefile b/Documentation/Makefile index 2aae4c9cbb..f5605b7767 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -139,6 +139,7 @@ ASCIIDOC_CONF = -f asciidoc.conf ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ -amanversion=$(GIT_VERSION) \ -amanmanual='Git Manual' -amansource='Git' +ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) MANPAGE_XSL = manpage-normal.xsl @@ -193,6 +194,7 @@ ASCIIDOC_DOCBOOK = docbook5 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' +ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation XMLTO_EXTRA += -x manpage.xsl @@ -294,9 +296,7 @@ docdep_prereqs = \ cmd-list.made $(cmds_txt) doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl - $(QUIET_GEN)$(RM) $@+ $@ && \ - $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \ - mv $@+ $@ + $(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR) ifneq ($(MAKECMDGOALS),clean) -include doc.dep @@ -316,8 +316,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) - $(QUIET_GEN)$(RM) $@ && \ - $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \ + $(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \ date >$@ mergetools_txt = mergetools-diff.txt mergetools-merge.txt @@ -325,7 +324,7 @@ mergetools_txt = mergetools-diff.txt mergetools-merge.txt $(mergetools_txt): mergetools-list.made mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) - $(QUIET_GEN)$(RM) $@ && \ + $(QUIET_GEN) \ $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && \ . ../git-mergetool--lib.sh && \ show_tool_names can_diff "* " || :' >mergetools-diff.txt && \ @@ -354,32 +353,23 @@ clean: $(RM) manpage-base-url.xsl $(RM) GIT-ASCIIDOCFLAGS -$(MAN_HTML): %.html : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_HTML) -d manpage -o $@+ $< && \ - mv $@+ $@ +$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $< -$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_HTML) -o $@+ $< && \ - mv $@+ $@ +$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $< manpage-base-url.xsl: manpage-base-url.xsl.in $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl) - $(QUIET_XMLTO)$(RM) $@ && \ - $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< -%.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_XML) -d manpage -o $@+ $< && \ - mv $@+ $@ +%.xml : %.txt $(ASCIIDOC_DEPS) + $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $< user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ - $(TXT_TO_XML) -d book -o $@+ $< && \ - mv $@+ $@ + $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $< technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) @@ -400,46 +390,35 @@ XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css XSLTOPTS += --param generate.consistent.ids 1 user-manual.html: user-manual.xml $(XSLT) - $(QUIET_XSLTPROC)$(RM) $@+ $@ && \ - xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \ - mv $@+ $@ + $(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< git.info: user-manual.texi $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi user-manual.texi: user-manual.xml - $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ - $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \ - $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \ - rm $@++ && \ - mv $@+ $@ + $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \ + $(PERL_PATH) fix-texi.perl <$@+ >$@ && \ + $(RM) $@+ user-manual.pdf: user-manual.xml - $(QUIET_DBLATEX)$(RM) $@+ $@ && \ - $(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \ - mv $@+ $@ + $(QUIET_DBLATEX)$(DBLATEX) -o $@ $(DBLATEX_COMMON) $< gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl - $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + $(QUIET_DB2TEXI) \ ($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \ $(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \ - rm $(xml)+ &&) true) > $@++ && \ - $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \ - rm $@++ && \ - mv $@+ $@ + $(RM) $(xml)+ &&) true) > $@+ && \ + $(PERL_PATH) cat-texi.perl $@ <$@+ >$@ && \ + $(RM) $@+ gitman.info: gitman.texi $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml - $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ - $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \ - mv $@+ $@ + $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@ howto-index.txt: howto-index.sh $(HOWTO_TXT) - $(QUIET_GEN)$(RM) $@+ $@ && \ - '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \ - mv $@+ $@ + $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt @@ -448,10 +427,9 @@ WEBDOC_DEST = /pub/software/scm/git/docs howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS - $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(QUIET_ASCIIDOC) \ sed -e '1,/^$$/d' $< | \ - $(TXT_TO_HTML) - >$@+ && \ - mv $@+ $@ + $(TXT_TO_HTML) - >$@ install-webdoc : html '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST) @@ -492,4 +470,7 @@ doc-l10n install-l10n:: $(MAKE) -C po $@ endif +# Delete the target file on error +.DELETE_ON_ERROR: + .PHONY: FORCE diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index af0a9da62e..015cf24631 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -47,7 +47,7 @@ Veteran contributors who are especially interested in helping mentor newcomers are present on the list. In order to avoid search indexers, group membership is required to view messages; anyone can join and no approval is required. -==== https://webchat.freenode.net/#git-devel[#git-devel] on Freenode +==== https://web.libera.chat/#git-devel[#git-devel] on Libera Chat This IRC channel is for conversations between Git contributors. If someone is currently online and knows the answer to your question, you can receive help @@ -827,7 +827,7 @@ either examining recent pull requests where someone has been granted `/allow` (https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search: is:pr is:open "/allow"]), in which case both the author and the person who granted the `/allow` can now `/allow` you, or by inquiring on the -https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode +https://web.libera.chat/#git-devel[#git-devel] IRC channel on Libera Chat linking your pull request and asking for someone to `/allow` you. If the CI fails, you can update your changes with `git rebase -i` and push your diff --git a/Documentation/RelNotes/1.6.0.3.txt b/Documentation/RelNotes/1.6.0.3.txt index ae0577836a..ad36c0f0b7 100644 --- a/Documentation/RelNotes/1.6.0.3.txt +++ b/Documentation/RelNotes/1.6.0.3.txt @@ -50,7 +50,7 @@ Fixes since v1.6.0.2 if the working tree is currently dirty. * "git for-each-ref --format=%(subject)" fixed for commits with no - no newline in the message body. + newline in the message body. * "git remote" fixed to protect printf from user input. diff --git a/Documentation/RelNotes/1.8.4.txt b/Documentation/RelNotes/1.8.4.txt index 255e185af6..2e7529928b 100644 --- a/Documentation/RelNotes/1.8.4.txt +++ b/Documentation/RelNotes/1.8.4.txt @@ -365,7 +365,7 @@ details). (merge 2fbd4f9 mh/maint-lockfile-overflow later to maint). * Invocations of "git checkout" used internally by "git rebase" were - counted as "checkout", and affected later "git checkout -" to the + counted as "checkout", and affected later "git checkout -", which took the user to an unexpected place. (merge 3bed291 rr/rebase-checkout-reflog later to maint). diff --git a/Documentation/RelNotes/2.29.0.txt b/Documentation/RelNotes/2.29.0.txt index 06ba2f803f..1f41302ebb 100644 --- a/Documentation/RelNotes/2.29.0.txt +++ b/Documentation/RelNotes/2.29.0.txt @@ -184,8 +184,8 @@ Performance, Internal Implementation, Development Support etc. the ref backend in use, as its format is much richer than the normal refs, and written directly by "git fetch" as a plain file.. - * An unused binary has been discarded, and and a bunch of commands - have been turned into into built-in. + * An unused binary has been discarded, and a bunch of commands + have been turned into built-in. * A handful of places in in-tree code still relied on being able to execute the git subcommands, especially built-ins, in "git-foo" diff --git a/Documentation/RelNotes/2.32.0.txt b/Documentation/RelNotes/2.32.0.txt index b47d569dc9..87d56fa1aa 100644 --- a/Documentation/RelNotes/2.32.0.txt +++ b/Documentation/RelNotes/2.32.0.txt @@ -47,11 +47,6 @@ UI, Workflows & Features tweak both the message and the contents, and only the message, respectively. - * When accessing a server with a URL like https://user:pass@site/, we - did not to fall back to the basic authentication with the - credential material embedded in the URL after the "Negotiate" - authentication failed. Now we do. - * "git send-email" learned to honor the core.hooksPath configuration. * "git format-patch -v" learned to allow a reroll count that is @@ -371,6 +366,30 @@ Fixes since v2.31 empty directories under $GIT_DIR/refs/ for (merge 5f03e5126d wc/packed-ref-removal-cleanup later to maint). + * "git clean" and "git ls-files -i" had confusion around working on + or showing ignored paths inside an ignored directory, which has + been corrected. + (merge b548f0f156 en/dir-traversal later to maint). + + * The handling of "%(push)" formatting element of "for-each-ref" and + friends was broken when the same codepath started handling + "%(push:)", which has been corrected. + (merge 1e1c4c5eac zh/ref-filter-push-remote-fix later to maint). + + * The bash prompt script (in contrib/) did not work under "set -u". + (merge 5c0cbdb107 en/prompt-under-set-u later to maint). + + * The "chainlint" feature in the test framework is a handy way to + catch common mistakes in writing new tests, but tends to get + expensive. An knob to selectively disable it has been introduced + to help running tests that the developer has not modified. + (merge 2d86a96220 jk/test-chainlint-softer later to maint). + + * The "rev-parse" command did not diagnose the lack of argument to + "--path-format" option, which was introduced in v2.31 era, which + has been corrected. + (merge 99fc555188 wm/rev-parse-path-format-wo-arg later to maint). + * Other code cleanup, docfix, build fix, etc. (merge f451960708 dl/cat-file-doc-cleanup later to maint). (merge 12604a8d0c sv/t9801-test-path-is-file-cleanup later to maint). diff --git a/Documentation/RelNotes/2.33.0.txt b/Documentation/RelNotes/2.33.0.txt new file mode 100644 index 0000000000..7960c4f7ab --- /dev/null +++ b/Documentation/RelNotes/2.33.0.txt @@ -0,0 +1,280 @@ +Git 2.33 Release Notes +====================== + +Backward compatibility notes +---------------------------- + + * The "-m" option in "git log -m" that does not specify which format, + if any, of diff is desired did not have any visible effect; it now + implies some form of diff (by default "--patch") is produced. + + You can disable the diff output with "git log -m --no-patch", but + then there probably isn't much point in passing "-m" in the first + place ;-). + + +Updates since Git 2.32 +---------------------- + +UI, Workflows & Features + + * "git send-email" learned the "--sendmail-cmd" command line option + and the "sendemail.sendmailCmd" configuration variable, which is a + more sensible approach than the current way of repurposing the + "smtp-server" that is meant to name the server to instead name the + command to talk to the server. + + * The "-m" option in "git log -m" that does not specify which format, + if any, of diff is desired did not have any visible effect; it now + implies some form of diff (by default "--patch") is produced. + + * The userdiff pattern for C# learned the token "record". + + * "git rev-list" learns to omit the "commit " header + lines from the output with the `--no-commit-header` option. + + * "git worktree add --lock" learned to record why the worktree is + locked with a custom message. + + +Performance, Internal Implementation, Development Support etc. + + * The code to handle the "--format" option in "for-each-ref" and + friends made too many string comparisons on %(atom)s used in the + format string, which has been corrected by converting them into + enum when the format string is parsed. + + * Use the hashfile API in the codepath that writes the index file to + reduce code duplication. + + * Repeated rename detections in a sequence of mergy operations have + been optimize out. + + * Preliminary clean-up of tests before the main reftable changes + hits the codebase. + + * The backend for "diff -G/-S" has been updated to use pcre2 engine + when available. + + * Use ".DELETE_ON_ERROR" pseudo target to simplify our Makefile. + + * Code cleanup around struct_type_init() functions. + + * "git send-email" optimization. + + * GitHub Actions / CI update. + (merge 0dc787a9f2 js/ci-windows-update later to maint). + + * Object accesses in repositories with many alternate object store + have been optimized. + + * "git log" has been optimized not to waste cycles to load ref + decoration data that may not be needed. + + * Many "printf"-like helper functions we have have been annotated + with __attribute__() to catch placeholder/parameter mismatches. + + * Tests that cover protocol bits have been updated and helpers + used there have been consolidated. + + * The CI gained a new job to run "make sparse" check. + + * "git status" codepath learned to work with sparsely populated index + without hydrating it fully. + + * A guideline for gender neutral documentation has been added. + + * Documentation on "git diff -l" and diff.renameLimit have been + updated, and the defaults for these limits have been raised. + + * The completion support used to offer alternate spelling of options + that exist only for compatibility, which has been corrected. + + * "TEST_OUTPUT_DIRECTORY=there make test" failed to work, which has + been corrected. + + * "git bundle" gained more test coverage. + + * "git read-tree" had a codepath where blobs are fetched one-by-one + from the promisor remote, which has been corrected to fetch in bulk. + + +Fixes since v2.32 +----------------- + + * We historically rejected a very short string as an author name + while accepting a patch e-mail, which has been loosened. + (merge 72ee47ceeb ef/mailinfo-short-name later to maint). + + * The parallel checkout codepath did not initialize object ID field + used to talk to the worker processes in a futureproof way. + + * Rewrite code that triggers undefined behaviour warning. + (merge aafa5df0df jn/size-t-casted-to-off-t-fix later to maint). + + * The description of "fast-forward" in the glossary has been updated. + (merge e22f2daed0 ry/clarify-fast-forward-in-glossary later to maint). + + * Recent "git clone" left a temporary directory behind when the + transport layer returned an failure. + (merge 6aacb7d861 jk/clone-clean-upon-transport-error later to maint). + + * "git fetch" over protocol v2 left its side of the socket open after + it finished speaking, which unnecessarily wasted the resource on + the other side. + (merge ae1a7eefff jk/fetch-pack-v2-half-close-early later to maint). + + * The command line completion (in contrib/) learned that "git diff" + takes the "--anchored" option. + (merge d1e7c2cac9 tb/complete-diff-anchored later to maint). + + * "git-svn" tests assumed that "locale -a", which is used to pick an + available UTF-8 locale, is available everywhere. A knob has been + introduced to allow testers to specify a suitable locale to use. + (merge 482c962de4 dd/svn-test-wo-locale-a later to maint). + + * Update "git subtree" to work better on Windows. + (merge 77f37de39f js/subtree-on-windows-fix later to maint). + + * Remove multimail from contrib/ + (merge f74d11471f js/no-more-multimail later to maint). + + * Make the codebase MSAN clean. + (merge 4dbc55e87d ah/uninitialized-reads-fix later to maint). + + * Work around inefficient glob substitution in older versions of bash + by rewriting parts of a test. + (merge eb87c6f559 jx/t6020-with-older-bash later to maint). + + * Avoid duplicated work while building reachability bitmaps. + (merge aa9ad6fee5 jk/bitmap-tree-optim later to maint). + + * We broke "GIT_SKIP_TESTS=t?000" to skip certain tests in recent + update, which got fixed. + + * The side-band demultiplexer that is used to display progress output + from the remote end did not clear the line properly when the end of + line hits at a packet boundary, which has been corrected. + + * Some test scripts assumed that readlink(1) was universally + installed and available, which is not the case. + (merge 7c0afdf23c jk/test-without-readlink-1 later to maint). + + * Recent update to completion script (in contrib/) broke those who + use the __git_complete helper to define completion to their custom + command. + (merge cea232194d fw/complete-cmd-idx-fix later to maint). + + * Output from some of our tests were affected by the width of the + terminal that they were run in, which has been corrected by + exporting a fixed value in the COLUMNS environment. + (merge c49a177bec ab/fix-columns-to-80-during-tests later to maint). + + * On Windows, mergetool has been taught to find kdiff3.exe just like + it finds winmerge.exe. + (merge 47eb4c6890 ms/mergetools-kdiff3-on-windows later to maint). + + * When we cannot figure out how wide the terminal is, we use a + fallback value of 80 ourselves (which cannot be avoided), but when + we run the pager, we export it in COLUMNS, which forces the pager + to use the hardcoded value, even when the pager is perfectly + capable to figure it out itself. Stop exporting COLUMNS when we + fall back on the hardcoded default value for our own use. + (merge 9b6e2c8b98 js/stop-exporting-bogus-columns later to maint). + + * "git cat-file --batch-all-objects"" misbehaved when "--batch" is in + use and did not ask for certain object traits. + (merge ee02ac6164 zh/cat-file-batch-fix later to maint). + + * Some code and doc clarification around "git push". + + * The "union" conflict resultion variant misbehaved when used with + binary merge driver. + (merge 382b601acd jk/union-merge-binary later to maint). + + * Prevent "git p4" from failing to submit changes to binary file. + (merge 54662d5958 dc/p4-binary-submit-fix later to maint). + + * "git grep --and -e foo" ought to have been diagnosed as an error + but instead segfaulted, which has been corrected. + (merge fe7fe62d8d rs/grep-parser-fix later to maint). + + * The merge code had funny interactions between content based rename + detection and directory rename detection. + (merge 3585d0ea23 en/merge-dir-rename-corner-case-fix later to maint). + + * When rebuilding the multi-pack index file reusing an existing one, + we used to blindly trust the existing file and ended up carrying + corrupted data into the updated file, which has been corrected. + (merge f89ecf7988 tb/midx-use-checksum later to maint). + + * Update the location of system-side configuration file on Windows. + (merge e355307692 js/gfw-system-config-loc-fix later to maint). + + * Code recently added to support common ancestry negotiation during + "git push" did not sanity check its arguments carefully enough. + (merge eff40457a4 ab/fetch-negotiate-segv-fix later to maint). + + * Update the documentation not to assume users are of certain gender + and adds to guidelines to do so. + (merge 46a237f42f ds/gender-neutral-doc later to maint). + + * "git commit --allow-empty-message" won't abort the operation upon + an empty message, but the hint shown in the editor said otherwise. + (merge 6f70f00b4f hj/commit-allow-empty-message later to maint). + + * The code that gives an error message in "git multi-pack-index" when + no subcommand is given tried to print a NULL pointer as a strong, + which has been corrected. + (merge 88617d11f9 tb/reverse-midx later to maint). + + * CI update. + (merge a066a90db6 js/ci-check-whitespace-updates later to maint). + + * Documentation fix for "git pull --rebase=no". + (merge d3236becec fc/pull-no-rebase-merges-theirs-into-ours later to maint). + + * A race between repacking and using pack bitmaps has been corrected. + (merge dc1daacdcc jk/check-pack-valid-before-opening-bitmap later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge bfe35a6165 ah/doc-describe later to maint). + (merge f302c1e4aa jc/clarify-revision-range later to maint). + (merge 3127ff90ea tl/fix-packfile-uri-doc later to maint). + (merge a84216c684 jk/doc-color-pager later to maint). + (merge 4e0a64a713 ab/trace2-squelch-gcc-warning later to maint). + (merge 225f7fa847 ps/rev-list-object-type-filter later to maint). + (merge 5317dfeaed dd/honor-users-tar-in-tests later to maint). + (merge ace6d8e3d6 tk/partial-clone-repack-doc later to maint). + (merge 7ba68e0cf1 js/trace2-discard-event-docfix later to maint). + (merge 8603c419d3 fc/doc-default-to-upstream-config later to maint). + (merge 1d72b604ef jk/revision-squelch-gcc-warning later to maint). + (merge abcb66c614 ar/typofix later to maint). + (merge 9853830787 ah/graph-typofix later to maint). + (merge aac578492d ab/config-hooks-path-testfix later to maint). + (merge 98c7656a18 ar/more-typofix later to maint). + (merge 6fb9195f6c jk/doc-max-pack-size later to maint). + (merge 4184cbd635 ar/mailinfo-memcmp-to-skip-prefix later to maint). + (merge 91d2347033 ar/doc-libera-chat-in-my-first-contrib later to maint). + (merge 338abb0f04 ab/cmd-foo-should-return later to maint). + (merge 546096a5cb ab/xdiff-bug-cleanup later to maint). + (merge b7b793d1e7 ab/progress-cleanup later to maint). + (merge d94f9b8e90 ba/object-info later to maint). + (merge 52ff891c03 ar/test-code-cleanup later to maint). + (merge a0538e5c8b dd/document-log-decorate-default later to maint). + (merge ce24797d38 mr/cmake later to maint). + (merge 9eb542f2ee ab/pre-auto-gc-hook-test later to maint). + (merge 9fffc38583 bk/doc-commit-typofix later to maint). + (merge 1cf823d8f0 ks/submodule-cleanup later to maint). + (merge ebbf5d2b70 js/config-mak-windows-pcre-fix later to maint). + (merge 617480d75b hn/refs-iterator-peel-returns-boolean later to maint). + (merge 6a24cc71ed ar/submodule-helper-include-cleanup later to maint). + (merge 5632e838f8 rs/khash-alloc-cleanup later to maint). + (merge b1d87fbaf1 jk/typofix later to maint). + (merge e04170697a ab/gitignore-discovery-doc later to maint). + (merge 8232a0ff48 dl/packet-read-response-end-fix later to maint). + (merge eb448631fb dl/diff-merge-base later to maint). + (merge c510928a25 hn/refs-debug-empty-prefix later to maint). + (merge ddcb189d9d tb/bitmap-type-filter-comment-fix later to maint). + (merge 878b399734 pb/submodule-recurse-doc later to maint). + (merge 734283855f jk/config-env-doc later to maint). diff --git a/Documentation/RelNotes/2.8.0.txt b/Documentation/RelNotes/2.8.0.txt index 27320b6a9f..38453281b8 100644 --- a/Documentation/RelNotes/2.8.0.txt +++ b/Documentation/RelNotes/2.8.0.txt @@ -377,7 +377,7 @@ notes for details). on that order. * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a - rev, i.e. the object named by the the pathname with wildcard + rev, i.e. the object named by the pathname with wildcard characters in a tree object. (merge aac4fac nd/dwim-wildcards-as-pathspecs later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 55287d72e0..3e215f4d80 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -373,9 +373,8 @@ If you like, you can put extra tags at the end: . `Acked-by:` says that the person who is more familiar with the area the patch attempts to modify liked the patch. . `Reviewed-by:`, unlike the other tags, can only be offered by the - reviewer and means that she is completely satisfied that the patch - is ready for application. It is usually offered only after a - detailed review. + reviewers themselves when they are completely satisfied with the + patch after a detailed analysis. . `Tested-by:` is used to indicate that the person applied the patch and found it to have the desired effect. diff --git a/Documentation/config/blame.txt b/Documentation/config/blame.txt index 9468e8599c..4d047c1790 100644 --- a/Documentation/config/blame.txt +++ b/Documentation/config/blame.txt @@ -27,7 +27,7 @@ blame.ignoreRevsFile:: file names will reset the list of ignored revisions. This option will be handled before the command line option `--ignore-revs-file`. -blame.markUnblamables:: +blame.markUnblamableLines:: Mark lines that were changed by an ignored revision that we could not attribute to another commit with a '*' in the output of linkgit:git-blame[1]. diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt index d5daacb13a..e05d520a86 100644 --- a/Documentation/config/color.txt +++ b/Documentation/config/color.txt @@ -127,8 +127,9 @@ color.interactive.:: interactive commands. color.pager:: - A boolean to enable/disable colored output when the pager is in - use (default is true). + A boolean to specify whether `auto` color modes should colorize + output going to the pager. Defaults to true; set this to false + if your pager does not understand ANSI color codes. color.push:: A boolean to enable/disable color in push errors. May be set to diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 2d3331f55c..32f84838ac 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -118,9 +118,10 @@ diff.orderFile:: relative to the top of the working tree. diff.renameLimit:: - The number of files to consider when performing the copy/rename - detection; equivalent to the 'git diff' option `-l`. This setting - has no effect if rename detection is turned off. + The number of files to consider in the exhaustive portion of + copy/rename detection; equivalent to the 'git diff' option + `-l`. If not set, the default value is currently 1000. This + setting has no effect if rename detection is turned off. diff.renames:: Whether and how Git detects renames. If set to "false", diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index 6af6f5edb2..63748c02b7 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -69,7 +69,8 @@ fetch.negotiationAlgorithm:: setting defaults to "skipping". Unknown values will cause 'git fetch' to error out. + -See also the `--negotiation-tip` option for linkgit:git-fetch[1]. +See also the `--negotiate-only` and `--negotiation-tip` options to +linkgit:git-fetch[1]. fetch.showForcedUpdates:: Set to false to enable `--no-show-forced-updates` in diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index cb2ed58907..e27cc63944 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -14,7 +14,7 @@ merge.defaultToUpstream:: branches at the remote named by `branch..remote` are consulted, and then they are mapped via `remote..fetch` to their corresponding remote-tracking branches, and the tips of - these tracking branches are merged. + these tracking branches are merged. Defaults to true. merge.ff:: By default, Git does not create an extra merge commit when merging @@ -33,10 +33,12 @@ merge.verifySignatures:: include::fmt-merge-msg.txt[] merge.renameLimit:: - The number of files to consider when performing rename detection - during a merge; if not specified, defaults to the value of - diff.renameLimit. This setting has no effect if rename detection - is turned off. + The number of files to consider in the exhaustive portion of + rename detection during a merge. If not specified, defaults + to the value of diff.renameLimit. If neither + merge.renameLimit nor diff.renameLimit are specified, + currently defaults to 7000. This setting has no effect if + rename detection is turned off. merge.renames:: Whether Git detects renames. If set to "false", rename detection diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index c0844d8d8e..763f7af7c4 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -99,12 +99,23 @@ pack.packSizeLimit:: packing to a file when repacking, i.e. the git:// protocol is unaffected. It can be overridden by the `--max-pack-size` option of linkgit:git-repack[1]. Reaching this limit results - in the creation of multiple packfiles; which in turn prevents - bitmaps from being created. - The minimum size allowed is limited to 1 MiB. - The default is unlimited. - Common unit suffixes of 'k', 'm', or 'g' are - supported. + in the creation of multiple packfiles. ++ +Note that this option is rarely useful, and may result in a larger total +on-disk size (because Git will not store deltas between packs), as well +as worse runtime performance (object lookup within multiple packs is +slower than a single pack, and optimizations like reachability bitmaps +cannot cope with multiple packs). ++ +If you need to actively run Git using smaller packfiles (e.g., because your +filesystem does not support large files), this option may help. But if +your goal is to transmit a packfile over a medium that supports limited +sizes (e.g., removable media that cannot store the whole repository), +you are likely better off creating a single large packfile and splitting +it using a generic multi-volume archive tool (e.g., Unix `split`). ++ +The minimum size allowed is limited to 1 MiB. The default is unlimited. +Common unit suffixes of 'k', 'm', or 'g' are supported. pack.useBitmaps:: When true, git will use pack bitmaps (if available) when packing diff --git a/Documentation/config/push.txt b/Documentation/config/push.txt index f2667b2689..632033638c 100644 --- a/Documentation/config/push.txt +++ b/Documentation/config/push.txt @@ -24,15 +24,14 @@ push.default:: * `tracking` - This is a deprecated synonym for `upstream`. -* `simple` - in centralized workflow, work like `upstream` with an - added safety to refuse to push if the upstream branch's name is - different from the local one. +* `simple` - pushes the current branch with the same name on the remote. + -When pushing to a remote that is different from the remote you normally -pull from, work as `current`. This is the safest option and is suited -for beginners. +If you are working on a centralized workflow (pushing to the same repository you +pull from, which is typically `origin`), then you need to configure an upstream +branch with the same name. + -This mode has become the default in Git 2.0. +This mode is the default since Git 2.0, and is the safest option suited for +beginners. * `matching` - push all branches having the same name on both ends. This makes the repository you are pushing to remember the set of diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt index cbc5af42fd..50baa5d6bf 100644 --- a/Documentation/config/sendemail.txt +++ b/Documentation/config/sendemail.txt @@ -8,9 +8,6 @@ sendemail.smtpEncryption:: See linkgit:git-send-email[1] for description. Note that this setting is not subject to the 'identity' mechanism. -sendemail.smtpssl (deprecated):: - Deprecated alias for 'sendemail.smtpEncryption = ssl'. - sendemail.smtpsslcertpath:: Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification. diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt index 413f907cba..9ed775281f 100644 --- a/Documentation/config/stash.txt +++ b/Documentation/config/stash.txt @@ -6,9 +6,9 @@ stash.useBuiltin:: remaining users that setting this now does nothing. stash.showIncludeUntracked:: - If this is set to true, the `git stash show` command without an - option will show the untracked files of a stash entry. Defaults to - false. See description of 'show' command in linkgit:git-stash[1]. + If this is set to true, the `git stash show` command will show + the untracked files of a stash entry. Defaults to false. See + description of 'show' command in linkgit:git-stash[1]. stash.showPatch:: If this is set to true, the `git stash show` command without an diff --git a/Documentation/config/submodule.txt b/Documentation/config/submodule.txt index d7a63c8c12..ee454f8126 100644 --- a/Documentation/config/submodule.txt +++ b/Documentation/config/submodule.txt @@ -58,8 +58,9 @@ submodule.active:: commands. See linkgit:gitsubmodules[7] for details. submodule.recurse:: - Specifies if commands recurse into submodules by default. This - applies to all commands that have a `--recurse-submodules` option + A boolean indicating if commands should enable the `--recurse-submodules` + option by default. + Applies to all commands that support this option (`checkout`, `fetch`, `grep`, `pull`, `push`, `read-tree`, `reset`, `restore` and `switch`) except `clone` and `ls-files`. Defaults to false. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 530d115914..0aebe83205 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -49,10 +49,9 @@ ifdef::git-log[] --diff-merges=m::: -m::: This option makes diff output for merge commits to be shown in - the default format. `-m` will produce the output only if `-p` - is given as well. The default format could be changed using + the default format. The default format could be changed using `log.diffMerges` configuration parameter, which default value - is `separate`. + is `separate`. `-m` implies `-p`. + --diff-merges=first-parent::: --diff-merges=1::: @@ -62,7 +61,8 @@ ifdef::git-log[] --diff-merges=separate::: This makes merge commits show the full diff with respect to each of the parents. Separate log entry and diff is generated - for each parent. + for each parent. This is the format that `-m` produced + historically. + --diff-merges=combined::: --diff-merges=c::: @@ -588,11 +588,17 @@ When used together with `-B`, omit also the preimage in the deletion part of a delete/create pair. -l:: - The `-M` and `-C` options require O(n^2) processing time where n - is the number of potential rename/copy targets. This - option prevents rename/copy detection from running if - the number of rename/copy targets exceeds the specified - number. + The `-M` and `-C` options involve some preliminary steps that + can detect subsets of renames/copies cheaply, followed by an + exhaustive fallback portion that compares all remaining + unpaired destinations to all relevant sources. (For renames, + only remaining unpaired sources are relevant; for copies, all + original sources are relevant.) For N sources and + destinations, this exhaustive check is O(N^2). This option + prevents the exhaustive portion of rename/copy detection from + running if the number of source/destination files involved + exceeds the specified number. Defaults to diff.renameLimit. + Note that a value of 0 is treated as unlimited. ifndef::git-format-patch[] --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]:: diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 9e7b4e189c..e967ff1874 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -62,8 +62,17 @@ The argument to this option may be a glob on ref names, a ref, or the (possibly abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying this option multiple times, one for each matching ref name. + -See also the `fetch.negotiationAlgorithm` configuration variable -documented in linkgit:git-config[1]. +See also the `fetch.negotiationAlgorithm` and `push.negotiate` +configuration variables documented in linkgit:git-config[1], and the +`--negotiate-only` option below. + +--negotiate-only:: + Do not fetch anything from the server, and instead print the + ancestors of the provided `--negotiation-tip=*` arguments, + which we have in common with the server. ++ +Internally this is used to implement the `push.negotiate` option, see +linkgit:git-config[1]. --dry-run:: Show what would be done, without making any changes. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 340c5fbb48..95fec5f069 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -72,7 +72,7 @@ OPTIONS -p:: --patch:: - Use the interactive patch selection interface to chose + Use the interactive patch selection interface to choose which changes to commit. See linkgit:git-add[1] for details. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 5cddadafd2..2dc4bae6da 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -71,6 +71,7 @@ codes are: On success, the command returns the exit code 0. +[[OPTIONS]] OPTIONS ------- @@ -143,7 +144,13 @@ See also <>. -f config-file:: --file config-file:: - Use the given config file instead of the one specified by GIT_CONFIG. + For writing options: write to the specified file rather than the + repository `.git/config`. ++ +For reading options: read only from the specified file rather than from all +available files. ++ +See also <>. --blob blob:: Similar to `--file` but use the given blob instead of a file. E.g. @@ -325,21 +332,14 @@ All writing options will per default write to the repository specific configuration file. Note that this also affects options like `--replace-all` and `--unset`. *'git config' will only ever change one file at a time*. -You can override these rules either by command-line options or by environment -variables. The `--global`, `--system` and `--worktree` options will limit -the file used to the global, system-wide or per-worktree file respectively. -The `GIT_CONFIG` environment variable has a similar effect, but you -can specify any filename you want. +You can override these rules using the `--global`, `--system`, +`--local`, `--worktree`, and `--file` command-line options; see +<> above. ENVIRONMENT ----------- -GIT_CONFIG:: - Take the configuration from the given file instead of .git/config. - Using the "--global" option forces this to ~/.gitconfig. Using the - "--system" option forces this to $(prefix)/etc/gitconfig. - GIT_CONFIG_GLOBAL:: GIT_CONFIG_SYSTEM:: Take the configuration from the given files instead from global or @@ -367,6 +367,12 @@ This is useful for cases where you want to spawn multiple git commands with a common configuration but cannot depend on a configuration file, for example when writing scripts. +GIT_CONFIG:: + If no `--file` option is provided to `git config`, use the file + given by `GIT_CONFIG` as if it were provided via `--file`. This + variable has no effect on other Git commands, and is mostly for + historical compatibility; there is generally no reason to use it + instead of the `--file` option. [[EXAMPLES]] EXAMPLES diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index a88f6ae2c6..c6a79c2a0f 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -63,9 +63,10 @@ OPTIONS Automatically implies --tags. --abbrev=:: - Instead of using the default 7 hexadecimal digits as the - abbreviated object name, use digits, or as many digits - as needed to form a unique object name. An of 0 + Instead of using the default number of hexadecimal digits (which + will vary according to the number of objects in the repository with + a default of 7) of the abbreviated object name, use digits, or + as many digits as needed to form a unique object name. An of 0 will suppress long format, only showing the closest tag. --candidates=:: @@ -139,8 +140,11 @@ at the end. The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". -The hash suffix is "-g" + unambiguous abbreviation for the tip commit -of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). +The hash suffix is "-g" + an unambigous abbreviation for the tip commit +of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The +length of the abbreviation scales as the repository grows, using the +approximate number of objects in the repository and a bit of math +around the birthday paradox, and defaults to a minimum of 7. The "g" prefix stands for "git" and is used to allow describing the version of a software depending on the SCM the software is managed with. This is useful in an environment where people may use different SCMs. diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 7f4c8a8ce7..6236c75c9b 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -51,16 +51,20 @@ files on disk. --staged is a synonym of --cached. + If --merge-base is given, instead of using , use the merge base -of and HEAD. `git diff --merge-base A` is equivalent to -`git diff $(git merge-base A HEAD)`. +of and HEAD. `git diff --cached --merge-base A` is equivalent to +`git diff --cached $(git merge-base A HEAD)`. -'git diff' [] [--] [...]:: +'git diff' [] [--merge-base] [--] [...]:: This form is to view the changes you have in your working tree relative to the named . You can use HEAD to compare it with the latest commit, or a branch name to compare with the tip of a different branch. ++ +If --merge-base is given, instead of using , use the merge base +of and HEAD. `git diff --merge-base A` is equivalent to +`git diff $(git merge-base A HEAD)`. 'git diff' [] [--merge-base] [--] [...]:: diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 1bbf865a1b..0498e7bacb 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -39,7 +39,9 @@ OPTIONS full ref name (including prefix) will be printed. If 'auto' is specified, then if the output is going to a terminal, the ref names are shown as if 'short' were given, otherwise no ref names are - shown. The default option is 'short'. + shown. The option `--decorate` is short-hand for `--decorate=short`. + Default to configuration value of `log.decorate` if configured, + otherwise, `auto`. --decorate-refs=:: --decorate-refs-exclude=:: diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 25d9fbe37a..dbfd1f9017 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -128,10 +128,10 @@ depth is 4095. into multiple independent packfiles, each not larger than the given size. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. - This option - prevents the creation of a bitmap index. The default is unlimited, unless the config variable - `pack.packSizeLimit` is set. + `pack.packSizeLimit` is set. Note that this option may result in + a larger and slower repository; see the discussion in + `pack.packSizeLimit`. --honor-pack-keep:: This flag causes an object already in a local pack that diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 5c3fb67c01..7f4b2d1982 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -117,7 +117,7 @@ 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 current branch into the upstream branch. +When false, merge the upstream branch into the current branch. + When `interactive`, enable the interactive mode of rebase. + diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index a953c7c387..2f25aa3a29 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -244,8 +244,8 @@ Imagine that you have to rebase what you have already published. You will have to bypass the "must fast-forward" rule in order to replace the history you originally published with the rebased history. If somebody else built on top of your original history while you are -rebasing, the tip of the branch at the remote may advance with her -commit, and blindly pushing with `--force` will lose her work. +rebasing, the tip of the branch at the remote may advance with their +commit, and blindly pushing with `--force` will lose their work. + This option allows you to say that you expect the history you are updating is what you rebased and want to replace. If the remote ref diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index ef310f362e..24c00c9384 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -121,7 +121,9 @@ depth is 4095. If specified, multiple packfiles may be created, which also prevents the creation of a bitmap index. The default is unlimited, unless the config variable - `pack.packSizeLimit` is set. + `pack.packSizeLimit` is set. Note that this option may result in + a larger and slower repository; see the discussion in + `pack.packSizeLimit`. -b:: --write-bitmap-index:: diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 93708aefea..3db4eab4ba 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -167,6 +167,14 @@ Sending `sendemail.envelopeSender` configuration variable; if that is unspecified, choosing the envelope sender is left to your MTA. +--sendmail-cmd=:: + Specify a command to run to send the email. The command should + be sendmail-like; specifically, it must support the `-i` option. + The command will be executed in the shell if necessary. Default + is the value of `sendemail.sendmailcmd`. If unspecified, and if + --smtp-server is also unspecified, git-send-email will search + for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH. + --smtp-encryption=:: Specify the encryption to use, either 'ssl' or 'tls'. Any other value reverts to plain SMTP. Default is the value of @@ -211,13 +219,16 @@ a password is obtained using 'git-credential'. --smtp-server=:: If set, specifies the outgoing SMTP server to use (e.g. - `smtp.example.com` or a raw IP address). Alternatively it can - specify a full pathname of a sendmail-like program instead; - the program must support the `-i` option. Default value can - be specified by the `sendemail.smtpServer` configuration - option; the built-in default is to search for `sendmail` in - `/usr/sbin`, `/usr/lib` and $PATH if such program is - available, falling back to `localhost` otherwise. + `smtp.example.com` or a raw IP address). If unspecified, and if + `--sendmail-cmd` is also unspecified, the default is to search + for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH if such a + program is available, falling back to `localhost` otherwise. ++ +For backward compatibility, this option can also specify a full pathname +of a sendmail-like program instead; the program must support the `-i` +option. This method does not support passing arguments or using plain +command names. For those use cases, consider using `--sendmail-cmd` +instead. --smtp-server-port=:: Specifies a port different from the default port (SMTP diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index a8c8c32f1e..be6084ccef 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -91,8 +91,10 @@ show [-u|--include-untracked|--only-untracked] [] []:: By default, the command shows the diffstat, but it will accept any format known to 'git diff' (e.g., `git stash show -p stash@{1}` to view the second most recent entry in patch form). - You can use stash.showIncludeUntracked, stash.showStat, and - stash.showPatch config variables to change the default behavior. + If no `` is provided, the default behavior will be given + by the `stash.showStat`, and `stash.showPatch` config variables. You + can also use `stash.showIncludeUntracked` to set whether + `--include-untracked` is enabled by default. pop [--index] [-q|--quiet] []:: diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index f1bb1fa5f5..8a7cbdd19c 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -9,7 +9,7 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- [verse] -'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b ] [] +'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason ]] [-b ] [] 'git worktree list' [--porcelain] 'git worktree lock' [--reason ] 'git worktree move' @@ -242,7 +242,7 @@ With `list`, annotate missing working trees as prunable if they are older than `