diff --git a/.b4-config b/.b4-config new file mode 100644 index 00000000000000..fd4fb56b6d5678 --- /dev/null +++ b/.b4-config @@ -0,0 +1,6 @@ +# Note that these are default values that you can tweak via the typical +# git-config(1) machinery. You thus shouldn't ever have to change this file. +# See also https://b4.docs.kernel.org/en/latest/config.html. +[b4] +send-same-thread = shallow +prep-cover-template = ./.b4-cover-template diff --git a/.b4-cover-template b/.b4-cover-template new file mode 100644 index 00000000000000..8168d8a10b3a9e --- /dev/null +++ b/.b4-cover-template @@ -0,0 +1,12 @@ +${cover} + +--- +${shortlog} + +${diffstat} + +${range_diff} +--- +base-commit: ${base_commit} +change-id: ${change_id} +${prerequisites} diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index cf341d74dbff21..828207c951c16e 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -5,23 +5,33 @@ on: [push, pull_request] env: DEVELOPER: 1 -# If more than one workflow run is triggered for the very same commit hash -# (which happens when multiple branches pointing to the same commit), only -# the first one is allowed to run, the second will be kept in the "queued" -# state. This allows a successful completion of the first run to be reused -# in the second run via the `skip-if-redundant` logic in the `config` job. +# For pull requests, only the latest workflow run is allowed to proceed. +# Older runs are canceled when a new revision is pushed. # -# The only caveat is that if a workflow run is triggered for the same commit -# hash that another run is already being held, that latter run will be -# canceled. For more details about the `concurrency` attribute, see: +# For pushes, if more than one workflow run is triggered for the very same +# commit hash (which happens when multiple branches point to the same commit), +# only the first one is allowed to run. This allows a successful completion of +# the first run to be reused in the second run via the `skip-if-redundant` +# logic in the `config` job. +# +# For more details about the `concurrency` attribute, see: # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency concurrency: - group: ${{ github.sha }} + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: ci-config: name: config - if: vars.CI_BRANCHES == '' || contains(vars.CI_BRANCHES, github.ref_name) + if: | + (fromJSON(vars.CI_CONFIG).allow == '' || + contains(fromJSON(vars.CI_CONFIG).allow, github.ref_name)) && + (fromJSON(vars.CI_CONFIG).reject == '' || + !contains(fromJSON(vars.CI_CONFIG).reject, github.ref_name)) && + (fromJSON(vars.CI_CONFIG).allow-prefix == '' || + startsWith(github.ref_name, fromJSON(vars.CI_CONFIG).allow-prefix)) && + (fromJSON(vars.CI_CONFIG).reject-prefix == '' || + !startsWith(github.ref_name, fromJSON(vars.CI_CONFIG).reject-prefix)) runs-on: ubuntu-latest outputs: enabled: ${{ steps.check-ref.outputs.enabled }}${{ steps.skip-if-redundant.outputs.enabled }} @@ -411,16 +421,15 @@ jobs: # A RHEL 8 compatible distro. Supported until 2029-05-31. - jobname: almalinux-8 image: almalinux:8 - # Supported until 2026-08-31. - - jobname: debian-11 - image: debian:11 env: jobname: ${{matrix.vector.jobname}} CC: ${{matrix.vector.cc}} CI_JOB_IMAGE: ${{matrix.vector.image}} CUSTOM_PATH: /custom runs-on: ubuntu-latest - container: ${{matrix.vector.image}} + container: + image: ${{ matrix.vector.image }} + options: ${{ github.repository_visibility == 'private' && '--pids-limit 16384 --ulimit nproc=16384:16384 --ulimit nofile=32768:32768' || '' }} steps: - name: prepare libc6 for actions if: matrix.vector.jobname == 'linux32' @@ -458,8 +467,8 @@ jobs: if: needs.ci-config.outputs.enabled == 'yes' env: jobname: StaticAnalysis - CI_JOB_IMAGE: ubuntu-22.04 - runs-on: ubuntu-22.04 + CI_JOB_IMAGE: ubuntu-latest + runs-on: ubuntu-latest concurrency: group: static-analysis-${{ github.ref }} cancel-in-progress: ${{ needs.ci-config.outputs.skip_concurrent == 'yes' }} diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 1a8e90932cc292..0242283c3c5571 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -88,13 +88,8 @@ test:osx: tags: - saas-macos-large-m2pro variables: - TEST_OUTPUT_DIRECTORY: "/Volumes/RAMDisk" + TEST_OUTPUT_DIRECTORY: "/tmp/test-output" before_script: - # Create a 4GB RAM disk that we use to store test output on. This small hack - # significantly speeds up tests by more than a factor of 2 because the - # macOS runners use network-attached storage as disks, which is _really_ - # slow with the many small writes that our tests do. - - sudo diskutil apfs create $(hdiutil attach -nomount ram://8192000) RAMDisk - ./ci/install-dependencies.sh script: - ./ci/run-build-and-tests.sh @@ -152,6 +147,9 @@ test:mingw64: needs: - job: "build:mingw64" artifacts: true + variables: + # Windows runners don't have enough RAM to run EXPENSIVE tests. + GIT_TEST_LONG: false before_script: - *windows_before_script - git-sdk/usr/bin/bash.exe -l -c 'tar xf artifacts/artifacts.tar.gz' @@ -200,6 +198,9 @@ test:msvc-meson: script: - | & "C:/Program Files/Git/usr/bin/bash.exe" -l -c 'ci/run-test-slice-meson.sh build $CI_NODE_INDEX $CI_NODE_TOTAL' + variables: + # Windows runners don't have enough RAM to run EXPENSIVE tests. + GIT_TEST_LONG: false after_script: - | if ($env:CI_JOB_STATUS -ne "success") { @@ -226,7 +227,7 @@ test:fuzz-smoke-tests: - ./ci/run-build-and-minimal-fuzzers.sh static-analysis: - image: ubuntu:22.04 + image: ubuntu:latest stage: analyze needs: [ ] variables: diff --git a/.mailmap b/.mailmap index c2e3939beb286d..e3fab1df9dbfa8 100644 --- a/.mailmap +++ b/.mailmap @@ -39,12 +39,13 @@ Chris Shoemaker Chris Wright Christian Ludwig Cord Seele -Christian Couder +Christian Couder Christian Stimming Christopher Díaz Riveros Christopher Diaz Riveros Clemens Buchacher Clemens Buchacher Csaba Henk +D. Ben Knoble Dan Johnson Dana L. How Dana L. How Dana How @@ -65,6 +66,8 @@ Derrick Stolee Deskin Miller Đoàn Trần Công Danh Doan Tran Cong Danh Dirk Süsserott +Elijah Newren +Elijah Newren Emily Shaffer Eric Blake Eric Hanchrow @@ -277,6 +280,7 @@ Sven Verdoolaege SZEDER Gábor Tao Qingyun <845767657@qq.com> Tay Ray Chuan +Taylor Blau Ted Percival Theodore Ts'o Thomas Ackermann diff --git a/Documentation/Makefile b/Documentation/Makefile index 2699f0b24af192..f8dea4b3953250 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -129,6 +129,7 @@ TECH_DOCS += technical/long-running-process-protocol TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/packfile-uri TECH_DOCS += technical/pack-heuristics +TECH_DOCS += technical/paint-down-to-common TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone TECH_DOCS += technical/platform-support diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index b9fdefce0224c9..34bfa2e3a9aaec 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -790,7 +790,7 @@ We can note a few things: v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of three patches in the second iteration. Each iteration is sent with a new cover letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the - previous iteration (more on that below). + first iteration (more on that below). NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without _i_/_n_ numbering (in the above thread overview, no single-patch topic appears, @@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not be merged. ---- -At this point the tutorial diverges, in order to demonstrate two +At this point the tutorial diverges, in order to demonstrate three different methods of formatting your patchset and getting it reviewed. The first method to be covered is GitGitGadget, which is useful for those @@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some setup which can change depending on your system and will not be covered in this tutorial. +The third method to be covered is `b4`, which builds on top of `git +format-patch` and `git send-email`. This method is the recommended way to +submit patches via mail as it automates a lot of the bookkeeping required by +`git send-email`. + Regardless of which method you choose, your engagement with reviewers will be -the same; the review process will be covered after the sections on GitGitGadget -and `git send-email`. +the same; the review process will be covered after the sections on GitGitGadget, +`git send-email` and `b4`. [[howto-ggg]] == Sending Patches via GitGitGadget @@ -1214,7 +1219,7 @@ between your last version and now, if it's something significant. You do not need the exact same body in your second cover letter; focus on explaining to reviewers the changes you've made that may not be as visible. -You will also need to go and find the Message-ID of your previous cover letter. +You will also need to go and find the Message-ID of your first cover letter. You can either note it when you send the first series, from the output of `git send-email`, or you can look it up on the https://lore.kernel.org/git[mailing list]. Find your cover letter in the @@ -1227,8 +1232,8 @@ Message-ID: Your Message-ID is ``. This example will be used below as well; make sure to replace it with the correct Message-ID for your -**previous cover letter** - that is, if you're sending v2, use the Message-ID -from v1; if you're sending v3, use the Message-ID from v2. +**first cover letter** - that is, for any subsequent version that you send, +always use the Message-ID from v1. While you're looking at the email, you should also note who is CC'd, as it's common practice in the mailing list to keep all CCs on a thread. You can add @@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644 2.21.0.392.gf8f6787159e-goog ---- +[[howto-b4]] +== Sending Patches with `b4` + +`b4` is a tool that builds on top of `git format-patch` and `git send-email`. +It automates much of the bookkeeping involved in sending a patch series to a +mailing-list-based project. + +Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference. + +[[prep-b4]] +=== Preparing a Patch Series + +`b4` tracks your patch series as a branch. To start tracking the `psuh` branch +you have been working on, run: + +---- +$ b4 prep --enroll master +---- + +This enrolls the current branch, using `master` as the base of the topic. `b4` +manages the cover letter as part of the branch, so you can edit it at any time +with: + +---- +$ b4 prep --edit-cover +---- + +The cover letter not only tracks the content of the top-level mail, but also +the set of recipients. You can add recipients by adding `To:` and `Cc:` +trailer lines. + +[[send-b4]] +=== Sending the Patches + +Before sending the series out for real, you can inspect what `b4` would send by +passing `--dry-run`: + +---- +$ b4 send --dry-run +---- + +Once you are happy with the result, send the series with: + +---- +$ b4 send +---- + +[[v2-b4]] +=== Sending v2 + +When you are ready to send a new iteration of your series, refine your +patches as usual using linkgit:git-rebase[1]. Note that you typically want to +rebase on top of the cover letter. You can configure an alias to enable easy +rebases going forward: + +--- +$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"' +$ git b4-rebase -i +--- + +Before sending out the new version you should also update the cover letter with +`b4 prep --edit-cover` to note the relevant changes compared to the previous +version. You can inspect the changes between the two versions with `b4 prep +--compare-to=v1`. + +Same as with the first version, you can use `b4 send` to send out the second +version. `b4` automatically bumps the version to `v2`, generates the range-diff +against the previous iteration, and threads the new series as a reply to the +cover letter of the first version. + +[[configure-b4]] +=== Configure b4 + +`b4` can be configured via linkgit:git-config[1]. In addition to that, projects +can have their own set of defaults in `.b4-config` in the root tree, which also +uses Git's config format. The user's configuration always takes precedence over +the per-project defaults. + +Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation] +for more information on the available options. + [[now-what]] == My Patch Got Emailed - Now What? @@ -1330,6 +1416,28 @@ previous one" patches over 2 days), reviewers would strongly prefer if a single polished version came 2 days later instead, and that version with fewer mistakes were the only one they would need to review. +This consideration applies not only when going from the initial patch to v2, +but also to later iterations of the same series. There is no fixed rule for how +long to wait before sending a new version. A useful default is to send at most +one new version of the same patch series per day. This gives multiple reviewers +time to comment, gives reviewers across time zones a fair chance to +participate, lets you batch feedback together, and gives you time to think +through the comments you received. Knowing that you should not immediately send +another version also encourages you to review the patches more carefully before +sending them, catch small mistakes such as typos and off-by-one errors +yourself, and let reviewers spend more of their attention on design, +algorithms, and other substantial issues. + +The right timing depends on the topic and the feedback. Larger series usually +need more review time. If the only comments so far are minor, such as typo +fixes, it often makes sense to wait a little longer in case deeper reviews are +still coming. If the comments call for substantial rework, do not rush out an +updated version before you have reviewed the larger changes carefully. Instead, +reply to the review that prompted the rewrite, say that you are preparing a +substantial rework, and mention which parts of the current series will become +obsolete so reviewers can avoid spending time on them until the updated series +is ready. + [[reviewing]] === Responding to Reviews @@ -1337,11 +1445,13 @@ fewer mistakes were the only one they would need to review. After a few days, you will hopefully receive a reply to your patchset with some comments. Woohoo! Now you can get back to work. -It's good manners to reply to each comment, notifying the reviewer that you have -made the change suggested, feel the original is better, or that the comment -inspired you to do something a new way which is superior to both the original -and the suggested change. This way reviewers don't need to inspect your v2 to -figure out whether you implemented their comment or not. +It's good manners to reply to each comment in the mailing list discussion +instead of letting the next version of your patch be your only response. Tell +the reviewer whether you plan to make the suggested change, keep the original, +or pursue a different approach. This way reviewers can respond to your reasoning +before you spend time preparing a version they may not agree with, and later do +not need to inspect your v2 to figure out whether you implemented their comment +or not. Reviewers may ask you about what you wrote in the patchset, either in the proposed commit log message or in the changes themselves. You @@ -1367,6 +1477,11 @@ effect which had not occurred to you. It is always okay to ask for clarification if you aren't sure why a change was suggested, or what the reviewer is asking you to do. +When replying to review comments, quote only the parts of the message that are +relevant to your response. It is usually helpful to trim away unrelated context, +such as large portions of the patch that are not being discussed, while keeping +enough quoted text for readers to understand what you are responding to. + Make sure your email client has a plaintext email mode and it is turned on; the Git list rejects HTML email. Please also follow the mailing list etiquette outlined in the diff --git a/Documentation/RelNotes/2.55.0.adoc b/Documentation/RelNotes/2.55.0.adoc index f5643534dcc19c..e7e77a8112385c 100644 --- a/Documentation/RelNotes/2.55.0.adoc +++ b/Documentation/RelNotes/2.55.0.adoc @@ -85,8 +85,8 @@ Performance, Internal Implementation, Development Support etc. * Promisor remote handling has been refactored and fixed in preparation for auto-configuration of advertised remotes. - * Rust support is enabled by default (but still allows opting out) in - some future version of Git. + * Rust support is enabled by default (but still allows opting out); + in Git version 3.0, Rust will become mandatory. * Preparation of the xdiff/ codebase to work with Rust. diff --git a/Documentation/RelNotes/2.56.0.adoc b/Documentation/RelNotes/2.56.0.adoc new file mode 100644 index 00000000000000..27becd62a941da --- /dev/null +++ b/Documentation/RelNotes/2.56.0.adoc @@ -0,0 +1,753 @@ +Git v2.56 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * Advice shown by "git status" when the local branch is behind or has + diverged from its push branch has been updated to suggest "git pull + ". + + * The handling of promisor-remote protocol capability has been updated + to allow the other side to add to the list of promisor remotes via the + 'promisor.acceptFromServerURL' configuration variable. + + * The 'ort' merge backend has been hardened against corrupt trees by + ensuring it aborts under appropriate error conditions. + + * The `fetch.followRemoteHEAD` configuration variable has been added to + provide a default for the per-remote `remote..followRemoteHEAD` + setting. + + * "git log --follow" has been updated to better handle non-linear + history, in which the path being tracked gets renamed differently in + multiple history lines. + + * The "git repo info" command has been taught new keys to output both + absolute and relative paths for "gitdir" and "commondir", supported by + a new path-formatting helper extracted from "git rev-parse". + + * When 'git push origin/main' or 'git branch origin main' is run, the + command is now recognized as a potential typo, and advice has been + added to offer a typo fix. + + * The 'git refs' toolbox has been extended with new 'create', 'delete', + 'update', and 'rename' subcommands to create, delete, update, and + rename references, respectively. + + * The experimental 'git history' command has been taught a new 'drop' + subcommand to remove a commit, with its descendants replayed onto its + parent. + + * The alignment of commit object name abbreviations in 'git blame' + output has been optimized to reserve a column for marks (caret, + question mark, or asterisk) only when such marks are actually shown. + + * Option parsing with 'git rev-parse --parseopt' and in most 'git' + subcommands has been updated to exit with 0 (instead of 129) when the + help option ('-h' or '--help') is requested directly by the user, + aligning with standard Unix convention. + + * The '[includeIf "condition"]' conditional inclusion facility for + configuration files has been taught to use the location of the + worktree in its condition. + + * The usage string and SYNOPSIS for 'git fast-export' have been + standardized to make them consistent with each other and with other + commands. + + * 'git log --graph' has been modified to visually distinguish parentless + 'root' commits (and commits that become roots due to history + simplification) by indenting them, preventing them from appearing + falsely related to unrelated commits rendered immediately above them. + + * Userdiff patterns for Swift have been added, with support for + Swift-specific constructs such as attributes, modifiers, failable + initializers, and generics. + + * Configuration file locking has been updated to retry for a short + period, avoiding failures when multiple processes attempt to update + the configuration simultaneously. + + * The 'remote-object-info' command has been added to 'git cat-file + --batch-command', allowing clients to request object metadata + (currently size) from a remote server via protocol v2 without + downloading the entire object. Format placeholders are dynamically + filtered on the client based on server-advertised capabilities, + returning empty strings for inapplicable or unsupported fields. + + * 'git branch -d' has been taught to report when a branch cannot be + deleted because it is being used in an active bisect run. + + * 'git mv' has been updated to check for a missing destination + leading directory during the checking phase, allowing 'git mv -n' + to report the failure. The error message when the rename(2) + syscall fails has also been improved to name both the source and + the destination. + + * 'git add' has been taught a new '--resolved' option to stage + conflict-resolved paths, while leaving unrelated local changes + unstaged. It scans the unmerged paths for leftover conflict + markers and aborts if any are found. + + * The known limitations of the ref format migration in 'git refs' have + been moved to be displayed as a warning admonition directly under the + description of the 'migrate' subcommand, improving visibility. A + reference to 'git-maintenance' has also been corrected to use the + 'linkgit' macro. + + * The 'git bisect' command has been taught a + '--reset-when-found[=]' option that tells the command to + automatically run 'git bisect reset' to jump back to the original + state or to the found culprit. + + * The 'git branch' command has been taught the '--delete-merged' option + to remove local branches that are already merged into their tracked + remote-tracking branches. + + * The 'remote-object-info' command for 'git cat-file --batch-command' + has been extended to support the '%(objecttype)' placeholder. + + * The usage string of 'git fast-import' has been updated to use the + parse_options() API for displaying help, and its SYNOPSIS in the + documentation has been standardized to match. + + * The error message given by 'git send-email' when a message file is + missing a 'Subject:' header has been clarified, and the error string + is now terminated with a newline so that Perl avoids appending its + internal source location data. + + * The '--shallow-file' option of 'git' command requires a value, but the + code did not check the presence of a value and instead segfaulted + without one, which has been corrected. + + * 'git repack' has been taught '--drop-filtered' to delete local + promisor blobs exceeding a limit (currently 'blob:limit=') in partial + clones, reclaiming space. Guards prevent running during other + operations or if referenced by the index. + + * The documentation for 'git format-rev' has been updated to use the + [synopsis] block definition on code blocks to properly highlight + placeholders, and a quoting inconsistency in the running text has + been fixed. + + * The DWIM logic in 'git worktree add' sometimes tried to infer a + remote-tracking branch when an explicit '-b' or '-B' option was + given to create a new branch, causing the explicit branch name to + be ignored, which has been corrected. + + * The command line completion (in contrib/) has been taught to handle + the experimental 'git history' command. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * The refactoring of 'setup.c' has been continued to drop remaining + global state (`git_work_tree_cfg`, `is_bare_repository_cfg`), updating + `is_bare_repository()` to no longer implicitly rely on + `the_repository`. + + * Project-specific configuration for b4 has been introduced, and the + documentation has been updated to recommend using it as a + streamlined method for submitting patches. + + * The default format path of git cat-file --batch has been optimized + to use strbuf_add_oid_hex() and strbuf_add_uint() instead of + strbuf_addf(), yielding a noticeable speedup. + + * Commands that list branches and tags (like git branch and git tag) + have been optimized to pass the namespace prefix when initializing + their ref iterator, avoiding a loose-ref scaling regression in + repositories with many unrelated loose references. + + * The packed object source has been refactored into a proper struct + odb_source. + + * The global configuration variables protect_hfs and protect_ntfs have + been migrated into struct repo_config_values to tie them to + per-repository configuration state. + + * The trailer sections in SubmittingPatches have been updated to + encourage use of standard trailers. + + * The documentation in SubmittingPatches has been updated to clarify how + patch contributors should respond to design and viability critiques, + and how the resolution of such critiques should be recorded in the + final commit messages. + + * The pack-objects command has been updated to support reachability + bitmaps and delta-islands concurrently with the `--path-walk` option, + allowing faster packaging by falling back to path-walk when bitmaps + cannot fully satisfy the request. + + * Documentation on community contribution guidelines has been updated to + encourage replying to review comments before rerolling, and to advise + a default limit of at most one reroll per day to give reviewers across + different time zones enough time to participate. + + * The lazy priority queue optimization pattern (deferring actual removal + in 'prio_queue_get()' to allow get+put fusion) has been folded + directly into 'prio_queue' itself, speeding up commit traversal + workflows and simplifying callers. + + * The 'reprepare()' callback for object database sources has been + generalized into a 'prepare()' callback with an optional flush cache + flag, and a new 'odb_prepare()' wrapper has been introduced to allow + pre-opening object database sources. + + * The 'whence' field in 'struct object_info' has been removed. The + backend-specific object information retrieval has been refactored into + an opt-in 'struct object_info_source' structure. + + * A racy build failure under Meson has been corrected by ensuring that + the generated header file 'hook-list.h' is built before compiling + files in 'builtin_sources' that depend on it. + + * The repository discovery and repository configuration phases, which + were previously intertwined in 'setup.c', have been split. Repository + discovery has been updated to populate a 'struct repo_discovery' + without modifying the repository state, which is then taken by + repository configuration to initialize the repository, paving the way + for clean unification of repository configuration. + + * The 'SubmittingPatches' document has been updated to explicitly + describe the expectation for contributors to retract or abandon their + patch series when they are no longer pursuing it. + + * The contributor guide has been updated to advise new contributors to + trim irrelevant quoted text when replying to review comments, matching + the existing advice given to reviewers. + + * The build system has been updated to support building universal macOS + binaries when 'Rust' is enabled, by compiling separate static archives + for each target triple listed in 'RUST_TARGETS' and combining them + using the macOS 'lipo' tool. The 'git-credential-osxkeychain' helper + has been updated to link against '$(RUST_LIB)' when 'Rust' is enabled. + + * The test suite has been updated to use the 'test_grep' helper instead + of bare 'grep' for test assertions, allowing file contents to be + printed on failure for easier debugging. A new 'greplint' linter has + been introduced to detect and prevent new bare 'grep' assertions from + being added to the test suite. + + * The pipelines in 't1410-reflog.sh' have been replaced with the + 'test_stdout_line_count' helper to avoid suppressing the exit code of + 'git' commands, ensuring failures are not hidden from the test suite. + + * The cache-scanning loop in 'next_cache_entry()' has been optimized + to avoid rescanning already-unpacked index entries, preventing a + quadratic performance slow-down when diffing the working tree + against a commit with a pathspec matching early index entries. + + * The global configuration variable 'ignore_case' (representing the + 'core.ignorecase' configuration) has been migrated into 'struct + repo_config_values' to tie it to a specific repository instance. + + * The performance of ref updates and reads using the 'reftable' backend + in the presence of many deletion tombstone records has been optimized + by removing the tombstone suppression flag from the merged iterator + and instead skipping tombstones at higher-level call sites where + iteration bounds are known. + + * Various code paths have been hardened against potential NULL-pointer + dereferences and invalid file descriptor accesses flagged by + Coverity. + + * The in-tree 'b4' cover letter template has been updated to include the + 'change-id' trailer, ensuring that sent tags generated by 'b4' contain + the required tracking information for subsequent runs. + + * 'git receive-pack' has been refactored to use ODB transaction + interfaces instead of directly managing 'tmp_objdir' for staging + incoming objects, bringing it closer to being ODB backend agnostic. + + * The test script 't/t9811-git-p4-label-import.sh' has been + modernized to use 'test_path_is_file' and 'test_path_is_missing' + instead of raw 'test -f' and '! test -f' calls. + + * A redundant strbuf_reset() call in the 'HAVE_GETDELIM' path of + strbuf_getwholeline() has been removed, as getdelim() overwrites the + buffer and the length is updated afterward. + + * The object database enumeration interface odb_for_each_object() has + been taught to accept object filters, allowing the underlying backends + to optimize the traversal by using reachability bitmaps when + available. 'git cat-file --batch-all-objects' has been updated to use + this generic interface, simplifying its code and avoiding direct + access to ODB backend internals. + + * The test script 't/t1100-commit-tree-options.sh' has been modernized + by converting test cases to the modern style (using single quotes and + tab indentation) and moving the creation of the expected file inside + the setup test so it runs under the protection of the test harness. + + * The test script 't/t7614-merge-signoff.sh' has been updated to avoid + suppressing the exit code of 'git' commands in a pipe. + + * The 'git rev-list --no-walk' command has been corrected to restore + pathspec filtering, which was lost when the streaming walk was + refactored. + + * The ref subsystem and the worktree API have been refactored to pass a + repository pointer down the call chain, allowing them to drop + references to the global 'the_repository' variable. As part of this, + the handling of the 'core.packedRefsTimeout' configuration has been + moved into the per-repository ref store structure. + + * 'git branch --contains' and 'git for-each-ref --contains' have been + optimized to use the memoized commit traversal previously used only by + 'git tag --contains', significantly speeding up connectivity checks + across many candidate refs with shared history. + + * The passing of push destination specifications in the 'remote-curl' + helper has been simplified by removing the explicit 'count' parameter + and relying on the NULL-termination of the array. + + * The dependency on the global 'the_repository' variable in the + 'refspec.c' API has been removed by passing the hash algorithm + explicitly to refspec-parsing functions and storing it in 'struct + refspec'. + + * The enumeration of untracked and ignored files in 'git status' has + been optimized by avoiding quadratic complexity when inserting into + string lists, reducing the construction cost from O(n^2) to O(n log + n). + + * The copy_file() and copy_file_with_time() functions have been + refactored to take a repository parameter, allowing the removal of the + implicit dependency on the global 'the_repository' variable in + 'copy.c'. + + * The tempfile and lockfile APIs have been refactored to stop depending + on the 'the_repository' global variable, and their callers have been + updated to use the repository-aware variants. + + * The 'trust_executable_bit' (coming from the 'core.filemode' + configuration) has been migrated into 'struct repo_config_values' to + tie it to a specific repository instance. + + * The 'excludes_file' and various other global configuration variables + (including 'editor_program', 'pager_program', 'askpass_program', and + 'push_default') have been migrated into the per-repository structure. + + * The 'git stash push' command has been optimized to avoid unnecessary + sparse index expansion when pathspecs are wholly inside the + sparse-checkout cone. Also, a potential out-of-bounds read in the + sparse-index expansion check helper pathspec_needs_expanded_index() + has been fixed by consistently using the parsed, prefixed path. + + * The logic to write loose objects has been refactored and moved from + 'object-file.c' to the loose backend source file 'odb/source-loose.c', + making the loose backend more self-contained. This is achieved by + first refactoring force_object_loose() to use generic ODB write + interfaces instead of loose-backend internals. + + * Object database housekeeping in 'git gc' and 'git maintenance' has + been refactored to be pluggable. The files-backend-specific logic, + including incremental and geometric repacking as well as object + pruning, has been moved out of the command implementation and into the + files object database source, enabling future alternative object + database backends to implement their own housekeeping services. + + * The image version used by the static-analysis CI job has been bumped + to ubuntu-latest (Ubuntu 24.04), which brings in a newer Coccinelle + version that resolves a severe performance regression. A false + positive warning from the 'CHECK_ASSERTION_SIDE_EFFECTS' build with + GCC 15 in the Bloom filter code has also been silenced to facilitate + the image upgrade. + + * The alias tests in 't/t0014-alias.sh' have been updated to dynamically + query the list of deprecated commands using 'git + --list-cmds=deprecated' to avoid test failures when running with + 'WITH_BREAKING_CHANGES' in a build directory that contains stale + executables of formerly deprecated commands. + + * The code path that deals with relative paths in the diff-lib has + been cleaned up. + + * The get_commit_action() function has been refactored to be a pure + predicate by moving the side-effecting line-level log range folding to + simplify_commit(). This ensures that evaluating a commit's action + before the walk reaches it does not prematurely mutate its tracked + line ranges, making it safer for potential lookahead evaluations. + + * Synopsis and options in the documentation for 'git format-patch', + 'git imap-send', 'git send-email', and 'git request-pull' have been + updated to the modern style. + + * A new test helper commit_body() has been introduced to print the + message body of a commit, and various tests have been updated to use + it instead of spelling out the command pipeline manually and losing + the exit status of the 'git cat-file' command on the upstream of the + pipe. + + * Tests for 'git merge-base --is-ancestor' have been added to cover + exit codes (0 for success, 1 for non-ancestor, 128 for errors) and + to ensure it cannot be combined with '--all'. + + * The 'TRACE2_ANCESTRY' prerequisite in the 't0213' test script has been + refined to avoid failures under user-mode emulation by verifying that + the ancestry collector reports the expected process names rather than + the emulator binary name. + + * Concurrent downloads of packfiles via packfile URIs and dumb HTTP are + safer by avoiding concurrent appends to the staging file. Opening in + read-write mode with separate file offsets prevents corruption and + preserves resumability. 'fetch-pack' now tolerates pre-existing + '.keep' files. + + * The 'ssh-agent' tests in 't7528' have been fixed to work when the + user's login shell is csh-like, by explicitly passing '-s' to + 'ssh-agent' to force Bourne shell syntax. + + * A compatibility wrapper for writev(3p) has been reintroduced, + including fixes for CMake build and 'MAX_IO_SIZE' limits on NonStop. + Calls to write(3p) in send_sideband() and cat_blob() have been + refactored to use writev(3p) wrappers to reduce syscall overhead. + + * The creation of the on-disk data structures for the object database + has been made pluggable, allowing future backends to customize their + setup. As part of this, the initialization of the object database + has been deferred, and the loading of the loose-object map has been + detangled from repository initialization. + + * The 'struct odb_read_stream' and 'struct odb_write_stream' + structures have been consolidated into a single unified 'struct + odb_stream' structure, simplifying object database streaming APIs + and enabling streaming of arbitrary object types. + + * The sequencer has been updated to release the object database before + spawning 'git commit'. This prevents open file handles from + blocking auto-maintenance tasks, such as repacking, on systems like + Windows where open files cannot be easily unlinked. + + * The merge-base computation has been optimized by stopping the walk + early when one side's exclusive commits in the queue are exhausted, + yielding significant speedups for queries with one-sided histories. + + * A handful of code paths have been corrected to check return values + from functions like curl_easy_duphandle(), deflateInit(), lseek(), + dup(), and strbuf_getline_lf(), resolving several Coverity warnings + about unchecked returns. + + * The setting of a now-unused member '.pretty_given' in the sequencer + machinery has been removed. + + * The performance of adding numerous new packfiles has been improved + by introducing a fast path for known-new packfiles to skip an + unnecessary traversal in packfile_list_append(), avoiding a + quadratic complexity regression on load. + + * The unused name parameter in 'struct chdir_notify_entry' has been + removed from chdir_notify_register(), chdir_notify_unregister(), and + related callback signatures across several subsystems, simplifying the + API now that trace output no longer uses it. + + * A heap-use-after-free bug in the object name parsing code when + reporting failures with a relative path to a sparse directory has + been corrected. + + * The object database (odb) API has been refactored to distinguish + between missing objects and corrupt ones by returning more + descriptive error statuses. Both the packed and loose backends now + faithfully propagate error details using a generic strbuf error + mechanism, removing backend-specific leakage from central lookup + paths. + + * The object database layer has been simplified by eagerly loading + alternate object directories upon initialization, instead of + deferring it to the first object lookup. This eliminates the need + for scattered lazy-loading calls throughout the codebase and paves + the way for integrating alternates with the pluggable backends. + + * The threshold for geometric repacking to trigger based on loose + object count has been adjusted to match that of 'git gc --auto', + preventing over-aggressive repacking during concurrent writes. + + * The 'git receive-pack' command has been updated to use a new ODB + transaction interface for writing incoming packfiles, making it more + backend-agnostic. + + * The mechanism to generate a packfile corresponding to the result of + a fetch/push has been made pluggable through a set of object + database callback functions, removing hardcoded references to + 'pack-objects' and enabling alternative ODBs to serve packfiles + themselves. + + * The pack-objects command has been updated to record the total bytes + written to pack files in trace2 output, allowing performance + analysis of different compression settings by comparing the + resulting pack sizes. + + * The global variable 'fetch_if_missing' has been moved to a member in + 'struct repository', continuing the libification process and + allowing per-repository control (such as for submodules). + + +Fixes since v2.55 +----------------- + + * A regression in the error diagnosis code for invalid .git files has + been fixed, avoiding a potential NULL-pointer crash when reporting + that a .git file does not point to a valid repository. + (merge 54a441bcea jk/setup-gitfile-diag-fix later to maint). + + * Support for hashing loose or packed objects larger than 4GB on Windows + and other LLP64 platforms has been improved by converting object header + buffers and data-handling functions from 'unsigned long' to 'size_t'. + (merge d99e13d0be po/hash-object-size-t later to maint). + + * The display of the rebase todo list in "git status" has been + improved to correctly abbreviate object IDs for more commands and + avoid misinterpreting refs as object IDs. + (merge 6f34e5f9e3 pw/status-rebase-todo later to maint). + + * Reference backend configuration has been updated to load lazily to + avoid recursive calls during repository initialization when 'onbranch' + configuration conditions are evaluated. This has also fixed a memory + leak and allowed the unused `chdir_notify_reparent()` machinery to be + dropped. + (merge d6522d01df ps/refs-onbranch-fixes later to maint). + + * The connectivity check has been refactored to search for promisor + objects in a generic way using the object database interface, + rather than iterating packfiles directly. This allows connectivity + checks to work properly in repositories that do not use packfiles. + (merge 66ee9cb930 ps/connected-generic-promisor-checks later to maint). + + * A test checking interactions between git rebase --quit and + autostash in t3420-rebase-autostash.sh has been corrected to use + test_path_is_missing instead of ! grep on a file that shouldn't + exist in the conflicted state. + (merge eaad121fef sg/t3420-do-not-grep-in-missing-file later to maint). + + * The GPG and SSH signature parsing code has been corrected to strip + carriage return characters only when they immediately precede line + feeds, instead of unconditionally stripping all carriage returns. + (merge 5dea8b690b ad/gpg-strip-cr-before-lf later to maint). + + * A memory leak in the 'reftable_writer_new()' initialization function + has been fixed by delaying the allocation of 'struct reftable_writer' + until after input options are validated. + (merge c6fb3b9c3e jk/reftable-leakfix later to maint). + + * A memory leak in the '--base' handling of 'git format-patch' has been + plugged, and the leak reporting of the test suite when running under a + TAP harness has been improved. + (merge 973a0373ff jk/format-patch-leakfix later to maint). + + * A write file stream resource leak has been fixed as part of a code + cleanup. + (merge ebb4d2ffa3 jc/history-message-prep-fix later to maint). + + * Various memory leaks in the Bloom-filter code paths that are exposed + when running tests with the 'GIT_TEST_COMMIT_GRAPH_CHANGED_PATHS=1' + environment variable have been plugged. + (merge 459088ec2e jk/bloom-leak-fixes later to maint). + + * The wincred credential helper has been updated to avoid memory + corruption when erasing credentials and to prevent silent + credential loss when storing OAuth tokens, by correcting buffer + allocations and arguments passed to safe-CRT APIs. + (merge f635ab9ab4 js/wincred-fixes later to maint). + + * Various code paths that initialize a cryptographic hash context but + bail out or finish without calling 'git_hash_final()' have been taught + to call 'git_hash_discard()' to release allocated resources, fixing + memory leaks when Git is built with non-default backends like + 'OpenSSL' or 'libgcrypt'. + (merge 600588d2aa jk/hash-algo-leak-fixes later to maint). + + * Various resource leaks, invalid file descriptor closures, and process + handle ownership issues flagged by Coverity have been fixed. + (merge 9184231173 js/coverity-fixes later to maint). + + * Dockerized CI jobs running in private GitHub repositories have been + adjusted to use explicit process and file limits, preventing resource + exhaustion errors on private runners. + (merge bad766fbac js/ci-dockerized-pid-limit later to maint). + + * Various test scripts have been updated to clean up large temporary + files and repositories, reducing peak disk usage during testing. + Also, expensive tests have been disabled on platforms that lack + sufficient resources (like 32-bit platforms and Windows CI runners), + and the long test suite has been enabled in GitLab CI. + (merge 84248444ad ps/t-fixes-for-git-test-long later to maint). + + * The UTF-8 precomposition wrapper on macOS has been updated to use a + flexible array member to represent the name of a directory entry, + preventing fortified libc checks from failing when the name is + reallocated to be larger than 'NAME_MAX' bytes. + (merge 1eb281159f ih/precompose-flex-array later to maint). + + * The 'git_hash_*()' wrappers have been updated to be used consistently + across the codebase instead of direct calls to members of 'struct + git_hash_algo', and 'git_hash_discard()' has been made idempotent to + simplify cleanups. + (merge 9e396aa553 jk/git-hash-cleanups later to maint). + + * The sideband demultiplexer has been updated to recognize ANSI SGR + escape sequences that use colon-separated subfields (e.g., for + 256-color or true-color codes). + (merge 3792b2aea4 mm/sideband-ansi-sgr-colon-fix later to maint). + + * The 'reftable' code has been hardened against corrupted tables by + fixing out-of-bounds writes, out-of-bounds reads, and abort calls + during parsing. + (merge ca93c27328 ps/reftable-hardening later to maint). + + * A description in the release notes for Git 2.55.0 has been + retroactively updated to clarify that Rust support is enabled by + default, but still optional, and will become mandatory in Git 3.0. + (merge 18b2009d14 jc/relnotes-2.55-rust-fix later to maint). + + * The early-exit optimization in 'paint_down_to_common()' has been + gated on the queue being generation-ordered, fixing a bug where + 'git merge-base' (without '--all') could return incorrect results + on repositories with v1 commit graphs and clock skew. + (merge ae68032a8d kk/commit-reach-find-all-fix later to maint). + + * The client-side parser of the server-advertised bundle-URI list has + been updated to drain the remaining response in order to avoid + protocol desynchronization when the server sends a misconfigured list. + Also, the server-side has been taught to omit empty configuration + values instead of sending invalid key-value lines. + (merge 50de1169e4 tc/bundle-uri-empty-fix later to maint). + + * The 'topo_levels' slab was propagated only to the topmost layer of a + split commit-graph chain, causing topological levels for commits in + base layers to be recomputed during incremental writes. This has been + corrected. + + * The stream-based object signature verification path has been + corrected to avoid double-closing the stream on read errors. + (merge cfd52a74a0 ps/odb-stream-double-close-fix later to maint). + + * The '-i' shorthand for the '--init' option, which was accepted by the + 'git submodule update' command until it was broken in a modernization + of the option-parsing code, has been restored. + (merge ff1da37f58 dm/submodule-update-i-shorthand later to maint). + + * An accidental use of the '%zu' format specifier in 'git + submodule--helper' has been corrected to use 'PRIuMAX' and cast the + value to 'uintmax_t' to avoid portability issues. + (merge 3279c13c00 jc/submodule-helper-avoid-zu later to maint). + + * The rebase post-rewrite notes-copying logic has been corrected. When + a commit is dropped during rebase (e.g., because its changes are + already upstream), it is no longer recorded as rewritten, preventing + its notes from being copied to an unrelated commit. + (merge 42554b78fd pw/rebase-drop-notes-with-commit later to maint). + + * A few memory problems in the Rust interface to C hash functions have + been corrected. The 'Clone' implementation of 'CryptoHasher' now + properly initializes the context before cloning, and its 'Drop' + implementation now discards the context to prevent leaks. + + * The object ID shortening and linking in the 'commitdiff' view of + 'gitweb' has been corrected to work even when the index line carries + a trailing file mode. + (merge fda513d6fe tl/gitweb-shorten-hashes-with-modes later to maint). + + * When the push remote is specified as a URL, the fetch refspec of a + uniquely matching configured remote is now used to find and update + the remote-tracking branch (e.g., '@{push}'). + + * Traversals with '--exclude-first-parent-only' have been corrected + to properly stop after the first parent even when it has already + been marked as 'SEEN'. + (merge 47382f7398 jc/exclude-first-parent-seen later to maint). + + * A segfault when 'git clone --revision' talks to a server that does not + support protocol v2 (falling back to protocol v0) has been corrected. + (merge 1034ad383f af/clone-revision-v0-segfault-fix later to maint). + + * rewrites_release() in 'remote.c' has been updated to free 'struct + rewrite' instances, their '.instead_of' arrays, and their contents. + (merge dcef3bf041 jc/remote-insteadof-leakfix later to maint). + + * The remote-matching logic for submodules has been corrected to resolve + 'url.*.insteadOf' aliases before comparing the inventoried URL from + '.gitmodules' with the URLs of configured remotes. + + * 'git diff --relative' running with '--cached' has been corrected to + avoid a segfault when encountering unmerged paths outside the + prefix. + (merge 447126ed7d jk/diff-relative-cached-unmerged later to maint). + + * Two bugs in how 'git rebase' handles skipped 'fixup' and 'squash' + commands have been fixed. One bug caused an incorrect commit count to + be shown in the template message when multiple commands were skipped, + and another prevented the editor from opening when the final command + in a chain containing 'fixup -c' was skipped. + + * Git for Windows has been updated to avoid auto-detecting the symlink + type if the target path starts with a slash, preventing NTLM + credential leaks when checking out repositories with crafted + symbolic links pointing to network shares. + + * 'git cat-file --batch-command' that asked for 'contents' without + 'type' segfaults, which has been corrected. + (merge 2abc7f0304 jk/cat-file-batch-wo-type-fix later to maint). + + * A memory leak in 'git merge' when run without arguments (which + triggers the default-to-upstream path) has been fixed. A test has + been added to cover this case. + (merge 68cce04a02 tc/merge-default-to-upstream-leakfix later to maint). + + * A boundary case check in reachability bitmap traversal has been + corrected to properly handle the object at position zero, which was + previously skipped, leading to redundant bitmap loading. + (merge b56b48301e dl/pack-bitmap-position-zero later to maint). + + * A crash in the 'sparse-index' collapse code when encountering an + invalidated cache-tree node (due to an intent-to-add path) has been + fixed by avoiding collapsing such subtrees. + (merge eede1e69fe ds/sparse-index-ita-crash later to maint). + + * Documentation for 'git replay' has been updated to refer to its + configuration variables. + (merge 48c0549f5c kh/doc-replay-config later to maint). + + * Documentation for 'git interpret-trailers' has been updated to explain + the format of trailer keys (alphanumeric characters and hyphens), + replace outdated terminology, define key terms upfront, and document + how comment lines in the input are treated. + (merge 4515c86fd9 kh/doc-trailers later to maint). + + * The 'pack-objects' and delta-encoding code paths have been updated to + use 'size_t' instead of 'unsigned long' for object sizes and offset + limits, avoiding potential truncation issues on 64-bit Windows. + (merge d50ac11724 js/pack-objects-delta-size-t later to maint). + + * A client requesting the promisor-remote capability without a value + caused a null pointer dereference, which has been corrected by + rejecting a request without an argument. + (merge dd6b35ff71 en/serve-promisor-remote-fix later to maint). + + * Various tests in 't7900-maintenance.sh' have been updated to use a + throwaway repository, and auto-detaching of maintenance tasks is now + disabled for these tests to fix flaky races with concurrent background + maintenance jobs. + (merge 2775d8bcd1 ps/t7900-deflake-maintenance later to maint). + + * The help text for the '-l' option of 'git diff' has been updated. + (merge 764243bdf4 en/diff-l-opt-help later to maint). + + * 'git -C diff fi' did not complete 'file', which has + been corrected. + (merge 354d1bf3a0 jc/complete-diff-tracked-paths later to maint). + + * 'git -C checkout fi' did not complete 'file', which has + been corrected. + (merge 05e2ab1f31 jc/complete-checkout later to maint). + + * The trailer parsing machinery has been updated to avoid mistaking + lines that begin with a URL (e.g., 'https://...') as trailer lines. + This prevents intended textual URLs from being mangled or mistakenly + treated as metadata keys. + + * Other code cleanup, docfix, build fix, etc. + (merge 026636128f ss/submittingpatches-typofix later to maint). + (merge d2af22cc21 jc/rerere-doc-typofix later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f042bb5aaf4a45..c60855f7069492 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -48,13 +48,41 @@ area. . 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. + respond to them with "Reply-All" on the mailing list, instead of + letting an updated patch series be your only response. Tell + reviewers which suggestions you plan to use, which ones you disagree + with, and when a comment leads you to consider a different approach. + Use these replies and any follow-up discussion as input when + preparing an updated set of patches. ++ +Be particularly mindful of critiques regarding the high-level design +or viability of your proposal (e.g., questioning if the feature is +worth implementing, or if the chosen approach is appropriate). Defend +your design decisions on the list first and work with reviewers and +other members to improve the design before revising the implementation. +This will avoid wasting effort on an implementation before its design is +solid. ++ +Make sure that any new version explains and justifies those design +decisions more clearly, in the cover letter and in the revised commit +messages. Aim to make the reviewers say "it is now clear why we may +want to do this with the updated version". ++ +Topics with unresolved fundamental design critiques will not be +considered ready for merging. + It is often beneficial to allow some time for reviewers to provide feedback before sending a new version, rather than sending an updated series immediately after receiving a review. This helps collect broader -input and avoids unnecessary churn from many rapid iterations. +input, gives reviewers in different time zones a fair chance to comment, +and avoids unnecessary churn from many rapid iterations. Waiting also +encourages you to polish each version before sending it, so reviewers +can focus on substantial issues rather than typos or other small +mistakes. ++ +As a rough default, avoid sending more than one new version of the same +series per day, while considering the size of the series and the depth +of review. . These early update iterations are expected to be full replacements, not incremental updates on top of what you posted already. If you @@ -89,12 +117,26 @@ input and avoids unnecessary churn from many rapid iterations. 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 + topic are appropriate, so such 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 waits to become part of the next major release. +But sometimes things do not work as planned: + +. If a mailing list discussion convinces you that your changes aren't + ideal, please explicitly retract the topic to save the maintainer + time and effort. + +. If you must drop a topic due to shifting priorities, lack of time, + or other commitments, notify the list as a courtesy so others can + take over. Anyone can resurrect the topic later when they have the + capacity to do so. + +. Topics with unaddressed review comments that remain inactive for + four weeks may be discarded by the maintainer. + In the following sections, many techniques and conventions are listed to help your patches get reviewed effectively in such a life cycle. @@ -323,6 +365,10 @@ The body should provide a meaningful commit message, which: . alternate solutions considered but discarded, if any. +. records the resolution of design or viability concerns raised by the + community during the review, if any, ensuring the historical record + explains why the chosen approach was accepted over alternatives. + [[present-tense]] The problem statement that describes the status quo is written in the present tense. Write "The code does X when it is given input Y", @@ -375,7 +421,7 @@ or, on an older version of Git without support for --pretty=reference: .... [[sign-off]] -=== Certify your work by adding your `Signed-off-by` trailer +=== Certify your work by adding your `Signed-off-by:` trailer To improve tracking of who did what, we ask you to certify that you wrote the patch or have the right to pass it on under the same license @@ -412,7 +458,7 @@ d. I understand and agree that this project and the contribution this project or the open source license(s) involved. ____ -you add a "Signed-off-by" trailer to your commit, that looks like +you add a `Signed-off-by:` trailer to your commit, that looks like this: .... @@ -422,19 +468,23 @@ this: This line can be added by Git if you run the git-commit command with the -s option. -Notice that you can place your own `Signed-off-by` trailer when +Notice that you can place your own `Signed-off-by:` trailer when forwarding somebody else's patch with the above rules for D-C-O. Indeed you are encouraged to do so. Do not forget to place an in-body "From: " line at the beginning to properly attribute the change to its true author (see (2) above). +Place this `Signed-off-by:` trailer at the end, after trailers added by +others and after other trailers added by you; see +<> below ("chronological order"). + This procedure originally came from the Linux kernel project, so our rule is quite similar to theirs, but what exactly it means to sign-off your patch differs from project to project, so it may be different from that of the project you are accustomed to. [[real-name]] -Please use a known identity in the `Signed-off-by` trailer, since we cannot +Please use a known identity in the `Signed-off-by:` trailer, since we cannot accept anonymous contributions. It is common, but not required, to use some form of your real name. We realize that some contributors are not comfortable doing so or prefer to contribute under a pseudonym or preferred name and we can accept @@ -445,7 +495,15 @@ The goal of this policy is to allow us to have sufficient information to contact you if questions arise about your contribution. [[commit-trailers]] -If you like, you can put extra trailers at the end: +=== Commit trailers +It is polite to credit people who have helped with your work to a +substantial enough degree. This project uses commit trailers for that, +where the credited person is written out like a Git author, i.e. with +both their name and their email address. Note that the threshold to +credit someone is a judgement call, and crediting someone for simple +review work is certainly not necessary. + +These are the common trailers in use: . `Reported-by:` is used to credit someone who found the bug that the patch attempts to fix. @@ -458,6 +516,10 @@ If you like, you can put extra trailers at the end: and found it to have the desired effect. . `Co-authored-by:` is used to indicate that people exchanged drafts of a patch before submitting it. +. `Based-on-patch-by:` is used when someone else authored parts of the + patch that you are submitting. This might be relevant if someone sent + a patch to the mailing list with their sign-off. (Be mindful and ask + them to sign off on it if they did not.) . `Helped-by:` is used to credit someone who suggested ideas for changes without providing the precise changes in patch form. . `Mentored-by:` is used to credit someone with helping develop a @@ -469,8 +531,18 @@ While you can also create your own trailer if the situation warrants it, we encourage you to instead use one of the common trailers in this project highlighted above. +Other projects might regularly refer to other kinds of data, like +`Fixes:` and `Link:` in the Linux Kernel project, but these ones in +particular are not used in this project. + Only capitalize the very first letter of the trailer, i.e. favor -"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". +`Signed-off-by:` over `Signed-Off-By:` and `Acked-by:` over `Acked-By:`. + +As mentioned under <> above, trailers are added in +chronological order; one person might sign-off on a patch and send it to +someone else, who then in turn adds her own sign-off. Further, any +trailers that you add beyond your sign-off should come before that +sign-off. That makes it clear what trailers which person added. [[cover-letter]] === Cover Letter @@ -587,8 +659,8 @@ 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. +`Tested-by:` (see <>), and "cc:" them +when sending such a final version for inclusion. ==== `format-patch` and `send-email` @@ -598,8 +670,10 @@ 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]). +`send-email`, but you can instead use GitGitGadget or `b4` to send in +your patches (see link:MyFirstContribution.html[MyFirstContribution]). +Contributors are encouraged to use `b4`, which automates much of the +bookkeeping that is otherwise done by hand. People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for @@ -613,10 +687,13 @@ 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. +how to submit updated versions of a patch series. Before sending another +version, make sure you have answered meaningful review comments in the existing +discussion. Also give reviewers enough time to comment before sending another +version. If your log message (including your name on the -`Signed-off-by` trailer) is not writable in ASCII, make sure that +`Signed-off-by:` trailer) is not writable in ASCII, make sure that you send off a message in the correct encoding. WARNING: Be wary of your MUAs word-wrap @@ -636,7 +713,7 @@ previously sent. The `git format-patch` command follows the best current practice to format the body of an e-mail message. At the beginning of the patch should come your commit message, ending with the -`Signed-off-by` trailers, and a line that consists of three dashes, +`Signed-off-by:` trailers, and a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit diff --git a/Documentation/config.adoc b/Documentation/config.adoc index 15b1a4d5934758..f67dcd2f8e05dd 100644 --- a/Documentation/config.adoc +++ b/Documentation/config.adoc @@ -146,6 +146,51 @@ refer to linkgit:gitignore[5] for details. For convenience: This is the same as `gitdir` except that matching is done case-insensitively (e.g. on case-insensitive file systems) +`worktree`:: + The data that follows the keyword `worktree` and a colon is used as a + glob pattern. If the working directory of the current worktree matches + the pattern, the include condition is met. ++ +The worktree location is the path where files are checked out (as returned +by `git rev-parse --show-toplevel`). This is different from `gitdir`, which +matches the `.git` directory path. In a linked worktree, the worktree path +is the directory where that worktree's files are located, not the main +repository's `.git` directory. ++ +The pattern uses the same glob syntax as `gitdir` (including `~/`, `./`, +`**/`, and trailing-`/` prefix matching). This condition will never match +in a bare repository (which has no worktree). ++ +Unlike `gitdir`, the `worktree` condition currently matches only the +realpath-resolved worktree location. If the working tree was entered via a +symbolic link, a pattern that uses the symbolic-link spelling may not match; +use the real path instead. ++ +This is useful when you want to apply configuration based on where the +working tree is located on the filesystem. For example, a contributor who +works on the same project both personally and as an employee can use +different `user.name` and `user.email` values depending on which directory +the worktree is checked out under: ++ +---- +[includeIf "worktree:/home/user/work/"] + path = ~/.config/git/work.inc +[includeIf "worktree:/home/user/personal/"] + path = ~/.config/git/personal.inc +---- ++ +While `extensions.worktreeConfig` (see linkgit:git-worktree[1]) also supports +per-worktree configuration, it stores the config inside each repository's +`.git/config.worktree` file and requires running `git config --worktree` +inside each worktree individually. In contrast, `includeIf "worktree:..."` +can be set once in a global or system-level configuration file (e.g. +`~/.config/git/config`) and applies to all repositories at once based on +their worktree location. + +`worktree/i`:: + This is the same as `worktree` except that matching is done + case-insensitively (e.g. on case-insensitive file systems) + `onbranch`:: The data that follows the keyword `onbranch` and a colon is taken to be a pattern with standard globbing wildcards and two additional @@ -244,6 +289,14 @@ Example [includeIf "gitdir:~/to/group/"] path = /path/to/foo.inc +; include if the worktree is at /path/to/project-build +[includeIf "worktree:/path/to/project-build"] + path = build-config.inc + +; include for all worktrees inside /path/to/group +[includeIf "worktree:/path/to/group/"] + path = group-config.inc + ; relative paths are always relative to the including ; file (if the condition is true); their location is not ; affected by the condition @@ -515,6 +568,8 @@ include::config/remotes.adoc[] include::config/repack.adoc[] +include::config/replay.adoc[] + include::config/rerere.adoc[] include::config/revert.adoc[] diff --git a/Documentation/config/advice.adoc b/Documentation/config/advice.adoc index 257db58918179a..81f80a92745123 100644 --- a/Documentation/config/advice.adoc +++ b/Documentation/config/advice.adoc @@ -48,6 +48,10 @@ all advice messages. to create a local branch after the fact. diverging:: Shown when a fast-forward is not possible. + fetchRemoteHEADWarn:: + Shown when linkgit:git-fetch[1] reveals that a remote `HEAD` + differs from what is set locally and the user has opted into + receiving a warning in this situation. fetchShowForcedUpdates:: Shown when linkgit:git-fetch[1] takes a long time to calculate forced updates after ref updates, or to warn @@ -90,6 +94,11 @@ all advice messages. Shown when linkgit:git-push[1] rejects a forced update of a branch when its remote-tracking ref has updates that we do not have locally. + pushRepoLooksLikeRef:: + Shown when the repository given to linkgit:git-push[1] is not + a configured remote but looks like a `/` ref, + suggesting that the remote and branch be given as separate + arguments. pushUnqualifiedRefname:: Shown when linkgit:git-push[1] gives up trying to guess based on the source and destination refs what diff --git a/Documentation/config/branch.adoc b/Documentation/config/branch.adoc index a4db9fa5c87eab..c2acd89c9936cb 100644 --- a/Documentation/config/branch.adoc +++ b/Documentation/config/branch.adoc @@ -55,6 +55,7 @@ This option defaults to `never`. repository), you would want to set `remote.pushDefault` to specify the remote to push to for all branches, and use this option to override it for a specific branch. + The value may be the name of a configured remote or a repository URL. `branch..merge`:: Defines, together with `branch..remote`, the upstream branch @@ -102,3 +103,10 @@ for details). `git branch --edit-description`. Branch description is automatically added to the `format-patch` cover letter or `request-pull` summary. + +`branch..deleteMerged`:: + If set to `false`, branch __ is exempt from + `git branch --delete-merged`. Useful for a topic branch you + intend to develop further after an initial round has been + merged upstream. Defaults to true. Explicit deletion via + `git branch -d` is unaffected. diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc index a0ebf03e2eb050..0b697f53f10111 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -118,6 +118,13 @@ core.trustctime:: crawlers and some backup systems). See linkgit:git-update-index[1]. True by default. +core.useNanosec:: + If true, use nanosecond precision for ctime and mtime + comparisons between the index and the working tree (if Git + was compiled to respect this option). + This is unsafe on some platforms; + see link:technical/racy-git.html[Racy Git]. False by default. + core.splitIndex:: If true, the split-index feature of the index will be used. See linkgit:git-update-index[1]. False by default. @@ -589,6 +596,14 @@ core.packedRefsTimeout:: all; -1 means to try indefinitely. Default is 1000 (i.e., retry for 1 second). +core.configLockTimeout:: + The length of time, in milliseconds, to retry when trying to + lock a configuration file for writing. Value 0 means not to + retry at all; -1 means to try indefinitely. Default is 1000 + (i.e., retry for 1 second). This is read from the configuration + that is already on disk before the lock is taken, so it can be + set persistently like any other option. + core.pager:: Text viewer for use by Git commands (e.g., 'less'). The value is meant to be interpreted by the shell. The order of preference diff --git a/Documentation/config/fetch.adoc b/Documentation/config/fetch.adoc index 04ac90912d3a58..00435e9a16d9f9 100644 --- a/Documentation/config/fetch.adoc +++ b/Documentation/config/fetch.adoc @@ -126,3 +126,22 @@ the new bundle URI. The creation token values are chosen by the provider serving the specific bundle URI. If you modify the URI at `fetch.bundleURI`, then be sure to remove the value for the `fetch.bundleCreationToken` value before fetching. + +`fetch.followRemoteHEAD`:: + When fetching using a default refspec, this setting determines how to handle + differences between a fetched remote's `HEAD` and the local + `remotes//HEAD` symbolic-ref. Its value is one of ++ +-- +`create`;; + Create `remotes//HEAD` if a ref exists on the remote, but not locally. + An existing symbolic-ref will not be touched. This is the default value. +`warn`;; + Display a warning if the remote advertises a different `HEAD` than what is + set locally. Behaves like "create" if the local symbolic-ref doesn't exist. +`always`;; + Silently update `remotes//HEAD` whenever the remote advertises a new + value. +`never`;; + Never create or modify the `remotes//HEAD` symbolic-ref. +-- diff --git a/Documentation/config/imap.adoc b/Documentation/config/imap.adoc index cb8f5e2700ae13..6b97776bc3ab47 100644 --- a/Documentation/config/imap.adoc +++ b/Documentation/config/imap.adoc @@ -41,7 +41,7 @@ `imap.authMethod`:: Specify the authentication method for authenticating with the IMAP server. If Git was built with the NO_CURL option, or if your curl version is older - than 7.34.0, or if you're running git-imap-send with the `--no-curl` + than 7.34.0, or if you're running `git-imap-send` with the `--no-curl` option, the only supported methods are `PLAIN`, `CRAM-MD5`, `OAUTHBEARER` and `XOAUTH2`. If this is not set then `git imap-send` uses the basic IMAP plaintext `LOGIN` command. diff --git a/Documentation/config/log.adoc b/Documentation/config/log.adoc index f20cc25cd7c3bf..f7dfce69b5f95e 100644 --- a/Documentation/config/log.adoc +++ b/Documentation/config/log.adoc @@ -53,13 +53,16 @@ This is the same as the `--decorate` option of the `git log`. `log.follow`:: If `true`, `git log` will act as if the `--follow` option was used when a single is given. This has the same limitations as `--follow`, - i.e. it cannot be used to follow multiple files and does not work well - on non-linear history. + i.e. it cannot be used to follow multiple files. `log.graphColors`:: A list of colors, separated by commas, that can be used to draw history lines in `git log --graph`. +`log.graphIndent`:: + If `true`, indent visual roots when rendering the graphs with `--graph`. + Set true by default. It can be overriden with `--[no-]graph-indent`. + `log.showRoot`:: If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc index b578856dde1dd4..77977dcc48eee9 100644 --- a/Documentation/config/maintenance.adoc +++ b/Documentation/config/maintenance.adoc @@ -101,7 +101,7 @@ maintenance.geometric-repack.auto:: there are packfiles that need to be merged together to retain the geometric progression, or when there are at least this many loose objects that would be written into a new packfile. The default value is - 100. + 6700. maintenance.geometric-repack.splitFactor:: This integer config option controls the factor used for the geometric @@ -121,10 +121,10 @@ maintenance.rerere-gc.auto:: This integer config option controls how often the `rerere-gc` task should be run as part of `git maintenance run --auto`. If zero, then the `rerere-gc` task will not run with the `--auto` option. A negative - value will force the task to run every time. Otherwise, any positive - value implies the command will run when the "rr-cache" directory exists - and has at least one entry, regardless of whether it is stale or not. - This heuristic may be refined in the future. The default value is 1. + value will force the task to run every time. Otherwise, a positive + value implies the command should run when the estimated number of stale + entries that would be pruned is greater than or equal to the configured + value. The default value is 512. maintenance.worktree-prune.auto:: This integer config option controls how often the `worktree-prune` task diff --git a/Documentation/config/pack.adoc b/Documentation/config/pack.adoc index 22384c2d2f0773..1da696234564cc 100644 --- a/Documentation/config/pack.adoc +++ b/Documentation/config/pack.adoc @@ -14,6 +14,18 @@ pack.windowMemory:: suffixed with "k", "m", or "g". When left unconfigured (or set explicitly to 0), there will be no limit. +pack.windowSlotLimit:: + The maximum number of "expensive" delta candidate comparisons + that will be performed for each object. See the description of + `--window-slot-limit` in linkgit:git-pack-objects[1]. If + unconfigured, no limit is applied. + +pack.windowByteLimit:: + Same as `pack.windowSlotLimit`, but scaled by the number of + bytes in each candidate object. See the description of + `--window-byte-limit` in linkgit:git-pack-objects[1]. If + unconfigured, no limit is applied. + pack.compression:: An integer -1..9, indicating the compression level for objects in a pack file. -1 is the zlib default. 0 means no diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc index 39af63dcb87a32..c1f3d766a64cc0 100644 --- a/Documentation/config/promisor.adoc +++ b/Documentation/config/promisor.adoc @@ -32,24 +32,136 @@ variable is set to "true", and the "name" and "url" fields are always advertised regardless of this setting. promisor.acceptFromServer:: - If set to "all", a client will accept all the promisor remotes - a server might advertise using the "promisor-remote" - capability. If set to "knownName" the client will accept - promisor remotes which are already configured on the client - and have the same name as those advertised by the client. This - is not very secure, but could be used in a corporate setup - where servers and clients are trusted to not switch name and - URLs. If set to "knownUrl", the client will accept promisor - remotes which have both the same name and the same URL - configured on the client as the name and URL advertised by the - server. This is more secure than "all" or "knownName", so it - should be used if possible instead of those options. Default - is "none", which means no promisor remote advertised by a - server will be accepted. By accepting a promisor remote, the - client agrees that the server might omit objects that are - lazily fetchable from this promisor remote from its responses - to "fetch" and "clone" requests from the client. Name and URL - comparisons are case sensitive. See linkgit:gitprotocol-v2[5]. + Controls which promisor remotes advertised by a server (using the + "promisor-remote" protocol capability) a client will accept. By + accepting a promisor remote, the client agrees that the server + might omit objects that are lazily fetchable from this promisor + remote from its responses to "fetch" and "clone" requests. ++ +Note that this option does not cause new remotes to be automatically +created in the client's configuration. It only allows remotes which +are somehow already configured to be trusted for the current +operation, or their fields to be updated (if `promisor.storeFields` is +set and the remote already exists locally). To allow Git to +automatically create and persist new remotes from server +advertisements, use `promisor.acceptFromServerUrl`. ++ +The available options are: ++ +* `none` (default): No promisor remote advertised by a server will be + accepted. ++ +* `knownUrl`: The client will accept promisor remotes that are already + configured on the client and have both the same name and the same URL + as advertised by the server. This is more secure than `all` or + `knownName`, and should be used if possible instead of those options. ++ +* `knownName`: The client will accept promisor remotes that are already + configured on the client and have the same name as those advertised + by the server. This is not very secure, but could be used in a corporate + setup where servers and clients are trusted to not switch names and URLs. ++ +* `all`: The client will accept all the promisor remotes a server might + advertise. This is the least secure option and should only be used in + fully trusted environments. ++ +Name and URL comparisons are case-sensitive. See linkgit:gitprotocol-v2[5] +for protocol details. + +promisor.acceptFromServerUrl:: + A glob pattern to specify which server-advertised URLs a + client is allowed to act on. When a URL matches, the client + will accept the advertised remote as a promisor remote, may + automatically create a new remote configuration for it and may + automatically accept field updates (such as authentication + tokens) from the server, even if `promisor.acceptFromServer` + is set to `none` (the default). ++ +This option can appear multiple times in config files. An advertised +URL will be accepted if it matches _ANY_ glob pattern specified by +this option in _ANY_ config file read by Git. ++ +When both `promisor.acceptFromServer` and `promisor.acceptFromServerUrl` +are set, `promisor.acceptFromServerUrl` is consulted first and takes +precedence: if a matching pattern leads to acceptance (either by +auto-configuring an unknown remote or by accepting field updates for +a known remote whose URL matches both the local configuration and the +allowlist), the advertised remote is accepted regardless of the +`promisor.acceptFromServer` setting. If no pattern in +`promisor.acceptFromServerUrl` triggers acceptance, the decision is +left to `promisor.acceptFromServer`. ++ +Note however that, even when an advertised URL matches a pattern in +`promisor.acceptFromServerUrl`, an already-existing remote on the +client whose name matches the advertised name but whose configured URL +differs from the advertised one will _NOT_ be accepted through +`promisor.acceptFromServerUrl`. This prevents a server from silently +re-pointing an existing client-side remote at a different URL. (Such a +remote may still be accepted through `promisor.acceptFromServer=all` +or `=knownName`, which have their own, looser semantics; see the +documentation of that option.) ++ +Be _VERY_ careful with these patterns: `*` matches any sequence of +characters within the 'host' and 'path' parts of a URL (but cannot +cross part boundaries). An overly broad pattern is a major security +risk, as a matching URL allows a server to auto-configure new remotes +and to update fields (such as authentication tokens) on known remotes +without further confirmation. To minimize security risks, follow these +guidelines: ++ +-- +1. Start with a secure protocol scheme, like `https://` or `ssh://`. ++ +2. Only allow domain names or paths where you control and trust _ALL_ + the content. Be especially careful with shared hosting platforms + like `github.com` or `gitlab.com`. A broad pattern like + `https://gitlab.com/*` is dangerous because it trusts every + repository on the entire platform. Always restrict such patterns to + your specific organization or namespace (e.g., + `https://gitlab.com/your-org/*`). ++ +3. Never use globs at the end of domain names. For example, + `https://cdn.your-org.com/*` might be safe, but + `https://cdn.your-org.com*/*` is a major security risk because + the latter matches `https://cdn.your-org.com.hacker.net/repo`. ++ +4. Be careful using globs at the beginning of domain names. While the + code ensures a `*` in the host cannot cross into the path, a + pattern like `https://*.example.com/*` will still match any + subdomain. This is extremely dangerous on shared hosting platforms + (e.g., `https://*.github.io/*` trusts every user's site on the + entire platform). +-- ++ +Before matching, both the advertised URL and the pattern are +normalized: the scheme and host are lowercased, percent-encoded +characters are decoded where possible, and path segments like `..` +are resolved. The port must also match exactly (e.g., +`https://example.com:8080/*` will not match a URL advertised on +port 9999). The username and password components of the URL are +ignored during matching. Note that embedding credentials in URLs is +discouraged. Passing authentication tokens via the `token` field of +the `promisor-remote` capability is strongly preferred. ++ +The glob pattern can optionally be prefixed with a remote name and an +equals sign (e.g., `cdn=https://cdn.example.com/*`). If such a prefix +is provided, accepted remotes will be saved under that name. If no +such prefix is provided, a safe remote name will be automatically +generated by sanitizing the URL and prefixing it with +`promisor-auto-`. ++ +If a remote with the chosen name already exists but points to a +different URL, Git will append a numeric suffix (e.g., `-1`, `-2`) to +the name to prevent overwriting existing configurations. You should +make sure that this doesn't happen often though, as remotes will be +rejected if the numeric suffix increases too much. In all cases, the +original name advertised by the server is recorded in the +`remote..advertisedAs` configuration variable for tracing and +debugging purposes. ++ +For the security implications of accepting a promisor remote, see the +documentation of `promisor.acceptFromServer`. For details on the +protocol, see linkgit:gitprotocol-v2[5]. promisor.checkFields:: A comma or space separated list of additional remote related diff --git a/Documentation/config/remote.adoc b/Documentation/config/remote.adoc index eb9c8a3c488448..3a20d0f7524e72 100644 --- a/Documentation/config/remote.adoc +++ b/Documentation/config/remote.adoc @@ -91,6 +91,15 @@ remote..promisor:: When set to true, this remote will be used to fetch promisor objects. +remote..advertisedAs:: + When a promisor remote is automatically configured using + information advertised by a server through the + `promisor-remote` protocol capability (see + `promisor.acceptFromServerUrl`), the server's originally + advertised name is saved in this variable. This is for + information, tracing and debugging purposes. Users should not + typically modify or create such configuration entries. + remote..partialclonefilter:: The filter that will be applied when fetching from this promisor remote. Changing or clearing this value will only affect fetches for new commits. @@ -157,15 +166,12 @@ Blank values signal to ignore all previous values, allowing a reset of the list from broader config scenarios. remote..followRemoteHEAD:: - How linkgit:git-fetch[1] should handle updates to `remotes//HEAD` - when fetching using the configured refspecs of a remote. - The default value is "create", which will create `remotes//HEAD` - if it exists on the remote, but not locally; this will not touch an - already existing local reference. Setting it to "warn" will print - a message if the remote has a different value than the local one; - in case there is no local reference, it behaves like "create". - A variant on "warn" is "warn-if-not-$branch", which behaves like - "warn", but if `HEAD` on the remote is `$branch` it will be silent. - Setting it to "always" will silently update `remotes//HEAD` to - the value on the remote. Finally, setting it to "never" will never - change or create the local reference. + When fetching this remote using its default refspec, this setting determines + how to handle differences between the remote's `HEAD` and the local + `remotes//HEAD` symbolic-ref. Overrides the value of + `fetch.followRemoteHEAD`. See `fetch.followRemoteHEAD` for a description of + accepted values. ++ +In addition to the values supported by `fetch.followRemoteHEAD`, this setting +may also take on the value "warn-if-not-`$branch`", which behaves like "warn", +but ignores the warning if the remote's `HEAD` is `remotes//$branch`. diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc index 7d549d2f0e5195..84e17e313a1f07 100644 --- a/Documentation/config/replay.adoc +++ b/Documentation/config/replay.adoc @@ -1,11 +1,18 @@ replay.refAction:: - Specifies the default mode for handling reference updates in - `git replay`. The value can be: + Specifies the default mode for handling reference updates. + The value can be: + -- - * `update`: Update refs directly using an atomic transaction (default behavior). - * `print`: Output update-ref commands for pipeline use. +//// +These use the first sentences from the description list in git-replay(1). +//// +`update`;; (default) Update refs directly using an atomic transaction. +`print`;; Output update-ref commands for pipeline use. -- + -This setting can be overridden with the `--ref-action` command-line option. -When not configured, `git replay` defaults to `update` mode. +ifdef::git-replay[] +See `--ref-action`. +endif::git-replay[] +ifndef::git-replay[] +See `--ref-action` in linkgit:git-replay[1] for details. +endif::git-replay[] diff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc index 1d700559b4a4c3..5499f91036b3ec 100644 --- a/Documentation/config/sendemail.adoc +++ b/Documentation/config/sendemail.adoc @@ -1,25 +1,25 @@ -sendemail.identity:: +`sendemail.identity`:: A configuration identity. When given, causes values in the `sendemail.` subsection to take precedence over values in the `sendemail` section. The default identity is the value of `sendemail.identity`. -sendemail.smtpEncryption:: +`sendemail.smtpEncryption`:: See linkgit:git-send-email[1] for description. Note that this setting is not subject to the `identity` mechanism. -sendemail.smtpSSLCertPath:: +`sendemail.smtpSSLCertPath`:: Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification. -sendemail.smtpSSLClientCert:: +`sendemail.smtpSSLClientCert`:: Path to the client certificate file to present if requested by the server. This is required when the server is set up to verify client certificates. If the corresponding private key is not included in the file, it must be supplied using `sendemail.smtpSSLClientKey` or the `--smtp-ssl-client-key` option. -sendemail.smtpSSLClientKey:: +`sendemail.smtpSSLClientKey`:: Path to the client private key file that corresponds to the client certificate. To avoid misconfiguration, this configuration must be used in conjunction with `sendemail.smtpSSLClientCert` or the @@ -28,45 +28,45 @@ sendemail.smtpSSLClientKey:: the certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more details. -sendemail..*:: - Identity-specific versions of the `sendemail.*` parameters +`sendemail..`:: + Identity-specific versions of the `sendemail.` parameters found below, taking precedence over those when this identity is selected, through either the command-line or `sendemail.identity`. -sendemail.multiEdit:: +`sendemail.multiEdit`:: If `true` (default), a single editor instance will be spawned to edit files you have to edit (patches when `--annotate` is used, and the summary when `--compose` is used). If `false`, files will be edited one after the other, spawning a new editor each time. -sendemail.confirm:: +`sendemail.confirm`:: Sets the default for whether to confirm before sending. Must be one of `always`, `never`, `cc`, `compose`, or `auto`. See `--confirm` in the linkgit:git-send-email[1] documentation for the meaning of these values. -sendemail.mailmap:: +`sendemail.mailmap`:: If `true`, makes linkgit:git-send-email[1] assume `--mailmap`, otherwise assume `--no-mailmap`. `False` by default. -sendemail.mailmap.file:: +`sendemail.mailmap.file`:: The location of a linkgit:git-send-email[1] specific augmenting mailmap file. The default mailmap and `mailmap.file` are loaded first. Thus, entries in this file take precedence over entries in the default mailmap locations. See linkgit:gitmailmap[5]. -sendemail.mailmap.blob:: +`sendemail.mailmap.blob`:: Like `sendemail.mailmap.file`, but consider the value as a reference to a blob in the repository. Entries in `sendemail.mailmap.file` take precedence over entries here. See linkgit:gitmailmap[5]. -sendemail.aliasesFile:: +`sendemail.aliasesFile`:: To avoid typing long email addresses, point this to one or more email aliases files. You must also supply `sendemail.aliasFileType`. -sendemail.aliasFileType:: - Format of the file(s) specified in sendemail.aliasesFile. Must be +`sendemail.aliasFileType`:: + Format of the file(s) specified in `sendemail.aliasesFile`. Must be one of `mutt`, `mailrc`, `pine`, `elm`, `gnus`, or `sendmail`. + What an alias file in each format looks like can be found in @@ -75,7 +75,7 @@ differences and limitations from the standard formats are described below: + -- -sendmail;; +`sendmail`;; * Quoted aliases and quoted addresses are not supported: lines that contain a `"` symbol are ignored. * Redirection to a file (`/path/name`) or pipe (`|command`) is not @@ -85,54 +85,54 @@ sendmail;; explicitly unsupported constructs, and any other lines that are not recognized by the parser. -- -sendemail.annotate:: -sendemail.bcc:: -sendemail.cc:: -sendemail.ccCmd:: -sendemail.chainReplyTo:: -sendemail.envelopeSender:: -sendemail.from:: -sendemail.headerCmd:: -sendemail.signedOffByCc:: -sendemail.smtpPass:: -sendemail.suppressCc:: -sendemail.suppressFrom:: -sendemail.to:: -sendemail.toCmd:: -sendemail.smtpDomain:: -sendemail.smtpServer:: -sendemail.smtpServerPort:: -sendemail.smtpServerOption:: -sendemail.smtpUser:: -sendemail.imapSentFolder:: -sendemail.useImapOnly:: -sendemail.thread:: -sendemail.transferEncoding:: -sendemail.validate:: -sendemail.xmailer:: +`sendemail.annotate`:: +`sendemail.bcc`:: +`sendemail.cc`:: +`sendemail.ccCmd`:: +`sendemail.chainReplyTo`:: +`sendemail.envelopeSender`:: +`sendemail.from`:: +`sendemail.headerCmd`:: +`sendemail.signedOffByCc`:: +`sendemail.smtpPass`:: +`sendemail.suppressCc`:: +`sendemail.suppressFrom`:: +`sendemail.to`:: +`sendemail.toCmd`:: +`sendemail.smtpDomain`:: +`sendemail.smtpServer`:: +`sendemail.smtpServerPort`:: +`sendemail.smtpServerOption`:: +`sendemail.smtpUser`:: +`sendemail.imapSentFolder`:: +`sendemail.useImapOnly`:: +`sendemail.thread`:: +`sendemail.transferEncoding`:: +`sendemail.validate`:: +`sendemail.xmailer`:: These configuration variables all provide a default for linkgit:git-send-email[1] command-line options. See its documentation for details. -sendemail.outlookidfix:: +`sendemail.outlookidfix`:: If `true`, makes linkgit:git-send-email[1] assume `--outlook-id-fix`, and if `false` assume `--no-outlook-id-fix`. If not specified, it will behave the same way as if `--outlook-id-fix` is not specified. -sendemail.signedOffCc (deprecated):: +`sendemail.signedOffCc` (deprecated):: Deprecated alias for `sendemail.signedOffByCc`. -sendemail.smtpBatchSize:: +`sendemail.smtpBatchSize`:: Number of messages to be sent per connection, after that a relogin will happen. If the value is `0` or undefined, send all messages in one connection. See also the `--batch-size` option of linkgit:git-send-email[1]. -sendemail.smtpReloginDelay:: +`sendemail.smtpReloginDelay`:: Seconds to wait before reconnecting to the smtp server. See also the `--relogin-delay` option of linkgit:git-send-email[1]. -sendemail.forbidSendmailVariables:: +`sendemail.forbidSendmailVariables`:: To avoid common misconfiguration mistakes, linkgit:git-send-email[1] will abort with a warning if any configuration options for `sendmail` exist. Set this variable to bypass the check. diff --git a/Documentation/config/worktree.adoc b/Documentation/config/worktree.adoc index a248076ea50bd5..0930183b91cb8f 100644 --- a/Documentation/config/worktree.adoc +++ b/Documentation/config/worktree.adoc @@ -5,8 +5,9 @@ set to true, `worktree add` tries to find a remote-tracking branch whose name uniquely matches the new branch name. If such a branch exists, it is checked out and set as "upstream" - for the new branch. If no such match can be found, it falls - back to creating a new branch from the current `HEAD`. + for the new branch. If multiple matches are found, the command + fails. If no such match can be found, it falls back to + creating a new branch from the current `HEAD`. `worktree.useRelativePaths`:: Link worktrees using relative paths (when "`true`") or absolute diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index c8242e24627eef..e605d2867801d0 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -13,8 +13,8 @@ endif::git-diff[] endif::git-format-patch[] ifdef::git-format-patch[] --p:: ---no-stat:: +`-p`:: +`--no-stat`:: Generate plain patches without any diffstats. endif::git-format-patch[] @@ -893,8 +893,8 @@ endif::git-format-patch[] reverted with `--ita-visible-in-index`. Both options are experimental and could be removed in future. ---max-depth=:: - For each pathspec given on command line, descend at most `` +`--max-depth=`:: + For each pathspec given on command line, descend at most __ levels of directories. A value of `-1` means no limit. Cannot be combined with wildcards in the pathspec. Given a tree containing `foo/bar/baz`, the following list shows the diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc index 941135dc637d90..16b06e38e185d1 100644 --- a/Documentation/git-add.adoc +++ b/Documentation/git-add.adoc @@ -11,7 +11,7 @@ SYNOPSIS git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize] - [--chmod=(+|-)x] [--pathspec-from-file= [--pathspec-file-nul]] + [--resolved] [--chmod=(+|-)x] [--pathspec-from-file= [--pathspec-file-nul]] [--] [...] DESCRIPTION @@ -195,6 +195,14 @@ for `git add --no-all ...`, i.e. ignored removed files. while a _CRLF_ cleans to _LF_, a _CRCRLF_ sequence is only partially cleaned to _CRLF_. +`--resolved`:: + Update the index for unmerged paths matching __ where + no conflict markers remain in the working tree. Unmerged paths + without conflict markers (including binary files and file + deletions) are staged as resolved, while any path with leftover + conflict markers causes the command to refuse to stage any files. + Cannot be combined with `-u` or `-A`. + `--chmod=(+|-)x`:: Override the executable bit of the added files. The executable bit is only changed in the index, the files on disk are left diff --git a/Documentation/git-bisect.adoc b/Documentation/git-bisect.adoc index d2115b29905f41..aabddd42ca4d31 100644 --- a/Documentation/git-bisect.adoc +++ b/Documentation/git-bisect.adoc @@ -10,7 +10,7 @@ SYNOPSIS -------- [synopsis] git bisect start [--term-(bad|new)= --term-(good|old)=] - [--no-checkout] [--first-parent] [ [...]] [--] [...] + [--no-checkout] [--first-parent] [--reset-when-found[=]] [ [...]] [--] [...] git bisect (bad|new|) [] git bisect (good|old|) [...] git bisect terms [--term-(good|old) | --term-(bad|new)] @@ -20,7 +20,7 @@ git bisect reset [] git bisect (visualize|view) git bisect replay git bisect log -git bisect run [...] +git bisect run [--reset-when-found[=]] [...] git bisect help DESCRIPTION @@ -385,6 +385,16 @@ ignored. This option is particularly useful in avoiding false positives when a merged branch contained broken or non-buildable commits, but the merge itself was OK. +`--reset-when-found[=]`:: + Once the first bad commit is found, report it and clean up the + bisection state. `` may be `original` to return to the commit + checked out before `git bisect start`, or `found` to leave the first + bad commit checked out. If `` is omitted, it defaults to + `original`. ++ +This option may be given to `git bisect start` or to `git bisect run`. It +cannot be used for a bisection started with `--no-checkout`. + EXAMPLES -------- diff --git a/Documentation/git-blame.adoc b/Documentation/git-blame.adoc index 8808009e87eb1d..2b74e455997c8c 100644 --- a/Documentation/git-blame.adoc +++ b/Documentation/git-blame.adoc @@ -88,11 +88,12 @@ include::blame-options.adoc[] include::diff-algorithm-option.adoc[] `--abbrev=`:: - Instead of using the default _7+1_ hexadecimal digits as the - abbreviated object name, use _+1_ digits, where __ is at - least __ but ensures the commit object names are unique. - Note that 1 column - is used for a caret to mark the boundary commit. + Instead of using the default _7_ hexadecimal digits as the + abbreviated object name, use at least __ digits, but ensure + the commit object names are unique. + If commits marked with caret (boundary), question mark (ignored) + or asterisk (unblamable) are shown, extend unmarked object names + to align them. THE DEFAULT FORMAT diff --git a/Documentation/git-branch.adoc b/Documentation/git-branch.adoc index c0afddc424d610..bfdf4593298631 100644 --- a/Documentation/git-branch.adoc +++ b/Documentation/git-branch.adoc @@ -13,6 +13,7 @@ git branch [--color[=] | --no-color] [--show-current] [--column[=] | --no-column] [--sort=] [--merged []] [--no-merged []] [--contains []] [--no-contains []] + [(--forked )...] [--points-at ] [--format=] [(-r|--remotes) | (-a|--all)] [--list] [...] @@ -24,6 +25,7 @@ git branch (-m|-M) [] git branch (-c|-C) [] git branch (-d|-D) [-r] ... git branch --edit-description [] +git branch [--dry-run] (--delete-merged )... [...] DESCRIPTION ----------- @@ -51,7 +53,8 @@ merged into the named commit (i.e. the branches whose tip commits are reachable from the named commit) will be listed. With `--no-merged` only branches not merged into the named commit will be listed. If the __ argument is missing it defaults to `HEAD` (i.e. the tip of the current -branch). +branch). With `--forked`, only branches whose configured upstream matches +the given branch or pattern will be listed. The command's second form creates a new branch head named __ which points to the current `HEAD`, or __ if given. As a @@ -199,6 +202,45 @@ This option is only applicable in non-verbose mode. Print the name of the current branch. In detached `HEAD` state, nothing is printed. +`--delete-merged `:: + Delete local branches whose configured upstream matches + __, but only when their tip is reachable from that + upstream. In other words, the work on the branch has already + landed on the upstream it tracks, so the local copy is no longer + needed. __ may name a ref, a remote (using the branch its + `HEAD` points at), or a shell-style glob. The option can be + repeated to widen the upstream match. + Optional __ arguments limit which local branches + are considered, e.g. `git branch --delete-merged 'origin/*' + 'topic-*'`. ++ +A branch is not deleted when: ++ +-- +* its configured upstream ref no longer exists, +* it is checked out in any worktree, +* pushing it to the remote configured by + `branch..remote` would update its upstream, so it cannot be + distinguished from a branch that just looks fully merged right + after a pull; this is determined by the remote's configured push and + fetch refspecs, +* it is the local upstream of a branch that is not being deleted, or +* `branch..deleteMerged` is set to `false`. +-- ++ +When such a local upstream branch has its own upstream deleted by the +same operation, its upstream configuration is cleared. ++ +A branch whose work has not yet been merged into its upstream is +silently skipped. Delete it with `git branch -D` if you want to +remove it anyway. + +`--dry-run`:: + With `--delete-merged`, print which branches would be + deleted and exit without touching any ref. Useful for + sanity-checking a wide pattern like `'origin/*'` before + committing to the deletion. + `-v`:: `-vv`:: `--verbose`:: @@ -311,6 +353,14 @@ superproject's "origin/main", but tracks the submodule's "origin/main". Only list branches whose tips are not reachable from __ (`HEAD` if not specified). Implies `--list`. +`--forked `:: + Only list branches whose configured upstream matches + __. The argument can be a ref (e.g. `origin/main`, + `master`), a remote name like `origin` for the branch its + `origin/HEAD` points at, or a shell-style glob (e.g. + `'origin/*'`). The option can be repeated to widen the + filter. Implies `--list`. + `--points-at `:: Only list branches of __. diff --git a/Documentation/git-cat-file.adoc b/Documentation/git-cat-file.adoc index 86b9181599317e..514bfc00328caf 100644 --- a/Documentation/git-cat-file.adoc +++ b/Documentation/git-cat-file.adoc @@ -169,6 +169,13 @@ info :: Print object info for object reference ``. This corresponds to the output of `--batch-check`. +remote-object-info ...:: + Print object info for object references `` at specified + `` without downloading objects from the remote. + Raise an error when the `object-info` capability is not supported by the remote. + Raise an error when no object references are provided. + This command may be combined with `--buffer`. + flush:: Used with `--buffer` to execute all preceding commands that were issued since the beginning or since the last flush was issued. When `--buffer` @@ -301,7 +308,8 @@ one per line, and print information based on the command given. With `--batch-command`, the `info` command followed by an object will print information about the object the same way `--batch-check` would, and the `contents` command followed by an object prints contents in the same way -`--batch` would. +`--batch` would. The `remote-object-info` command followed by a remote and +object IDs prints object info from the remote without downloading the objects. You can specify the information shown for each object by using a custom ``. The `` is copied literally to stdout for each @@ -340,6 +348,10 @@ newline. The available atoms are: after that first run of whitespace (i.e., the "rest" of the line) are output in place of the `%(rest)` atom. +The command `remote-object-info` only supports the `%(objectname)`, +`%(objectsize)` and `%(objecttype)` placeholders. See `CAVEATS` below for more +information. + If no format is specified, the default format is `%(objectname) %(objecttype) %(objectsize)`. @@ -438,6 +450,10 @@ scripting purposes. CAVEATS ------- +Note that only `%(objectname)`, `%(objectsize)` and `%(objecttype)` are +currently supported by the `remote-object-info` command. Using any other +placeholder in the format string will return an empty string in its position. + Note that the sizes of objects on disk are reported accurately, but care should be taken in drawing conclusions about which refs or objects are responsible for disk usage. The size of a packed non-delta object may be diff --git a/Documentation/git-diff.adoc b/Documentation/git-diff.adoc index 272331afbaec73..388b9110588f41 100644 --- a/Documentation/git-diff.adoc +++ b/Documentation/git-diff.adoc @@ -152,6 +152,13 @@ section "3-Way Merge" for detailed information. "Unmerged". Can be used only when comparing the working tree with the index. +`--no-progress`:: +`--progress`:: + Disable or enable progress reporting during long computations; + the default is to enable progress reporting when stderr is a + terminal. Currently the only computation with progress support + is inexact rename detection. + `...`:: The __ parameters, when given, are used to limit the diff to the named paths (you can give directory diff --git a/Documentation/git-fast-export.adoc b/Documentation/git-fast-export.adoc index 297b57bb2efdc2..719aeca244d534 100644 --- a/Documentation/git-fast-export.adoc +++ b/Documentation/git-fast-export.adoc @@ -9,7 +9,7 @@ git-fast-export - Git data exporter SYNOPSIS -------- [verse] -'git fast-export' [] | 'git fast-import' +'git fast-export' [] [] [[--] ...] DESCRIPTION ----------- diff --git a/Documentation/git-fast-import.adoc b/Documentation/git-fast-import.adoc index d68bc52b7e9cd7..fd165e11d2d259 100644 --- a/Documentation/git-fast-import.adoc +++ b/Documentation/git-fast-import.adoc @@ -9,7 +9,7 @@ git-fast-import - Backend for fast Git data importers SYNOPSIS -------- [verse] -frontend | 'git fast-import' [] +'git fast-import' [] DESCRIPTION ----------- @@ -65,6 +65,13 @@ Only enable this option if you trust the program generating the fast-import stream! This option is enabled automatically for remote-helpers that use the `import` capability, as they are already trusted to run their own code. ++ +Note that this option has to be spelled in full, and has to appear +before any option whose value is separated from it by a space, for +the unsafe `feature` commands in the stream to be allowed. So +`--allow-unsafe` or `--depth 5 --allow-unsafe-features` still refuse +them, while `--allow-unsafe-features --depth 5` and +`--depth=5 --allow-unsafe-features` allow them. `--signed-tags=`:: Specify how to handle signed tags. Behaves in the same way as diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index f7905c0f7c0322..191f64b77d1758 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -8,8 +8,8 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- -[verse] -'git format-patch' [-k] [(-o|--output-directory) | --stdout] +[synopsis] +git format-patch [-k] [(-o|--output-directory) | --stdout] [--no-thread | --thread[=