diff --git a/.gitattributes b/.gitattributes index 26490ad60a74d0..0a0fc950b169ec 100644 --- a/.gitattributes +++ b/.gitattributes @@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace /t/oid-info/* text eol=lf /Documentation/git-merge.adoc conflict-marker-size=32 /Documentation/git-merge-file.adoc conflict-marker-size=32 +/Documentation/gitmergeconflicts.adoc conflict-marker-size=32 /Documentation/gitk.adoc conflict-marker-size=32 /Documentation/user-manual.adoc conflict-marker-size=32 /t/t????-*.sh conflict-marker-size=32 diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index fe8155772ab832..2531a6bc535eda 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -65,7 +65,7 @@ jobs: echo "skip_concurrent=$skip_concurrent" >>$GITHUB_OUTPUT - name: skip if the commit or tree was already tested id: skip-if-redundant - uses: actions/github-script@v9 + uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9 if: steps.check-ref.outputs.enabled == 'yes' with: github-token: ${{secrets.GITHUB_TOKEN}} @@ -114,8 +114,8 @@ jobs: group: windows-build-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v6 - - uses: git-for-windows/setup-git-for-windows-sdk@v2 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + - uses: git-for-windows/setup-git-for-windows-sdk@aed153d1258c311b680b81584a72a1a4807401f0 # v2 - name: Install GCC-compatible Rust target shell: bash run: | @@ -149,7 +149,7 @@ jobs: - name: zip up tracked files run: git archive -o artifacts/tracked.tar.gz HEAD - name: upload tracked files and build artifacts - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: windows-artifacts path: artifacts @@ -166,14 +166,14 @@ jobs: cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - name: download tracked files and build artifacts - uses: actions/download-artifact@v8 + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: name: windows-artifacts path: ${{github.workspace}} - name: extract tracked files and build artifacts shell: bash run: tar xf artifacts.tar.gz && tar xf tracked.tar.gz - - uses: git-for-windows/setup-git-for-windows-sdk@v2 + - uses: git-for-windows/setup-git-for-windows-sdk@aed153d1258c311b680b81584a72a1a4807401f0 # v2 - name: test shell: bash run: . /etc/profile && ci/run-test-slice.sh $((${{matrix.nr}} + 1)) 10 @@ -183,7 +183,7 @@ jobs: run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: failed-tests-windows-${{ matrix.nr }} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -199,20 +199,20 @@ jobs: group: vs-build-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v6 - - uses: git-for-windows/setup-git-for-windows-sdk@v2 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + - uses: git-for-windows/setup-git-for-windows-sdk@aed153d1258c311b680b81584a72a1a4807401f0 # v2 - name: initialize vcpkg - uses: actions/checkout@v6 + uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 with: repository: 'microsoft/vcpkg' path: 'compat/vcbuild/vcpkg' - name: download vcpkg artifacts - uses: git-for-windows/get-azure-pipelines-artifact@v0 + uses: git-for-windows/get-azure-pipelines-artifact@2e424b98e1251b725d6064c5f1a9f854a33e5b88 # v0 with: repository: git/git definitionId: 9 - name: add msbuild to PATH - uses: microsoft/setup-msbuild@v3 + uses: microsoft/setup-msbuild@30375c66a4eea26614e0d39710365f22f8b0af57 # v3 - name: copy dlls to root shell: cmd run: compat\vcbuild\vcpkg_copy_dlls.bat release @@ -234,7 +234,7 @@ jobs: - name: zip up tracked files run: git archive -o artifacts/tracked.tar.gz HEAD - name: upload tracked files and build artifacts - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: vs-artifacts path: artifacts @@ -250,9 +250,9 @@ jobs: group: vs-test-${{ matrix.nr }}-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: git-for-windows/setup-git-for-windows-sdk@v2 + - uses: git-for-windows/setup-git-for-windows-sdk@aed153d1258c311b680b81584a72a1a4807401f0 # v2 - name: download tracked files and build artifacts - uses: actions/download-artifact@v8 + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: name: vs-artifacts path: ${{github.workspace}} @@ -270,7 +270,7 @@ jobs: run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: failed-tests-windows-vs-${{ matrix.nr }} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -284,8 +284,8 @@ jobs: group: windows-meson-build-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v6 - - uses: actions/setup-python@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 - name: Set up dependencies shell: pwsh run: pip install meson ninja @@ -296,7 +296,7 @@ jobs: shell: pwsh run: meson compile -C build - name: Upload build artifacts - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: windows-meson-artifacts path: build @@ -312,13 +312,13 @@ jobs: group: windows-meson-test-${{ matrix.nr }}-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v6 - - uses: actions/setup-python@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 - name: Set up dependencies shell: pwsh run: pip install meson ninja - name: Download build artifacts - uses: actions/download-artifact@v8 + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: name: windows-meson-artifacts path: build @@ -331,7 +331,7 @@ jobs: run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: failed-tests-windows-meson-${{ matrix.nr }} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -349,16 +349,16 @@ jobs: vector: - jobname: osx-clang cc: clang - pool: macos-14 + pool: macos-15 - jobname: osx-reftable cc: clang - pool: macos-14 + pool: macos-26 - jobname: osx-gcc cc: gcc-13 - pool: macos-14 + pool: macos-26 - jobname: osx-meson cc: clang - pool: macos-14 + pool: macos-15 env: CC: ${{matrix.vector.cc}} CC_PACKAGE: ${{matrix.vector.cc_package}} @@ -367,7 +367,7 @@ jobs: TEST_OUTPUT_DIRECTORY: ${{github.workspace}}/t runs-on: ${{matrix.vector.pool}} steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 - run: ci/install-dependencies.sh - run: ci/run-build-and-tests.sh - name: print test failures @@ -375,7 +375,7 @@ jobs: run: ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: failed-tests-${{matrix.vector.jobname}} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -388,7 +388,7 @@ jobs: CI_JOB_IMAGE: ubuntu-latest runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 - run: ci/install-dependencies.sh - run: ci/run-build-and-minimal-fuzzers.sh dockerized: @@ -405,9 +405,6 @@ jobs: - jobname: linux-sha256 image: ubuntu:rolling cc: clang - - jobname: linux-reftable-sha256 - image: ubuntu:rolling - cc: clang - jobname: linux-feature-testbed image: ubuntu:latest - jobname: linux-breaking-changes @@ -464,7 +461,7 @@ jobs: else apt-get -q update && apt-get -q -y install git fi - - uses: actions/checkout@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 - run: ci/install-dependencies.sh - run: useradd builder --create-home - run: chown -R builder . @@ -474,7 +471,7 @@ jobs: run: sudo --preserve-env --set-home --user=builder ci/print-test-failures.sh - name: Upload failed tests' directories if: failure() && env.FAILED_TEST_ARTIFACTS != '' - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: failed-tests-${{matrix.vector.jobname}} path: ${{env.FAILED_TEST_ARTIFACTS}} @@ -489,7 +486,7 @@ jobs: group: static-analysis-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 - run: ci/install-dependencies.sh - run: ci/run-static-analysis.sh - run: ci/check-directional-formatting.bash @@ -505,7 +502,7 @@ jobs: group: rust-analysis-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 - run: ci/install-dependencies.sh - run: ci/run-rust-checks.sh sparse: @@ -519,7 +516,7 @@ jobs: group: sparse-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 - name: Install other dependencies run: ci/install-dependencies.sh - run: make sparse @@ -535,6 +532,6 @@ jobs: CI_JOB_IMAGE: ubuntu-latest runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 - run: ci/install-dependencies.sh - run: ci/test-documentation.sh diff --git a/.gitignore b/.gitignore index 0209bd16f209c2..501605abe01775 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,4 @@ /fuzz_corpora -/target/ -/Cargo.lock /GIT-BUILD-DIR /GIT-BUILD-OPTIONS /GIT-CFLAGS @@ -262,3 +260,5 @@ Release/ /contrib/buildsystems/out /contrib/libgit-rs/target /contrib/libgit-sys/target +/rust/target +/rust/Cargo.lock diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 9b7698a00370cb..843d0c17bb8c24 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -39,9 +39,6 @@ test:linux: - jobname: linux-sha256 image: ubuntu:rolling CC: clang - - jobname: linux-reftable-sha256 - image: ubuntu:rolling - CC: clang - jobname: linux-feature-testbed image: ubuntu:latest - jobname: linux-breaking-changes @@ -253,6 +250,8 @@ check-whitespace: image: ubuntu:latest stage: analyze needs: [ ] + variables: + GIT_DEPTH: 0 before_script: - ./ci/install-dependencies.sh # Since $CI_MERGE_REQUEST_TARGET_BRANCH_SHA is only defined for merged @@ -273,6 +272,7 @@ check-style: variables: CC: clang jobname: ClangFormat + GIT_DEPTH: 0 before_script: - ./ci/install-dependencies.sh # Since $CI_MERGE_REQUEST_TARGET_BRANCH_SHA is only defined for merged diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc index c2cef3f528fcac..62fbbd2a1390ae 100644 --- a/Documentation/BreakingChanges.adoc +++ b/Documentation/BreakingChanges.adoc @@ -171,6 +171,11 @@ JGit, libgit2 and Gitoxide need to support it. matches the default branch name used in new repositories by many of the big Git forges. +* Git will accept hex object IDs only in lowercase. The fact that Git has + historically allowed uppercase characters in hex object IDs has been the + source of a variety of bugs and security problems in software using Git. We + don't expect most users to notice any change. + * Git will require Rust as a mandatory part of the build process. While Git already started to adopt Rust in Git 2.49, all parts written in Rust are optional for the time being. This includes: diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index c06f5d3071968c..23a4d2186af430 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -311,13 +311,8 @@ For C programs: . since late 2023 with 8277dbe987 we have been using the bool type from . - C99 features we have test balloons for: - - . since late 2024 with v2.48.0-rc0~20, we have test balloons for - compound literal syntax, e.g., (struct foo){ .member = value }; - our hope is that no platforms we care about have trouble using - them, and officially adopt its wider use in mid 2026. Do not add - more use of the syntax until that happens. + . since late 2024 with v2.48.0-rc0~20, we have been using compound + literals, e.g., (struct foo){ .member = value }; New C99 features that we cannot use yet: diff --git a/Documentation/Makefile b/Documentation/Makefile index f8dea4b3953250..573877496f1015 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -54,10 +54,12 @@ MAN7_TXT += gitcore-tutorial.adoc MAN7_TXT += gitcredentials.adoc MAN7_TXT += gitcvs-migration.adoc MAN7_TXT += gitdatamodel.adoc +MAN7_TXT += gitdetached-head.adoc MAN7_TXT += gitdiffcore.adoc MAN7_TXT += giteveryday.adoc MAN7_TXT += gitfaq.adoc MAN7_TXT += gitglossary.adoc +MAN7_TXT += gitmergeconflicts.adoc MAN7_TXT += gitpacking.adoc MAN7_TXT += gitnamespaces.adoc MAN7_TXT += gitremote-helpers.adoc @@ -122,6 +124,7 @@ TECH_DOCS += technical/bitmap-format TECH_DOCS += technical/build-systems TECH_DOCS += technical/bundle-uri TECH_DOCS += technical/commit-graph +TECH_DOCS += technical/connectivity-check TECH_DOCS += technical/directory-rename-detection TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/large-object-promisors diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index 34bfa2e3a9aaec..c58253fd54c141 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -1174,85 +1174,6 @@ press `y` or `a` at these prompts your emails will be sent! Congratulations! Awesome, now the community will drop everything and review your changes. (Just kidding - be patient!) -[[v2-git-send-email]] -=== Sending v2 - -This section will focus on how to send a v2 of your patchset. To learn what -should go into v2, skip ahead to <> for -information on how to handle comments from reviewers. - -We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll -mark the tip of our v1 branch for easy reference: - ----- -$ git checkout psuh -$ git branch psuh-v1 ----- - -Refine your patch series by using `git rebase -i` to adjust commits based upon -reviewer comments. Once the patch series is ready for submission, generate your -patches again, but with some new flags: - ----- -$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master.. ----- - -The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a -range-diff between `psuh-v1` and `psuh` in the cover letter (see -linkgit:git-range-diff[1]). This helps tell reviewers about the differences -between your v1 and v2 patches. - -The `-v2` parameter tells `format-patch` to output your patches -as version "2". For instance, you may notice that your v2 patches are -all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format -your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]", -and your range-diff will be prefaced with "Range-diff against v1". - -After you run this command, `format-patch` will output the patches to the `psuh/` -directory, alongside the v1 patches. Using a single directory makes it easy to -refer to the old v1 patches while proofreading the v2 patches, but you will need -to be careful to send out only the v2 patches. We will use a pattern like -`psuh/v2-*.patch` (not `psuh/*.patch`, which would match v1 and v2 patches). - -Edit your cover letter again. Now is a good time to mention what's different -between your last version and now, if it's something significant. You do not -need the exact same body in your second cover letter; focus on explaining to -reviewers the changes you've made that may not be as visible. - -You will also need to go and find the Message-ID of your first cover letter. -You can either note it when you send the first series, from the output of `git -send-email`, or you can look it up on the -https://lore.kernel.org/git[mailing list]. Find your cover letter in the -archives, click on it, then click "permalink" or "raw" to reveal the Message-ID -header. It should match: - ----- -Message-ID: ----- - -Your Message-ID is ``. This example will be used -below as well; make sure to replace it with the correct Message-ID for your -**first cover letter** - that is, for any subsequent version that you send, -always use the Message-ID from v1. - -While you're looking at the email, you should also note who is CC'd, as it's -common practice in the mailing list to keep all CCs on a thread. You can add -these CC lines directly to your cover letter with a line like so in the header -(before the Subject line): - ----- -CC: author@example.com, Othe R ----- - -Now send the emails again, paying close attention to which messages you pass in -to the command: - ----- -$ git send-email --to=target@example.com - --in-reply-to="" - psuh/v2-*.patch ----- - [[single-patch]] === Bonus Chapter: One-Patch Changes @@ -1348,29 +1269,6 @@ Once you are happy with the result, send the series with: $ b4 send ---- -[[v2-b4]] -=== Sending v2 - -When you are ready to send a new iteration of your series, refine your -patches as usual using linkgit:git-rebase[1]. Note that you typically want to -rebase on top of the cover letter. You can configure an alias to enable easy -rebases going forward: - ---- -$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"' -$ git b4-rebase -i ---- - -Before sending out the new version you should also update the cover letter with -`b4 prep --edit-cover` to note the relevant changes compared to the previous -version. You can inspect the changes between the two versions with `b4 prep ---compare-to=v1`. - -Same as with the first version, you can use `b4 send` to send out the second -version. `b4` automatically bumps the version to `v2`, generates the range-diff -against the previous iteration, and threads the new series as a reply to the -cover letter of the first version. - [[configure-b4]] === Configure b4 @@ -1416,56 +1314,33 @@ previous one" patches over 2 days), reviewers would strongly prefer if a single polished version came 2 days later instead, and that version with fewer mistakes were the only one they would need to review. -This consideration applies not only when going from the initial patch to v2, -but also to later iterations of the same series. There is no fixed rule for how -long to wait before sending a new version. A useful default is to send at most -one new version of the same patch series per day. This gives multiple reviewers -time to comment, gives reviewers across time zones a fair chance to -participate, lets you batch feedback together, and gives you time to think -through the comments you received. Knowing that you should not immediately send -another version also encourages you to review the patches more carefully before -sending them, catch small mistakes such as typos and off-by-one errors -yourself, and let reviewers spend more of their attention on design, -algorithms, and other substantial issues. - -The right timing depends on the topic and the feedback. Larger series usually -need more review time. If the only comments so far are minor, such as typo -fixes, it often makes sense to wait a little longer in case deeper reviews are -still coming. If the comments call for substantial rework, do not rush out an -updated version before you have reviewed the larger changes carefully. Instead, -reply to the review that prompted the rewrite, say that you are preparing a -substantial rework, and mention which parts of the current series will become -obsolete so reviewers can avoid spending time on them until the updated series -is ready. - [[reviewing]] === Responding to Reviews -After a few days, you will hopefully receive a reply to your patchset with some -comments. Woohoo! Now you can get back to work. - -It's good manners to reply to each comment in the mailing list discussion -instead of letting the next version of your patch be your only response. Tell -the reviewer whether you plan to make the suggested change, keep the original, -or pursue a different approach. This way reviewers can respond to your reasoning -before you spend time preparing a version they may not agree with, and later do -not need to inspect your v2 to figure out whether you implemented their comment -or not. - -Reviewers may ask you about what you wrote in the patchset, either in -the proposed commit log message or in the changes themselves. You -should answer these questions in your response messages, but often the -reason why reviewers asked these questions to understand what you meant -to write is because your patchset needed clarification to be understood. - -Do not be satisfied by just answering their questions in your response -and hear them say that they now understand what you wanted to say. -Update your patches to clarify the points reviewers had trouble with, -and prepare your v2; the words you used to explain your v1 to answer -reviewers' questions may be useful thing to use. Your goal is to make -your v2 clear enough so that it becomes unnecessary for you to give the -same explanation to the next person who reads it. +After a few days, you may receive comments on your patch series. +Carefully read them to understand the reviewers' perspective, and do +not hesitate to ask for clarification. + +Reviewers may also ask about your proposed commit log or the changes. +Answer these in your response. They often ask because the patch needs +clarification; use this feedback to improve your writing, and update +the patch so the next reader does not have to ask the same question. + +Do not start coding, much less send the next version, until you finish +discussing the current one and both sides know what to expect. This +saves time, lets reviewers respond before you write a patch they have +to reject, and avoids forcing them to inspect 'v2' only to find their +concerns unaddressed. + +Do not iterate too quickly; at most one iteration per day is good +practice. This allows multiple reviewers to comment, gives +participants in different time zones a fair chance, lets you batch +feedback, and gives you time to digest comments before coding. + +Knowing you cannot immediately send another version encourages careful +self-review, letting you catch small mistakes yourself so reviewers +can focus on design and other substantive issues. If you are going to push back on a comment, be polite and explain why you feel your original is better; be prepared that the reviewer may still disagree with @@ -1501,6 +1376,108 @@ changing history, but since it's local history which you haven't shared with anyone, that is okay for now! (Later, it may not make sense to do this; take a look at the section below this one for some context.) +[[v2-git-send-email]] +=== Sending v2 + +This section will focus on how to send a v2 of your patchset. To learn what +should go into v2, skip ahead to <> for +information on how to handle comments from reviewers. + +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll +mark the tip of our v1 branch for easy reference: + +---- +$ git checkout psuh +$ git branch psuh-v1 +---- + +Refine your patch series by using `git rebase -i` to adjust commits based upon +reviewer comments. Once the patch series is ready for submission, generate your +patches again, but with some new flags: + +---- +$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master.. +---- + +The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a +range-diff between `psuh-v1` and `psuh` in the cover letter (see +linkgit:git-range-diff[1]). This helps tell reviewers about the differences +between your v1 and v2 patches. + +The `-v2` parameter tells `format-patch` to output your patches +as version "2". For instance, you may notice that your v2 patches are +all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format +your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]", +and your range-diff will be prefaced with "Range-diff against v1". + +After you run this command, `format-patch` will output the patches to the `psuh/` +directory, alongside the v1 patches. Using a single directory makes it easy to +refer to the old v1 patches while proofreading the v2 patches, but you will need +to be careful to send out only the v2 patches. We will use a pattern like +`psuh/v2-*.patch` (not `psuh/*.patch`, which would match v1 and v2 patches). + +Edit your cover letter again. Now is a good time to mention what's different +between your last version and now, if it's something significant. You do not +need the exact same body in your second cover letter; focus on explaining to +reviewers the changes you've made that may not be as visible. + +You will also need to go and find the Message-ID of your first cover letter. +You can either note it when you send the first series, from the output of `git +send-email`, or you can look it up on the +https://lore.kernel.org/git[mailing list]. Find your cover letter in the +archives, click on it, then click "permalink" or "raw" to reveal the Message-ID +header. It should match: + +---- +Message-ID: +---- + +Your Message-ID is ``. This example will be used +below as well; make sure to replace it with the correct Message-ID for your +**first cover letter** - that is, for any subsequent version that you send, +always use the Message-ID from v1. + +While you're looking at the email, you should also note who is CC'd, as it's +common practice in the mailing list to keep all CCs on a thread. You can add +these CC lines directly to your cover letter with a line like so in the header +(before the Subject line): + +---- +CC: author@example.com, Othe R +---- + +Now send the emails again, paying close attention to which messages you pass in +to the command: + +---- +$ git send-email --to=target@example.com + --in-reply-to="" + psuh/v2-*.patch +---- + +[[v2-b4]] +=== Sending v2 + +When you are ready to send a new iteration of your series, refine your +patches as usual using linkgit:git-rebase[1]. Note that you typically want to +rebase on top of the cover letter. You can configure an alias to enable easy +rebases going forward: + +--- +$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"' +$ git b4-rebase -i +--- + +Before sending out the new version you should also update the cover letter with +`b4 prep --edit-cover` to note the relevant changes compared to the previous +version. You can inspect the changes between the two versions with `b4 prep +--compare-to=v1`. + +Same as with the first version, you can use `b4 send` to send out the second +version. `b4` automatically bumps the version to `v2`, generates the range-diff +against the previous iteration, and threads the new series as a reply to the +cover letter of the first version. + [[after-approval]] === After Review Approval diff --git a/Documentation/MyFirstObjectWalk.adoc b/Documentation/MyFirstObjectWalk.adoc index 413a9fdb05c56e..76e635b93ac034 100644 --- a/Documentation/MyFirstObjectWalk.adoc +++ b/Documentation/MyFirstObjectWalk.adoc @@ -145,7 +145,7 @@ used to track the allocated size of the list. Per entry, we find: `item` is the object provided upon which to base the object walk. Items in Git -can be blobs, trees, commits, or tags. (See `Documentation/gittutorial-2.adoc`.) +can be blobs, trees, commits, or tags. (See `Documentation/gitdatamodel.adoc`.) `name` is the object ID (OID) of the object - a hex string you may be familiar with from using Git to organize your source in the past. Check the tutorial diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c60855f7069492..3238a339320a9a 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -271,6 +271,15 @@ fixed by accident to avoid regression. Also, try merging your work to that are still in flight may have unexpected interactions with what you are trying to do in your topic. +A bugfix patch should include tests in test_expect_success() blocks that +demonstrate the breakage when the code change that implements the fix is +omitted. Submit tests as `test_expect_success` in the same commit as +your code change that fixes the bug. A separate commit that only changes +`test_expect_failure` to `test_expect_success` can leave the behavior +being tested out of the diff context, making the fix harder to review. +Reviewers who want to verify that your test reproduces the bug can +temporarily undo the code changes while keeping the test. + Pushing to a fork of https://github.com/git/git will use their CI integration to test your changes on Linux, Mac and Windows. See the <> section for details. diff --git a/Documentation/config/advice.adoc b/Documentation/config/advice.adoc index 3d91c90eda72f9..83039ba48bc797 100644 --- a/Documentation/config/advice.adoc +++ b/Documentation/config/advice.adoc @@ -98,6 +98,10 @@ all advice messages. Shown when linkgit:git-push[1] rejects a forced update of a branch when its remote-tracking ref has updates that we do not have locally. + pushRefUnverifiable:: + Shown when linkgit:git-push[1] rejects a forced update of + a branch when we are unable to verify the remote-tracking + ref is integrated locally. pushRepoLooksLikeRef:: Shown when the repository given to linkgit:git-push[1] is not a configured remote but looks like a `/` ref, @@ -132,6 +136,10 @@ all advice messages. give directions on how to proceed from the current state. sequencerInUse:: Shown when a sequencer command is already in progress. + shallowHistory:: + Shown when `~` cannot resolve enough ancestors of + `` because history stops at a shallow boundary, to + suggest fetching more history. skippedCherryPicks:: Shown when linkgit:git-rebase[1] skips a commit that has already been cherry-picked onto the upstream branch. diff --git a/Documentation/config/branch.adoc b/Documentation/config/branch.adoc index c2acd89c9936cb..be9b296bdad25f 100644 --- a/Documentation/config/branch.adoc +++ b/Documentation/config/branch.adoc @@ -106,7 +106,7 @@ for details). `branch..deleteMerged`:: If set to `false`, branch __ is exempt from - `git branch --delete-merged`. Useful for a topic branch you - intend to develop further after an initial round has been - merged upstream. Defaults to true. Explicit deletion via - `git branch -d` is unaffected. + `git branch --delete-merged` and `--delete-integrated`. Useful + for a topic branch you intend to develop further after an + initial round has been merged upstream. Defaults to true. + Explicit deletion via `git branch -d` is unaffected. diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc index bdc74d291cc38c..c56436092fd672 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -376,7 +376,7 @@ core.logAllRefUpdates:: `refs/heads/`), remote refs (i.e. under `refs/remotes/`), note refs (i.e. under `refs/notes/`), and the symbolic ref `HEAD`. If it is set to `always`, then a missing reflog is automatically - created for any ref under `refs/`. + created for any ref, including root refs such as `ORIG_HEAD`. + This information can be used to determine what commit was the tip of a branch "2 days ago". @@ -604,6 +604,12 @@ core.configLockTimeout:: that is already on disk before the lock is taken, so it can be set persistently like any other option. +core.indexLockTimeout:: + The length of time, in milliseconds, to retry when trying to + lock the index file for writing. Value 0 means not to retry at + all; -1 means to try indefinitely. Default is 1000 (i.e., retry + for 1 second). Not supported by all commands. + core.pager:: Text viewer for use by Git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc index be6678bb5b5585..4f3a66a4543434 100644 --- a/Documentation/config/extensions.adoc +++ b/Documentation/config/extensions.adoc @@ -56,6 +56,29 @@ preciousObjects::: For historical reasons, this extension is respected regardless of the `core.repositoryFormatVersion` setting. +objectStorage::: + Specify the object storage format and a corresponding payload. The + value can be either a format name or a URI: ++ +-- +* A format name alone (e.g., `files`). + +* A URI format `://` explicitly specifies both the + format and payload (e.g., `files:///foo/bar`). + +Supported formats are: + +include::../object-storage-format.adoc[] + +-- ++ +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 make +preexisting objects inaccessible. ++ +NOTE: This extension is still considered EXPERIMENTAL and may be subject to +change. + refStorage::: Specify the ref storage format and a corresponding payload. The value can be either a format name or a URI: diff --git a/Documentation/config/fetch.adoc b/Documentation/config/fetch.adoc index 00435e9a16d9f9..20bf199b447404 100644 --- a/Documentation/config/fetch.adoc +++ b/Documentation/config/fetch.adoc @@ -10,6 +10,20 @@ reference. Defaults to `on-demand`, or to the value of `submodule.recurse` if set. +`fetch.submoduleErrors`:: + Controls how errors from submodule fetches are handled when + `--recurse-submodules` is in effect. When set to `fail` (the default), + any submodule fetch error causes the overall `git fetch` or `git pull` + to exit with a non-zero status. When set to `warn`, submodule fetch + errors are reported to standard error but do not affect the exit + status of the command. This is useful when working in repositories + where some branches reference submodule commits that are not yet + available on the submodule remote, but those commits are not needed + for the currently checked-out branch. ++ +The value of this option can be overridden by the `--submodule-errors` +option of linkgit:git-fetch[1]. + `fetch.fsckObjects`:: If it is set to true, git-fetch-pack will check all fetched objects. See `transfer.fsckObjects` for what's diff --git a/Documentation/config/gpg.adoc b/Documentation/config/gpg.adoc index 240e46c050545c..4970766e03a6e4 100644 --- a/Documentation/config/gpg.adoc +++ b/Documentation/config/gpg.adoc @@ -70,9 +70,9 @@ A repository that only allows signed commits can store the file in the repository itself using a path relative to the top-level of the working tree. This way only committers with an already valid key can add or change keys in the keyring. + -Since OpensSSH 8.8 this file allows specifying a key lifetime using valid-after & -valid-before options. Git will mark signatures as valid if the signing key was -valid at the time of the signature's creation. This allows users to change a +Since OpenSSH 8.8 this file allows specifying a key lifetime using valid-after & +valid-before options. Git validates the signature by checking the committer or +tagger timestamp is within the validity time range. This allows users to change a signing key without invalidating all previously made signatures. + Using a SSH CA key with the cert-authority option @@ -83,3 +83,6 @@ gpg.ssh.revocationFile:: See ssh-keygen(1) for details. If a public key is found in this file then it will always be treated as having trust level "never" and signatures will show as invalid. + If the file does not exist, signature verification fails, unless + the path is prefixed with `:(optional)` (see the `pathname` type in + linkgit:git-config[1]). diff --git a/Documentation/config/hook.adoc b/Documentation/config/hook.adoc index 083dc60a1325f2..332657e70f2f0b 100644 --- a/Documentation/config/hook.adoc +++ b/Documentation/config/hook.adoc @@ -47,7 +47,8 @@ hook..parallel:: the effective job count is greater than 1. {see-git-hook} hook..enabled:: - Switch to enable or disable all hooks for the `` hook event. + Switch to enable or disable all hooks for the `` hook event, + configured hooks and the traditional hook in the hooks directory alike. When set to `false`, no hooks fire for that event, regardless of any per-hook `hook..enabled` settings. Defaults to `true`. {see-git-hook} diff --git a/Documentation/config/init.adoc b/Documentation/config/init.adoc index e45bd692dbc91e..dbd9c663ee3268 100644 --- a/Documentation/config/init.adoc +++ b/Documentation/config/init.adoc @@ -20,6 +20,11 @@ endif::[] precedence over this config. `init.defaultRefFormat`:: Deprecated alias of `init.defaultRefStorageFormat`. +`init.defaultObjectStorageFormat`:: + Allows overriding the default object storage format for new + repositories. See `--object-storage-format=` in linkgit:git-init[1]. + Both the command line option and the `GIT_DEFAULT_OBJECT_STORAGE_FORMAT` + environment variable take precedence over this config. init.defaultSubmodulePathConfig:: A boolean that specifies if `git init` and `git clone` should diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc index 3a20d0f7524e72..1a6455af6cfe65 100644 --- a/Documentation/config/remote.adoc +++ b/Documentation/config/remote.adoc @@ -33,6 +33,15 @@ remote..fetch:: The default set of "refspec" for linkgit:git-fetch[1]. See linkgit:git-fetch[1]. +remote..fetchRefmap:: + The default value of the `--refmap` option, used to map refs being + fetched to remote-tracking refs to store, the same way + `remote..fetch` does for an explicit refspec. + `remote..fetch`, if also configured, still decides what is + fetched. If it is not set either, a refspec-less fetch instead + infers what to fetch from local branches built on this remote. + See the `--refmap` entry in linkgit:git-fetch[1]. + remote..push:: The default set of "refspec" for linkgit:git-push[1]. See linkgit:git-push[1]. @@ -173,5 +182,5 @@ remote..followRemoteHEAD:: accepted values. + In addition to the values supported by `fetch.followRemoteHEAD`, this setting -may also take on the value "warn-if-not-`$branch`", which behaves like "warn", -but ignores the warning if the remote's `HEAD` is `remotes//$branch`. +may also take on the value "warn-if-not-``", which behaves like "warn", +but ignores the warning if the remote's `HEAD` is `remotes//`. diff --git a/Documentation/config/rerere.adoc b/Documentation/config/rerere.adoc index 3a78b5ebb1dc02..60e78e499fbd4d 100644 --- a/Documentation/config/rerere.adoc +++ b/Documentation/config/rerere.adoc @@ -10,3 +10,12 @@ rerere.enabled:: enabled if there is an `rr-cache` directory under the `$GIT_DIR`, e.g. if "rerere" was previously used in the repository. + +rerere.lockTimeout:: + The length of time, in milliseconds, to wait for the rerere + lock when another process holds it, typically a background + `git rerere gc`. Value 0 means not to wait at all; -1 means + to wait indefinitely. Default is 1000 (i.e., wait for 1 + second). A `git rerere gc` run by `git maintenance run --auto` + or `git gc --auto` does not wait and does nothing while the + lock is held. diff --git a/Documentation/config/status.adoc b/Documentation/config/status.adoc index b5dd85b761f6f9..1d847d3a8ac497 100644 --- a/Documentation/config/status.adoc +++ b/Documentation/config/status.adoc @@ -23,8 +23,9 @@ status.compareBranches:: are supported. They are interpreted as `branch@{upstream}` and `branch@{push}` for the current branch. + -If not set, the default behavior is equivalent to `@{upstream}`, which -compares against the configured upstream tracking branch. +If not set, the default behavior is equivalent to `@{upstream} @{push}`, +which compares against both the configured upstream and push tracking +branches. + The entries are shown in the order they appear in the configuration. Duplicate entries that resolve to the same ref are suppressed after @@ -36,11 +37,11 @@ Example: + ---- [status] - compareBranches = @{upstream} @{push} + compareBranches = @{upstream} ---- + -This would show comparisons against both the configured upstream and push -tracking branches for the current branch. +This would only show the comparison against the configured upstream +tracking branch for the current branch. status.displayCommentPrefix:: If set to true, linkgit:git-status[1] will insert a comment diff --git a/Documentation/config/transfer.adoc b/Documentation/config/transfer.adoc index f1ce50f4a6e6ba..f77b25ff8b9732 100644 --- a/Documentation/config/transfer.adoc +++ b/Documentation/config/transfer.adoc @@ -1,3 +1,33 @@ +transfer.connectivityCheck:: + Choose which algorithm to use for the connectivity check + performed during object transfer operations such as + linkgit:git-fetch[1] and linkgit:git-receive-pack[1]. + The connectivity check verifies that all objects reachable + from the incoming tips are available locally or, in a partial + clone, promised by a promisor remote. + The variants are as follows: ++ +-- +`full` (default);; + Walk the full object closure of the boundary commits. +`incremental`;; + Verify incoming commits by diffing their trees against parent + trees, recursively descending only into entries that differ. + The largest benefits occur when incoming commits change a + small fraction of a large tree closure, and it can be slower + than `full` when there are many incoming commits. + Falls back to `full` for clones, pushes into an empty + repository and deepening fetches. +`auto`;; +`auto=`;; + Choose between `full` and `incremental` with a heuristic. + Currently `incremental` is used when there are at most + __ incoming commits (1000 by default), and `full` + otherwise. The heuristic may change in future versions. +-- ++ +Unknown values are treated as `full`, with a warning. + transfer.credentialsInUrl:: A configured URL can contain plaintext credentials in the form `://:@/`. You may want diff --git a/Documentation/detached-head.adoc b/Documentation/detached-head.adoc new file mode 100644 index 00000000000000..a918a7579985f0 --- /dev/null +++ b/Documentation/detached-head.adoc @@ -0,0 +1,60 @@ +`HEAD` is where Git stores your current branch or commit. `HEAD` can either be: + +1. A branch, which is your current branch. +2. A commit ID, when you don't have a current branch. + This is called "detached HEAD state". + +It can sometimes be useful for `HEAD` to be a commit ID, because +it lets you easily check out an old version of your project. For +example, a data scientist could use this to run an old version of a +data pipeline or a programmer could use this to figure out when a bug +was introduced. + +But it's important to know that if you create new commits while in +detached HEAD state, those commits won't be on a branch. This makes +those new commits much harder to find later. Also, Git considers commits +that aren't on any branch (or a tag or other reference) to be garbage. +Git will eventually permanently delete those "garbage" commits during +garbage collection. Those commits will be deleted after 30 days by +default, see linkgit:git-gc[1] for more. + +There are 3 main ways you can end up in detached HEAD state: + +1. `git checkout COMMIT_ID` or `git switch --detach COMMIT_ID`, + where `COMMIT_ID` is a commit ID. +2. `git checkout v1.3`, where v1.3 is a tag name +3. `git checkout origin/main`, where `origin/main` is + a remote-tracking branch + +Checking out a tag puts you in detached HEAD state because `HEAD` can +only be a branch or a commit, not a tag or any other reference. +So `git checkout TAG` will set HEAD to the tagged commit. + +The easiest way to avoid accidentally ending up in detached HEAD state +is to use linkgit:git-switch[1] instead of linkgit:git-checkout[1] to +switch branches. `git switch` won't let you detach unless you explicitly +pass the `--detach` argument. + +To get back onto a branch, you can: + +1. Switch to the branch you want to be on, with `git switch BRANCHNAME`. +2. Create a new branch at the current commit, with `git switch -c BRANCHNAME`. + You might want to do this if you've created new commits, so that you can + find the commit later and so that it won't be garbage collected. + +If you switch branches after making commits in detached HEAD state, Git +will warn you that you might be about to "lose" those commits and print +out the commit ID. You can also always find those commits later using +linkgit:git-reflog[1]. + +Here's what that warning looks like: + +------------------------- +Warning: you are leaving 1 commit behind, not connected to +any of your branches: + + 48c09f6 fix bug +------------------------- + +For a more in-depth explanation of how `HEAD` works in Git, +see linkgit:gitdatamodel[7] (`git help datamodel`). diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index 47dea1de8e5328..9f67ae88684b2b 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -244,6 +244,16 @@ endif::git-pull[] refspecs and rely entirely on the refspecs supplied as command-line arguments. See section on "Configured Remote-tracking Branches" for details. ++ +When a refmap is active (from `--refmap` or `remote..fetchRefmap`) but +nothing to fetch is specified on the command line, nor is there a +`remote..fetch`, infer what to fetch from local branches built on +this remote: remote-tracking branches from this remote that are also +configured as the `@{upstream}` of a local branch are fetched. The +refmap only decides where those fetched refs land, the same as it +would for an explicit refspec, and does not narrow which branches are +selected. It is what turns this on, since without it the fetched +branches would have nowhere to land. `-t`:: `--tags`:: @@ -294,6 +304,14 @@ ifndef::git-pull[] `--no-recurse-submodules`:: Disable recursive fetching of submodules (this has the same effect as using the `--recurse-submodules=no` option). + +`--submodule-errors=(fail|warn)`:: + Control how errors from submodule fetches are handled when + `--recurse-submodules` is in effect. When set to `fail` (the default), + any submodule fetch error causes the overall `git fetch` to exit with a + non-zero status. When set to `warn`, submodule fetch errors are reported + to standard error but do not affect the exit status of the command. Can + also be configured via `fetch.submoduleErrors`. See linkgit:git-config[1]. endif::git-pull[] `--set-upstream`:: diff --git a/Documentation/for-each-ref-options.adoc b/Documentation/for-each-ref-options.adoc index 54e2fa95c2911e..2b6d4ede0b9920 100644 --- a/Documentation/for-each-ref-options.adoc +++ b/Documentation/for-each-ref-options.adoc @@ -73,7 +73,7 @@ TAB %(refname)`. using the same rules as __ above. `--include-root-refs`:: - List root refs (`HEAD` and pseudorefs) apart from regular refs. + Also list root refs, such as `HEAD` or `ORIG_HEAD`. `--start-after=`:: Allows paginating the output by skipping references up to and including the diff --git a/Documentation/git-branch.adoc b/Documentation/git-branch.adoc index bfdf4593298631..489a9d5fd03010 100644 --- a/Documentation/git-branch.adoc +++ b/Documentation/git-branch.adoc @@ -26,6 +26,7 @@ git branch (-c|-C) [] git branch (-d|-D) [-r] ... git branch --edit-description [] git branch [--dry-run] (--delete-merged )... [...] +git branch [--dry-run] (--delete-integrated )... [...] DESCRIPTION ----------- @@ -235,11 +236,24 @@ A branch whose work has not yet been merged into its upstream is silently skipped. Delete it with `git branch -D` if you want to remove it anyway. +`--delete-integrated `:: + Like `--delete-merged`, but also delete a branch whose changes + the upstream already has even though its commits are not there, + as happens after a squash or rebase merge. Such a branch is + deleted when some upstream commit since the fork point has all + of its changes, even if they were later reverted, and the + message names the first such commit. It does not matter who made + that commit. A file counts when the commit has the branch's + version of it, or when merging the branch's version into the + commit's leaves it unchanged, which reads the file and may + download blobs in a partial clone. The same rules for which + branches are kept apply as for `--delete-merged`. + `--dry-run`:: - With `--delete-merged`, print which branches would be - deleted and exit without touching any ref. Useful for - sanity-checking a wide pattern like `'origin/*'` before - committing to the deletion. + With `--delete-merged` or `--delete-integrated`, print which + branches would be deleted and exit without touching any ref. + Useful for sanity-checking a wide pattern like `'origin/*'` + before committing to the deletion. `-v`:: `-vv`:: diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index 2aefea02287456..4e9e94e24ddd0c 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -376,135 +376,8 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. [[DETACHED_HEAD]] DETACHED HEAD ------------- -`HEAD` normally refers to a named branch (e.g. `master`). Meanwhile, each -branch refers to a specific commit. Let's look at a repo with three -commits, one of them tagged, and with branch `master` checked out: ------------- - HEAD (refers to branch 'master') - | - v -a---b---c branch 'master' (refers to commit 'c') - ^ - | - tag 'v2.0' (refers to commit 'b') ------------- - -When a commit is created in this state, the branch is updated to refer to -the new commit. Specifically, `git commit` creates a new commit `d`, whose -parent is commit `c`, and then updates branch `master` to refer to new -commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers -to commit `d`: - ------------- -$ edit; git add; git commit - - HEAD (refers to branch 'master') - | - v -a---b---c---d branch 'master' (refers to commit 'd') - ^ - | - tag 'v2.0' (refers to commit 'b') ------------- - -It is sometimes useful to be able to checkout a commit that is not at -the tip of any named branch, or even to create a new commit that is not -referenced by a named branch. Let's look at what happens when we -checkout commit `b` (here we show two ways this may be done): - ------------- -$ git checkout v2.0 # or -$ git checkout master^^ - - HEAD (refers to commit 'b') - | - v -a---b---c---d branch 'master' (refers to commit 'd') - ^ - | - tag 'v2.0' (refers to commit 'b') ------------- - -Notice that regardless of which checkout command we use, `HEAD` now refers -directly to commit `b`. This is known as being in detached `HEAD` state. -It means simply that `HEAD` refers to a specific commit, as opposed to -referring to a named branch. Let's see what happens when we create a commit: - ------------- -$ edit; git add; git commit - - HEAD (refers to commit 'e') - | - v - e - / -a---b---c---d branch 'master' (refers to commit 'd') - ^ - | - tag 'v2.0' (refers to commit 'b') ------------- - -There is now a new commit `e`, but it is referenced only by `HEAD`. We can -of course add yet another commit in this state: - ------------- -$ edit; git add; git commit - - HEAD (refers to commit 'f') - | - v - e---f - / -a---b---c---d branch 'master' (refers to commit 'd') - ^ - | - tag 'v2.0' (refers to commit 'b') ------------- - -In fact, we can perform all the normal Git operations. But, let's look -at what happens when we then checkout `master`: - ------------- -$ git checkout master - - HEAD (refers to branch 'master') - e---f | - / v -a---b---c---d branch 'master' (refers to commit 'd') - ^ - | - tag 'v2.0' (refers to commit 'b') ------------- - -It is important to realize that at this point nothing refers to commit -`f`. Eventually commit `f` (and by extension commit `e`) will be deleted -by the routine Git garbage collection process, unless we create a reference -before that happens. If we have not yet moved away from commit `f`, -any of these will create a reference to it: - ------------- -$ git checkout -b foo # or "git switch -c foo" <1> -$ git branch foo <2> -$ git tag foo <3> ------------- -<1> creates a new branch `foo`, which refers to commit `f`, and then - updates `HEAD` to refer to branch `foo`. In other words, we'll no longer - be in detached `HEAD` state after this command. -<2> similarly creates a new branch `foo`, which refers to commit `f`, - but leaves `HEAD` detached. -<3> creates a new tag `foo`, which refers to commit `f`, - leaving `HEAD` detached. - -If we have moved away from commit `f`, then we must first recover its object -name (typically by using git reflog), and then we can create a reference to -it. For example, to see the last two commits to which `HEAD` referred, we -can use either of these commands: - ------------- -$ git reflog -2 HEAD # or -$ git log -g -2 HEAD ------------- +include::detached-head.adoc[] [[ARGUMENT_DISAMBIGUATION]] ARGUMENT DISAMBIGUATION diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc index f4cd8b9db7a954..069e434961ff49 100644 --- a/Documentation/git-cherry-pick.adoc +++ b/Documentation/git-cherry-pick.adoc @@ -19,8 +19,7 @@ Given one or more existing commits, apply the change each one introduces, recording a new commit for each. This requires your working tree to be clean (no modifications from the HEAD commit). -When it is not obvious how to apply a change, the following -happens: +When a merge conflict happens: 1. The current branch and `HEAD` pointer stay at the last commit successfully made. @@ -36,8 +35,8 @@ happens: conflict markers `<<<<<<<` and `>>>>>>>`. 5. No other modifications are made. -See linkgit:git-merge[1] for some hints on resolving such -conflicts. +See linkgit:gitmergeconflicts[7] (or `git help mergeconflicts`) +for a guide to handling merge conflicts. OPTIONS ------- @@ -259,6 +258,7 @@ $ git cherry-pick -Xpatience topic^ <4> SEE ALSO -------- linkgit:git-revert[1] +linkgit:gitmergeconflicts[7] GIT --- diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc index 07f7cf1a98dd3f..dd3b44817a7e42 100644 --- a/Documentation/git-clone.adoc +++ b/Documentation/git-clone.adoc @@ -360,6 +360,17 @@ include::ref-storage-format.adoc[] `--ref-format=`:: Deprecated alias of `--ref-storage-format=`. +`--object-storage-format=`:: +Specify the given object storage __ for the repository. Backends that +require additional configuration accept a payload in the form +`://`, for example a path or a connection string identifying +the database that shall store the objects. The valid values are: ++ +include::object-storage-format.adoc[] ++ +Local clones (see `--local`) fall back to the regular transport when either +repository uses a non-default object storage. + `-j`:: `--jobs=`:: The number of submodules fetched at the same time. diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc index 8329c1034b9b30..98c50a3be5c81c 100644 --- a/Documentation/git-commit.adoc +++ b/Documentation/git-commit.adoc @@ -102,21 +102,23 @@ include::diff-context-options.adoc[] + The commit created by plain `--fixup=` has a title composed of "fixup!" followed by the title of __, -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 +and is recognized specially by `git rebase --autosquash`. The `-m`, +`-F`, `-C`, or `-c` 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 `git rebase --autosquash`. + The commit created by `--fixup=amend:` is similar but its title is instead prefixed with "amend!". The log message of __ 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 -from the "amend!" commit. It is an error for the "amend!" commit's -log message to be empty unless `--allow-empty-message` is -specified. +opened in an editor so it can be refined. The replacement message may +also be supplied directly using `-m`, `-F`, or `-C`, bypassing the +need to open an editor, or using `-c` to open the editor pre-populated +with the referenced commit's message. When `git rebase +--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 diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index c5e1cec1a50495..e02a50c27a8f5c 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -66,13 +66,6 @@ Only enable this option if you trust the program generating the fast-import stream! This option is enabled automatically for remote-helpers that use the `import` capability, as they are already trusted to run their own code. -+ -Note that this option has to be spelled in full, and has to appear -before any option whose value is separated from it by a space, for -the unsafe `feature` commands in the stream to be allowed. So -`--allow-unsafe` or `--depth 5 --allow-unsafe-features` still refuse -them, while `--allow-unsafe-features --depth 5` and -`--depth=5 --allow-unsafe-features` allow them. `--signed-tags=`:: Specify how to handle signed tags. Behaves in the same way as diff --git a/Documentation/git-format-rev.adoc b/Documentation/git-format-rev.adoc index c2268c92b56bac..184f5ca2e9ada1 100644 --- a/Documentation/git-format-rev.adoc +++ b/Documentation/git-format-rev.adoc @@ -9,7 +9,7 @@ git-format-rev - EXPERIMENTAL: Pretty format revisions on demand SYNOPSIS -------- [synopsis] -(EXPERIMENTAL!) git format-rev --stdin-mode= --format= [--[no-]notes=] [-z] [--[no-]null-output] [--[no-]null-input] +(EXPERIMENTAL!) git format-rev [] --stdin-mode= --format= DESCRIPTION ----------- @@ -33,8 +33,8 @@ OPTIONS The argument `rev` is also accepted. `text`;; Formats all commit object names found in freeform text. These - must be full object names, i.e. abbreviated hexadecimal object - names will not be interpreted. + must be full object names, i.e. abbreviated hexadecimal (_hex_) + object names will not be interpreted. + Anything that is parsed as an object name but that is not found to be a commit object name is left alone (echoed). @@ -76,6 +76,44 @@ This is useful if the output could contain newlines, for example if the + This is useful if the input revision expressions could contain newlines. +`--color[=]`:: +`--no-color`:: + Respect color formatting. The default color behavior is + `auto`. Bare `--color` is the same as `--color=always`. ++ +Giving `--no-color` is the same as `--color=never`. ++ +__ must be one of: ++ +-- +`always`;; + Always use color, even if the output is something like a file. +`never`;; + Never use color. +`auto`;; + Use color when the output is a terminal but not when the output + is something like a file. +-- + +`--abbrev[=]`:: +`--no-abbrev`:: + Abbreviate the commit hex output. Without __ it will find the + minimum length which can describe the commit uniquely, with some + extra slack. Giving __ specifies the minimum length; a longer + length will be used if needed. ++ +Giving `--no-abbrev` will turn off abbreviation, showing the full commit +hex output. ++ +Note that some pretty formats use `--abbrev`. This behavior can be +controlled with these two options. + +`--date=`:: + Date format for pretty formats. Note that date atoms like `%aI` + are not affected. This option cannot be negated. ++ +include::rev-list-option-date-alternatives.adoc[] + [[io]] INPUT AND OUTPUT FORMAT ----------------------- diff --git a/Documentation/git-init.adoc b/Documentation/git-init.adoc index b02af22ad11e3e..9e022a7ba8bde6 100644 --- a/Documentation/git-init.adoc +++ b/Documentation/git-init.adoc @@ -11,7 +11,7 @@ SYNOPSIS [synopsis] git init [-q | --quiet] [--bare] [--template=] [--separate-git-dir ] [--object-format=] - [--ref-storage-format=] + [--ref-storage-format=] [--object-storage-format=] [-b | --initial-branch=] [--shared[=]] [] @@ -68,6 +68,14 @@ include::ref-storage-format.adoc[] `--ref-format=`:: Deprecated alias of `--ref-storage-format=`. +`--object-storage-format=`:: +Specify the given object storage __ for the repository. Backends that +require additional configuration accept a payload in the form +`://`, for example a path or a connection string identifying +the database that shall store the objects. The valid values are: ++ +include::object-storage-format.adoc[] + `--template=`:: Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) diff --git a/Documentation/git-ls-files.adoc b/Documentation/git-ls-files.adoc index 14ebad8b718d45..bb2a8888443b84 100644 --- a/Documentation/git-ls-files.adoc +++ b/Documentation/git-ls-files.adoc @@ -127,6 +127,10 @@ OPTIONS --exclude-standard:: Add the standard Git exclusions: .git/info/exclude, .gitignore in each directory, and the user's global exclusion file. ++ +With `--others`, an enabled untracked cache can be updated in the index +after a complete traversal. Use `--no-optional-locks` (see linkgit:git[1]) +to disable this optional index update. --error-unmatch:: If any does not appear in the index, treat this as an diff --git a/Documentation/git-ls-remote.adoc b/Documentation/git-ls-remote.adoc index d71c4ab3e290c5..7ce7df31498f8a 100644 --- a/Documentation/git-ls-remote.adoc +++ b/Documentation/git-ls-remote.adoc @@ -35,7 +35,7 @@ OPTIONS with other git subcommands. --refs:: - Do not show peeled tags or pseudorefs like `HEAD` in the output. + Do not show peeled tags or refs outside `refs/`. -q:: --quiet:: @@ -118,7 +118,7 @@ line shows the name of the object the tag points at. EXAMPLES -------- -* List all references (including symbolics and pseudorefs), peeling +* List all references (including `HEAD` and symbolic refs), peeling tags: + ---- diff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc index a055384ad6956c..5b7b41cd10a8be 100644 --- a/Documentation/git-merge.adoc +++ b/Documentation/git-merge.adoc @@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation, A merge stops if there's a conflict that cannot be resolved automatically or if `--no-commit` was provided when initiating the merge. At that point you can run `git merge --abort` or `git merge ---continue`. +--continue`. See linkgit:gitmergeconflicts[7] +(or `git help mergeconflicts`) for a guide to handling merge conflicts. `git merge --abort` will abort the merge process and try to reconstruct the pre-merge state. However, if there were uncommitted changes when the @@ -231,127 +232,6 @@ git merge v1.2.3^0 git merge --ff-only v1.2.3 ---- -HOW CONFLICTS ARE PRESENTED ---------------------------- - -During a merge, the working tree files are updated to reflect the result -of the merge. Among the changes made to the common ancestor's version, -non-overlapping ones (that is, you changed an area of the file while the -other side left that area intact, or vice versa) are incorporated in the -final result verbatim. When both sides made changes to the same area, -however, Git cannot randomly pick one side over the other, and asks you to -resolve it by leaving what both sides did to that area. - -By default, Git uses the same style as the one used by the "merge" program -from the RCS suite to present such a conflicted hunk, like this: - ------------- -Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed, -or cleanly resolved because both sides changed the same way. -<<<<<<< yours:sample.txt -Conflict resolution is hard; -let's go shopping. -======= -Git makes conflict resolution easy. ->>>>>>> theirs:sample.txt -And here is another line that is cleanly resolved or unmodified. ------------- - -The area where a pair of conflicting changes happened is marked with markers -+<<<<<<<+, `=======`, and +>>>>>>>+. The part before the `=======` -is typically your side, and the part afterwards is typically their side. - -The default format does not show what the original said in the conflicting -area. You cannot tell how many lines are deleted and replaced with -Barbie's remark on your side. The only thing you can tell is that your -side wants to say it is hard and you'd prefer to go shopping, while the -other side wants to claim it is easy. - -An alternative style can be used by setting the `merge.conflictStyle` -configuration variable to either `diff3` or `zdiff3`. In `diff3` -style, the above conflict may look like this: - ------------- -Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed, -<<<<<<< yours:sample.txt -or cleanly resolved because both sides changed the same way. -Conflict resolution is hard; -let's go shopping. -||||||| base:sample.txt -or cleanly resolved because both sides changed identically. -Conflict resolution is hard. -======= -or cleanly resolved because both sides changed the same way. -Git makes conflict resolution easy. ->>>>>>> theirs:sample.txt -And here is another line that is cleanly resolved or unmodified. ------------- - -while in `zdiff3` style, it may look like this: - ------------- -Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed, -or cleanly resolved because both sides changed the same way. -<<<<<<< yours:sample.txt -Conflict resolution is hard; -let's go shopping. -||||||| base:sample.txt -or cleanly resolved because both sides changed identically. -Conflict resolution is hard. -======= -Git makes conflict resolution easy. ->>>>>>> theirs:sample.txt -And here is another line that is cleanly resolved or unmodified. ------------- - -In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses -another +|||||||+ marker that is followed by the original text. You can -tell that the original just stated a fact, and your side simply gave in to -that statement and gave up, while the other side tried to have a more -positive attitude. You can sometimes come up with a better resolution by -viewing the original. - - -HOW TO RESOLVE CONFLICTS ------------------------- - -After seeing a conflict, you can do two things: - - * Decide not to merge. The only clean-ups you need are to reset - the index file to the `HEAD` commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; `git merge --abort` - can be used for this. - - * Resolve the conflicts. Git will mark the conflicts in - the working tree. Edit the files into shape and - `git add` them to the index. Use `git commit` or - `git merge --continue` to seal the deal. The latter command - checks whether there is a (interrupted) merge in progress - before calling `git commit`. - -You can work through the conflict with a number of tools: - - * Use a mergetool. `git mergetool` to launch a graphical - mergetool which will work through the merge with you. - - * Look at the diffs. `git diff` will show a three-way diff, - highlighting changes from both the `HEAD` and `MERGE_HEAD` - versions. `git diff AUTO_MERGE` will show what changes you've - made so far to resolve textual conflicts. - - * Look at the diffs from each branch. `git log --merge -p ` - will show diffs first for the `HEAD` version and then the - `MERGE_HEAD` version. - - * Look at the originals. `git show :1:filename` shows the - common ancestor, `git show :2:filename` shows the `HEAD` - version, and `git show :3:filename` shows the `MERGE_HEAD` - version. - - EXAMPLES -------- @@ -406,6 +286,7 @@ linkgit:git-reset[1], linkgit:git-diff[1], linkgit:git-ls-files[1], linkgit:git-add[1], linkgit:git-rm[1], linkgit:git-mergetool[1] +linkgit:gitmergeconflicts[7] GIT --- diff --git a/Documentation/git-pack-objects.adoc b/Documentation/git-pack-objects.adoc index ccad938c5b9f1b..c2416a6f147312 100644 --- a/Documentation/git-pack-objects.adoc +++ b/Documentation/git-pack-objects.adoc @@ -13,6 +13,7 @@ SYNOPSIS [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=] [--depth=] [--revs [--unpacked | --all]] [--keep-pack=] + [--ignore-pack-keep-from=] [--cruft] [--cruft-expiration=