diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 9301a1edd6..909dd9cdbb 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -113,15 +113,13 @@ jobs: cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - uses: actions/checkout@v4 - - name: setup SDK - shell: powershell - run: ci/install-sdk.ps1 + - uses: git-for-windows/setup-git-for-windows-sdk@v1 - name: build - shell: powershell + shell: bash env: HOME: ${{runner.workspace}} NO_PERL: 1 - run: git-sdk/usr/bin/bash.exe -l -c 'ci/make-test-artifacts.sh artifacts' + run: . /etc/profile && 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 @@ -149,12 +147,10 @@ jobs: - name: extract tracked files and build artifacts shell: bash run: tar xf artifacts.tar.gz && tar xf tracked.tar.gz - - name: setup SDK - shell: powershell - run: ci/install-sdk.ps1 + - uses: git-for-windows/setup-git-for-windows-sdk@v1 - name: test - shell: powershell - run: git-sdk/usr/bin/bash.exe -l -c 'ci/run-test-slice.sh ${{matrix.nr}} 10' + shell: bash + run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10 - name: print test failures if: failure() && env.FAILED_TEST_ARTIFACTS != '' shell: bash @@ -252,6 +248,58 @@ jobs: with: name: failed-tests-windows-vs-${{ matrix.nr }} path: ${{env.FAILED_TEST_ARTIFACTS}} + + windows-meson-build: + name: win+Meson build + needs: ci-config + if: needs.ci-config.outputs.enabled == 'yes' + runs-on: windows-latest + concurrency: + group: windows-meson-build-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + - name: Set up dependencies + shell: pwsh + run: pip install meson ninja + - name: Setup + shell: pwsh + run: meson setup build -Dperl=disabled + - name: Compile + shell: pwsh + run: meson compile -C build + - name: Upload build artifacts + uses: actions/upload-artifact@v4 + with: + name: windows-meson-artifacts + path: build + windows-meson-test: + name: win+Meson test + runs-on: windows-latest + needs: [ci-config, windows-meson-build] + strategy: + fail-fast: false + matrix: + nr: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + concurrency: + group: windows-meson-test-${{ matrix.nr }}-${{ github.ref }} + cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + - name: Set up dependencies + shell: pwsh + run: pip install meson ninja + - name: Download build artifacts + uses: actions/download-artifact@v4 + with: + name: windows-meson-artifacts + path: build + - name: Test + shell: pwsh + run: meson test -C build --list | Select-Object -Skip 1 | Select-String .* | Group-Object -Property { $_.LineNumber % 10 } | Where-Object Name -EQ ${{ matrix.nr }} | ForEach-Object { meson test -C build --no-rebuild --print-errorlogs $_.Group } + regular: name: ${{matrix.vector.jobname}} (${{matrix.vector.pool}}) needs: ci-config @@ -269,9 +317,8 @@ jobs: - jobname: linux-reftable cc: clang pool: ubuntu-latest - - jobname: linux-gcc + - jobname: linux-breaking-changes cc: gcc - cc_package: gcc-8 pool: ubuntu-20.04 - jobname: linux-TEST-vars cc: gcc @@ -286,9 +333,9 @@ jobs: - jobname: osx-gcc cc: gcc-13 pool: macos-13 - - jobname: linux-gcc-default - cc: gcc - pool: ubuntu-latest + - jobname: osx-meson + cc: clang + pool: macos-13 - jobname: linux-leaks cc: gcc pool: ubuntu-latest @@ -298,11 +345,15 @@ jobs: - jobname: linux-asan-ubsan cc: clang pool: ubuntu-latest + - jobname: linux-meson + cc: gcc + pool: ubuntu-latest env: CC: ${{matrix.vector.cc}} CC_PACKAGE: ${{matrix.vector.cc_package}} jobname: ${{matrix.vector.jobname}} distro: ${{matrix.vector.pool}} + TEST_OUTPUT_DIRECTORY: ${{github.workspace}}/t runs-on: ${{matrix.vector.pool}} steps: - uses: actions/checkout@v4 @@ -342,12 +393,21 @@ jobs: - jobname: linux-musl image: alpine distro: alpine-latest + # Supported until 2025-04-02. - jobname: linux32 image: i386/ubuntu:focal distro: ubuntu32-20.04 - jobname: pedantic image: fedora distro: fedora-latest + # A RHEL 8 compatible distro. Supported until 2029-05-31. + - jobname: almalinux-8 + image: almalinux:8 + distro: almalinux-8 + # Supported until 2026-08-31. + - jobname: debian-11 + image: debian:11 + distro: debian-11 env: jobname: ${{matrix.vector.jobname}} distro: ${{matrix.vector.distro}} diff --git a/.gitignore b/.gitignore index 6687bd6db4..e82aa19df0 100644 --- a/.gitignore +++ b/.gitignore @@ -12,7 +12,6 @@ /GIT-TEST-SUITES /GIT-USER-AGENT /GIT-VERSION-FILE -/bin-wrappers/ /git /git-add /git-am @@ -195,9 +194,11 @@ /config-list.h /command-list.h /hook-list.h +/version-def.h *.tar.gz *.dsc *.deb +/git.rc /git.spec *.exe *.[aos] diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 526ecfe030..b67a284fa9 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -20,6 +20,7 @@ test:linux: - saas-linux-medium-amd64 variables: CUSTOM_PATH: "/custom" + TEST_OUTPUT_DIRECTORY: "/tmp/test-output" before_script: - ./ci/install-dependencies.sh script: @@ -31,11 +32,12 @@ test:linux: if test "$CI_JOB_STATUS" != 'success' then sudo --preserve-env --set-home --user=builder ./ci/print-test-failures.sh + mv "$TEST_OUTPUT_DIRECTORY"/failed-test-artifacts t/ fi parallel: matrix: - jobname: linux-old - image: ubuntu:16.04 + image: ubuntu:20.04 CC: gcc - jobname: linux-sha256 image: ubuntu:latest @@ -43,17 +45,13 @@ test:linux: - jobname: linux-reftable image: ubuntu:latest CC: clang - - jobname: linux-gcc + - jobname: linux-breaking-changes image: ubuntu:20.04 CC: gcc - CC_PACKAGE: gcc-8 - jobname: linux-TEST-vars image: ubuntu:20.04 CC: gcc CC_PACKAGE: gcc-8 - - jobname: linux-gcc-default - image: ubuntu:latest - CC: gcc - jobname: linux-leaks image: ubuntu:latest CC: gcc @@ -67,6 +65,9 @@ test:linux: image: fedora:latest - jobname: linux-musl image: alpine:latest + - jobname: linux-meson + image: ubuntu:latest + CC: gcc artifacts: paths: - t/failed-test-artifacts @@ -99,10 +100,13 @@ test:osx: parallel: matrix: - jobname: osx-clang - image: macos-13-xcode-14 + image: macos-14-xcode-15 CC: clang - jobname: osx-reftable - image: macos-13-xcode-14 + image: macos-14-xcode-15 + CC: clang + - jobname: osx-meson + image: macos-14-xcode-15 CC: clang artifacts: paths: @@ -141,6 +145,44 @@ test:mingw64: - git-sdk/usr/bin/bash.exe -l -c 'ci/print-test-failures.sh' parallel: 10 +.msvc-meson: + tags: + - saas-windows-medium-amd64 + before_script: + - choco install -y git meson ninja openssl + - Import-Module $env:ChocolateyInstall\helpers\chocolateyProfile.psm1 + - refreshenv + # The certificate store for Python on Windows is broken and fails to fetch + # certificates, see https://bugs.python.org/issue36011. This seems to + # mostly be an issue with how the GitLab image is set up as it is a + # non-issue on GitHub Actions. Work around the issue by importing + # cetrificates manually. + - Invoke-WebRequest https://curl.haxx.se/ca/cacert.pem -OutFile cacert.pem + - openssl pkcs12 -export -nokeys -in cacert.pem -out certs.pfx -passout "pass:" + - Import-PfxCertificate -CertStoreLocation Cert:\LocalMachine\Root -FilePath certs.pfx + +build:msvc-meson: + extends: .msvc-meson + stage: build + script: + - meson setup build -Dperl=disabled + - meson compile -C build + artifacts: + paths: + - build + +test:msvc-meson: + extends: .msvc-meson + stage: test + when: manual + timeout: 6h + needs: + - job: "build:msvc-meson" + artifacts: true + script: + - meson test -C build --list | Select-Object -Skip 1 | Select-String .* | Group-Object -Property { $_.LineNumber % $Env:CI_NODE_TOTAL + 1 } | Where-Object Name -EQ $Env:CI_NODE_INDEX | ForEach-Object { meson test -C build --no-rebuild --print-errorlogs $_.Group } + parallel: 10 + test:fuzz-smoke-tests: image: ubuntu:latest stage: test diff --git a/Documentation/.gitignore b/Documentation/.gitignore index a48448de32..9f4bb3c4bf 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -12,6 +12,9 @@ cmds-*.txt mergetools-*.txt SubmittingPatches.txt tmp-doc-diff/ +tmp-meson-diff/ GIT-ASCIIDOCFLAGS /.build/ /GIT-EXCLUDED-PROGRAMS +/asciidoc.conf +/asciidoctor-extensions.rb diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index 27acff86db..7c388e56c8 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -154,6 +154,31 @@ Cf. , , <20230323204047.GA9290@coredump.intra.peff.net>, +* Support for storing shorthands for remote URLs in "$GIT_COMMON_DIR/branches/" + and "$GIT_COMMON_DIR/remotes/" has been long superseded by storing remotes in + the repository configuration. ++ +The mechanism has originally been introduced in f170e4b39d ([PATCH] fetch/pull: +short-hand notation for remote repositories., 2005-07-16) and was superseded by +6687f8fea2 ([PATCH] Use .git/remote/origin, not .git/branches/origin., +2005-08-20), where we switched from ".git/branches/" to ".git/remotes/". That +commit already mentions an upcoming deprecation of the ".git/branches/" +directory, and starting with a1d4aa7424 (Add repository-layout document., +2005-09-01) we have also marked this layout as deprecated. Eventually we also +started to migrate away from ".git/remotes/" in favor of config-based remotes, +and we have marked the directory as legacy in 3d3d282146 (Documentation: +Grammar correction, wording fixes and cleanup, 2011-08-23) ++ +As our documentation mentions, these directories are not to be found in modern +repositories at all and most users aren't even aware of these mechanisms. They +have been deprecated for almost 20 years and 14 years respectively, and we are +not aware of any active users that have complained about this deprecation. +Furthermore, the ".git/branches/" directory is nowadays misleadingly named and +may cause confusion as "branches" are almost exclusively used in the context of +references. ++ +These features will be removed. + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 87904791cb..ba047ed224 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -583,7 +583,7 @@ For C programs: Run `GIT_DEBUGGER=1 ./bin-wrappers/git foo` to simply use gdb as is, or run `GIT_DEBUGGER=" " ./bin-wrappers/git foo` to use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" - ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + ./bin-wrappers/git log` (See `bin-wrappers/wrap-for-bin.sh`.) - The primary data structure that a subsystem 'S' deals with is called `struct S`. Functions that operate on `struct S` are named @@ -703,16 +703,30 @@ Program Output Error Messages - - Do not end error messages with a full stop. + - Do not end a single-sentence error message with a full stop. - Do not capitalize the first word, only because it is the first word - in the message ("unable to open %s", not "Unable to open %s"). But + in the message ("unable to open '%s'", not "Unable to open '%s'"). But "SHA-3 not supported" is fine, because the reason the first word is capitalized is not because it is at the beginning of the sentence, but because the word would be spelled in capital letters even when it appeared in the middle of the sentence. - - Say what the error is first ("cannot open %s", not "%s: cannot open") + - Say what the error is first ("cannot open '%s'", not "%s: cannot open"). + + - Enclose the subject of an error inside a pair of single quotes, + e.g. `die(_("unable to open '%s'"), path)`. + + - Unless there is a compelling reason not to, error messages from + porcelain commands should be marked for translation, e.g. + `die(_("bad revision %s"), revision)`. + + - Error messages from the plumbing commands are sometimes meant for + machine consumption and should not be marked for translation, + e.g., `die("bad revision %s", revision)`. + + - BUG("message") are for communicating the specific error to developers, + thus should not be translated. Externally Visible Names diff --git a/Documentation/Makefile b/Documentation/Makefile index 0f55baa252..aedfe99d1d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,6 +1,8 @@ # Import tree-wide shared Makefile behavior and libraries include ../shared.mak +.PHONY: FORCE + # Guard against environment variables MAN1_TXT = MAN5_TXT = @@ -111,6 +113,7 @@ TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches TECH_DOCS += ToolsForGit TECH_DOCS += technical/bitmap-format +TECH_DOCS += technical/build-systems TECH_DOCS += technical/bundle-uri TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/long-running-process-protocol @@ -148,16 +151,12 @@ man5dir = $(mandir)/man5 man7dir = $(mandir)/man7 # DESTDIR = -GIT_DATE := $(shell git show --quiet --pretty='%as') - ASCIIDOC = asciidoc ASCIIDOC_EXTRA = ASCIIDOC_HTML = xhtml11 ASCIIDOC_DOCBOOK = docbook ASCIIDOC_CONF = -f asciidoc.conf -ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \ - -amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' \ - -arevdate='$(GIT_DATE)' +ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK) @@ -182,6 +181,10 @@ endif -include ../config.mak.autogen -include ../config.mak +# Set GIT_VERSION_OVERRIDE such that version_gen knows to substitute +# GIT_VERSION in case it was set by the user. +GIT_VERSION_OVERRIDE := $(GIT_VERSION) + ifndef NO_MAN_BOLD_LITERAL XMLTO_EXTRA += -m manpage-bold-literal.xsl endif @@ -210,6 +213,12 @@ ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS DBLATEX_COMMON = XMLTO_EXTRA += --skip-validation XMLTO_EXTRA += -x manpage.xsl + +asciidoctor-extensions.rb: asciidoctor-extensions.rb.in FORCE + $(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@) +else +asciidoc.conf: asciidoc.conf.in FORCE + $(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@) endif ASCIIDOC_DEPS += docinfo.html @@ -218,6 +227,7 @@ SHELL_PATH ?= $(SHELL) # Shell quote; SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) +ASCIIDOC_EXTRA += -abuild_dir='$(shell pwd)' ifdef DEFAULT_PAGER DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER)) ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)' @@ -268,22 +278,17 @@ install-pdf: pdf install-html: html '$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir) -../GIT-VERSION-FILE: FORCE - $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE - -ifneq ($(filter-out lint-docs clean,$(MAKECMDGOALS)),) --include ../GIT-VERSION-FILE -endif +mergetools_txt = mergetools-diff.txt mergetools-merge.txt # # Determine "include::" file references in asciidoc files. # docdep_prereqs = \ - mergetools-list.made $(mergetools_txt) \ + $(mergetools_txt) \ cmd-list.made $(cmds_txt) doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl - $(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR) + $(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl "$(shell pwd)" >$@ $(QUIET_STDERR) ifneq ($(MAKECMDGOALS),clean) -include doc.dep @@ -305,22 +310,14 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) - $(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \ + $(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl .. . $(cmds_txt) && \ date >$@ -mergetools_txt = mergetools-diff.txt mergetools-merge.txt - -$(mergetools_txt): mergetools-list.made - -mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*) - $(QUIET_GEN) \ - $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=diff && \ - . ../git-mergetool--lib.sh && \ - show_tool_names can_diff' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-diff.txt && \ - $(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=merge && \ - . ../git-mergetool--lib.sh && \ - show_tool_names can_merge' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-merge.txt && \ - date >$@ +mergetools-%.txt: generate-mergetool-list.sh ../git-mergetool--lib.sh $(wildcard ../mergetools/*) +mergetools-diff.txt: + $(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. diff $@ +mergetools-merge.txt: + $(QUIET_GEN)$(SHELL_PATH) ./generate-mergetool-list.sh .. merge $@ TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK)) @@ -341,6 +338,8 @@ clean: $(RM) SubmittingPatches.txt $(RM) $(cmds_txt) $(mergetools_txt) *.made $(RM) GIT-ASCIIDOCFLAGS + $(RM) asciidoc.conf asciidoctor-extensions.rb + $(RM) -rf tmp-meson-diff docinfo.html: docinfo-html.in $(QUIET_GEN)$(RM) $@ && cat $< >$@ @@ -364,16 +363,16 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< %.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 +user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS) $(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)) - $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh + $(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \ - asciidoc.conf GIT-ASCIIDOCFLAGS + $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt SubmittingPatches.txt: SubmittingPatches @@ -413,16 +412,16 @@ gitman.info: gitman.texi $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@ -howto-index.txt: howto-index.sh $(HOWTO_TXT) - $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@ +howto-index.txt: howto/howto-index.sh $(HOWTO_TXT) + $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@ -$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt +$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt 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 +$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC) \ sed -e '1,/^$$/d' $< | \ $(TXT_TO_HTML) - >$@ @@ -496,6 +495,20 @@ lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh +.PHONY: lint-docs-meson +lint-docs-meson: + @# awk acts up when trying to match single quotes, so we use \047 instead. + @mkdir -p tmp-meson-diff && \ + awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \ + grep -v -e '#' -e '^$$' | \ + sort >tmp-meson-diff/meson.txt && \ + ls git*.txt scalar.txt | grep -v -e git-bisect-lk2009.txt -e git-tools.txt >tmp-meson-diff/actual.txt && \ + if ! cmp tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; then \ + echo "Meson man pages differ from actual man pages:"; \ + diff -u tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; \ + exit 1; \ + fi + ## Lint: list of targets above .PHONY: lint-docs lint-docs: lint-docs-fsck-msgids @@ -503,6 +516,7 @@ lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order lint-docs: lint-docs-manpages +lint-docs: lint-docs-meson ifeq ($(wildcard po/Makefile),po/Makefile) doc-l10n install-l10n:: diff --git a/Documentation/RelNotes/2.40.4.txt b/Documentation/RelNotes/2.40.4.txt new file mode 100644 index 0000000000..0ff29f3cfc --- /dev/null +++ b/Documentation/RelNotes/2.40.4.txt @@ -0,0 +1,5 @@ +Git v2.40.4 Release Notes +========================= + +This release lets Git refuse to accept URLs that contain control +sequences. This addresses CVE-2024-50349 and CVE-2024-52006. diff --git a/Documentation/RelNotes/2.41.3.txt b/Documentation/RelNotes/2.41.3.txt new file mode 100644 index 0000000000..b5aba88790 --- /dev/null +++ b/Documentation/RelNotes/2.41.3.txt @@ -0,0 +1,6 @@ +Git v2.41.3 Release Notes +========================= + +This release merges up the fix that appears in v2.40.4 to address +the security issues CVE-2024-50349 and CVE-2024-52006; see the +release notes for that version for details. diff --git a/Documentation/RelNotes/2.42.4.txt b/Documentation/RelNotes/2.42.4.txt new file mode 100644 index 0000000000..3129d76e75 --- /dev/null +++ b/Documentation/RelNotes/2.42.4.txt @@ -0,0 +1,6 @@ +Git v2.42.4 Release Notes +========================= + +This release merges up the fix that appears in v2.40.4 and v2.41.3 +to address the security issues CVE-2024-50349 and CVE-2024-52006; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.43.6.txt b/Documentation/RelNotes/2.43.6.txt new file mode 100644 index 0000000000..2114b9f78d --- /dev/null +++ b/Documentation/RelNotes/2.43.6.txt @@ -0,0 +1,7 @@ +Git v2.43.6 Release Notes +========================= + +This release merges up the fix that appears in v2.40.4, v2.41.3 +and v2.42.4 to address the security issues CVE-2024-50349 and +CVE-2024-52006; see the release notes for these versions for +details. diff --git a/Documentation/RelNotes/2.44.3.txt b/Documentation/RelNotes/2.44.3.txt new file mode 100644 index 0000000000..5862845458 --- /dev/null +++ b/Documentation/RelNotes/2.44.3.txt @@ -0,0 +1,7 @@ +Git v2.44.3 Release Notes +========================= + +This release merges up the fix that appears in v2.40.4, v2.41.3, +v2.42.4 and v2.43.6 to address the security issues CVE-2024-50349 +and CVE-2024-52006; see the release notes for these versions +for details. diff --git a/Documentation/RelNotes/2.45.3.txt b/Documentation/RelNotes/2.45.3.txt index 2a1e9aa608..ddb3cb694b 100644 --- a/Documentation/RelNotes/2.45.3.txt +++ b/Documentation/RelNotes/2.45.3.txt @@ -1,7 +1,12 @@ Git v2.45.3 Release Notes ========================= -This primarily is to backport various small fixes accumulated on the +This release merges up the fix that appears in v2.40.4, v2.41.3, +v2.42.4, v2.43.6 and v2.44.3 to address the security issues +CVE-2024-50349 and CVE-2024-52006; see the release notes for +these versions for details. + +This version also backports various small fixes accumulated on the 'master' front during the development towards Git 2.46, the next feature release. diff --git a/Documentation/RelNotes/2.46.3.txt b/Documentation/RelNotes/2.46.3.txt new file mode 100644 index 0000000000..4af032b63c --- /dev/null +++ b/Documentation/RelNotes/2.46.3.txt @@ -0,0 +1,6 @@ +Git v2.46.3 Release Notes +========================= + +This release merges up the fix that appears in v2.40.4, v2.41.3, v2.42.4, +v2.43.6, v2.44.3 and v2.45.3 to address the security issues CVE-2024-50349 and +CVE-2024-52006; see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.47.2.txt b/Documentation/RelNotes/2.47.2.txt new file mode 100644 index 0000000000..7a52ad8cb4 --- /dev/null +++ b/Documentation/RelNotes/2.47.2.txt @@ -0,0 +1,7 @@ +Git v2.47.2 Release Notes +========================= + +This release merges up the fix that appears in v2.40.4, v2.41.3, +v2.42.4, v2.43.6, v2.44.3, v2.45.3 and v2.46.3 to address the +security issues CVE-2024-50349 and CVE-2024-52006; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.48.0.txt b/Documentation/RelNotes/2.48.0.txt index b9d1b129cd..eff93be37a 100644 --- a/Documentation/RelNotes/2.48.0.txt +++ b/Documentation/RelNotes/2.48.0.txt @@ -21,6 +21,24 @@ UI, Workflows & Features * Drop support for older libcURL and Perl. + * End-user experience of "git mergetool" when the command errors out + has been improved. + + * "git bundle --unbundle" and "git clone" running on a bundle file + both learned to trigger fsck over the new objects with configurable + fck check levels. + + * When "git fetch $remote" notices that refs/remotes/$remote/HEAD is + missing and discovers what branch the other side points with its + HEAD, refs/remotes/$remote/HEAD is updated to point to it. + + * "git fetch" honors "remote..followRemoteHEAD" settings to + tweak the remote-tracking HEAD in "refs/remotes//HEAD". + + * "git range-diff" learned to optionally show and compare merge + commits in the ranges being compared, with the --diff-merges + option. + Performance, Internal Implementation, Development Support etc. -------------------------------------------------------------- @@ -29,15 +47,15 @@ Performance, Internal Implementation, Development Support etc. * The way AsciiDoc is used for SYNOPSIS part of the manual pages has been revamped. The sources, at least for the simple cases, got - vastly pleasant to work with. + vastly more pleasant to work with. * The reftable library is now prepared to expect that the memory allocation function given to it may fail to allocate and to deal with such an error. * An extra worktree attached to a repository points at each other to - allow finding the repository from the worktree and vice versa - possible. Turn this linkage to relative paths. + allow finding the repository from the worktree (and vice versa) + possible. Use relative paths for this linkage. * Enable Windows-based CI in GitLab. @@ -76,7 +94,7 @@ Performance, Internal Implementation, Development Support etc. * Update the project's CodingGuidelines to discourage naming functions with a "_1()" suffix. - * Updates the '.clang-format' to match project conventions. + * Update '.clang-format' to match project conventions. * Centralize documentation for repository extensions into a single place. @@ -98,7 +116,7 @@ Performance, Internal Implementation, Development Support etc. * The migration procedure between two ref backends has been optimized. * "git fsck" learned to issue warnings on "curiously formatted" ref - contents that have always been taken valid but something Git + contents that have always been treated as valid but that Git wouldn't have written itself (e.g., missing terminating end-of-line after the full object name). @@ -107,18 +125,61 @@ Performance, Internal Implementation, Development Support etc. * Built-in Git subcommands are supplied the repository object to work with; they learned to do the same when they invoke sub-subcommands. + * Drop support for ancient environments in various CI jobs. + + * Isolate the reftable subsystem from the rest of Git's codebase by + using fewer pieces of Git's infrastructure. + + * Optimize reading random references out of the reftable backend by + allowing reuse of iterator objects. + + * Backport oss-fuzz tests to our codebase. + + * Introduce a new repository extension to prevent older Git versions + from mis-interpreting worktrees created with relative paths. + + * Yet another "pass the repository through the callchain" topic. + + * "git describe" learned to stop digging the history needlessly + deeper. + + * Build procedure update plus introduction of Meson based builds. + + * Recent reftable updates mistook a NULL return from a request for + 0-byte allocation as OOM and died unnecessarily, which has been + corrected. + + * Reftable backend adds check for upper limit of log's update_index. + + * Start working to make the codebase buildable with -Wsign-compare. + + * Regression fix for 'show-index' when run outside of a repository. + + * The meson-build procedure is integrated into CI to catch and + prevent bitrotting. + + * "git refs migrate" learned to also migrate the reflog data across + backends. + + * The developer documentation has been updated to give the latest + info on gitk and git-gui maintainer. + + + * CI jobs that run threaded programs under LSan has been giving false + positives from time to time, which has been worked around. + Fixes since v2.47 ----------------- * Doc update to clarify how periodical maintenance are scheduled, - spread across time to avoid thundering hurds. + spread across time to avoid thundering herds. * Use after free and double freeing at the end in "git log -L... -p" had been identified and fixed. * On macOS, fsmonitor can fall into a race condition that results in - a client waiting forever to be notified for an event that have + a client waiting forever to be notified about an event that has already happened. This problem has been corrected. * "git maintenance start" crashed due to an uninitialized variable @@ -142,7 +203,7 @@ Fixes since v2.47 * The dumb-http code regressed when the result of re-indexing a pack yielded an *.idx file that differs in content from the *.idx file it downloaded from the remote. This has been corrected by no longer - relying on: the *.idx file we got from the remote. + relying on the *.idx file we got from the remote. * When called with '--left-right' and '--use-bitmap-index', 'rev-list' will produce output without any left/right markers, which has been @@ -166,7 +227,7 @@ Fixes since v2.47 * "git gc" discards any objects that are outside promisor packs that are referred to by an object in a promisor pack, and we do not refetch them from the promisor at runtime, resulting an unusable - repository. Work it around by including these objects in the + repository. Work around it by including these objects in the referring promisor pack at the receiving end of the fetch. * Avoid build/test breakage on a system without working malloc debug @@ -204,8 +265,66 @@ Fixes since v2.47 * The sequencer failed to honor core.commentString in some places. + * Describe a case where an option value needs to be spelled as a + separate argument, i.e. "--opt val", not "--opt=val". + (merge 1bc1e94091 jc/doc-opt-tilde-expand later to maint). + + * Loosen overly strict ownership check introduced in the recent past, + to keep the promise "cloning a suspicious repository is a safe + first step to inspect it". + (merge 0ffb5a6bf1 bc/allow-upload-pack-from-other-people later to maint). + + * "git fast-import" learned to reject paths with ".." and "." as + their components to avoid creating invalid tree objects. + (merge 8cb4c6e62f en/fast-import-verify-path later to maint). + + * The --ancestry-path option is designed to be given a commit that is + on the path, which was not documented, which has been corrected. + (merge bc1a980759 kk/doc-ancestry-path later to maint). + + * "git tag" has been taught to refuse to create refs/tags/HEAD + since such a tag will be confusing in the context of the UI provided by + the Git Porcelain commands. + (merge bbd445d5ef jc/forbid-head-as-tagname later to maint). + + * The advice messages now tell the newer 'git config set' command to + set the advice.token configuration variable to squelch a message. + (merge 6c397d0104 bf/explicit-config-set-in-advice-messages later to maint). + + * The syntax ":/" to name the latest commit with the matching + text was broken with a recent change, which has been corrected. + (merge 0ff919e87a ps/commit-with-message-syntax-fix later to maint). + + * Fix performance regression of a recent "fatten promisor pack with + local objects" protection against an unwanted gc. + + * "git log -p --remerge-diff --reverse" was completely broken. + (merge f94bfa1516 js/log-remerge-keep-ancestry later to maint). + + * "git bundle create" with an annotated tag on the positive end of + the revision range had a workaround code for older limitation in + the revision walker, which has become unnecessary. + (merge dd1072dfa8 tc/bundle-with-tag-remove-workaround later to maint). + + * GitLab CI updates. + (merge c6b43f663e ps/ci-gitlab-update later to maint). + + * Code to reuse objects based on bitmap contents have been tightened + to avoid race condition even when multiple packs are involved. + (merge 62b3ec8a3f tb/bitmap-fix-pack-reuse later to maint). + + * An earlier "csum-file checksum does not have to be computed with + sha1dc" topic had a few code paths that had initialized an + implementation of a hash function to be used by an unmatching hash + by mistake, which have been corrected. + (merge 599a63409b ps/weak-sha1-for-tail-sum-fix later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 77af53f56f aa/t7300-modernize later to maint). (merge dcd590a39d bf/t-readme-mention-reftable later to maint). (merge 68e3c69efa kh/trailer-in-glossary later to maint). (merge 91f88f76e6 tb/boundary-traversal-fix later to maint). + (merge 168ebb7159 jc/doc-error-message-guidelines later to maint). + (merge 18693d7d65 kh/doc-bundle-typofix later to maint). + (merge e2f5d3b491 kh/doc-update-ref-grammofix later to maint). + (merge 8525e92886 mh/doc-windows-home-env later to maint). diff --git a/Documentation/RelNotes/2.48.1.txt b/Documentation/RelNotes/2.48.1.txt new file mode 100644 index 0000000000..26c59b6e3b --- /dev/null +++ b/Documentation/RelNotes/2.48.1.txt @@ -0,0 +1,7 @@ +Git v2.48.1 Release Notes +========================= + +This release merges up the fix that appears in v2.40.4, v2.41.3, +v2.42.4, v2.43.6, v2.44.3, v2.45.3, v2.46.3, and v2.47.2 to address +the security issues CVE-2024-50349 and CVE-2024-52006; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.49.0.txt b/Documentation/RelNotes/2.49.0.txt new file mode 100644 index 0000000000..72984fea5d --- /dev/null +++ b/Documentation/RelNotes/2.49.0.txt @@ -0,0 +1,140 @@ +Git v2.49 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * Completion script updates for zsh + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * More -Wsign-compare fixes. + + * meson-based build now supports the unsafe-sha1 build knob. + + * The code to check LSan results has been simplified and made more + robust. + (merge 164a2516eb jk/lsan-race-ignore-false-positive later to maint). + + * More code paths have a repository passed through the callchain, + instead of assuming the primary the_repository object. + + * Move a few more unit tests to the clar test framework. + + * Introduce a new API to visit objects in batches based on a common + path, or by type. + + * Following the procedure we established to introduce breaking + changes for Git 3.0, allow an early opt-in for removing support of + $GIT_DIR/branches/ and $GIT_DIR/remotes/ directories to configure + remotes. + + +Fixes since v2.48 +----------------- + + * "git submodule" learned various ways to spell the same option, + e.g. "--branch=B" can be spelled "--branch B" or "-bB". + (merge b86f0f9071 re/submodule-parse-opt later to maint). + + * Tweak the help text used for the option value placeholders by + parse-options API so that translations can customize the "<>" + placeholder signal (e.g. "--option="). + (merge 5b34dd08d0 as/long-option-help-i18n later to maint). + + * CI jobs gave sporadic failures, which turns out that that the + object finalization code was giving an error when it did not have + to. + (merge d7fcbe2c56 ps/object-collision-check later to maint). + + * The code to compute "unique" name used git_rand() which can fail or + get stuck; the callsite does not require cryptographic security. + Introduce the "insecure" mode and use it appropriately. + (merge 0b4f8afef6 ps/reftable-get-random-fix later to maint). + + * A misconfigured "fsck.skiplist" configuration variable was not + diagnosed as an error, which has been corrected. + (merge ca7158076f jt/fsck-skiplist-parse-fix later to maint). + + * Extended SHA-1 expression parser did not work well when a branch + with an unusual name (e.g. "foo{bar") is involved. + (merge 191f0c8db2 en/object-name-with-funny-refname-fix later to maint). + + * The meson build procedure looked for the 'version-def.h' file in a + wrong directory, which has been corrected. + (merge 4771501c0a tc/meson-use-our-version-def-h later to maint). + + * The meson build procedure for Documentation/technical/ hierarchy was + missing necessary dependencies, which has been corrected. + (merge 1dca492edd sj/meson-doc-technical-dependency-fix later to maint). + + * The "instaweb" bound only to local IP address without "--local" and + to all addresses with "--local", which was the other way around, when + using Python's http.server class, which has been corrected. + (merge 76baf97fa1 ak/instaweb-python-port-binding-fix later to maint). + + * Document that it is insecure to use Personal Access Tokens, which + some hosting providers take as username/password, embedded in URLs. + (merge a90ff409f0 mh/doc-credential-helpers-with-pat later to maint). + + * The help text from "git $cmd -h" appear on the standard output for + some $cmd and the standard error for others. The built-in commands + have been fixed to show them on the standard output consistently. + (merge f66d1423f5 jc/show-usage-help later to maint). + + * The meson-driven build is now aware of "git-subtree" housed in + contrib/subtree hierarchy. + (merge 8454b42f94 ps/build-meson-subtree later to maint). + + * It was possible for "git unpack-objects" and "git index-pack" to + make an unaligned access, which has been corrected. + (merge 98046591b9 jk/pack-header-parse-alignment-fix later to maint). + + * The "cache" credential back-end did not handle authtype correctly, + which has been corrected. + (merge 0b43274850 mh/credential-cache-authtype-request-fix later to maint). + + * "git branch --sort=..." and "git for-each-ref --format=... --sort=..." + did not work as expected with some atoms, which has been corrected. + (merge c5490ce9d1 rs/ref-fitler-used-atoms-value-fix later to maint). + + * reflog entries for symbolic ref updates were broken, which has been + corrected. + (merge 3519492430 kn/reflog-symref-fix later to maint). + + * The trace2 code was not prepared to show a configuration variable + that is set to true using the valueless true syntax, which has been + corrected. + (merge 2fd367cf63 am/trace2-with-valueless-true later to maint). + + * The "git refs migrate" command did not migrate the reflog for + refs/stash, which is the contents of the stashes, which has been + corrected. + (merge a0bea0978f ps/reflog-migration-with-logall-fix later to maint). + + * Doc and short-help text for "show-index" has been clarified to + stress that the command reads its data from the standard input. + (merge 49edce4ff9 jc/show-index-h-update later to maint). + + * The API around choosing to use unsafe variant of SHA-1 + implementation has been updated in an attempt to make it harder to + abuse. + (merge 04292c3796 tb/unsafe-hash-cleanup later to maint). + + * Fix bugs in an earlier attempt to fix "git refs migration". + (merge f11f0a5a2d kn/reflog-migration-fix-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge ddb5287894 jk/t7407-use-test-grep later to maint). + (merge 21e1b44865 aj/difftool-config-doc-fix later to maint). + (merge 6a63995335 mh/gitattr-doc-markup-fix later to maint). + (merge 43850dcf9c sk/unit-test-hash later to maint). + (merge 4ad47d2de3 jc/cli-doc-option-and-config later to maint). + (merge 2d0ff147e5 jp/t8002-printf-fix later to maint). + (merge 69666e6746 ja/doc-restore-markup-update later to maint). + (merge d11d003ba5 sk/strlen-returns-size_t later to maint). + (merge 77b2d29e91 ja/doc-notes-markup-updates later to maint). + (merge 6979bf6f8f jk/combine-diff-cleanup later to maint). + (merge 8705c9bd13 kn/pack-write-with-reduced-globals later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index db17bc7fe2..958e3cc3d5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -692,16 +692,17 @@ rebase when I receive your patches). Some parts of the system have dedicated maintainers with their own repositories. -- `git-gui/` comes from git-gui project, maintained by Johannes Sixt: +- `git-gui/` comes from the git-gui project, maintained by Johannes Sixt: https://github.com/j6t/git-gui -- `gitk-git/` comes from Paul Mackerras's gitk project: + Contibutions should go via the git mailing list. - git://git.ozlabs.org/~paulus/gitk +- `gitk-git/` comes from the gitk project, maintained by Johannes Sixt: - Those who are interested in improving gitk can volunteer to help Paul - maintain it, cf. . + https://github.com/j6t/gitk + + Contibutions should go via the git mailing list. - `po/` comes from the localization coordinator, Jiang Xin: diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf.in similarity index 90% rename from Documentation/asciidoc.conf rename to Documentation/asciidoc.conf.in index f6da6d1fbd..f2aef6cb79 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf.in @@ -21,13 +21,26 @@ tilde=~ apostrophe=' backtick=` litdd=-- +manmanual=Git Manual +mansource=Git @GIT_VERSION@ +revdate=@GIT_DATE@ + +ifdef::doctype-book[] +[titles] + underlines="__","==","--","~~","^^" +endif::doctype-book[] ifdef::backend-docbook[] [linkgit-inlinemacro] +ifndef::doctype-book[] {0%{target}} {0#} {0#{target}{0}} {0#} +endif::doctype-book[] +ifdef::doctype-book[] +{target}{0?({0})} +endif::doctype-book[] [literal-inlinemacro] {eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb.in similarity index 92% rename from Documentation/asciidoctor-extensions.rb rename to Documentation/asciidoctor-extensions.rb.in index cb24480b63..2494f17a51 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb.in @@ -29,13 +29,12 @@ module Git class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor def process document, output if document.basebackend? 'docbook' - mansource = document.attributes['mansource'] - manversion = document.attributes['manversion'] - manmanual = document.attributes['manmanual'] + output = output.sub(/.*?<\/refmiscinfo>/, "") + output = output.sub(/.*?<\/refmiscinfo>/, "") + output = output.sub(/.*?<\/date>/, "@GIT_DATE@") new_tags = "" \ - "#{mansource}\n" \ - "#{manversion}\n" \ - "#{manmanual}\n" + "Git @GIT_VERSION@\n" \ + "Git Manual\n" output = output.sub(/<\/refmeta>/, new_tags + "") end output diff --git a/Documentation/build-docdep.perl b/Documentation/build-docdep.perl index 1b3ac8fdd9..315efaa2fa 100755 --- a/Documentation/build-docdep.perl +++ b/Documentation/build-docdep.perl @@ -1,5 +1,6 @@ #!/usr/bin/perl +my ($build_dir) = @ARGV; my %include = (); my %included = (); @@ -10,6 +11,7 @@ for my $text (<*.txt>) { chomp; s/^include::\s*//; s/\[\]//; + s/{build_dir}/${build_dir}/; $include{$text}{$_} = 1; $included{$_} = 1; } diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 755a110bc4..e260a98977 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -3,12 +3,13 @@ use File::Compare qw(compare); sub format_one { - my ($out, $nameattr) = @_; + my ($source_dir, $out, $nameattr) = @_; my ($name, $attr) = @$nameattr; + my ($path) = "$source_dir/Documentation/$name.txt"; my ($state, $description); my $mansection; $state = 0; - open I, '<', "$name.txt" or die "No such file $name.txt"; + open I, '<', "$path" or die "No such file $path.txt"; while () { if (/^(?:git|scalar)[a-z0-9-]*\(([0-9])\)$/) { $mansection = $1; @@ -29,7 +30,7 @@ sub format_one { } close I; if (!defined $description) { - die "No description found in $name.txt"; + die "No description found in $path.txt"; } if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) { print $out "linkgit:$name\[$mansection\]::\n\t"; @@ -43,9 +44,9 @@ sub format_one { } } -my ($input, @categories) = @ARGV; +my ($source_dir, $build_dir, @categories) = @ARGV; -open IN, "<$input"; +open IN, "<$source_dir/command-list.txt"; while () { last if /^### command list/; } @@ -63,17 +64,17 @@ close IN; for my $out (@categories) { my ($cat) = $out =~ /^cmds-(.*)\.txt$/; - open O, '>', "$out+" or die "Cannot open output file $out+"; + my ($path) = "$build_dir/$out"; + open O, '>', "$path+" or die "Cannot open output file $out+"; for (@{$cmds{$cat}}) { - format_one(\*O, $_); + format_one($source_dir, \*O, $_); } close O; - if (-f "$out" && compare("$out", "$out+") == 0) { - unlink "$out+"; + if (-f "$path" && compare("$path", "$path+") == 0) { + unlink "$path+"; } else { - print STDERR "$out\n"; - rename "$out+", "$out"; + rename "$path+", "$path"; } } diff --git a/Documentation/config/commit.txt b/Documentation/config/commit.txt index 62f0d92fda..d3f4624fd2 100644 --- a/Documentation/config/commit.txt +++ b/Documentation/config/commit.txt @@ -1,29 +1,34 @@ -commit.cleanup:: +ifdef::git-commit[] +:see-git-commit: +endif::git-commit[] +ifndef::git-commit[] +:see-git-commit: See linkgit:git-commit[1] for details. +endif::git-commit[] +`commit.cleanup`:: This setting overrides the default of the `--cleanup` option in - `git commit`. See linkgit:git-commit[1] for details. Changing the - default can be useful when you always want to keep lines that begin + `git commit`. {see-git-commit} Changing the default can be useful + when you always want to keep lines that begin with the comment character `#` in your log message, in which case you would do `git config commit.cleanup whitespace` (note that you will have to remove the help lines that begin with `#` in the commit log template yourself, if you do this). -commit.gpgSign:: - +`commit.gpgSign`:: A boolean to specify whether all commits should be GPG signed. Use of this option when doing operations such as rebase can result in a large number of commits being signed. It may be convenient to use an agent to avoid typing your GPG passphrase several times. -commit.status:: +`commit.status`:: A boolean to enable/disable inclusion of status information in the commit message template when using an editor to prepare the commit - message. Defaults to true. + message. Defaults to `true`. -commit.template:: +`commit.template`:: Specify the pathname of a file to use as the template for new commit messages. -commit.verbose:: +`commit.verbose`:: A boolean or int to specify the level of verbosity with `git commit`. - See linkgit:git-commit[1]. + {see-git-commit} diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt index 470482ff4c..80a7c77772 100644 --- a/Documentation/config/credential.txt +++ b/Documentation/config/credential.txt @@ -22,6 +22,17 @@ credential.useHttpPath:: or https URL to be important. Defaults to false. See linkgit:gitcredentials[7] for more information. +credential.sanitizePrompt:: + By default, user names and hosts that are shown as part of the + password prompt are not allowed to contain control characters (they + will be URL-encoded by default). Configure this setting to `false` to + override that behavior. + +credential.protectProtocol:: + By default, Carriage Return characters are not allowed in the protocol + that is used when Git talks to a credential helper. This setting allows + users to override this default. + credential.username:: If no username is set for a network authentication, use this username by default. See credential..* below, and diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 45f3fe855c..1135a62a0a 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -218,8 +218,6 @@ endif::git-diff[] Set this option to `true` to make the diff driver cache the text conversion outputs. See linkgit:gitattributes[5] for details. -include::../mergetools-diff.txt[] - `diff.indentHeuristic`:: Set this option to `false` to disable the default heuristics that shift diff hunk boundaries to make patches easier to read. diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt index 447c40d85a..6cd47331a9 100644 --- a/Documentation/config/difftool.txt +++ b/Documentation/config/difftool.txt @@ -13,6 +13,8 @@ diff.guitool:: and requires that a corresponding difftool..cmd variable is defined. +include::{build_dir}/mergetools-diff.txt[] + difftool..cmd:: Specify the command to invoke the specified diff tool. The specified command is evaluated in shell with the following diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt index 5dc569d1c9..5cb4721a0e 100644 --- a/Documentation/config/extensions.txt +++ b/Documentation/config/extensions.txt @@ -63,6 +63,12 @@ Note that this setting should only be set by linkgit:git-init[1] or linkgit:git-clone[1]. Trying to change it after initialization will not work and will produce hard-to-diagnose issues. +relativeWorktrees:: + If enabled, indicates at least one worktree has been linked with + relative paths. Automatically set if a worktree has been created or + repaired with either the `--relative-paths` option or with the + `worktree.useRelativePaths` config set to `true`. + worktreeConfig:: If enabled, then worktrees will load config settings from the `$GIT_DIR/config.worktree` file in addition to the diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index 8851b6cede..82554d65a0 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -101,7 +101,7 @@ merge.guitool:: Any other value is treated as a custom merge tool and requires that a corresponding mergetool..cmd variable is defined. -include::../mergetools-merge.txt[] +include::{build_dir}/mergetools-merge.txt[] merge.verbosity:: Controls the amount of output shown by the recursive merge diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt index 43db8e808d..b7e536496f 100644 --- a/Documentation/config/notes.txt +++ b/Documentation/config/notes.txt @@ -1,4 +1,4 @@ -notes.mergeStrategy:: +`notes.mergeStrategy`:: Which merge strategy to choose by default when resolving notes conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or `cat_sort_uniq`. Defaults to `manual`. See the "NOTES MERGE STRATEGIES" @@ -7,17 +7,17 @@ notes.mergeStrategy:: This setting can be overridden by passing the `--strategy` option to linkgit:git-notes[1]. -notes..mergeStrategy:: +`notes..mergeStrategy`:: Which merge strategy to choose when doing a notes merge into - refs/notes/. This overrides the more general - "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in + `refs/notes/`. This overrides the more general + `notes.mergeStrategy`. See the "NOTES MERGE STRATEGIES" section in linkgit:git-notes[1] for more information on the available strategies. -notes.displayRef:: +`notes.displayRef`:: Which ref (or refs, if a glob or specified more than once), in addition to the default set by `core.notesRef` or `GIT_NOTES_REF`, to read notes from when showing commit - messages with the 'git log' family of commands. + messages with the `git log` family of commands. + This setting can be overridden with the `GIT_NOTES_DISPLAY_REF` environment variable, which must be a colon separated list of refs or @@ -26,27 +26,27 @@ globs. A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored. + -This setting can be disabled by the `--no-notes` option to the 'git -log' family of commands, or by the `--notes=` option accepted by +This setting can be disabled by the `--no-notes` option to the linkgit:git-log[1] +family of commands, or by the `--notes=` option accepted by those commands. + -The effective value of "core.notesRef" (possibly overridden by -GIT_NOTES_REF) is also implicitly added to the list of refs to be +The effective value of `core.notesRef` (possibly overridden by +`GIT_NOTES_REF`) is also implicitly added to the list of refs to be displayed. -notes.rewrite.:: - When rewriting commits with (currently `amend` or +`notes.rewrite.`:: + When rewriting commits with __ (currently `amend` or `rebase`), if this variable is `false`, git will not copy notes from the original to the rewritten commit. Defaults to - `true`. See also "`notes.rewriteRef`" below. + `true`. See also `notes.rewriteRef` below. + This setting can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable, which must be a colon separated list of refs or globs. -notes.rewriteMode:: +`notes.rewriteMode`:: When copying notes during a rewrite (see the - "notes.rewrite." option), determines what to do if + `notes.rewrite.` option), determines what to do if the target commit already has a note. Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to `concatenate`. @@ -54,7 +54,7 @@ notes.rewriteMode:: This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` environment variable. -notes.rewriteRef:: +`notes.rewriteRef`:: When copying notes during a rewrite, specifies the (fully qualified) ref whose notes should be copied. May be a glob, in which case notes in all matching refs will be copied. You diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt index 6d8b7d6c63..4118c219c1 100644 --- a/Documentation/config/remote.txt +++ b/Documentation/config/remote.txt @@ -101,6 +101,19 @@ remote..serverOption:: The default set of server options used when fetching from this remote. These server options can be overridden by the `--server-option=` command line arguments. + +remote..followRemoteHEAD:: + How linkgit:git-fetch[1] should handle updates to `remotes//HEAD`. + The default value is "create", which will create `remotes//HEAD` + if it exists on the remote, but not locally, but will not touch an + already existing local reference. Setting to "warn" will print + a message if the remote has a different value, than the local one and + in case there is no local reference, it behaves like "create". + A variant on "warn" is "warn-if-not-$branch", which behaves like + "warn", but if `HEAD` on the remote is `$branch` it will be silent. + Setting to "always" will silently update it to the value on the remote. + Finally, setting it to "never" will never change or create the local + reference. + This is a multi-valued variable, and an empty value can be used in a higher priority configuration file (e.g. `.git/config` in a repository) to clear diff --git a/Documentation/config/worktree.txt b/Documentation/config/worktree.txt index 048e349482..5e35c7d018 100644 --- a/Documentation/config/worktree.txt +++ b/Documentation/config/worktree.txt @@ -7,3 +7,13 @@ worktree.guessRemote:: such a branch exists, it is checked out and set as "upstream" for the new branch. If no such match can be found, it falls back to creating a new branch from the current HEAD. + +worktree.useRelativePaths:: + Link worktrees using relative paths (when "true") or absolute + paths (when "false"). This is particularly useful for setups + where the repository and worktrees may be moved between + different locations or environments. Defaults to "false". ++ +Note that setting `worktree.useRelativePaths` to "true" implies enabling the +`extension.relativeWorktrees` config (see linkgit:git-config[1]), +thus making it incompatible with older versions of Git. diff --git a/Documentation/generate-mergetool-list.sh b/Documentation/generate-mergetool-list.sh new file mode 100755 index 0000000000..6700498b93 --- /dev/null +++ b/Documentation/generate-mergetool-list.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +if test "$#" -ne 3 +then + echo >&2 "USAGE: $0 " + exit 1 +fi + +SOURCE_DIR="$1" +TOOL_MODE="$2" +OUTPUT="$3" +MERGE_TOOLS_DIR="$SOURCE_DIR/mergetools" + +( + . "$SOURCE_DIR"/git-mergetool--lib.sh && + show_tool_names can_$TOOL_MODE +) | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >"$OUTPUT" diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 504b8a8143..03cd36fe8d 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -32,7 +32,7 @@ Git commands that fetch or otherwise "read" via protocols such as possible linkgit:git-clone[1] a new repository from a bundle, to use linkgit:git-fetch[1] to fetch from one, and to list the references contained within it with linkgit:git-ls-remote[1]. There's no -corresponding "write" support, i.e.a 'git push' into a bundle is not +corresponding "write" support, i.e. a 'git push' into a bundle is not supported. BUNDLE FORMAT diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 7acb4cb176..de8d8f5893 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -63,6 +63,9 @@ symbolic link, the clone will fail. This is a security measure to prevent the unintentional copying of files by dereferencing the symbolic links. + +This option does not work with repositories owned by other users for security +reasons, and `--no-local` must be specified for the clone to succeed. ++ *NOTE*: this operation can race with concurrent modification to the source repository, similar to running `cp -r ` while modifying __. @@ -384,6 +387,12 @@ $ cd my-linux $ git clone --bare -l /home/proj/.git /pub/scm/proj.git ------------ +* Clone a local repository from a different user: ++ +------------ +$ git clone --no-local /home/otheruser/proj.git /pub/scm/proj.git +------------ + CONFIGURATION ------------- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index c822113c11..602e2f1200 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -7,8 +7,8 @@ git-commit - Record changes to the repository SYNOPSIS -------- -[verse] -'git commit' [-a | --interactive | --patch] [-s] [-v] [-u] [--amend] +[synopsis] +git commit [-a | --interactive | --patch] [-s] [-v] [-u[]] [--amend] [--dry-run] [(-c | -C | --squash) | --fixup [(amend|reword):]] [-F | -m ] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=] @@ -23,31 +23,31 @@ Create a new commit containing the current contents of the index and the given log message describing the changes. The new commit is a direct child of HEAD, usually the tip of the current branch, and the branch is updated to point to it (unless no branch is associated with -the working tree, in which case HEAD is "detached" as described in +the working tree, in which case `HEAD` is "detached" as described in linkgit:git-checkout[1]). The content to be committed can be specified in several ways: 1. by using linkgit:git-add[1] to incrementally "add" changes to the - index before using the 'commit' command (Note: even modified files + index before using the `commit` command (Note: even modified files must be "added"); 2. by using linkgit:git-rm[1] to remove files from the working tree - and the index, again before using the 'commit' command; + and the index, again before using the `commit` command; -3. by listing files as arguments to the 'commit' command - (without --interactive or --patch switch), in which +3. by listing files as arguments to the `commit` command + (without `--interactive` or `--patch` switch), in which case the commit will ignore changes staged in the index, and instead record the current content of the listed files (which must already be known to Git); -4. by using the -a switch with the 'commit' command to automatically +4. by using the `-a` switch with the `commit` command to automatically "add" changes from all known files (i.e. all files that are already listed in the index) and to automatically "rm" files in the index that have been removed from the working tree, and then perform the actual commit; -5. by using the --interactive or --patch switches with the 'commit' command +5. by using the `--interactive` or `--patch` switches with the `commit` command to decide one by one which files or hunks should be part of the commit in addition to contents in the index, before finalizing the operation. See the ``Interactive Mode'' section of @@ -58,139 +58,139 @@ summary of what is included by any of the above for the next commit by giving the same set of parameters (options and paths). If you make a commit and then find a mistake immediately after -that, you can recover from it with 'git reset'. +that, you can recover from it with `git reset`. :git-commit: 1 OPTIONS ------- --a:: ---all:: - Tell the command to automatically stage files that have +`-a`:: +`--all`:: + Automatically stage files that have been modified and deleted, but new files you have not told Git about are not affected. --p:: ---patch:: +`-p`:: +`--patch`:: Use the interactive patch selection interface to choose which changes to commit. See linkgit:git-add[1] for details. --C :: ---reuse-message=:: - Take an existing commit object, and reuse the log message +`-C `:: +`--reuse-message=`:: + Take an existing __ object, and reuse the log message and the authorship information (including the timestamp) when creating the commit. --c :: ---reedit-message=:: - Like '-C', but with `-c` the editor is invoked, so that +`-c `:: +`--reedit-message=`:: + Like `-C`, but with `-c` the editor is invoked, so that the user can further edit the commit message. ---fixup=[(amend|reword):]:: - Create a new commit which "fixes up" `` when applied with +`--fixup=[(amend|reword):]`:: + Create a new commit which "fixes up" __ when applied with `git rebase --autosquash`. Plain `--fixup=` creates a - "fixup!" commit which changes the content of `` but leaves + "fixup!" commit which changes the content of __ but leaves its log message untouched. `--fixup=amend:` is similar but creates an "amend!" commit which also replaces the log message of - `` with the log message of the "amend!" commit. + __ with the log message of the "amend!" commit. `--fixup=reword:` creates an "amend!" commit which - replaces the log message of `` with its own log message - but makes no changes to the content of ``. + replaces the log message of __ with its own log message + but makes no changes to the content of __. + The commit created by plain `--fixup=` has a subject -composed of "fixup!" followed by the subject line from , +composed of "fixup!" followed by the subject line from __, and is recognized specially by `git rebase --autosquash`. The `-m` option may be used to supplement the log message of the created commit, but the additional commentary will be thrown away once the -"fixup!" commit is squashed into `` by +"fixup!" commit is squashed into __ by `git rebase --autosquash`. + The commit created by `--fixup=amend:` is similar but its subject is instead prefixed with "amend!". The log message of - is copied into the log message of the "amend!" commit and +__ is copied into the log message of the "amend!" commit and opened in an editor so it can be refined. When `git rebase ---autosquash` squashes the "amend!" commit into ``, the -log message of `` is replaced by the refined log message +--autosquash` squashes the "amend!" commit into __, the +log message of __ is replaced by the refined log message from the "amend!" commit. It is an error for the "amend!" commit's log message to be empty unless `--allow-empty-message` is specified. + `--fixup=reword:` is shorthand for `--fixup=amend: ---only`. It creates an "amend!" commit with only a log message + --only`. It creates an "amend!" commit with only a log message (ignoring any changes staged in the index). When squashed by `git -rebase --autosquash`, it replaces the log message of `` +rebase --autosquash`, it replaces the log message of __ without making any other changes. + Neither "fixup!" nor "amend!" commits change authorship of -`` when applied by `git rebase --autosquash`. +__ when applied by `git rebase --autosquash`. See linkgit:git-rebase[1] for details. ---squash=:: - Construct a commit message for use with `rebase --autosquash`. +`--squash=`:: + Construct a commit message for use with `git rebase --autosquash`. The commit message subject line is taken from the specified commit with a prefix of "squash! ". Can be used with additional commit message options (`-m`/`-c`/`-C`/`-F`). See linkgit:git-rebase[1] for details. ---reset-author:: - When used with -C/-c/--amend options, or when committing after a +`--reset-author`:: + When used with `-C`/`-c`/`--amend` options, or when committing after a conflicting cherry-pick, declare that the authorship of the resulting commit now belongs to the committer. This also renews the author timestamp. ---short:: +`--short`:: When doing a dry-run, give the output in the short-format. See linkgit:git-status[1] for details. Implies `--dry-run`. ---branch:: +`--branch`:: Show the branch and tracking info even in short-format. ---porcelain:: +`--porcelain`:: When doing a dry-run, give the output in a porcelain-ready format. See linkgit:git-status[1] for details. Implies `--dry-run`. ---long:: +`--long`:: When doing a dry-run, give the output in the long-format. Implies `--dry-run`. --z:: ---null:: +`-z`:: +`--null`:: When showing `short` or `porcelain` status output, print the - filename verbatim and terminate the entries with NUL, instead of LF. + filename verbatim and terminate the entries with _NUL_, instead of _LF_. If no format is given, implies the `--porcelain` output format. Without the `-z` option, filenames with "unusual" characters are quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). --F :: ---file=:: - Take the commit message from the given file. Use '-' to +`-F `:: +`--file=`:: + Take the commit message from __. Use '-' to read the message from the standard input. ---author=:: +`--author=`:: Override the commit author. Specify an explicit author using the - standard `A U Thor ` format. Otherwise + standard `A U Thor ` format. Otherwise __ is assumed to be a pattern and is used to search for an existing - commit by that author (i.e. rev-list --all -i --author=); + commit by that author (i.e. `git rev-list --all -i --author=`); the commit author is then copied from the first such commit found. ---date=:: +`--date=`:: Override the author date used in the commit. --m :: ---message=:: - Use the given as the commit message. +`-m `:: +`--message=`:: + Use __ as the commit message. If multiple `-m` options are given, their values are concatenated as separate paragraphs. + The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. --t :: ---template=:: +`-t `:: +`--template=`:: When editing the commit message, start the editor with the - contents in the given file. The `commit.template` configuration + contents in __. The `commit.template` configuration variable is often used to give this option implicitly to the command. This mechanism can be used by projects that want to guide participants with some hints on what to write in the message @@ -200,56 +200,54 @@ The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. include::signoff-option.txt[] ---trailer [(=|:)]:: - Specify a (, ) pair that should be applied as a +`--trailer [(=|:)]`:: + Specify a (__, __) pair that should be applied as a trailer. (e.g. `git commit --trailer "Signed-off-by:C O Mitter \ " --trailer "Helped-by:C O Mitter \ - "` will add the "Signed-off-by" trailer - and the "Helped-by" trailer to the commit message.) + "` will add the `Signed-off-by` trailer + and the `Helped-by` trailer to the commit message.) The `trailer.*` configuration variables (linkgit:git-interpret-trailers[1]) can be used to define if a duplicated trailer is omitted, where in the run of trailers 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. +`-n`:: +`--[no-]verify`:: + Bypass the `pre-commit` and `commit-msg` hooks. See also linkgit:githooks[5]. ---allow-empty:: +`--allow-empty`:: Usually recording a commit that has the exact same tree as its sole parent commit is a mistake, and the command prevents you from making such a commit. This option bypasses the safety, and is primarily for use by foreign SCM interface scripts. ---allow-empty-message:: - Like --allow-empty this command is primarily for use by foreign - SCM interface scripts. It allows you to create a commit with an - empty commit message without using plumbing commands like - linkgit:git-commit-tree[1]. +`--allow-empty-message`:: + Create a commit with an empty commit message without using plumbing + commands like linkgit:git-commit-tree[1]. Like `--allow-empty`, this + command is primarily for use by foreign SCM interface scripts. ---cleanup=:: - This option determines how the supplied commit message should be +`--cleanup=`:: + Determine how the supplied commit message should be cleaned up before committing. The '' can be `strip`, `whitespace`, `verbatim`, `scissors` or `default`. + -- -strip:: +`strip`:: Strip leading and trailing empty lines, trailing whitespace, commentary and collapse consecutive empty lines. -whitespace:: +`whitespace`:: Same as `strip` except #commentary is not removed. -verbatim:: +`verbatim`:: Do not change the message at all. -scissors:: +`scissors`:: Same as `whitespace` except that everything from (and including) the line found below is truncated, if the message is to be edited. - "`#`" can be customized with core.commentChar. + "`#`" can be customized with `core.commentChar`. # ------------------------ >8 ------------------------ -default:: +`default`:: Same as `strip` if the message is to be edited. Otherwise `whitespace`. -- @@ -257,19 +255,18 @@ default:: The default can be changed by the `commit.cleanup` configuration variable (see linkgit:git-config[1]). --e:: ---edit:: - The message taken from file with `-F`, command line with - `-m`, and from commit object with `-C` are usually used as - the commit log message unmodified. This option lets you - further edit the message taken from these sources. +`-e`:: +`--edit`:: + Let the user further edit the message taken from __ + with `-F `, command line with `-m `, and + from __ with `-C `. ---no-edit:: +`--no-edit`:: Use the selected commit message without launching an editor. For example, `git commit --amend --no-edit` amends a commit without changing its commit message. ---amend:: +`--amend`:: Replace the tip of the current branch by creating a new commit. The recorded tree is prepared as usual (including the effect of the `-i` and `-o` options and explicit @@ -295,23 +292,23 @@ You should understand the implications of rewriting history if you amend a commit that has already been published. (See the "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) ---no-post-rewrite:: - Bypass the post-rewrite hook. +`--no-post-rewrite`:: + Bypass the `post-rewrite` hook. --i:: ---include:: +`-i`:: +`--include`:: Before making a commit out of staged contents so far, stage the contents of paths given on the command line as well. This is usually not what you want unless you are concluding a conflicted merge. --o:: ---only:: +`-o`:: +`--only`:: Make a commit by taking the updated working tree contents of the paths specified on the command line, disregarding any contents that have been staged for other paths. This is the default mode of operation of - 'git commit' if any paths are given on the command line, + `git commit` if any paths are given on the command line, in which case this option can be omitted. If this option is specified together with `--amend`, then no paths need to be specified, which can be used to amend @@ -319,48 +316,48 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) already been staged. If used together with `--allow-empty` paths are also not required, and an empty commit will be created. ---pathspec-from-file=:: - Pathspec is passed in `` instead of commandline args. If - `` is exactly `-` then standard input is used. Pathspec - elements are separated by LF or CR/LF. Pathspec elements can be +`--pathspec-from-file=`:: + Pass pathspec in __ instead of commandline args. If + __ is exactly `-` then standard input is used. Pathspec + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and global `--literal-pathspecs`. ---pathspec-file-nul:: +`--pathspec-file-nul`:: Only meaningful with `--pathspec-from-file`. Pathspec elements are - separated with NUL character and all other characters are taken + separated with _NUL_ character and all other characters are taken literally (including newlines and quotes). --u[]:: ---untracked-files[=]:: +`-u[]`:: +`--untracked-files[=]`:: Show untracked files. + -- -The mode parameter is optional (defaults to 'all'), and is used to -specify the handling of untracked files; when -u is not used, the -default is 'normal', i.e. show untracked files and directories. +The __ parameter is optional (defaults to `all`), and is used to +specify the handling of untracked files; when `-u` is not used, the +default is `normal`, i.e. show untracked files and directories. The possible options are: - - 'no' - Show no untracked files - - 'normal' - Shows untracked files and directories - - 'all' - Also shows individual files in untracked directories. +`no`:: Show no untracked files +`normal`:: Shows untracked files and directories +`all`:: Also shows individual files in untracked directories. All usual spellings for Boolean value `true` are taken as `normal` and `false` as `no`. -The default can be changed using the status.showUntrackedFiles +The default can be changed using the `status.showUntrackedFiles` configuration variable documented in linkgit:git-config[1]. -- --v:: ---verbose:: - Show unified diff between the HEAD commit and what +`-v`:: +`--verbose`:: + Show unified diff between the `HEAD` commit and what would be committed at the bottom of the commit message template to help the user describe the commit by reminding what changes the commit has. Note that this diff output doesn't have its - lines prefixed with '#'. This diff will not be a part + lines prefixed with `#`. This diff will not be a part of the commit message. See the `commit.verbose` configuration variable in linkgit:git-config[1]. + @@ -368,40 +365,40 @@ If specified twice, show in addition the unified diff between what would be committed and the worktree files, i.e. the unstaged changes to tracked files. --q:: ---quiet:: +`-q`:: +`--quiet`:: Suppress commit summary message. ---dry-run:: +`--dry-run`:: Do not create a commit, but show a list of paths that are to be committed, paths with local changes that will be left uncommitted and paths that are untracked. ---status:: +`--status`:: Include the output of linkgit:git-status[1] in the commit message template when using an editor to prepare the commit message. Defaults to on, but can be used to override - configuration variable commit.status. + configuration variable `commit.status`. ---no-status:: +`--no-status`:: Do not include the output of linkgit:git-status[1] in the commit message template when using an editor to prepare the default commit message. --S[]:: ---gpg-sign[=]:: ---no-gpg-sign:: - GPG-sign commits. The `keyid` argument is optional and +`-S[]`:: +`--gpg-sign[=]`:: +`--no-gpg-sign`:: + GPG-sign commits. The __ is optional and defaults to the committer identity; if specified, it must be stuck to the option without a space. `--no-gpg-sign` is useful to countermand both `commit.gpgSign` configuration variable, and earlier `--gpg-sign`. -\--:: +`--`:: Do not interpret any more arguments as options. -...:: - When pathspec is given on the command line, commit the contents of +`...`:: + When __ is given on the command line, commit the contents of the files that match the pathspec without recording the changes already added to the index. The contents of these files are also staged for the next commit on top of what have been staged before. @@ -412,10 +409,10 @@ EXAMPLES -------- When recording your own work, the contents of modified files in your working tree are temporarily stored to a staging area -called the "index" with 'git add'. A file can be +called the "index" with `git add`. A file can be reverted back, only in the index but not in the working tree, to that of the last commit with `git restore --staged `, -which effectively reverts 'git add' and prevents the changes to +which effectively reverts `git add` and prevents the changes to this file from participating in the next commit. After building the state to be committed incrementally with these commands, `git commit` (without any pathname parameter) is used to record what @@ -443,7 +440,7 @@ $ git commit -a ------------ The command `git commit -a` first looks at your working tree, -notices that you have modified hello.c and removed goodbye.c, +notices that you have modified `hello.c` and removed `goodbye.c`, and performs necessary `git add` and `git rm` for you. After staging changes to many files, you can alter the order the @@ -471,13 +468,13 @@ $ git commit this second commit would record the changes to `hello.c` and `hello.h` as expected. -After a merge (initiated by 'git merge' or 'git pull') stops +After a merge (initiated by `git merge` or `git pull`) stops because of conflicts, cleanly merged paths are already staged to be committed for you, and paths that conflicted are left in unmerged state. You would have to first -check which paths are conflicting with 'git status' +check which paths are conflicting with `git status` and after fixing them manually in your working tree, you would -stage the result as usual with 'git add': +stage the result as usual with `git add`: ------------ $ git status | grep unmerged @@ -507,12 +504,12 @@ COMMIT INFORMATION Author and committer information is taken from the following environment variables, if set: - GIT_AUTHOR_NAME - GIT_AUTHOR_EMAIL - GIT_AUTHOR_DATE - GIT_COMMITTER_NAME - GIT_COMMITTER_EMAIL - GIT_COMMITTER_DATE + * `GIT_AUTHOR_NAME` + * `GIT_AUTHOR_EMAIL` + * `GIT_AUTHOR_DATE` + * `GIT_COMMITTER_NAME` + * `GIT_COMMITTER_EMAIL` + * `GIT_COMMITTER_DATE` (nb "<", ">" and "\n"s are stripped) @@ -524,7 +521,7 @@ that, see the `credential.username` variable in linkgit:git-config[1]. In case (some of) these environment variables are not set, the information is taken from the configuration items `user.name` and `user.email`, or, if not -present, the environment variable EMAIL, or, if that is not set, +present, the environment variable `EMAIL`, or, if that is not set, system user name and the hostname used for outgoing mail (taken from `/etc/mailname` and falling back to the fully qualified hostname when that file does not exist). @@ -555,7 +552,7 @@ include::i18n.txt[] ENVIRONMENT AND CONFIGURATION VARIABLES --------------------------------------- The editor used to edit the commit log message will be chosen from the -`GIT_EDITOR` environment variable, the core.editor configuration variable, the +`GIT_EDITOR` environment variable, the `core.editor` configuration variable, the `VISUAL` environment variable, or the `EDITOR` environment variable (in that order). See linkgit:git-var[1] for details. diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index 487cc557a8..54fa7a27e1 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -78,6 +78,23 @@ variable (this example increases the cache time to 1 hour): $ git config credential.helper 'cache --timeout=3600' ------------------------------------------------------- +PERSONAL ACCESS TOKENS +---------------------- + +Some remotes accept personal access tokens, which are randomly +generated and hard to memorise. They typically have a lifetime of weeks +or months. + +git-credential-cache is inherently unsuitable for persistent storage of +personal access tokens. The credential will be forgotten after the cache +timeout. Even if you configure a long timeout, credentials will be +forgotten if the daemon dies. + +To avoid frequently regenerating personal access tokens, configure a +credential helper with persistent storage. Alternatively, configure an +OAuth credential helper to generate credentials automatically. See +linkgit:gitcredentials[7], sections "Available helpers" and "OAuth". + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 84022f99d7..5c8e6ff566 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -7,19 +7,19 @@ git-notes - Add or inspect object notes SYNOPSIS -------- -[verse] -'git notes' [list []] -'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=] [--[no-]stripspace] [-F | -m | (-c | -C) ] [-e] [] -'git notes' copy [-f] ( --stdin | [] ) -'git notes' append [--allow-empty] [--[no-]separator | --separator=] [--[no-]stripspace] [-F | -m | (-c | -C) ] [-e] [] -'git notes' edit [--allow-empty] [] [--[no-]stripspace] -'git notes' show [] -'git notes' merge [-v | -q] [-s ] -'git notes' merge --commit [-v | -q] -'git notes' merge --abort [-v | -q] -'git notes' remove [--ignore-missing] [--stdin] [...] -'git notes' prune [-n] [-v] -'git notes' get-ref +[synopsis] +git notes [list []] +git notes add [-f] [--allow-empty] [--[no-]separator | --separator=] [--[no-]stripspace] [-F | -m | (-c | -C) ] [-e] [] +git notes copy [-f] ( --stdin | [] ) +git notes append [--allow-empty] [--[no-]separator | --separator=] [--[no-]stripspace] [-F | -m | (-c | -C) ] [-e] [] +git notes edit [--allow-empty] [] [--[no-]stripspace] +git notes show [] +git notes merge [-v | -q] [-s ] +git notes merge --commit [-v | -q] +git notes merge --abort [-v | -q] +git notes remove [--ignore-missing] [--stdin] [...] +git notes prune [-n] [-v] +git notes get-ref DESCRIPTION @@ -33,34 +33,34 @@ ENVIRONMENT sections below. If this ref does not exist, it will be quietly created when it is first needed to store a note. A typical use of notes is to supplement a commit message without -changing the commit itself. Notes can be shown by 'git log' along with +changing the commit itself. Notes can be shown by `git log` along with the original commit message. To distinguish these notes from the message stored in the commit object, the notes are indented like the -message, after an unindented line saying "Notes ():" (or +message, after an unindented line saying "Notes (__):" (or "Notes:" for `refs/notes/commits`). Notes can also be added to patches prepared with `git format-patch` by using the `--notes` option. Such notes are added as a patch commentary after a three dash separator line. -To change which notes are shown by 'git log', see the -"notes.displayRef" discussion in <>. +To change which notes are shown by `git log`, see the +`notes.displayRef` discussion in <>. -See the "notes.rewrite." configuration for a way to carry +See the `notes.rewrite.` configuration for a way to carry notes across commands that rewrite commits. SUBCOMMANDS ----------- -list:: +`list`:: List the notes object for a given object. If no object is given, show a list of all note objects and the objects they - annotate (in the format " "). + annotate (in the format "` `"). This is the default subcommand if no subcommand is given. -add:: - Add notes for a given object (defaults to HEAD). Abort if the +`add`:: + Add notes for a given object (defaults to `HEAD`). Abort if the object already has notes (use `-f` to overwrite existing notes). However, if you're using `add` interactively (using an editor to supply the notes contents), then - instead of aborting - @@ -71,10 +71,10 @@ add:: fine-tune the message(s) supplied from `-m` and `-F` options interactively (using an editor) before adding the note. -copy:: +`copy`:: Copy the notes for the first object onto the second object (defaults to - HEAD). Abort if the second object already has notes, or if the first - object has none (use -f to overwrite existing notes to the + `HEAD`). Abort if the second object already has notes, or if the first + object has none (use `-f` to overwrite existing notes to the second object). This subcommand is equivalent to: `git notes add [-f] -C $(git notes list ) ` + @@ -84,27 +84,27 @@ In `--stdin` mode, take lines in the format SP [ SP ] LF ---------- + -on standard input, and copy the notes from each to its -corresponding . (The optional `` is ignored so that +on standard input, and copy the notes from each __ to its +corresponding __. (The optional __ is ignored so that the command can read the input given to the `post-rewrite` hook.) -append:: +`append`:: Append new message(s) given by `-m` or `-F` options to an existing note, or add them as a new note if one does not - exist, for the object (defaults to HEAD). When appending to + exist, for the object (defaults to `HEAD`). When appending to an existing note, a blank line is added before each new message as an inter-paragraph separator. The separator can be customized with the `--separator` option. Edit the notes to be appended given by `-m` and `-F` options with `-e` interactively (using an editor) before appending the note. -edit:: - Edit the notes for a given object (defaults to HEAD). +`edit`:: + Edit the notes for a given object (defaults to `HEAD`). -show:: - Show the notes for a given object (defaults to HEAD). +`show`:: + Show the notes for a given object (defaults to `HEAD`). -merge:: +`merge`:: Merge the given notes ref into the current notes ref. This will try to merge the changes made by the given notes ref (called "remote") since the merge-base (if @@ -112,35 +112,35 @@ merge:: + If conflicts arise and a strategy for automatically resolving conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given, -the "manual" resolver is used. This resolver checks out the +the `manual` resolver is used. This resolver checks out the conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to manually resolve the conflicts there. When done, the user can either finalize the merge with -'git notes merge --commit', or abort the merge with -'git notes merge --abort'. +`git notes merge --commit`, or abort the merge with +`git notes merge --abort`. -remove:: - Remove the notes for given objects (defaults to HEAD). When +`remove`:: + Remove the notes for given objects (defaults to `HEAD`). When giving zero or one object from the command line, this is equivalent to specifying an empty note message to the `edit` subcommand. -prune:: +`prune`:: Remove all notes for non-existing/unreachable objects. -get-ref:: +`get-ref`:: Print the current notes ref. This provides an easy way to retrieve the current notes ref (e.g. from scripts). OPTIONS ------- --f:: ---force:: +`-f`:: +`--force`:: When adding notes to an object that already has notes, overwrite the existing notes (instead of aborting). --m :: ---message=:: +`-m `:: +`--message=`:: Use the given note message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. @@ -148,95 +148,96 @@ OPTIONS single line between paragraphs will be stripped out. If you wish to keep them verbatim, use `--no-stripspace`. --F :: ---file=:: - Take the note message from the given file. Use '-' to +`-F `:: +`--file=`:: + Take the note message from the given file. Use `-` to read the note message from the standard input. Lines starting with `#` and empty lines other than a single line between paragraphs will be stripped out. If you wish to keep them verbatim, use `--no-stripspace`. --C :: ---reuse-message=:: +`-C `:: +`--reuse-message=`:: Take the given blob object (for example, another note) as the note message. (Use `git notes copy ` instead to copy notes between objects.). By default, message will be copied verbatim, but if you wish to strip out the lines starting with `#` and empty lines other than a single line - between paragraphs, use with`--stripspace` option. + between paragraphs, use with `--stripspace` option. --c :: ---reedit-message=:: - Like '-C', but with `-c` the editor is invoked, so that +`-c `:: +`--reedit-message=`:: + Like `-C`, but with `-c` the editor is invoked, so that the user can further edit the note message. ---allow-empty:: +`--allow-empty`:: Allow an empty note object to be stored. The default behavior is to automatically remove empty notes. ---[no-]separator, --separator=:: +`--[no-]separator`:: +`--separator=`:: Specify a string used as a custom inter-paragraph separator (a newline is added at the end as needed). If `--no-separator`, no separators will be added between paragraphs. Defaults to a blank line. ---[no-]stripspace:: +`--[no-]stripspace`:: Strip leading and trailing whitespace from the note message. Also strip out empty lines other than a single line between paragraphs. Lines starting with `#` will be stripped out in non-editor cases like `-m`, `-F` and `-C`, but not in editor case like `git notes edit`, `-c`, etc. ---ref :: - Manipulate the notes tree in . This overrides - `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref +`--ref `:: + Manipulate the notes tree in __. This overrides + `GIT_NOTES_REF` and the `core.notesRef` configuration. The ref specifies the full refname when it begins with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed to form a full name of the ref. ---ignore-missing:: +`--ignore-missing`:: Do not consider it an error to request removing notes from an object that does not have notes attached to it. ---stdin:: +`--stdin`:: Also read the object names to remove notes from the standard input (there is no reason you cannot combine this with object names from the command line). --n:: ---dry-run:: +`-n`:: +`--dry-run`:: Do not remove anything; just report the object names whose notes would be removed. --s :: ---strategy=:: +`-s `:: +`--strategy=`:: When merging notes, resolve notes conflicts using the given - strategy. The following strategies are recognized: "manual" - (default), "ours", "theirs", "union" and "cat_sort_uniq". - This option overrides the "notes.mergeStrategy" configuration setting. + strategy. The following strategies are recognized: `manual` + (default), `ours`, `theirs`, `union` and `cat_sort_uniq`. + This option overrides the `notes.mergeStrategy` configuration setting. See the "NOTES MERGE STRATEGIES" section below for more information on each notes merge strategy. ---commit:: - Finalize an in-progress 'git notes merge'. Use this option - when you have resolved the conflicts that 'git notes merge' - stored in .git/NOTES_MERGE_WORKTREE. This amends the partial - merge commit created by 'git notes merge' (stored in - .git/NOTES_MERGE_PARTIAL) by adding the notes in - .git/NOTES_MERGE_WORKTREE. The notes ref stored in the - .git/NOTES_MERGE_REF symref is updated to the resulting commit. +`--commit`:: + Finalize an in-progress `git notes merge`. Use this option + when you have resolved the conflicts that `git notes merge` + stored in `.git/NOTES_MERGE_WORKTREE`. This amends the partial + merge commit created by `git notes merge` (stored in + `.git/NOTES_MERGE_PARTIAL`) by adding the notes in + `.git/NOTES_MERGE_WORKTREE`. The notes ref stored in the + `.git/NOTES_MERGE_REF` symref is updated to the resulting commit. ---abort:: - Abort/reset an in-progress 'git notes merge', i.e. a notes merge +`--abort`:: + Abort/reset an in-progress `git notes merge`, i.e. a notes merge with conflicts. This simply removes all files related to the notes merge. --q:: ---quiet:: +`-q`:: +`--quiet`:: When merging notes, operate quietly. --v:: ---verbose:: +`-v`:: +`--verbose`:: When merging notes, be more verbose. When pruning notes, report all object names whose notes are removed. @@ -270,28 +271,28 @@ object, in which case the history of the notes can be read with NOTES MERGE STRATEGIES ---------------------- -The default notes merge strategy is "manual", which checks out +The default notes merge strategy is `manual`, which checks out conflicting notes in a special work tree for resolving notes conflicts (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the conflicts in that work tree. When done, the user can either finalize the merge with -'git notes merge --commit', or abort the merge with -'git notes merge --abort'. +`git notes merge --commit`, or abort the merge with +`git notes merge --abort`. Users may select an automated merge strategy from among the following using -either -s/--strategy option or configuring notes.mergeStrategy accordingly: +either `-s`/`--strategy` option or configuring `notes.mergeStrategy` accordingly: -"ours" automatically resolves conflicting notes in favor of the local +`ours` automatically resolves conflicting notes in favor of the local version (i.e. the current notes ref). -"theirs" automatically resolves notes conflicts in favor of the remote +`theirs` automatically resolves notes conflicts in favor of the remote version (i.e. the given notes ref being merged into the current notes ref). -"union" automatically resolves notes conflicts by concatenating the +`union` automatically resolves notes conflicts by concatenating the local and remote versions. -"cat_sort_uniq" is similar to "union", but in addition to concatenating +`cat_sort_uniq` is similar to `union`, but in addition to concatenating the local and remote versions, this strategy also sorts the resulting lines, and removes duplicate lines from the result. This is equivalent to applying the "cat | sort | uniq" shell pipeline to the local and @@ -320,7 +321,7 @@ Notes: In principle, a note is a regular Git blob, and any kind of (non-)format is accepted. You can binary-safely create notes from -arbitrary files using 'git hash-object': +arbitrary files using `git hash-object`: ------------ $ cc *.c @@ -331,7 +332,7 @@ $ git notes --ref=built add --allow-empty -C "$blob" HEAD (You cannot simply use `git notes --ref=built add -F a.out HEAD` because that is not binary-safe.) Of course, it doesn't make much sense to display non-text-format notes -with 'git log', so if you use such notes, you'll probably need to write +with `git log`, so if you use such notes, you'll probably need to write some special-purpose tools to do something useful with them. @@ -339,7 +340,7 @@ some special-purpose tools to do something useful with them. CONFIGURATION ------------- -core.notesRef:: +`core.notesRef`:: Notes ref to read and manipulate instead of `refs/notes/commits`. Must be an unabbreviated ref name. This setting can be overridden through the environment and diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt index fbdbe0befe..db0e4279b5 100644 --- a/Documentation/git-range-diff.txt +++ b/Documentation/git-range-diff.txt @@ -10,7 +10,8 @@ SYNOPSIS [verse] 'git range-diff' [--color=[]] [--no-color] [] [--no-dual-color] [--creation-factor=] - [--left-only | --right-only] + [--left-only | --right-only] [--diff-merges=] + [--remerge-diff] ( | ... | ) [[--] ...] @@ -81,6 +82,20 @@ to revert to color all lines according to the outer diff markers Suppress commits that are missing from the second specified range (or the "right range" when using the `...` format). +--diff-merges=:: + Instead of ignoring merge commits, generate diffs for them using the + corresponding `--diff-merges=` option of linkgit:git-log[1], + and include them in the comparison. ++ +Note: In the common case, the `remerge` mode will be the most natural one +to use, as it shows only the diff on top of what Git's merge machinery would +have produced. In other words, if a merge commit is the result of a +non-conflicting `git merge`, the `remerge` mode will represent it with an empty +diff. + +--remerge-diff:: + Convenience option, equivalent to `--diff-merges=remerge`. + --[no-]notes[=]:: This flag is passed to the `git log` program (see linkgit:git-log[1]) that generates the patches. diff --git a/Documentation/git-refs.txt b/Documentation/git-refs.txt index ce31f93061..9829984b0a 100644 --- a/Documentation/git-refs.txt +++ b/Documentation/git-refs.txt @@ -57,8 +57,6 @@ KNOWN LIMITATIONS The ref format migration has several known limitations in its current form: -* It is not possible to migrate repositories that have reflogs. - * It is not possible to migrate repositories that have worktrees. * There is no way to block concurrent writes to the repository during an diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 975825b44a..751f01b441 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -7,10 +7,10 @@ git-restore - Restore working tree files SYNOPSIS -------- -[verse] -'git restore' [] [--source=] [--staged] [--worktree] [--] ... -'git restore' [] [--source=] [--staged] [--worktree] --pathspec-from-file= [--pathspec-file-nul] -'git restore' (-p|--patch) [] [--source=] [--staged] [--worktree] [--] [...] +[synopsis] +git restore [] [--source=] [--staged] [--worktree] [--] ... +git restore [] [--source=] [--staged] [--worktree] --pathspec-from-file= [--pathspec-file-nul] +git restore (-p|--patch) [] [--source=] [--staged] [--worktree] [--] [...] DESCRIPTION ----------- @@ -32,8 +32,8 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. OPTIONS ------- --s :: ---source=:: +`-s `:: +`--source=`:: Restore the working tree files with the content from the given tree. It is common to specify the source tree by naming a commit, branch or tag associated with it. @@ -41,79 +41,79 @@ OPTIONS If not specified, the contents are restored from `HEAD` if `--staged` is given, otherwise from the index. + -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`. +As a special case, you may use `"..."` as a shortcut for the +merge base of __ and __ if there is exactly one merge base. You can +leave out at most one of ___ and __, in which case it defaults to `HEAD`. --p:: ---patch:: +`-p`:: +`--patch`:: Interactively select hunks in the difference between the - restore source and the restore location. See the ``Interactive - Mode'' section of linkgit:git-add[1] to learn how to operate + restore source and the restore location. See the "Interactive + Mode" section of linkgit:git-add[1] to learn how to operate the `--patch` mode. + Note that `--patch` can accept no pathspec and will prompt to restore all modified paths. --W:: ---worktree:: --S:: ---staged:: +`-W`:: +`--worktree`:: +`-S`:: +`--staged`:: Specify the restore location. If neither option is specified, by default the working tree is restored. Specifying `--staged` will only restore the index. Specifying both restores both. --q:: ---quiet:: +`-q`:: +`--quiet`:: Quiet, suppress feedback messages. Implies `--no-progress`. ---progress:: ---no-progress:: +`--progress`:: +`--no-progress`:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless `--quiet` is specified. This flag enables progress reporting even if not attached to a terminal, regardless of `--quiet`. ---ours:: ---theirs:: +`--ours`:: +`--theirs`:: When restoring files in the working tree from the index, use - stage #2 ('ours') or #3 ('theirs') for unmerged paths. + stage #2 (`ours`) or #3 (`theirs`) for unmerged paths. This option cannot be used when checking out paths from a tree-ish (i.e. with the `--source` option). + -Note that during `git rebase` and `git pull --rebase`, 'ours' and -'theirs' may appear swapped. See the explanation of the same options +Note that during `git rebase` and `git pull --rebase`, `ours` and +`theirs` may appear swapped. See the explanation of the same options in linkgit:git-checkout[1] for details. --m:: ---merge:: +`-m`:: +`--merge`:: When restoring files on the working tree from the index, recreate the conflicted merge in the unmerged paths. This option cannot be used when checking out paths from a tree-ish (i.e. with the `--source` option). ---conflict=