diff --git a/.github/workflows/check-whitespace.yml b/.github/workflows/check-whitespace.yml index a241a63428bd20..d0a78fc426f9e4 100644 --- a/.github/workflows/check-whitespace.yml +++ b/.github/workflows/check-whitespace.yml @@ -26,66 +26,7 @@ jobs: - name: git log --check id: check_out run: | - baseSha=${{github.event.pull_request.base.sha}} - problems=() - commit= - commitText= - commitTextmd= - goodparent= - while read dash sha etc - do - case "${dash}" in - "---") - if test -z "${commit}" - then - goodparent=${sha} - fi - commit="${sha}" - commitText="${sha} ${etc}" - commitTextmd="[${sha}](https://github.com/${{ github.repository }}/commit/${sha}) ${etc}" - ;; - "") - ;; - *) - if test -n "${commit}" - then - problems+=("1) --- ${commitTextmd}") - echo "" - echo "--- ${commitText}" - commit= - fi - case "${dash}" in - *:[1-9]*:) # contains file and line number information - dashend=${dash#*:} - problems+=("[${dash}](https://github.com/${{ github.repository }}/blob/${{github.event.pull_request.head.ref}}/${dash%%:*}#L${dashend%:}) ${sha} ${etc}") - ;; - *) - problems+=("\`${dash} ${sha} ${etc}\`") - ;; - esac - echo "${dash} ${sha} ${etc}" - ;; - esac - done <<< $(git log --check --pretty=format:"---% h% s" ${baseSha}..) - - if test ${#problems[*]} -gt 0 - then - if test -z "${commit}" - then - goodparent=${baseSha: 0:7} - fi - echo "🛑 Please review the Summary output for further information." - echo "### :x: A whitespace issue was found in one or more of the commits." >$GITHUB_STEP_SUMMARY - echo "" >>$GITHUB_STEP_SUMMARY - echo "Run these commands to correct the problem:" >>$GITHUB_STEP_SUMMARY - echo "1. \`git rebase --whitespace=fix ${goodparent}\`" >>$GITHUB_STEP_SUMMARY - echo "1. \`git push --force\`" >>$GITHUB_STEP_SUMMARY - echo " " >>$GITHUB_STEP_SUMMARY - echo "Errors:" >>$GITHUB_STEP_SUMMARY - for i in "${problems[@]}" - do - echo "${i}" >>$GITHUB_STEP_SUMMARY - done - - exit 2 - fi + ./ci/check-whitespace.sh \ + "${{github.event.pull_request.base.sha}}" \ + "$GITHUB_STEP_SUMMARY" \ + "https://github.com/${{github.repository}}" diff --git a/.github/workflows/coverity.yml b/.github/workflows/coverity.yml index 53cf12fe044425..48341e81f49066 100644 --- a/.github/workflows/coverity.yml +++ b/.github/workflows/coverity.yml @@ -45,7 +45,7 @@ jobs: - run: ci/install-dependencies.sh if: contains(matrix.os, 'ubuntu') || contains(matrix.os, 'macos') env: - runs_on_pool: ${{ matrix.os }} + distro: ${{ matrix.os }} # The Coverity site says the tool is usually updated twice yearly, so the # MD5 of download can be used to determine whether there's been an update. diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c147c4307bf80f..8e29c351720ab8 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -301,7 +301,7 @@ jobs: CC: ${{matrix.vector.cc}} CC_PACKAGE: ${{matrix.vector.cc_package}} jobname: ${{matrix.vector.jobname}} - runs_on_pool: ${{matrix.vector.pool}} + distro: ${{matrix.vector.pool}} runs-on: ${{matrix.vector.pool}} steps: - uses: actions/checkout@v4 @@ -340,12 +340,16 @@ jobs: vector: - jobname: linux-musl image: alpine + distro: alpine-latest - jobname: linux32 image: daald/ubuntu32:xenial + distro: ubuntu32-16.04 - jobname: pedantic image: fedora + distro: fedora-latest env: jobname: ${{matrix.vector.jobname}} + distro: ${{matrix.vector.distro}} runs-on: ubuntu-latest container: ${{matrix.vector.image}} steps: @@ -353,7 +357,7 @@ jobs: if: matrix.vector.jobname != 'linux32' - uses: actions/checkout@v1 # cannot be upgraded because Node.js Actions aren't supported in this container if: matrix.vector.jobname == 'linux32' - - run: ci/install-docker-dependencies.sh + - run: ci/install-dependencies.sh - run: ci/run-build-and-tests.sh - name: print test failures if: failure() && env.FAILED_TEST_ARTIFACTS != '' diff --git a/.gitignore b/.gitignore index f0a9b738f7d4d5..bf97276163b19b 100644 --- a/.gitignore +++ b/.gitignore @@ -126,6 +126,7 @@ /git-rebase /git-receive-pack /git-reflog +/git-refs /git-remote /git-remote-http /git-remote-https diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index c0fa2fe90b4b81..37b991e08079fc 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -9,8 +9,10 @@ workflow: test:linux: image: $image + variables: + CUSTOM_PATH: "/custom" before_script: - - ./ci/install-docker-dependencies.sh + - ./ci/install-dependencies.sh script: - useradd builder --create-home - chown -R builder "${CI_PROJECT_DIR}" @@ -93,12 +95,39 @@ test:osx: - t/failed-test-artifacts when: on_failure +test:fuzz-smoke-tests: + image: ubuntu:latest + variables: + CC: clang + before_script: + - ./ci/install-dependencies.sh + script: + - ./ci/run-build-and-minimal-fuzzers.sh + static-analysis: image: ubuntu:22.04 variables: jobname: StaticAnalysis before_script: - - ./ci/install-docker-dependencies.sh + - ./ci/install-dependencies.sh script: - ./ci/run-static-analysis.sh - ./ci/check-directional-formatting.bash + +check-whitespace: + image: ubuntu:latest + before_script: + - ./ci/install-dependencies.sh + script: + - ./ci/check-whitespace.sh "$CI_MERGE_REQUEST_TARGET_BRANCH_SHA" + rules: + - if: $CI_PIPELINE_SOURCE == 'merge_request_event' + +documentation: + image: ubuntu:latest + variables: + jobname: Documentation + before_script: + - ./ci/install-dependencies.sh + script: + - ./ci/test-documentation.sh diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt new file mode 100644 index 00000000000000..0532bfcf7f92bd --- /dev/null +++ b/Documentation/BreakingChanges.txt @@ -0,0 +1,135 @@ += Upcoming breaking changes + +The Git project aims to ensure backwards compatibility to the best extent +possible. Minor releases will not break backwards compatibility unless there is +a very strong reason to do so, like for example a security vulnerability. + +Regardless of that, due to the age of the Git project, it is only natural to +accumulate a backlog of backwards-incompatible changes that will eventually be +required to keep the project aligned with a changing world. These changes fall +into several categories: + +* Changes to long established defaults. +* Concepts that have been replaced with a superior design. +* Concepts, commands, configuration or options that have been lacking in major + ways and that cannot be fixed and which will thus be removed without any + replacement. + +Explicitly not included in this list are fixes to minor bugs that may cause a +change in user-visible behavior. + +The Git project irregularly releases breaking versions that deliberately break +backwards compatibility with older versions. This is done to ensure that Git +remains relevant, safe and maintainable going forward. The release cadence of +breaking versions is typically measured in multiple years. We had the following +major breaking releases in the past: + +* Git 1.6.0, released in August 2008. +* Git 2.0, released in May 2014. + +We use . release numbers these days, starting from Git 2.0. For +future releases, our plan is to increment in the release number when we +make the next breaking release. Before Git 2.0, the release numbers were +1.. with the intention to increment for "usual" breaking +releases, reserving the jump to Git 2.0 for really large backward-compatibility +breaking changes. + +The intent of this document is to track upcoming deprecations for future +breaking releases. Furthermore, this document also tracks what will _not_ be +deprecated. This is done such that the outcome of discussions document both +when the discussion favors deprecation, but also when it rejects a deprecation. + +Items should have a clear summary of the reasons why we do or do not want to +make the described change that can be easily understood without having to read +the mailing list discussions. If there are alternatives to the changed feature, +those alternatives should be pointed out to our users. + +All items should be accompanied by references to relevant mailing list threads +where the deprecation was discussed. These references use message-IDs, which +can visited via + + https://lore.kernel.org/git/$message_id/ + +to see the message and its surrounding discussion. Such a reference is there to +make it easier for you to find how the project reached consensus on the +described item back then. + +This is a living document as the environment surrounding the project changes +over time. If circumstances change, an earlier decision to deprecate or change +something may need to be revisited from time to time. So do not take items on +this list to mean "it is settled, do not waste our time bringing it up again". + +== Git 3.0 + +The following subsections document upcoming breaking changes for Git 3.0. There +is no planned release date for this breaking version yet. + +Proposed changes and removals only include items which are "ready" to be done. +In other words, this is not supposed to be a wishlist of features that should +be changed to or replaced in case the alternative was implemented already. + +=== Changes + +* The default hash function for new repositories will be changed from "sha1" + to "sha256". SHA-1 has been deprecated by NIST in 2011 and is nowadays + recommended against in FIPS 140-2 and similar certifications. Furthermore, + there are practical attacks on SHA-1 that weaken its cryptographic properties: ++ + ** The SHAppening (2015). The first demonstration of a practical attack + against SHA-1 with 2^57 operations. + ** SHAttered (2017). Generation of two valid PDF files with 2^63 operations. + ** Birthday-Near-Collision (2019). This attack allows for chosen prefix + attacks with 2^68 operations. + ** Shambles (2020). This attack allows for chosen prefix attacks with 2^63 + operations. ++ +While we have protections in place against known attacks, it is expected +that more attacks against SHA-1 will be found by future research. Paired +with the ever-growing capability of hardware, it is only a matter of time +before SHA-1 will be considered broken completely. We want to be prepared +and will thus change the default hash algorithm to "sha256" for newly +initialized repositories. ++ +An important requirement for this change is that the ecosystem is ready to +support the "sha256" object format. This includes popular Git libraries, +applications and forges. ++ +There is no plan to deprecate the "sha1" object format at this point in time. ++ +Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>, +<20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain>, +. + +=== Removals + +* Support for grafting commits has long been superseded by git-replace(1). + Grafts are inferior to replacement refs: ++ + ** Grafts are a local-only mechanism and cannot be shared across + repositories. + ** Grafts can lead to hard-to-diagnose problems when transferring objects + between repositories. ++ +The grafting mechanism has been marked as outdated since e650d0643b (docs: mark +info/grafts as outdated, 2014-03-05) and will be removed. ++ +Cf. <20140304174806.GA11561@sigill.intra.peff.net>. + +== Superseded features that will not be deprecated + +Some features have gained newer replacements that aim to improve the design in +certain ways. The fact that there is a replacement does not automatically mean +that the old way of doing things will eventually be removed. This section tracks +those features with newer alternatives. + +* The features git-checkout(1) offers are covered by the pair of commands + git-restore(1) and git-switch(1). Because the use of git-checkout(1) is still + widespread, and it is not expected that this will change anytime soon, all + three commands will stay. ++ +This decision may get revisited in case we ever figure out that there are +almost no users of any of the commands anymore. ++ +Cf. , +, +<112b6568912a6de6672bf5592c3a718e@manjaro.org>. diff --git a/Documentation/DecisionMaking.txt b/Documentation/DecisionMaking.txt new file mode 100644 index 00000000000000..dbb4c1f56981d0 --- /dev/null +++ b/Documentation/DecisionMaking.txt @@ -0,0 +1,74 @@ +Decision-Making Process in the Git Project +========================================== + +Introduction +------------ +This document describes the current decision-making process in the Git +project. It is a descriptive rather than prescriptive doc; that is, we want to +describe how things work in practice rather than explicitly recommending any +particular process or changes to the current process. + +Here we document how the project makes decisions for discussions +(with or without patches), in scale larger than an individual patch +series (which is fully covered by the SubmittingPatches document). + + +Larger Discussions (with patches) +--------------------------------- +As with discussions on an individual patch series, starting a larger-scale +discussion often begins by sending a patch or series to the list. This might +take the form of an initial design doc, with implementation following in later +iterations of the series (for example, +link:https://lore.kernel.org/git/0169ce6fb9ccafc089b74ae406db0d1a8ff8ac65.1688165272.git.steadmon@google.com/[adding unit tests] or +link:https://lore.kernel.org/git/20200420235310.94493-1-emilyshaffer@google.com/[config-based hooks]), +or it might include a full implementation from the beginning. +In either case, discussion progresses the same way for an individual patch series, +until consensus is reached or the topic is dropped. + + +Larger Discussions (without patches) +------------------------------------ +Occasionally, larger discussions might occur without an associated patch series. +These may be very large-scale technical decisions that are beyond the scope of +even a single large patch series, or they may be more open-ended, +policy-oriented discussions (examples: +link:https://lore.kernel.org/git/ZZ77NQkSuiRxRDwt@nand.local/[introducing Rust] +or link:https://lore.kernel.org/git/YHofmWcIAidkvJiD@google.com/[improving submodule UX]). +In either case, discussion progresses as described above for general patch series. + +For larger discussions without a patch series or other concrete implementation, +it may be hard to judge when consensus has been reached, as there are not any +official guidelines. If discussion stalls at this point, it may be helpful to +restart discussion with an RFC patch series (such as a partial, unfinished +implementation or proof of concept) that can be more easily debated. + +When consensus is reached that it is a good idea, the original +proposer is expected to coordinate the effort to make it happen, +with help from others who were involved in the discussion, as +needed. + +For decisions that require code changes, it is often the case that the original +proposer will follow up with a patch series, although it is also common for +other interested parties to provide an implementation (or parts of the +implementation, for very large changes). + +For non-technical decisions such as community norms or processes, it is up to +the community as a whole to implement and sustain agreed-upon changes. +The project leadership committe (PLC) may help the implementation of +policy decisions. + + +Other Discussion Venues +----------------------- +Occasionally decision proposals are presented off-list, e.g. at the semi-regular +Contributors' Summit. While higher-bandwidth face-to-face discussion is often +useful for quickly reaching consensus among attendees, generally we expect to +summarize the discussion in notes that can later be presented on-list. For an +example, see the thread +link:https://lore.kernel.org/git/AC2EB721-2979-43FD-922D-C5076A57F24B@jramsay.com.au/[Notes +from Git Contributor Summit, Los Angeles (April 5, 2020)] by James Ramsay. + +We prefer that "official" discussion happens on the list so that the full +community has opportunity to engage in discussion. This also means that the +mailing list archives contain a more-or-less complete history of project +discussions and decisions. diff --git a/Documentation/Makefile b/Documentation/Makefile index 3f2383a12c77d0..dc65759cb1b260 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -51,6 +51,7 @@ MAN7_TXT += gitdiffcore.txt MAN7_TXT += giteveryday.txt MAN7_TXT += gitfaq.txt MAN7_TXT += gitglossary.txt +MAN7_TXT += gitpacking.txt MAN7_TXT += gitnamespaces.txt MAN7_TXT += gitremote-helpers.txt MAN7_TXT += gitrevisions.txt @@ -103,6 +104,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) +TECH_DOCS += DecisionMaking TECH_DOCS += ReviewingGuidelines TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk @@ -484,12 +486,16 @@ $(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) +lint-docs-manpages: + $(QUIET_GEN)./lint-manpages.sh + ## Lint: list of targets above .PHONY: lint-docs lint-docs: lint-docs-fsck-msgids lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order +lint-docs: lint-docs-manpages ifeq ($(wildcard po/Makefile),po/Makefile) doc-l10n install-l10n:: diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index f06563e9817460..e41654c00a68e0 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1116,6 +1116,15 @@ $ git send-email --to=target@example.com psuh/*.patch NOTE: Check `git help send-email` for some other options which you may find valuable, such as changing the Reply-to address or adding more CC and BCC lines. +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + +not part of the core `git` binary and must be called directly. Clone the Git + +codebase and run `perl contrib/contacts/git-contacts`.] + +NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can +list potential reviewers. In addition, you can do `git send-email +--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to +automatically pass this list of emails to `send-email`. + NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but please don't send your patchset from the tutorial to the real mailing list! For now, you can send it to yourself, to make sure you understand how it will look. diff --git a/Documentation/RelNotes/2.45.3.txt b/Documentation/RelNotes/2.45.3.txt new file mode 100644 index 00000000000000..2a1e9aa60879aa --- /dev/null +++ b/Documentation/RelNotes/2.45.3.txt @@ -0,0 +1,107 @@ +Git v2.45.3 Release Notes +========================= + +This primarily is to backport various small fixes accumulated on the +'master' front during the development towards Git 2.46, the next +feature release. + + +Fixes since v2.45.2 +------------------- + + * Git-GUI has a new maintainer, Johannes Sixt. + + * Tests that try to corrupt in-repository files in chunked format did + not work well on macOS due to its broken "mv", which has been + worked around. + + * The maximum size of attribute files is enforced more consistently. + + * Unbreak CI jobs so that we do not attempt to use Python 2 that has + been removed from the platform. + + * Git 2.43 started using the tree of HEAD as the source of attributes + in a bare repository, which has severe performance implications. + For now, revert the change, without ripping out a more explicit + support for the attr.tree configuration variable. + + * Windows CI running in GitHub Actions started complaining about the + order of arguments given to calloc(); the imported regex code uses + the wrong order almost consistently, which has been corrected. + + * The SubmittingPatches document now refers folks to manpages + translation project. + + * "git rebase --signoff" used to forget that it needs to add a + sign-off to the resulting commit when told to continue after a + conflict stops its operation. + + * The procedure to build multi-pack-index got confused by the + replace-refs mechanism, which has been corrected by disabling the + latter. + + * "git stash -S" did not handle binary files correctly, which has + been corrected. + + * A scheduled "git maintenance" job is expected to work on all + repositories it knows about, but it stopped at the first one that + errored out. Now it keeps going. + + * zsh can pretend to be a normal shell pretty well except for some + glitches that we tickle in some of our scripts. Work them around + so that "vimdiff" and our test suite works well enough with it. + + * Command line completion support for zsh (in contrib/) has been + updated to stop exposing internal state to end-user shell + interaction. + + * The documentation for "git diff --name-only" has been clarified + that it is about showing the names in the post-image tree. + + * The chainlint script (invoked during "make test") did nothing when + it failed to detect the number of available CPUs. It now falls + back to 1 CPU to avoid the problem. + + * "git init" in an already created directory, when the user + configuration has includeif.onbranch, started to fail recently, + which has been corrected. + + * The safe.directory configuration knob has been updated to + optionally allow leading path matches. + + * An overly large ".gitignore" files are now rejected silently. + + * Fix for an embarrassing typo that prevented Python2 tests from running + anywhere. + + * Varargs functions that are unannotated as printf-like or execl-like + have been annotated as such. + + * The "-k" and "--rfc" options of "format-patch" will now error out + when used together, as one tells us not to add anything to the + title of the commit, and the other one tells us to add "RFC" in + addition to "PATCH". + + * When the user adds to "git rebase -i" instruction to "pick" a merge + commit, the error experience is not pleasant. Such an error is now + caught earlier in the process that parses the todo list. + + * We forgot to normalize the result of getcwd() to NFC on macOS where + all other paths are normalized, which has been corrected. This still + does not address the case where core.precomposeUnicode configuration + is not defined globally. + + * Earlier we stopped using the tree of HEAD as the default source of + attributes in a bare repository, but failed to document it. This + has been corrected. + + * An unused extern declaration for mingw has been removed to prevent + it from causing build failure. + + * A helper function shared between two tests had a copy-paste bug, + which has been corrected. + + * "git fetch-pack -k -k" without passing "--lock-pack" (which we + never do ourselves) did not work at all, which has been corrected. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.46.0.txt b/Documentation/RelNotes/2.46.0.txt new file mode 100644 index 00000000000000..a0b0b325bcc57b --- /dev/null +++ b/Documentation/RelNotes/2.46.0.txt @@ -0,0 +1,386 @@ +Git v2.46 Release Notes +======================= + +Backward Compatibility Notes + + (None at this moment) + +UI, Workflows & Features + + * The "--rfc" option of "git format-patch" learned to take an + optional string value to be used in place of "RFC" to tweak the + "[PATCH]" on the subject header. + + * The credential helper protocol, together with the HTTP layer, have + been enhanced to support authentication schemes different from + username & password pair, like Bearer and NTLM. + + * Command line completion script (in contrib/) learned to complete + "git symbolic-ref" a bit better (you need to enable plumbing + commands to be completed with GIT_COMPLETION_SHOW_ALL_COMMANDS). + + * When the user responds to a prompt given by "git add -p" with an + unsupported command, list of available commands were given, which + was too much if the user knew what they wanted to type but merely + made a typo. Now the user gets a much shorter error message. + + * The color parsing code learned to handle 12-bit RGB colors, spelled + as "#RGB" (in addition to "#RRGGBB" that is already supported). + + * The operation mode options (like "--get") the "git config" command + uses have been deprecated and replaced with subcommands (like "git + config get"). + + * "git tag" learned the "--trailer" option to futz with the trailers + in the same way as "git commit" does. + + * A new global "--no-advice" option can be used to disable all advice + messages, which is meant to be used only in scripts. + + * Updates to symbolic refs can now be made as a part of ref + transaction. + + * The trailer API has been reshuffled a bit. + + * Terminology to call various ref-like things are getting + straightened out. + + * The command line completion script (in contrib/) has been adjusted + to the recent update to "git config" that adopted subcommand based + UI. + + * The knobs to tweak how reftable files are written have been made + available as configuration variables. + + * When "git push" notices that the commit at the tip of the ref on + the other side it is about to overwrite does not exist locally, it + used to first try fetching it if the local repository is a partial + clone. The command has been taught not to do so and immediately + fail instead. + + * The promisor.quiet configuration knob can be set to true to make + lazy fetching from promisor remotes silent. + + * The inter/range-diff output has been moved to the end of the patch + when format-patch adds it to a single patch, instead of writing it + before the patch text, to be consistent with what is done for a + cover letter for a multi-patch series. + + * A new command has been added to migrate a repository that uses the + files backend for its ref storage to use the reftable backend, with + limitations. + + * "git diff --exit-code --ext-diff" learned to take the exit status + of the external diff driver into account when deciding the exit + status of the overall "git diff" invocation when configured to do + so. + + * "git update-ref --stdin" learned to handle transactional updates of + symbolic-refs. + + * "git format-patch --interdiff" for multi-patch series learned to + turn on cover letters automatically (unless told never to enable + cover letter with "--no-cover-letter" and such). + + * The "--heads" option of "ls-remote" and "show-ref" has been been + deprecated; "--branches" replaces "--heads". + + * For over a year, setting add.interactive.useBuiltin configuration + variable did nothing but giving a "this does not do anything" + warning. The warning has been removed. + + +Performance, Internal Implementation, Development Support etc. + + * Advertise "git contacts", a tool for newcomers to find people to + ask review for their patches, a bit more in our developer + documentation. + + * In addition to building the objects needed, try to link the objects + that are used in fuzzer tests, to make sure at least they build + without bitrot, in Linux CI runs. + + * Code to write out reftable has seen some optimization and + simplification. + + * Tests to ensure interoperability between reftable written by jgit + and our code have been added and enabled in CI. + + * The singleton index_state instance "the_index" has been eliminated + by always instantiating "the_repository" and replacing references + to "the_index" with references to its .index member. + + * Git-GUI has a new maintainer, Johannes Sixt. + + * The "test-tool" has been taught to run testsuite tests in parallel, + bypassing the need to use the "prove" tool. + + * The "whitespace check" task that was enabled for GitHub Actions CI + has been ported to GitLab CI. + + * The refs API lost functions that implicitly assumes to work on the + primary ref_store by forcing the callers to pass a ref_store as an + argument. + + * Code clean-up to reduce inter-function communication inside + builtin/config.c done via the use of global variables. + + * The pack bitmap code saw some clean-up to prepare for a follow-up topic. + + * Preliminary code clean-up for "git send-email". + + * The default "creation-factor" used by "git format-patch" has been + raised to make it more aggressively find matching commits. + + * Before discovering the repository details, We used to assume SHA-1 + as the "default" hash function, which has been corrected. Hopefully + this will smoke out codepaths that rely on such an unwarranted + assumptions. + + * The project decision making policy has been documented. + + * The strcmp-offset tests have been rewritten using the unit test + framework. + + * "git add -p" learned to complain when an answer with more than one + letter is given to a prompt that expects a single letter answer. + + * The alias-expanded command lines are logged to the trace output. + + * A new test was added to ensure git commands that are designed to + run outside repositories do work. + + * Basic unit tests for reftable have been reimplemented under the + unit test framework. + + * A pair of test helpers that essentially are unit tests on hash + algorithms have been rewritten using the unit-tests framework. + + * A test helper that essentially is unit tests on the "decorate" + logic has been rewritten using the unit-tests framework. + + * Many memory leaks in the sparse-checkout code paths have been + plugged. + + * "make check-docs" noticed problems and reported to its output but + failed to signal its findings with its exit status, which has been + corrected. + + * Building with "-Werror -Wwrite-strings" is now supported. + + * To help developers, the build procedure now allows builders to use + CFLAGS_APPEND to specify additional CFLAGS. + + * "oidtree" tests were rewritten to use the unit test framework. + + * The structure of the document that records longer-term project + decisions to deprecate/remove/update various behaviour has been + outlined. + + * The pseudo-merge reachability bitmap to help more efficient storage + of the reachability bitmap in a repository with too many refs has + been added. + + * When "git merge" sees that the index cannot be refreshed (e.g. due + to another process doing the same in the background), it died but + after writing MERGE_HEAD etc. files, which was useless for the + purpose to recover from the failure. + + * The output from "git cat-file --batch-check" and "--batch-command + (info)" should not be unbuffered, for which some tests have been + added. + + * A CPP macro USE_THE_REPOSITORY_VARIABLE is introduced to help + transition the codebase to rely less on the availability of the + singleton the_repository instance. + + * "git version --build-options" reports the version information of + OpenSSL and other libraries (if used) in the build. + + * Memory ownership rules for the in-core representation of + remote.*.url configuration values have been straightened out, which + resulted in a few leak fixes and code clarification. + + * When bundleURI interface fetches multiple bundles, Git failed to + take full advantage of all bundles and ended up slurping duplicated + objects, which has been corrected.. + + * The code to deal with modified paths that are out-of-cone in a + sparsely checked out working tree has been optimized. + + +Fixes since v2.45 +----------------- + + * "git rebase --signoff" used to forget that it needs to add a + sign-off to the resulting commit when told to continue after a + conflict stops its operation. + + * The procedure to build multi-pack-index got confused by the + replace-refs mechanism, which has been corrected by disabling the + latter. + + * The "-k" and "--rfc" options of "format-patch" will now error out + when used together, as one tells us not to add anything to the + title of the commit, and the other one tells us to add "RFC" in + addition to "PATCH". + + * "git stash -S" did not handle binary files correctly, which has + been corrected. + + * A scheduled "git maintenance" job is expected to work on all + repositories it knows about, but it stopped at the first one that + errored out. Now it keeps going. + + * zsh can pretend to be a normal shell pretty well except for some + glitches that we tickle in some of our scripts. Work them around + so that "vimdiff" and our test suite works well enough with it. + + * Command line completion support for zsh (in contrib/) has been + updated to stop exposing internal state to end-user shell + interaction. + + * Tests that try to corrupt in-repository files in chunked format did + not work well on macOS due to its broken "mv", which has been + worked around. + + * The maximum size of attribute files is enforced more consistently. + + * Unbreak CI jobs so that we do not attempt to use Python 2 that has + been removed from the platform. + + * Git 2.43 started using the tree of HEAD as the source of attributes + in a bare repository, which has severe performance implications. + For now, revert the change, without ripping out a more explicit + support for the attr.tree configuration variable. + + * The "--exit-code" option of "git diff" command learned to work with + the "--ext-diff" option. + + * Windows CI running in GitHub Actions started complaining about the + order of arguments given to calloc(); the imported regex code uses + the wrong order almost consistently, which has been corrected. + + * Expose "name conflict" error when a ref creation fails due to D/F + conflict in the ref namespace, to improve an error message given by + "git fetch". + (merge 9339fca23e it/refs-name-conflict later to maint). + + * The SubmittingPatches document now refers folks to manpages + translation project. + + * The documentation for "git diff --name-only" has been clarified + that it is about showing the names in the post-image tree. + + * The credential helper that talks with osx keychain learned to avoid + storing back the authentication material it just got received from + the keychain. + (merge e1ab45b2da kn/osxkeychain-skip-idempotent-store later to maint). + + * The chainlint script (invoked during "make test") did nothing when + it failed to detect the number of available CPUs. It now falls + back to 1 CPU to avoid the problem. + + * Revert overly aggressive "layered defence" that went into 2.45.1 + and friends, which broke "git-lfs", "git-annex", and other use + cases, so that we can rebuild necessary counterparts in the open. + + * "git init" in an already created directory, when the user + configuration has includeif.onbranch, started to fail recently, + which has been corrected. + + * Memory leaks in "git mv" has been plugged. + + * The safe.directory configuration knob has been updated to + optionally allow leading path matches. + + * An overly large ".gitignore" files are now rejected silently. + + * Upon expiration event, the credential subsystem forgot to clear + in-core authentication material other than password (whose support + was added recently), which has been corrected. + + * Fix for an embarrassing typo that prevented Python2 tests from running + anywhere. + + * Varargs functions that are unannotated as printf-like or execl-like + have been annotated as such. + + * "git am" has a safety feature to prevent it from starting a new + session when there already is a session going. It reliably + triggers when a mbox is given on the command line, but it has to + rely on the tty-ness of the standard input. Add an explicit way to + opt out of this safety with a command line option. + (merge 62c71ace44 jk/am-retry later to maint). + + * A leak in "git imap-send" that somehow escapes LSan has been + plugged. + + * Setting core.abbrev too early before the repository set-up + (typically in "git clone") caused segfault, which as been + corrected. + + * When the user adds to "git rebase -i" instruction to "pick" a merge + commit, the error experience is not pleasant. Such an error is now + caught earlier in the process that parses the todo list. + + * We forgot to normalize the result of getcwd() to NFC on macOS where + all other paths are normalized, which has been corrected. This still + does not address the case where core.precomposeUnicode configuration + is not defined globally. + + * Earlier we stopped using the tree of HEAD as the default source of + attributes in a bare repository, but failed to document it. This + has been corrected. + + * "git update-server-info" and "git commit-graph --write" have been + updated to use the tempfile API to avoid leaving cruft after + failing. + + * An unused extern declaration for mingw has been removed to prevent + it from causing build failure. + + * A helper function shared between two tests had a copy-paste bug, + which has been corrected. + + * "git fetch-pack -k -k" without passing "--lock-pack" (which we + never do ourselves) did not work at all, which has been corrected. + + * CI job to build minimum fuzzers learned to pass NO_CURL=NoThanks to + the build procedure, as its build environment does not offer, or + the rest of the build needs, anything cURL. + (merge 4e66b5a990 jc/fuzz-sans-curl later to maint). + + * "git diff --no-ext-diff" when diff.external is configured ignored + the "--color-moved" option. + (merge 0f4b0d4cf0 rs/diff-color-moved-w-no-ext-diff-fix later to maint). + + * "git archive --add-virtual-file=:" never paid + attention to the --prefix= option but the documentation + said it would. The documentation has been corrected. + (merge 72c282098d jc/archive-prefix-with-add-virtual-file later to maint). + + * When GIT_PAGER failed to spawn, depending on the code path taken, + we failed immediately (correct) or just spew the payload to the + standard output (incorrect). The code now always fail immediately + when GIT_PAGER fails. + (merge 78f0a5d187 rj/pager-die-upon-exec-failure later to maint). + + * date parser updates to be more careful about underflowing epoch + based timestamp. + (merge 9d69789770 db/date-underflow-fix later to maint). + + * The Bloom filter used for path limited history traversal was broken + on systems whose "char" is unsigned; update the implementation and + bump the format version to 2. + (merge 9c8a9ec787 tb/path-filter-fix later to maint). + + * Typofix. + (merge 231cf7370e as/pathspec-h-typofix later to maint). + + * Code clean-up. + (merge 4b837f821e rs/simplify-submodule-helper-super-prefix-invocation later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 493fdae046 ew/object-convert-leakfix later to maint). + (merge 00f3661a0a ss/doc-eol-attr-fix later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c647c7e1b4c3ee..d8a8caa7916980 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -7,6 +7,73 @@ Here are some guidelines for contributing back to this project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. +[[patch-flow]] +=== A typical life cycle of a patch series + +To help us understand the reason behind various guidelines given later +in the document, first let's understand how the life cycle of a +typical patch series for this project goes. + +. You come up with an itch. You code it up. You do not need any + pre-authorization from the project to do so. ++ +Your patches will be reviewed by other contributors on the mailing +list, and the reviews will be done to assess the merit of various +things, like the general idea behind your patch (including "is it +solving a problem worth solving in the first place?"), the reason +behind the design of the solution, and the actual implementation. +The guidelines given here are there to help your patches by making +them easier to understand by the reviewers. + +. You send the patches to the list and cc people who may need to know + about the change. Your goal is *not* necessarily to convince others + that what you are building is good. Your goal is to get help in + coming up with a solution for the "itch" that is better than what + you can build alone. ++ +The people who may need to know are the ones who worked on the code +you are touching. These people happen to be the ones who are +most likely to be knowledgeable enough to help you, but +they have no obligation to help you (i.e. you ask them for help, +you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would +help you find out who they are. + +. You get comments and suggestions for improvements. You may even get + them in an "on top of your change" patch form. You are expected to + respond to them with "Reply-All" on the mailing list, while taking + them into account while preparing an updated set of patches. + +. Polish, refine, and re-send your patches to the list and to the people + who spent their time to improve your patch. Go back to step (2). + +. While the above iterations improve your patches, the maintainer may + pick the patches up from the list and queue them to the `seen` + branch, in order to make it easier for people to play with it + without having to pick up and apply the patches to their trees + themselves. Being in `seen` has no other meaning. Specifically, it + does not mean the patch was "accepted" in any way. + +. When the discussion reaches a consensus that the latest iteration of + the patches are in good enough shape, the maintainer includes the + topic in the "What's cooking" report that are sent out a few times a + week to the mailing list, marked as "Will merge to 'next'." This + decision is primarily made by the maintainer with help from those + who participated in the review discussion. + +. After the patches are merged to the 'next' branch, the discussion + can still continue to further improve them by adding more patches on + top, but by the time a topic gets merged to 'next', it is expected + that everybody agrees that the scope and the basic direction of the + topic are appropriate, so such an incremental updates are limited to + small corrections and polishing. After a topic cooks for some time + (like 7 calendar days) in 'next' without needing further tweaks on + top, it gets merged to the 'master' branch and wait to become part + of the next major release. + +In the following sections, many techniques and conventions are listed +to help your patches get reviewed effectively in such a life cycle. + + [[choose-starting-point]] === Choose a starting point. @@ -192,8 +259,9 @@ reasons: which case, they can explain why they extend your code to cover files, too). -The goal of your log message is to convey the _why_ behind your -change to help future developers. +The goal of your log message is to convey the _why_ behind your change +to help future developers. The reviewers will also make sure that +your proposed log message will serve this purpose well. The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), @@ -397,17 +465,57 @@ letter. [[send-patches]] === Sending your patches. +==== Choosing your reviewers + :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] -Before sending any patches, please note that patches that may be +NOTE: Patches that may be security relevant should be submitted privately to the Git Security mailing list{security-ml}, instead of the public mailing list. -Learn to use format-patch and send-email if possible. These commands +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + +not part of the core `git` binary and must be called directly. Clone the Git + +codebase and run `perl contrib/contacts/git-contacts`.] + +Send your patch with "To:" set to the mailing list, with "cc:" listing +people who are involved in the area you are touching (the `git-contacts` +script in `contrib/contacts/`{contrib-scripts} can help to +identify them), to solicit comments and reviews. Also, when you made +trial merges of your topic to `next` and `seen`, you may have noticed +work by others conflicting with your changes. There is a good possibility +that these people may know the area you are touching well. + +If you are using `send-email`, you can feed it the output of `git-contacts` like +this: + +.... + git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch +.... + +:current-maintainer: footnote:[The current maintainer: gitster@pobox.com] +:git-ml: footnote:[The mailing list: git@vger.kernel.org] + +After the list reached a consensus that it is a good idea to apply the +patch, re-send it with "To:" set to the maintainer{current-maintainer} +and "cc:" the list{git-ml} for inclusion. This is especially relevant +when the maintainer did not heavily participate in the discussion and +instead left the review to trusted others. + +Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and +`Tested-by:` lines as necessary to credit people who helped your +patch, and "cc:" them when sending such a final version for inclusion. + +==== `format-patch` and `send-email` + +Learn to use `format-patch` and `send-email` if possible. These commands are optimized for the workflow of sending patches, avoiding many ways your existing e-mail client (often optimized for "multipart/*" MIME type e-mails) might render your patches unusable. +NOTE: Here we outline the procedure using `format-patch` and +`send-email`, but you can instead use GitGitGadget to send in your +patches (see link:MyFirstContribution.html[MyFirstContribution]). + People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for a developer to be able to "quote" your changes, using standard @@ -415,10 +523,12 @@ e-mail tools, so that they may comment on specific portions of your code. For this reason, each patch should be submitted "inline" in a separate message. -Multiple related patches should be grouped into their own e-mail -thread to help readers find all parts of the series. To that end, -send them as replies to either an additional "cover letter" message -(see below), the first patch, or the respective preceding patch. +All subsequent versions of a patch series and other related patches should be +grouped into their own e-mail thread to help readers find all parts of the +series. To that end, send them as replies to either an additional "cover +letter" message (see below), the first patch, or the respective preceding patch. +Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on +how to submit updated versions of a patch series. If your log message (including your name on the `Signed-off-by` trailer) is not writable in ASCII, make sure that @@ -498,42 +608,93 @@ patch, format it as "multipart/signed", not a text/plain message that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is not a text/plain, it's something else. -:security-ml-ref: footnoteref:[security-ml] +=== Handling Conflicts and Iterating Patches -As mentioned at the beginning of the section, patches that may be -security relevant should not be submitted to the public mailing list -mentioned below, but should instead be sent privately to the Git -Security mailing list{security-ml-ref}. +When revising changes made to your patches, it's important to +acknowledge the possibility of conflicts with other ongoing topics. To +navigate these potential conflicts effectively, follow the recommended +steps outlined below: -Send your patch with "To:" set to the mailing list, with "cc:" listing -people who are involved in the area you are touching (the `git -contacts` command in `contrib/contacts/` can help to -identify them), to solicit comments and reviews. Also, when you made -trial merges of your topic to `next` and `seen`, you may have noticed -work by others conflicting with your changes. There is a good possibility -that these people may know the area you are touching well. +. Build on a suitable base branch, see the <>, +and format-patch the series. If you are doing "rebase -i" in-place to +update from the previous round, this will reuse the previous base so +(2) and (3) may become trivial. -:current-maintainer: footnote:[The current maintainer: gitster@pobox.com] -:git-ml: footnote:[The mailing list: git@vger.kernel.org] +. Find the base of where the last round was queued ++ + $ mine='kn/ref-transaction-symref' + $ git checkout "origin/seen^{/^Merge branch '$mine'}...master" -After the list reached a consensus that it is a good idea to apply the -patch, re-send it with "To:" set to the maintainer{current-maintainer} -and "cc:" the list{git-ml} for inclusion. This is especially relevant -when the maintainer did not heavily participate in the discussion and -instead left the review to trusted others. +. Apply your format-patch result. There are two cases +.. Things apply cleanly and tests fine. Go to (4). +.. Things apply cleanly but does not build or test fails, or things do +not apply cleanly. ++ +In the latter case, you have textual or semantic conflicts coming from +the difference between the old base and the base you used to build in +(1). Identify what caused the breakages (e.g., a topic or two may have +merged since the base used by (2) until the base used by (1)). ++ +Check out the latest 'origin/master' (which may be newer than the base +used by (2)), "merge --no-ff" the topics you newly depend on in there, +and use the result of the merge(s) as the base, rebuild the series and +test again. Run format-patch from the last such merges to the tip of +your topic. If you did ++ + $ git checkout origin/master + $ git merge --no-ff --into-name kn/ref-transaction-symref fo/obar + $ git merge --no-ff --into-name kn/ref-transaction-symref ba/zqux + ... rebuild the topic ... ++ +Then you'd just format your topic above these "preparing the ground" +merges, e.g. ++ + $ git format-patch "HEAD^{/^Merge branch 'ba/zqux'}"..HEAD ++ +Do not forget to write in the cover letter you did this, including the +topics you have in your base on top of 'master'. Then go to (4). -Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and -`Tested-by:` lines as necessary to credit people who helped your -patch, and "cc:" them when sending such a final version for inclusion. +. Make a trial merge of your topic into 'next' and 'seen', e.g. ++ + $ git checkout --detach 'origin/seen' + $ git revert -m 1 + $ git merge kn/ref-transaction-symref ++ +The "revert" is needed if the previous iteration of your topic is +already in 'seen' (like in this case). You could choose to rebuild +master..origin/seen from scratch while excluding your previous +iteration, which may emulate what happens on the maintainers end more +closely. ++ +This trial merge may conflict. It is primarily to see what conflicts +_other_ topics may have with your topic. In other words, you do not +have to depend on it to make your topic work on 'master'. It may +become the job of the other topic owners to resolve conflicts if your +topic goes to 'next' before theirs. ++ +Make a note on what conflict you saw in the cover letter. You do not +necessarily have to resolve them, but it would be a good opportunity to +learn what others are doing in related areas. ++ + $ git checkout --detach 'origin/next' + $ git merge kn/ref-transaction-symref ++ +This is to see what conflicts your topic has with other topics that are +already cooking. This should not conflict if (3)-2 prepared a base on +top of updated master plus dependent topics taken from 'next'. Unless +the context is severe (one way to tell is try the same trial merge with +your old iteration, which may conflict in a similar way), expect that it +will be handled on maintainers end (if it gets unmanageable, I'll ask to +rebase when I receive your patches). == Subsystems with dedicated maintainers Some parts of the system have dedicated maintainers with their own repositories. -- `git-gui/` comes from git-gui project, maintained by Pratyush Yadav: +- `git-gui/` comes from git-gui project, maintained by Johannes Sixt: - https://github.com/prati0100/git-gui.git + https://github.com/j6t/git-gui - `gitk-git/` comes from Paul Mackerras's gitk project: @@ -548,54 +709,12 @@ repositories. Patches to these parts should be based on their trees. -[[patch-flow]] -== An ideal patch flow - -Here is an ideal patch flow for this project the current maintainer -suggests to the contributors: - -. You come up with an itch. You code it up. - -. Send it to the list and cc people who may need to know about - the change. -+ -The people who may need to know are the ones whose code you -are butchering. These people happen to be the ones who are -most likely to be knowledgeable enough to help you, but -they have no obligation to help you (i.e. you ask for help, -don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would -help you find out who they are. - -. You get comments and suggestions for improvements. You may - even get them in an "on top of your change" patch form. - -. Polish, refine, and re-send to the list and the people who - spend their time to improve your patch. Go back to step (2). - -. The list forms consensus that the last round of your patch is - good. Send it to the maintainer and cc the list. - -. A topic branch is created with the patch and is merged to `next`, - and cooked further and eventually graduates to `master`. - -In any time between the (2)-(3) cycle, the maintainer may pick it up -from the list and queue it to `seen`, in order to make it easier for -people to play with it without having to pick up and apply the patch to -their trees themselves. - -[[patch-status]] -== Know the status of your patch after submission +- The "Git documentation translations" project, led by Jean-Noël + Avila, translates our documentation pages. Their work products are + maintained separately from this project, not as part of our tree: -* You can use Git itself to find out when your patch is merged in - master. `git pull --rebase` will automatically skip already-applied - patches, and will let you know. This works only if you rebase on top - of the branch in which your patch has been merged (i.e. it will not - tell you if your patch is merged in `seen` if you rebase on top of - master). + https://github.com/jnavila/git-manpages-l10n/ -* Read the Git mailing list, the maintainer regularly posts messages - entitled "What's cooking in git.git" giving - the status of various proposed changes. == GitHub CI[[GHCI]] diff --git a/Documentation/config.txt b/Documentation/config.txt index 306b679e48b350..fedfaf30cd0d8b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -316,7 +316,8 @@ terminals, this is usually not the same as setting to "white black". Colors may also be given as numbers between 0 and 255; these use ANSI 256-color mode (but note that not all terminals may support this). If your terminal supports it, you may also specify 24-bit RGB values as -hex, like `#ff0ab3`. +hex, like `#ff0ab3`, or 12-bit RGB values like `#f1b`, which is +equivalent to the 24-bit color `#ff11bb`. + The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, `italic`, and `strike` (for crossed-out or "strikethrough" letters). @@ -383,6 +384,8 @@ include::config/apply.txt[] include::config/attr.txt[] +include::config/bitmap-pseudo-merge.txt[] + include::config/blame.txt[] include::config/branch.txt[] @@ -487,6 +490,8 @@ include::config/pager.txt[] include::config/pretty.txt[] +include::config/promisor.txt[] + include::config/protocol.txt[] include::config/pull.txt[] @@ -497,6 +502,8 @@ include::config/rebase.txt[] include::config/receive.txt[] +include::config/reftable.txt[] + include::config/remote.txt[] include::config/remotes.txt[] diff --git a/Documentation/config/add.txt b/Documentation/config/add.txt index e0354ceaed9e87..4d753f006ec1ef 100644 --- a/Documentation/config/add.txt +++ b/Documentation/config/add.txt @@ -5,9 +5,3 @@ add.ignore-errors (deprecated):: option of linkgit:git-add[1]. `add.ignore-errors` is deprecated, as it does not follow the usual naming convention for configuration variables. - -add.interactive.useBuiltin:: - Unused configuration variable. Used in Git versions v2.25.0 to - v2.36.0 to enable the built-in version of linkgit:git-add[1]'s - interactive mode, which then became the default in Git - versions v2.37.0 to v2.39.0. diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 3ee2ae54114f29..95aa24ef640319 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -99,6 +99,8 @@ advice.*:: `pushNonFFCurrent`, `pushNonFFMatching`, `pushAlreadyExists`, `pushFetchFirst`, `pushNeedsForce`, and `pushRefNeedsUpdate` simultaneously. + rebaseTodoError:: + Shown when there is an error after editing the rebase todo list. refSyntax:: Shown when the user provides an illegal ref name, to tell the user about the ref syntax documentation. diff --git a/Documentation/config/alias.txt b/Documentation/config/alias.txt index 01df96fab3df11..2c5db0ad8428e8 100644 --- a/Documentation/config/alias.txt +++ b/Documentation/config/alias.txt @@ -21,8 +21,23 @@ If the alias expansion is prefixed with an exclamation point, it will be treated as a shell command. For example, defining `alias.new = !gitk --all --not ORIG_HEAD`, the invocation `git new` is equivalent to running the shell command -`gitk --all --not ORIG_HEAD`. Note that shell commands will be -executed from the top-level directory of a repository, which may -not necessarily be the current directory. -`GIT_PREFIX` is set as returned by running `git rev-parse --show-prefix` -from the original current directory. See linkgit:git-rev-parse[1]. +`gitk --all --not ORIG_HEAD`. Note: ++ +* Shell commands will be executed from the top-level directory of a + repository, which may not necessarily be the current directory. +* `GIT_PREFIX` is set as returned by running `git rev-parse --show-prefix` + from the original current directory. See linkgit:git-rev-parse[1]. +* Shell command aliases always receive any extra arguments provided to + the Git command-line as positional arguments. +** Care should be taken if your shell alias is a "one-liner" script + with multiple commands (e.g. in a pipeline), references multiple + arguments, or is otherwise not able to handle positional arguments + added at the end. For example: `alias.cmd = "!echo $1 | grep $2"` + called as `git cmd 1 2` will be executed as 'echo $1 | grep $2 + 1 2', which is not what you want. +** A convenient way to deal with this is to write your script + operations in an inline function that is then called with any + arguments from the command-line. For example `alias.cmd = "!c() { + echo $1 | grep $2 ; }; c" will correctly execute the prior example. +** Setting `GIT_TRACE=1` can help you debug the command being run for + your alias. diff --git a/Documentation/config/attr.txt b/Documentation/config/attr.txt index 1a482d6af2b5d2..c4a58579935442 100644 --- a/Documentation/config/attr.txt +++ b/Documentation/config/attr.txt @@ -1,7 +1,6 @@ attr.tree:: A reference to a tree in the repository from which to read attributes, - instead of the `.gitattributes` file in the working tree. In a bare - repository, this defaults to `HEAD:.gitattributes`. If the value does - not resolve to a valid tree object, an empty tree is used instead. + instead of the `.gitattributes` file in the working tree. If the value + does not resolve to a valid tree object, an empty tree is used instead. When the `GIT_ATTR_SOURCE` environment variable or `--attr-source` command line option are used, this configuration variable has no effect. diff --git a/Documentation/config/bitmap-pseudo-merge.txt b/Documentation/config/bitmap-pseudo-merge.txt new file mode 100644 index 00000000000000..1f264eca99b847 --- /dev/null +++ b/Documentation/config/bitmap-pseudo-merge.txt @@ -0,0 +1,91 @@ +NOTE: The configuration options in `bitmapPseudoMerge.*` are considered +EXPERIMENTAL and may be subject to change or be removed entirely in the +future. For more information about the pseudo-merge bitmap feature, see +the "Pseudo-merge bitmaps" section of linkgit:gitpacking[7]. + +bitmapPseudoMerge..pattern:: + Regular expression used to match reference names. Commits + pointed to by references matching this pattern (and meeting + the below criteria, like `bitmapPseudoMerge..sampleRate` + and `bitmapPseudoMerge..threshold`) will be considered + for inclusion in a pseudo-merge bitmap. ++ +Commits are grouped into pseudo-merge groups based on whether or not +any reference(s) that point at a given commit match the pattern, which +is an extended regular expression. ++ +Within a pseudo-merge group, commits may be further grouped into +sub-groups based on the capture groups in the pattern. These +sub-groupings are formed from the regular expressions by concatenating +any capture groups from the regular expression, with a '-' dash in +between. ++ +For example, if the pattern is `refs/tags/`, then all tags (provided +they meet the below criteria) will be considered candidates for the +same pseudo-merge group. However, if the pattern is instead +`refs/remotes/([0-9])+/tags/`, then tags from different remotes will +be grouped into separate pseudo-merge groups, based on the remote +number. + +bitmapPseudoMerge..decay:: + Determines the rate at which consecutive pseudo-merge bitmap + groups decrease in size. Must be non-negative. This parameter + can be thought of as `k` in the function `f(n) = C * n^-k`, + where `f(n)` is the size of the `n`th group. ++ +Setting the decay rate equal to `0` will cause all groups to be the +same size. Setting the decay rate equal to `1` will cause the `n`th +group to be `1/n` the size of the initial group. Higher values of the +decay rate cause consecutive groups to shrink at an increasing rate. +The default is `1`. ++ +If all groups are the same size, it is possible that groups containing +newer commits will be able to be used less often than earlier groups, +since it is more likely that the references pointing at newer commits +will be updated more often than a reference pointing at an old commit. + +bitmapPseudoMerge..sampleRate:: + Determines the proportion of non-bitmapped commits (among + reference tips) which are selected for inclusion in an + unstable pseudo-merge bitmap. Must be between `0` and `1` + (inclusive). The default is `1`. + +bitmapPseudoMerge..threshold:: + Determines the minimum age of non-bitmapped commits (among + reference tips, as above) which are candidates for inclusion + in an unstable pseudo-merge bitmap. The default is + `1.week.ago`. + +bitmapPseudoMerge..maxMerges:: + Determines the maximum number of pseudo-merge commits among + which commits may be distributed. ++ +For pseudo-merge groups whose pattern does not contain any capture +groups, this setting is applied for all commits matching the regular +expression. For patterns that have one or more capture groups, this +setting is applied for each distinct capture group. ++ +For example, if your capture group is `refs/tags/`, then this setting +will distribute all tags into a maximum of `maxMerges` pseudo-merge +commits. However, if your capture group is, say, +`refs/remotes/([0-9]+)/tags/`, then this setting will be applied to +each remote's set of tags individually. ++ +Must be non-negative. The default value is 64. + +bitmapPseudoMerge..stableThreshold:: + Determines the minimum age of commits (among reference tips, + as above, however stable commits are still considered + candidates even when they have been covered by a bitmap) which + are candidates for a stable a pseudo-merge bitmap. The default + is `1.month.ago`. ++ +Setting this threshold to a smaller value (e.g., 1.week.ago) will cause +more stable groups to be generated (which impose a one-time generation +cost) but those groups will likely become stale over time. Using a +larger value incurs the opposite penalty (fewer stable groups which are +more useful). + +bitmapPseudoMerge..stableSize:: + Determines the size (in number of commits) of a stable + psuedo-merge bitmap. The default is `512`. diff --git a/Documentation/config/commitgraph.txt b/Documentation/config/commitgraph.txt index 30604e4a4c2967..7f8c9d6638f1a1 100644 --- a/Documentation/config/commitgraph.txt +++ b/Documentation/config/commitgraph.txt @@ -9,6 +9,29 @@ commitGraph.maxNewFilters:: commit-graph write` (c.f., linkgit:git-commit-graph[1]). commitGraph.readChangedPaths:: - If true, then git will use the changed-path Bloom filters in the - commit-graph file (if it exists, and they are present). Defaults to - true. See linkgit:git-commit-graph[1] for more information. + Deprecated. Equivalent to commitGraph.changedPathsVersion=-1 if true, and + commitGraph.changedPathsVersion=0 if false. (If commitGraph.changedPathVersion + is also set, commitGraph.changedPathsVersion takes precedence.) + +commitGraph.changedPathsVersion:: + Specifies the version of the changed-path Bloom filters that Git will read and + write. May be -1, 0, 1, or 2. Note that values greater than 1 may be + incompatible with older versions of Git which do not yet understand + those versions. Use caution when operating in a mixed-version + environment. ++ +Defaults to -1. ++ +If -1, Git will use the version of the changed-path Bloom filters in the +repository, defaulting to 1 if there are none. ++ +If 0, Git will not read any Bloom filters, and will write version 1 Bloom +filters when instructed to write. ++ +If 1, Git will only read version 1 Bloom filters, and will write version 1 +Bloom filters. ++ +If 2, Git will only read version 2 Bloom filters, and will write version 2 +Bloom filters. ++ +See linkgit:git-commit-graph[1] for more information. diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 5ce7b91f1d0d23..190bda17e51c57 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -79,6 +79,15 @@ diff.external:: you want to use an external diff program only on a subset of your files, you might want to use linkgit:gitattributes[5] instead. +diff.trustExitCode:: + If this boolean value is set to true then the + `diff.external` command is expected to return exit code + 0 if it considers the input files to be equal or 1 if it + considers them to be different, like `diff(1)`. + If it is set to false, which is the default, then the command + is expected to return exit code 0 regardless of equality. + Any other exit code causes Git to report a fatal error. + diff.ignoreSubmodules:: Sets the default value of --ignore-submodules. Note that this affects only 'git diff' Porcelain, and not lower level 'diff' @@ -164,6 +173,15 @@ diff..command:: The custom diff driver command. See linkgit:gitattributes[5] for details. +diff..trustExitCode:: + If this boolean value is set to true then the + `diff..command` command is expected to return exit code + 0 if it considers the input files to be equal or 1 if it + considers them to be different, like `diff(1)`. + If it is set to false, which is the default, then the command + is expected to return exit code 0 regardless of equality. + Any other exit code causes Git to report a fatal error. + diff..xfuncname:: The regular expression that the diff driver should use to recognize the hunk header. A built-in pattern may also be used. diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt index 5cc26555f19a4f..8b876cb4eb8e35 100644 --- a/Documentation/config/interactive.txt +++ b/Documentation/config/interactive.txt @@ -1,8 +1,8 @@ interactive.singleKey:: - In interactive commands, allow the user to provide one-letter - input with a single key (i.e., without hitting enter). - Currently this is used by the `--patch` mode of - linkgit:git-add[1], linkgit:git-checkout[1], + When set to true, allow the user to provide one-letter input + with a single key (i.e., without hitting the Enter key) in + interactive commands. This is currently used by the `--patch` + mode of linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-restore[1], linkgit:git-commit[1], linkgit:git-reset[1], and linkgit:git-stash[1]. diff --git a/Documentation/config/promisor.txt b/Documentation/config/promisor.txt new file mode 100644 index 00000000000000..98c5cb2ec20d34 --- /dev/null +++ b/Documentation/config/promisor.txt @@ -0,0 +1,3 @@ +promisor.quiet:: + If set to "true" assume `--quiet` when fetching additional + objects for a partial clone. diff --git a/Documentation/config/reftable.txt b/Documentation/config/reftable.txt new file mode 100644 index 00000000000000..05157279778339 --- /dev/null +++ b/Documentation/config/reftable.txt @@ -0,0 +1,48 @@ +reftable.blockSize:: + The size in bytes used by the reftable backend when writing blocks. + The block size is determined by the writer, and does not have to be a + power of 2. The block size must be larger than the longest reference + name or log entry used in the repository, as references cannot span + blocks. ++ +Powers of two that are friendly to the virtual memory system or +filesystem (such as 4kB or 8kB) are recommended. Larger sizes (64kB) can +yield better compression, with a possible increased cost incurred by +readers during access. ++ +The largest block size is `16777215` bytes (15.99 MiB). The default value is +`4096` bytes (4kB). A value of `0` will use the default value. + +reftable.restartInterval:: + The interval at which to create restart points. The reftable backend + determines the restart points at file creation. Every 16 may be + more suitable for smaller block sizes (4k or 8k), every 64 for larger + block sizes (64k). ++ +More frequent restart points reduces prefix compression and increases +space consumed by the restart table, both of which increase file size. ++ +Less frequent restart points makes prefix compression more effective, +decreasing overall file size, with increased penalties for readers +walking through more records after the binary search step. ++ +A maximum of `65535` restart points per block is supported. ++ +The default value is to create restart points every 16 records. A value of `0` +will use the default value. + +reftable.indexObjects:: + Whether the reftable backend shall write object blocks. Object blocks + are a reverse mapping of object ID to the references pointing to them. ++ +The default value is `true`. + +reftable.geometricFactor:: + Whenever the reftable backend appends a new table to the stack, it + performs auto compaction to ensure that there is only a handful of + tables. The backend does this by ensuring that tables form a geometric + sequence regarding the respective sizes of each table. ++ +By default, the geometric sequence uses a factor of 2, meaning that for any +table, the next-biggest table must at least be twice as big. A maximum factor +of 256 is supported. diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt index 0678b4bcfef7e6..8efc53e836d20b 100644 --- a/Documentation/config/remote.txt +++ b/Documentation/config/remote.txt @@ -5,10 +5,19 @@ remote.pushDefault:: remote..url:: The URL of a remote repository. See linkgit:git-fetch[1] or - linkgit:git-push[1]. + linkgit:git-push[1]. A configured remote can have multiple URLs; + in this case the first is used for fetching, and all are used + for pushing (assuming no `remote..pushurl` is defined). + Setting this key to the empty string clears the list of urls, + allowing you to override earlier config. remote..pushurl:: The push URL of a remote repository. See linkgit:git-push[1]. + If a `pushurl` option is present in a configured remote, it + is used for pushing instead of `remote..url`. A configured + remote can have multiple push URLs; in this case a push goes to + all of them. Setting this key to the empty string clears the + list of urls, allowing you to override earlier config. remote..proxy:: For remotes that require curl (http, https and ftp), the URL to diff --git a/Documentation/config/safe.txt b/Documentation/config/safe.txt index 577df40223a095..2d45c98b12d951 100644 --- a/Documentation/config/safe.txt +++ b/Documentation/config/safe.txt @@ -44,7 +44,8 @@ string `*`. This will allow all repositories to be treated as if their directory was listed in the `safe.directory` list. If `safe.directory=*` is set in system config and you want to re-enable this protection, then initialize your list with an empty value before listing the repositories -that you deem safe. +that you deem safe. Giving a directory with `/*` appended to it will +allow access to all repositories under the named directory. + As explained, Git only allows you to access repositories owned by yourself, i.e. the user who is running Git, by default. When Git diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 0e9456957e3784..cd0b81adbb69d1 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -329,12 +329,13 @@ explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). --name-only:: - Show only names of changed files. The file names are often encoded in UTF-8. + Show only the name of each changed file in the post-image tree. + The file names are often encoded in UTF-8. For more information see the discussion about encoding in the linkgit:git-log[1] manual page. --name-status:: - Show only names and status of changed files. See the description + Show only the name(s) and status of each changed file. See the description of the `--diff-filter` option on what the status letters mean. Just like `--name-only` the file names are often encoded in UTF-8. @@ -819,6 +820,11 @@ ifndef::git-log[] --quiet:: Disable all output of the program. Implies `--exit-code`. + Disables execution of external diff helpers whose exit code + is not trusted, i.e. their respective configuration option + `diff.trustExitCode` or `diff..trustExitCode` or + environment variable `GIT_EXTERNAL_DIFF_TRUST_EXIT_CODE` is + false. endif::git-log[] endif::git-format-patch[] diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 624a6e6fe4f975..69d5cc9f210825 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -18,7 +18,7 @@ SYNOPSIS [--quoted-cr=] [--empty=(stop|drop|keep)] [( | )...] -'git am' (--continue | --skip | --abort | --quit | --show-current-patch[=(diff|raw)] | --allow-empty) +'git am' (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty) DESCRIPTION ----------- @@ -208,6 +208,12 @@ Valid for the `--whitespace` option are: Abort the patching operation but keep HEAD and the index untouched. +--retry:: + Try to apply the last conflicting patch again. This is generally + only useful for passing extra options to the retry attempt + (e.g., `--3way`), since otherwise you'll just see the same + failure again. + --show-current-patch[=(diff|raw)]:: Show the message at which `git am` has stopped due to conflicts. If `raw` is specified, show the raw contents of diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 98526f2bebad16..a0e3fe7996e57b 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -53,7 +53,7 @@ OPTIONS --prefix=/:: Prepend / to paths in the archive. Can be repeated; its rightmost value is used for all tracked files. See below which - value gets used by `--add-file` and `--add-virtual-file`. + value gets used by `--add-file`. -o :: --output=:: @@ -67,9 +67,7 @@ OPTIONS --add-virtual-file=::: Add the specified contents to the archive. Can be repeated to add - multiple files. The path of the file in the archive is built - by concatenating the value of the last `--prefix` option (if any) - before this `--add-virtual-file` and ``. + multiple files. + The `` argument can start and end with a literal double-quote character; the contained file name is interpreted as a C-style string, @@ -81,6 +79,10 @@ if the path begins or ends with a double-quote character. The file mode is limited to a regular file, and the option may be subject to platform-dependent command-line limits. For non-trivial cases, write an untracked file and use `--add-file` instead. ++ +Note that unlike `--add-file` the path created in the archive is not +affected by the `--prefix` option, as a full `` can be given as +the value of the option. --worktree-attributes:: Look for attributes in .gitattributes files in the working tree diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index ac61113fcc6107..65c645d461aa14 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,21 +9,14 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [] [--type=] [--comment=] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] [ []] -'git config' [] [--type=] [--comment=] --add -'git config' [] [--type=] [--comment=] [--fixed-value] --replace-all [] -'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get [] -'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all [] -'git config' [] [--type=] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp [] -'git config' [] [--type=] [-z|--null] --get-urlmatch -'git config' [] [--fixed-value] --unset [] -'git config' [] [--fixed-value] --unset-all [] -'git config' [] --rename-section -'git config' [] --remove-section -'git config' [] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list -'git config' [] --get-color [] +'git config list' [] [] [--includes] +'git config get' [] [] [--includes] [--all] [--regexp=] [--value=] [--fixed-value] [--default=] +'git config set' [] [--type=] [--all] [--value=] [--fixed-value] +'git config unset' [] [--all] [--value=] [--fixed-value] +'git config rename-section' [] +'git config remove-section' [] +'git config edit' [] 'git config' [] --get-colorbool [] -'git config' [] -e | --edit DESCRIPTION ----------- @@ -31,7 +24,7 @@ You can query/set/replace/unset options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped. -Multiple lines can be added to an option by using the `--add` option. +Multiple lines can be added to an option by using the `--append` option. If you want to update or unset an option which can occur on multiple lines, a `value-pattern` (which is an extended regular expression, unless the `--fixed-value` option is given) needs to be given. Only the @@ -74,6 +67,42 @@ On success, the command returns the exit code 0. A list of all available configuration variables can be obtained using the `git help --config` command. +COMMANDS +-------- + +list:: + List all variables set in config file, along with their values. + +get:: + Emits the value of the specified key. If key is present multiple times + in the configuration, emits the last value. If `--all` is specified, + emits all values associated with key. Returns error code 1 if key is + not present. + +set:: + Set value for one or more config options. By default, this command + refuses to write multi-valued config options. Passing `--all` will + replace all multi-valued config options with the new value, whereas + `--value=` will replace all config options whose values match the given + pattern. + +unset:: + Unset value for one or more config options. By default, this command + refuses to unset multi-valued keys. Passing `--all` will unset all + multi-valued config options, whereas `--value` will unset all config + options whose values match the given pattern. + +rename-section:: + Rename the given section to a new name. + +remove-section:: + Remove the given section from the configuration file. + +edit:: + Opens an editor to modify the specified config file; either + `--system`, `--global`, `--local` (default), `--worktree`, or + `--file `. + [[OPTIONS]] OPTIONS ------- @@ -82,10 +111,9 @@ OPTIONS Default behavior is to replace at most one line. This replaces all lines matching the key (and optionally the `value-pattern`). ---add:: +--append:: Adds a new line to the option without altering any existing - values. This is the same as providing '^$' as the `value-pattern` - in `--replace-all`. + values. This is the same as providing '--value=^$' in `set`. --comment :: Append a comment at the end of new or modified lines. @@ -99,22 +127,16 @@ OPTIONS not contain linefeed characters (no multi-line comments are permitted). ---get:: - Get the value for a given key (optionally filtered by a regex - matching the value). Returns error code 1 if the key was not - found and the last value if multiple key values were found. +--all:: + With `get`, return all values for a multi-valued key. ---get-all:: - Like get, but returns all values for a multi-valued key. +---regexp:: + With `get`, interpret the name as a regular expression. Regular + expression matching is currently case-sensitive and done against a + canonicalized version of the key in which section and variable names + are lowercased, but subsection names are not. ---get-regexp:: - Like --get-all, but interprets the name as a regular expression and - writes out the key names. Regular expression matching is currently - case-sensitive and done against a canonicalized version of the key - in which section and variable names are lowercased, but subsection - names are not. - ---get-urlmatch :: +--url=:: When given a two-part as
., the value for
.. whose part matches the best to the given URL is returned (if no such key exists, the value for @@ -178,22 +200,6 @@ See also <>. section in linkgit:gitrevisions[7] for a more complete list of ways to spell blob names. ---remove-section:: - Remove the given section from the configuration file. - ---rename-section:: - Rename the given section to a new name. - ---unset:: - Remove the line matching the key from config file. - ---unset-all:: - Remove all lines matching the key from config file. - --l:: ---list:: - List all variables set in config file, along with their values. - --fixed-value:: When used with the `value-pattern` argument, treat `value-pattern` as an exact string instead of a regular expression. This will restrict @@ -248,8 +254,8 @@ Valid ``'s include: contain line breaks. --name-only:: - Output only the names of config variables for `--list` or - `--get-regexp`. + Output only the names of config variables for `list` or + `get`. --show-origin:: Augment the output of all queried config options with the @@ -273,23 +279,6 @@ Valid ``'s include: When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color []:: - - Find the color configured for `name` (e.g. `color.diff.new`) and - output it as the ANSI color escape sequence to the standard - output. The optional `default` parameter is used instead, if - there is no color configured for `name`. -+ -`--type=color [--default=]` is preferred over `--get-color` -(but note that `--get-color` will omit the trailing newline printed by -`--type=color`). - --e:: ---edit:: - Opens an editor to modify the specified config file; either - `--system`, `--global`, `--local` (default), `--worktree`, or - `--file `. - --[no-]includes:: Respect `include.*` directives in config files when looking up values. Defaults to `off` when a specific file is given (e.g., @@ -297,14 +286,64 @@ Valid ``'s include: config files. --default :: - When using `--get`, and the requested variable is not found, behave as if + When using `get`, and the requested variable is not found, behave as if were the value assigned to that variable. +DEPRECATED MODES +---------------- + +The following modes have been deprecated in favor of subcommands. It is +recommended to migrate to the new syntax. + +'git config ':: + Replaced by `git config get `. + +'git config []':: + Replaced by `git config set [--value=] `. + +-l:: +--list:: + Replaced by `git config list`. + +--get []:: + Replaced by `git config get [--value=] `. + +--get-all []:: + Replaced by `git config get [--value=] --all --show-names `. + +--get-regexp :: + Replaced by `git config get --all --show-names --regexp `. + +--get-urlmatch :: + Replaced by `git config get --all --show-names --url= `. + +--get-color []:: + Replaced by `git config get --type=color [--default=] `. + +--add :: + Replaced by `git config set --append `. + +--unset []:: + Replaced by `git config unset [--value=] `. + +--unset-all []:: + Replaced by `git config unset [--value=] --all `. + +--rename-section :: + Replaced by `git config rename-section `. + +--remove-section :: + Replaced by `git config remove-section `. + +-e:: +--edit:: + Replaced by `git config edit`. + CONFIGURATION ------------- `pager.config` is only respected when listing configuration, i.e., when -using `--list` or any of the `--get-*` which may return multiple results. -The default is to use a pager. +using `list` or `get` which may return multiple results. The default is to use +a pager. [[FILES]] FILES @@ -346,8 +385,8 @@ precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used. By default, options are only written to the repository specific -configuration file. Note that this also affects options like `--replace-all` -and `--unset`. *'git config' will only ever change one file at a time*. +configuration file. Note that this also affects options like `set` +and `unset`. *'git config' will only ever change one file at a time*. You can limit which configuration sources are read from or written to by specifying the path of a file with the `--file` option, or by specifying a @@ -482,7 +521,7 @@ Given a .git/config like this: you can set the filemode to true with ------------ -% git config core.filemode true +% git config set core.filemode true ------------ The hypothetical proxy command entries actually have a postfix to discern @@ -490,7 +529,7 @@ what URL they apply to. Here is how to change the entry for kernel.org to "ssh". ------------ -% git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$' +% git config set --value='for kernel.org$' core.gitproxy '"ssh" for kernel.org' ------------ This makes sure that only the key/value pair for kernel.org is replaced. @@ -498,7 +537,7 @@ This makes sure that only the key/value pair for kernel.org is replaced. To delete the entry for renames, do ------------ -% git config --unset diff.renames +% git config unset diff.renames ------------ If you want to delete an entry for a multivar (like core.gitproxy above), @@ -507,51 +546,45 @@ you have to provide a regex matching the value of exactly one line. To query the value for a given key, do ------------ -% git config --get core.filemode ------------- - -or - ------------- -% git config core.filemode +% git config get core.filemode ------------ or, to query a multivar: ------------ -% git config --get core.gitproxy "for kernel.org$" +% git config get --value="for kernel.org$" core.gitproxy ------------ If you want to know all the values for a multivar, do: ------------ -% git config --get-all core.gitproxy +% git config get --all --show-names core.gitproxy ------------ If you like to live dangerously, you can replace *all* core.gitproxy by a new one with ------------ -% git config --replace-all core.gitproxy ssh +% git config set --all core.gitproxy ssh ------------ However, if you really only want to replace the line for the default proxy, i.e. the one without a "for ..." postfix, do something like this: ------------ -% git config core.gitproxy ssh '! for ' +% git config set --value='! for ' core.gitproxy ssh ------------ To actually match only values with an exclamation mark, you have to ------------ -% git config section.key value '[!]' +% git config set --value='[!]' section.key value ------------ To add a new proxy, without altering any of the existing ones, use ------------ -% git config --add core.gitproxy '"proxy-command" for example.com' +% git config set --append core.gitproxy '"proxy-command" for example.com' ------------ An example to use customized color from the configuration in your @@ -559,8 +592,8 @@ script: ------------ #!/bin/sh -WS=$(git config --get-color color.diff.whitespace "blue reverse") -RESET=$(git config --get-color "" "reset") +WS=$(git config get --type=color --default="blue reverse" color.diff.whitespace) +RESET=$(git config get --type=color --default="reset" "") echo "${WS}your whitespace color or blue reverse${RESET}" ------------ @@ -568,11 +601,11 @@ For URLs in `https://weak.example.com`, `http.sslVerify` is set to false, while it is set to `true` for all others: ------------ -% git config --type=bool --get-urlmatch http.sslverify https://good.example.com +% git config get --type=bool --url=https://good.example.com http.sslverify true -% git config --type=bool --get-urlmatch http.sslverify https://weak.example.com +% git config get --type=bool --url=https://weak.example.com http.sslverify false -% git config --get-urlmatch http https://weak.example.com +% git config get --url=https://weak.example.com http http.cookieFile /tmp/cookie.txt http.sslverify false ------------ diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 918a0aa42b2415..e41493292f6f84 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials SYNOPSIS -------- ------------------ -'git credential' (fill|approve|reject) +'git credential' (fill|approve|reject|capability) ------------------ DESCRIPTION @@ -41,6 +41,9 @@ If the action is `reject`, git-credential will send the description to any configured credential helpers, which may erase any stored credentials matching the description. +If the action is `capability`, git-credential will announce any capabilities +it supports to standard output. + If the action is `approve` or `reject`, no output should be emitted. TYPICAL USE OF GIT CREDENTIAL @@ -111,7 +114,9 @@ attribute per line. Each attribute is specified by a key-value pair, separated by an `=` (equals) sign, followed by a newline. The key may contain any bytes except `=`, newline, or NUL. The value may -contain any bytes except newline or NUL. +contain any bytes except newline or NUL. A line, including the trailing +newline, may not exceed 65535 bytes in order to allow implementations to +parse efficiently. Attributes with keys that end with C-style array brackets `[]` can have multiple values. Each instance of a multi-valued attribute forms an @@ -178,6 +183,61 @@ empty string. Components which are missing from the URL (e.g., there is no username in the example above) will be left unset. +`authtype`:: + This indicates that the authentication scheme in question should be used. + Common values for HTTP and HTTPS include `basic`, `bearer`, and `digest`, + although the latter is insecure and should not be used. If `credential` + is used, this may be set to an arbitrary string suitable for the protocol in + question (usually HTTP). ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`credential`:: + The pre-encoded credential, suitable for the protocol in question (usually + HTTP). If this key is sent, `authtype` is mandatory, and `username` and + `password` are not used. For HTTP, Git concatenates the `authtype` value and + this value with a single space to determine the `Authorization` header. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`ephemeral`:: + This boolean value indicates, if true, that the value in the `credential` + field should not be saved by the credential helper because its usefulness is + limited in time. For example, an HTTP Digest `credential` value is computed + using a nonce and reusing it will not result in successful authentication. + This may also be used for situations with short duration (e.g., 24-hour) + credentials. The default value is false. ++ +The credential helper will still be invoked with `store` or `erase` so that it +can determine whether the operation was successful. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`state[]`:: + This value provides an opaque state that will be passed back to this helper + if it is called again. Each different credential helper may specify this + once. The value should include a prefix unique to the credential helper and + should ignore values that don't match its prefix. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`continue`:: + This is a boolean value, which, if enabled, indicates that this + authentication is a non-final part of a multistage authentication step. This + is common in protocols such as NTLM and Kerberos, where two rounds of client + authentication are required, and setting this flag allows the credential + helper to implement the multistage authentication step. This flag should + only be sent if a further stage is required; that is, if another round of + authentication is expected. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. This attribute is 'one-way' from a credential helper to +pass information to Git (or other programs invoking `git credential`). + `wwwauth[]`:: When an HTTP response is received by Git that includes one or more @@ -189,7 +249,45 @@ attribute 'wwwauth[]', where the order of the attributes is the same as they appear in the HTTP response. This attribute is 'one-way' from Git to pass additional information to credential helpers. -Unrecognised attributes are silently discarded. +`capability[]`:: + This signals that Git, or the helper, as appropriate, supports the capability + in question. This can be used to provide better, more specific data as part + of the protocol. A `capability[]` directive must precede any value depending + on it and these directives _should_ be the first item announced in the + protocol. ++ +There are two currently supported capabilities. The first is `authtype`, which +indicates that the `authtype`, `credential`, and `ephemeral` values are +understood. The second is `state`, which indicates that the `state[]` and +`continue` values are understood. ++ +It is not obligatory to use the additional features just because the capability +is supported, but they should not be provided without the capability. + +Unrecognised attributes and capabilities are silently discarded. + +[[CAPA-IOFMT]] +CAPABILITY INPUT/OUTPUT FORMAT +------------------------------ + +For `git credential capability`, the format is slightly different. First, a +`version 0` announcement is made to indicate the current version of the +protocol, and then each capability is announced with a line like `capability +authtype`. Credential helpers may also implement this format, again with the +`capability` argument. Additional lines may be added in the future; callers +should ignore lines which they don't understand. + +Because this is a new part of the credential helper protocol, older versions of +Git, as well as some credential helpers, may not support it. If a non-zero +exit status is received, or if the first line doesn't start with the word +`version` and a space, callers should assume that no capabilities are supported. + +The intention of this format is to differentiate it from the credential output +in an unambiguous way. It is possible to use very simple credential helpers +(e.g., inline shell scripts) which always produce identical output. Using a +distinct format allows users to continue to use this syntax without having to +worry about correctly implementing capability advertisements or accidentally +confusing callers querying for capabilities. GIT --- diff --git a/Documentation/git-for-each-repo.txt b/Documentation/git-for-each-repo.txt index 94bd19da263fa3..abe3527aacab55 100644 --- a/Documentation/git-for-each-repo.txt +++ b/Documentation/git-for-each-repo.txt @@ -42,6 +42,15 @@ These config values are loaded from system, global, and local Git config, as available. If `git for-each-repo` is run in a directory that is not a Git repository, then only the system and global config is used. +--keep-going:: + Continue with the remaining repositories if the command failed + on a repository. The exit code will still indicate that the + overall operation was not successful. ++ +Note that the exact exit code of the failing command is not passed +through as the exit code of the `for-each-repo` command: If the command +failed in any of the specified repositories, the overall exit code will +be 1. SUBPROCESS BEHAVIOR ------------------- diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 728bb3821c1729..8708b3159309d5 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -20,7 +20,7 @@ SYNOPSIS [--in-reply-to=] [--suffix=.] [--ignore-if-in-upstream] [--always] [--cover-from-description=] - [--rfc] [--subject-prefix=] + [--rfc[=]] [--subject-prefix=] [(--reroll-count|-v) ] [--to=] [--cc=] [--[no-]cover-letter] [--quiet] @@ -238,10 +238,21 @@ the patches (with a value of e.g. "PATCH my-project"). value of the `format.filenameMaxLength` configuration variable, or 64 if unconfigured. ---rfc:: - Prepends "RFC" to the subject prefix (producing "RFC PATCH" by - default). RFC means "Request For Comments"; use this when sending - an experimental patch for discussion rather than application. +--rfc[=]:: + Prepends the string __ (defaults to "RFC") to + the subject prefix. As the subject prefix defaults to + "PATCH", you'll get "RFC PATCH" by default. ++ +RFC means "Request For Comments"; use this when sending +an experimental patch for discussion rather than application. +"--rfc=WIP" may also be a useful way to indicate that a patch +is not complete yet ("WIP" stands for "Work In Progress"). ++ +If the convention of the receiving community for a particular extra +string is to have it _after_ the subject prefix, the string __ +can be prefixed with a dash ("`-`") to signal that the the rest of +the __ string should be appended to the subject prefix instead, +e.g., `--rfc='-(WIP)'` results in "PATCH (WIP)". -v :: --reroll-count=:: @@ -346,6 +357,11 @@ material (this may change in the future). between the previous and current series of patches by adjusting the creation/deletion cost fudge factor. See linkgit:git-range-diff[1]) for details. ++ +Defaults to 999 (the linkgit:git-range-diff[1] uses 60), as the use +case is to show comparison with an older iteration of the same +topic and the tool should find more correspondence between the two +sets of patches. --notes[=]:: --no-notes:: diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index e8f3ccb4337488..f5b02ef114eb5a 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -114,7 +114,7 @@ of end users. The official repository of the 'git gui' project can be found at: - https://github.com/prati0100/git-gui.git/ + https://github.com/j6t/git-gui GIT --- diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index 1c4f696ab57e2a..76c86c3ce4fee0 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -9,7 +9,7 @@ git-ls-remote - List references in a remote repository SYNOPSIS -------- [verse] -'git ls-remote' [--heads] [--tags] [--refs] [--upload-pack=] +'git ls-remote' [--branches] [--tags] [--refs] [--upload-pack=] [-q | --quiet] [--exit-code] [--get-url] [--sort=] [--symref] [ [...]] @@ -21,14 +21,16 @@ commit IDs. OPTIONS ------- --h:: ---heads:: +-b:: +--branches:: -t:: --tags:: - Limit to only refs/heads and refs/tags, respectively. + Limit to only local branches and local tags, respectively. These options are _not_ mutually exclusive; when given both, references stored in refs/heads and refs/tags are - displayed. Note that `git ls-remote -h` used without + displayed. Note that `--heads` and `-h` are deprecated + synonyms for `--branches` and `-b` and may be removed in + the future. Also note that `git ls-remote -h` used without anything else on the command line gives help, consistent with other git subcommands. diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index dd388fa21d5a51..84cb2edf6d0922 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -72,6 +72,11 @@ OPTIONS As the merge-base is provided directly, and do not need to specify commits; trees are enough. +-X