diff --git a/.editorconfig b/.editorconfig index 2d3929b5916a14..82e121a41754b5 100644 --- a/.editorconfig +++ b/.editorconfig @@ -8,6 +8,10 @@ insert_final_newline = true indent_style = tab tab_width = 8 +[templates/hooks/*.sample] +indent_style = tab +tab_width = 8 + [*.py] indent_style = space indent_size = 4 diff --git a/.gitattributes b/.gitattributes index 532b246caeb1f0..69dcb5bb2d0cde 100644 --- a/.gitattributes +++ b/.gitattributes @@ -19,3 +19,4 @@ CODE_OF_CONDUCT.md -whitespace /Documentation/user-manual.adoc conflict-marker-size=32 /t/t????-*.sh conflict-marker-size=32 /t/unit-tests/clar/test/expected/* whitespace=-blank-at-eof +/templates/hooks/*.sample whitespace=indent,trail,space,incomplete text eol=lf diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c8755e38de81ca..93042128d60d21 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -10,7 +10,8 @@ conveniently send your Pull Requests commits to our mailing list. Please read ["A note from the maintainer"](https://git.kernel.org/pub/scm/git/git.git/plain/MaintNotes?h=todo) to learn how the Git project is managed, and how you can work with it. -In addition, we highly recommend you to read [our submission guidelines](../Documentation/SubmittingPatches). +In addition, we highly recommend you to read +[our submission guidelines](https://git-scm.com/docs/SubmittingPatches). If you prefer video, then [this talk](https://www.youtube.com/watch?v=Q7i_qQW__q4&feature=youtu.be&t=6m4s) might be useful to you as the presenter walks you through the contribution diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 39e7e63c986bd1..ff2da34aaac54c 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -150,7 +150,7 @@ jobs: - uses: git-for-windows/setup-git-for-windows-sdk@v1 - name: test shell: bash - run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10 + run: . /etc/profile && ci/run-test-slice.sh $((${{matrix.nr}} + 1)) 10 - name: print test failures if: failure() && env.FAILED_TEST_ARTIFACTS != '' shell: bash @@ -240,7 +240,7 @@ jobs: shell: bash env: NO_SVN_TESTS: 1 - run: . /etc/profile && ci/run-test-slice.sh ${{matrix.nr}} 10 + run: . /etc/profile && ci/run-test-slice.sh $((${{matrix.nr}} + 1)) 10 - name: print test failures if: failure() && env.FAILED_TEST_ARTIFACTS != '' shell: bash @@ -300,8 +300,8 @@ jobs: name: windows-meson-artifacts path: build - name: Test - shell: pwsh - run: ci/run-test-slice-meson.sh build ${{matrix.nr}} 10 + shell: bash + run: ci/run-test-slice-meson.sh build $((${{matrix.nr}} + 1)) 10 - name: print test failures if: failure() && env.FAILED_TEST_ARTIFACTS != '' shell: bash diff --git a/.gitignore b/.gitignore index 0482224716d834..64ad9d181c40bf 100644 --- a/.gitignore +++ b/.gitignore @@ -79,6 +79,7 @@ /git-grep /git-hash-object /git-help +/git-history /git-hook /git-http-backend /git-http-fetch diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index b419a84e2cc660..83ec786c5a49d0 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -101,13 +101,13 @@ test:osx: parallel: matrix: - jobname: osx-clang - image: macos-14-xcode-15 + image: macos-15-xcode-16 CC: clang - jobname: osx-reftable - image: macos-14-xcode-15 + image: macos-15-xcode-16 CC: clang - jobname: osx-meson - image: macos-14-xcode-15 + image: macos-15-xcode-16 CC: clang artifacts: paths: @@ -157,6 +157,8 @@ test:mingw64: parallel: 10 .msvc-meson: + variables: + TEST_OUTPUT_DIRECTORY: "C:/Git-Test" tags: - saas-windows-medium-amd64 before_script: @@ -164,12 +166,13 @@ test:mingw64: - choco install -y git meson ninja rust-ms - Import-Module $env:ChocolateyInstall\helpers\chocolateyProfile.psm1 - refreshenv + - New-Item -Path $env:TEST_OUTPUT_DIRECTORY -ItemType Directory build:msvc-meson: extends: .msvc-meson stage: build script: - - meson setup build --vsenv -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred + - meson setup build --vsenv -Dperl=disabled -Dbackend_max_links=1 -Dcredential_helpers=wincred -Dtest_output_directory="$TEST_OUTPUT_DIRECTORY" - meson compile -C build artifacts: paths: @@ -183,11 +186,21 @@ test:msvc-meson: - job: "build:msvc-meson" artifacts: true script: - - meson test -C build --no-rebuild --print-errorlogs --slice $Env:CI_NODE_INDEX/$Env:CI_NODE_TOTAL + - | + & "C:/Program Files/Git/usr/bin/bash.exe" -l -c 'ci/run-test-slice-meson.sh build $CI_NODE_INDEX $CI_NODE_TOTAL' + after_script: + - | + if ($env:CI_JOB_STATUS -ne "success") { + & "C:/Program Files/Git/usr/bin/bash.exe" -l -c 'ci/print-test-failures.sh' + Move-Item -Path "$env:TEST_OUTPUT_DIRECTORY/failed-test-artifacts" -Destination t/ + } parallel: 10 artifacts: + paths: + - t/failed-test-artifacts reports: junit: build/meson-logs/testlog.junit.xml + when: on_failure test:fuzz-smoke-tests: image: ubuntu:latest diff --git a/.mailmap b/.mailmap index 1337b199c3c9e6..c2e3939beb286d 100644 --- a/.mailmap +++ b/.mailmap @@ -224,7 +224,8 @@ Peter Krefting Peter Krefting Petr Baudis Petr Baudis -Phil Hord +Phil Hord +Phil Hord Philip Jägenstedt Philip Oakley # secondary Philipp A. Hartmann @@ -282,6 +283,7 @@ Thomas Ackermann Thomas Rast Thomas Rast Thomas Rast +Tian Yuchen Timo Hirvonen Toby Allsopp Tom Grennan diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index df72fe01772a18..b8670751f5c705 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -33,6 +33,16 @@ Git in general, a few rough rules are: achieve and why the changes were necessary (more on this in the accompanying SubmittingPatches document). + - A label "NEEDSWORK:" followed by a description of the things to + be done is a way to leave in-code comments to document design + decisions yet to be made. 80% of the work to resolve a NEEDSWORK + comment is to decide if it still makes sense to do so, since the + situation around the codebase may have changed since the comment + was written. It can be a very valid change to remove an existing + NEEDSWORK comment without doing anything else, with the commit log + message describing a good argument why it does not make sense to do + the thing the NEEDSWORK comment mentioned. + Make your code readable and sensible, and don't try to be clever. As for more concrete guidelines, just imitate the existing code @@ -430,6 +440,8 @@ For C programs: */ _("Here is a translatable string explained by the above."); + We do not use // comments. + - Double negation is often harder to understand than no negation at all. @@ -656,6 +668,19 @@ For C programs: unsigned other_field:1; unsigned field_with_longer_name:1; + - Array names should be named in the singular form if the individual items are + subject of use. E.g.: + + char *dog[] = ...; + walk_dog(dog[0]); + walk_dog(dog[1]); + + Cases where the array is employed as a whole rather than as its unit parts, + the plural forms is preferable. E.g: + + char *dogs[] = ...; + walk_all_dogs(dogs); + For Perl programs: - Most of the C guidelines above apply. diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index f186dfbc898fd4..b9fdefce0224c9 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -331,7 +331,8 @@ on the command line, including the name of our command. (If `prefix` is empty for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so helpful. So what other context can we get? -Add a line to `#include "config.h"` and `#include "repository.h"`. +Add a line to `#include "config.h"`, `#include "repository.h"` and +`#include "environment.h"`. Then, add the following bits to the function body: function body: @@ -351,7 +352,7 @@ function body: apply standard precedence rules. `repo_config_get_string_tmp()` will look up a specific key ("user.name") and give you the value. There are a number of single-key lookup functions like this one; you can see them all (and more info -about how to use `repo_config()`) in `Documentation/technical/api-config.adoc`. +about how to use `repo_config()`) in `config.h`. You should see that the name printed matches the one you see when you run: @@ -429,6 +430,7 @@ Add the following includes: ---- #include "commit.h" #include "pretty.h" +#include "strbuf.h" ---- Then, add the following lines within your implementation of `cmd_psuh()` near @@ -503,8 +505,8 @@ git-psuh - Delight users' typo with a shy horse SYNOPSIS -------- -[verse] -'git-psuh [...]' +[synopsis] +git psuh [...] DESCRIPTION ----------- @@ -726,9 +728,10 @@ $ prove -j$(nproc) --shuffle t[0-9]*.sh ---- NOTE: You can also do this with `make test` or use any testing harness which can -speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the -tests are run in, which makes them resilient against unwanted inter-test -dependencies. `prove` also makes the output nicer. +speak TAP. `prove` can run concurrently. `-j$(nproc)` runs tests using all +available CPUs in parallel, but the job count can be adjusted as needed. +`shuffle` randomizes the order the tests are run in, which makes them resilient +against unwanted inter-test dependencies. `prove` also makes the output nicer. Go ahead and commit this change, as well. diff --git a/Documentation/RelNotes/2.54.0.adoc b/Documentation/RelNotes/2.54.0.adoc new file mode 100644 index 00000000000000..4ce30d9d5b1bcb --- /dev/null +++ b/Documentation/RelNotes/2.54.0.adoc @@ -0,0 +1,497 @@ +Git v2.54 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * "git add -p" and friends note what the current status of the hunk + being shown is. + + * "git history" history rewriting (experimental) command has been + added. + + * "git replay" is taught to drop commits that become empty (not the + ones that are empty in the original). + + * The help text and the documentation for the "--expire" option of + "git worktree [list|prune]" have been improved. + + * When "git show-index" is run outside a repository, it silently + defaults to SHA-1; the tool now warns when this happens. + + * "git merge-file" can be run outside a repository, but it ignored + all configuration, even the per-user ones. The command now uses + available configuration files to find its customization. + + * "auto filter" logic for large-object promisor remote. + + * "git rev-list" and friends learn "--maximal-only" to show only the + commits that are not reachable by other commits. + + * Command line completion (in contrib/) update for + "stash import/export". + + * "git repo info" learns "--keys" action to list known keys. + + * Extend the alias configuration syntax to allow aliases using + characters outside ASCII alphanumeric (plus '-'). + + * A signature on a commit that was GPG signed long time ago ought to + be still valid after the key that was used to sign it has expired, + but we showed them in alarming red. + + * "git subtree split --prefix=P " now checks the prefix P + against the tree of the (potentially quite different from the + current working tree) given commit. + + * "git add -p" learned a new mode that allows the user to revisit a + file that was already dealt with. + + * Allow the directory in which reference backends store their data to + be specified. + + * "gitweb" has been taught to be mobile friendly. + + * "git apply --directory=./un/../normalized/path" now normalizes the + given path before using it. + + * "git maintenance" starts using the "geometric" strategy by default. + + * "git config list" is taught to show the values interpreted for + specific type with "--type=" option. + + * "git add " has been taught to honor + submodule..ignore that is set to "all" (and requires "git add + -f" to override it). + + * Hook commands are now allowed to be defined (possibly centrally) + in the configuration files, and run multiple of them for the same + hook event. + + * The way end-users can add their own "git " subcommand by + storing "git-" in a directory on their $PATH has not been + documented clearly, which has been corrected. + + * "git send-email" learns to pass hostname/port to Authen::SASL + module. + + * "git send-email" learns to support use of client-side certificates. + + * "git send-email" has learned to be a bit more careful when it + accepts charset to use from the end-user, to avoid 'y' (mistaken + 'yes' when expecting a charset like 'UTF-8') and other nonsense. + + * "git status" learned to show comparison between the current branch + and various other branches listed on status.compareBranches + configuration. + + * "git repo structure" command learns to report maximum values on + various aspects of objects it inspects. + + * "git rebase" learns "--trailer" command to drive the + interpret-trailers machinery. + + * "git fast-import" learned to optionally replace signature on + commits whose signatures get invalidated due to replaying by + signing afresh. + + * "git history" learned the "split" subcommand. + + * The reference-transaction hook was taught to be triggered before + taking locks on references in the "preparing" phase. + + * "git apply" now reports the name of the input file along with the + line number when it encounters a corrupt patch, and correctly + resets the line counter when processing multiple patch files. + + * The HTTP transport learned to react to "429 Too Many Requests". + + * "git repo info -h" and "git repo structure -h" limit their help output + to the part that is specific to the subcommand. + + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * Avoid local submodule repository directory paths overlapping with + each other by encoding submodule names before using them as path + components. + + * The string_list API gains a new helper, string_list_sort_u(), and + new unit tests to extend coverage. + + * Improve set-up time of a perf test. + + * ISO C23 redefines strchr and friends that traditionally took + a const pointer and returned a non-const pointer derived from it to + preserve constness (i.e., if you ask for a substring in a const + string, you get a const pointer to the substring). Update code + paths that used non-const pointer to receive their results that did + not have to be non-const to adjust. + + * Rename three functions around the commit_list data structure. + + * Transaction to create objects (or not) is currently tied to the + repository, but in the future a repository can have multiple object + sources, which may have different transaction mechanisms. Make the + odb transaction API per object source. + + * "git merge-ours" is taught to work better in a sparse checkout. + + * Allow recording process ID of the process that holds the lock next + to a lockfile for diagnosis. + + * Reduce dependency on the_repository of xdiff-interface layer. + + * Code clean-up to use the commit_stack API. + + * "git diff --anchored=" has been optimized. + + * A CodingGuidelines update. + + * Add process ancestry data to trace2 on macOS to match what we + already do on Linux and Windows. Also adjust the way Windows + implementation reports this information to match the other two. + + * A handful of places used refs_for_each_ref_in() API incorrectly, + which has been corrected. + + * Some tests assumed "iconv" is available without honoring ICONV + prerequisite, which has been corrected. + + * Revamp object enumeration API around odb. + + * Additional tests were introduced to see the interaction with netrc + auth with auth failure on the http transport. + + * A couple of bugs in use of flag bits around odb API has been + corrected, and the flag bits reordered. + + * Plumb gitk/git-gui build and install procedure in meson based + builds. + + * The code to accept shallow "git push" has been optimized. + + * Simplify build procedure for oxskeychain (in contrib/). + + * Fix dependency screw-up in meson-based builds. + + * Wean the mailmap code off of the_repository dependency. + + * API clean-up for the worktree subsystem. + + * The last uses of the_repository in "tree-diff.c" have been + eradicated. + + * Clean-up the code around "git repo info" command. + + * Mark the merge-ort codebase to prevent more uses of the_repository + from getting added. + + * The core.attributesfile is intended to be set per repository, but + were kept track of by a single global variable in-core, which has + been corrected by moving it to per-repository data structure. + + * Use the hook API to replace ad-hoc invocation of hook scripts via + the run_command() API. + + * Code refactoring around refs-for-each-* API functions. + + * The parse-options API learned to notice an options[] array with + duplicated long options. + (merge 237e520d81 rs/parse-options-duplicated-long-options later to maint). + + * The code to maintain mapping between object names in multiple hash + functions is being added, written in Rust. + + * A bit of OIDmap API enhancement and cleanup. + + * Move gitlab CI from macOS 14 images that are being deprecated. + + * The object source API is getting restructured to allow plugging new + backends. + + * Reduce dependence on the global the_hash_algo and the_repository + variables of wt-status code path. + + * The way combined list-object filter options are parsed has been + revamped. + + * Editorconfig filename patterns were specified incorrectly, making + many source files inside subdirectories unaffected, which has been + corrected. + + * The run_command() API lost its implicit dependency on the singleton + `the_repository` instance. + + * The unit test helper function was taught to use backslash + + mnemonic notation for certain control characters like "\t", instead + of octal notation like "\011". + + * Adjust test-lint to allow "sed -E" to use ERE in the patterns. + + * Clar (unit testing framework) update from the upstream. + + * Reduce system overhead "git upload-pack" spends on relaying "git + pack-objects" output to the "git fetch" running on the other end of + the connection. + + * Add a coccinelle rule to break the build when "struct strbuf" gets + passed by value. + + * Further work on incremental repacking using MIDX/bitmap + + * The logic to count objects has been cleaned up. + + * Tweak the build infrastructure by moving tools around. + + * Uses of prio_queue as a LIFO stack of commits have been written + with commit_stack. + + * The cleanup of remaining bitmaps in "ahead_behind()" has been + simplified. + + * split-index.c has been updated to not use the global the_repository + and the_hash_algo variables. + + * The unsigned integer that is used as an bitset to specify the kind + of branches interpret_branch_name() function has been changed to + use a dedicated enum type. + + * Various updates to contrib/diff-highlight, including documentation + updates, test improvements, and color configuration handling. + + * Code paths that loop over another array to push each element into a + strvec have been rewritten to use strvec_pushv() instead. + + * In case homebrew breaks REG_ENHANCED again, leave a in-code comment + to suggest use of our replacement regex as a workaround. + + +Fixes since v2.53 +----------------- + + * HTTP transport failed to authenticate in some code paths, which has + been corrected. + (merge ed0f7a62f7 ap/http-probe-rpc-use-auth later to maint). + + * The computation of column width made by "git diff --stat" was + confused when pathnames contain non-ASCII characters. + (merge 04f5d95ef7 lp/diff-stat-utf8-display-width-fix later to maint). + + * The "-z" and "--max-depth" documentation (and implementation of + "-z") in the "git last-modified" command have been updated. + (merge 9dcc09bed1 tc/last-modified-options-cleanup later to maint). + + * A handful of code paths that started using batched ref update API + (after Git 2.51 or so) lost detailed error output, which have been + corrected. + (merge eff9299eac kn/ref-batch-output-error-reporting-fix later to maint). + + * "git blame --ignore-revs=... --color-lines" did not account for + ignored revisions passing blame to the same commit an adjacent line + gets blamed for. + (merge d519082d4e rs/blame-ignore-colors-fix later to maint). + + * Coccinelle rules update. + (merge 60614838a4 tc/memzero-array later to maint). + + * Giving "git last-modified" a tree (not a commit-ish) died an + uncontrolled death, which has been corrected. + (merge 525ef52301 tc/last-modified-not-a-tree later to maint). + + * Test contrib/ things in CI to catch breakages before they enter the + "next" branch. + (merge c591c3ceff jc/ci-test-contrib-too later to maint). + + * A handful of documentation pages have been modernized to use the + "synopsis" style. + (merge a34d1d53a6 ja/doc-synopsis-style-even-more later to maint). + + * Small clean-up of xdiff library to remove unnecessary data + duplication. + (merge 5086213bd2 pw/xdiff-cleanups later to maint). + + * Update sample commit-msg hook to complain when a log message has + material mailinfo considers the end of log message in the middle. + (merge 83804c361b pw/commit-msg-sample-hook later to maint). + + * "git pack-objects --stdin-packs" with "--exclude-promisor-objects" + fetched objects that are promised, which was not wanted. This has + been fixed. + (merge f4eff7116d ps/pack-concat-wo-backfill later to maint). + + * "git switch ", in an attempt to create a local branch + after a remote tracking branch of the same name gave an advise + message to disambiguate using "git checkout", which has been + updated to use "git switch". + (merge 12fee11f21 jc/checkout-switch-restore later to maint). + + * It does not make much sense to apply the "incomplete-line" + whitespace rule to symbolic links, whose contents almost always + lack the final newline. "git apply" and "git diff" are now taught + to exclude them for a change to symbolic links. + (merge 6a41481c6d jc/whitespace-incomplete-line later to maint). + + * "git format-patch --from=" did not honor the command line + option when writing out the cover letter, which has been corrected. + + * Update build precedure for mergetool documentation in meson-based builds. + (merge 58e4eeeeb5 pw/meson-doc-mergetool later to maint). + + * An earlier attempt to optimize "git subtree" discarded too much + relevant histories, which has been corrected. + + * A prefetch call can be triggered to access a stale diff_queue entry + after diffcore-break breaks a filepair into two and freed the + original entry that is no longer used, leading to a segfault, which + has been corrected. + (merge 2d88ab078d hy/diff-lazy-fetch-with-break-fix later to maint). + + * "git fetch --deepen" that tries to go beyond merged branch used to + get confused where the updated shallow points are, which has been + corrected. + (merge 3ef68ff40e sp/shallow-deepen-relative-fix later to maint). + + * "fsck" iterates over packfiles and its access to pack data caused + the list to be permuted, which caused it to loop forever; the code + to access pack data by "fsck" has been updated to avoid this. + (merge 13eb65d366 ps/fsck-stream-from-the-right-object-instance later to maint). + + * "git log --graph --stat" did not count the display width of colored + graph part of its own output correctly, which has been corrected. + (merge 064b869efc lp/diff-stat-utf8-display-width-fix later to maint). + + * The configuration variable format.noprefix did not behave as a + proper boolean variable, which has now been fixed and documented. + (merge ea3a62c40e kh/format-patch-noprefix-is-boolean later to maint). + + * CI fix. + (merge eb35167dd4 ps/ci-reduce-gitlab-envsize later to maint). + + * "git diff --no-index --find-object=" outside a + repository of course wouldn't be able to find the object and died + while parsing the command line. The command is made to die in a + bit more user-friendly way. + (merge b0ddc7947c mm/diff-no-index-find-object later to maint). + + * Fix typo-induced breakages in fsmonitor-watchman sample hook. + (merge 41366e4677 pt/fsmonitor-watchman-sample-fix later to maint). + + * "git for-each-repo" started from a secondary worktree did not work + as expected, which has been corrected. + (merge e87493b9b4 ds/for-each-repo-w-worktree later to maint). + + * The construct 'test "$(command)" = expectation' loses the exit + status from the command, which has been fixed by breaking up the + statement into pieces. + (merge d3edca979a fp/t3310-unhide-git-failures later to maint). + + * While discovering a ".git" directory, the code treats any stat() + failure as a sign that a filesystem entity .git does not exist + there, and ignores ".git" that is not a "gitdir" file or a + directory. The code has been tightened to notice and report + filesystem corruption better. + (merge 1dd27bfbfd ty/setup-error-tightening later to maint). + + * Plug a few leaks where mmap'ed memory regions are not unmapped. + (merge a8a69bbb64 jk/unleak-mmap later to maint). + + * A test now uses the symbolic constant $ZERO_OID instead of 40 "0" to + work better with SHA-256 as well as SHA-1. + (merge 30310f3cc4 ss/t3200-test-zero-oid later to maint). + + * Instead of hardcoded 'origin', use the configured default remote + when fetching from submodules. + (merge 3b5fb32da8 ng/submodule-default-remote later to maint). + + * The code in "git help" that shows configuration items in sorted + order was awkwardly organized and prone to bugs. + + * "imap-send" used to use functions whose use is going to be removed + with OpenSSL 4.0; rewrite them using public API that has been + available since OpenSSL 1.1 since 2016 or so. + (merge 6392a0b75d bb/imap-send-openssl-4.0-prep later to maint). + + * Fix an example in the user-manual. + (merge 5514f14617 gj/user-manual-fix-grep-example later to maint). + + * The final clean-up phase of the diff output could turn the result of + histogram diff algorithm suboptimal, which has been corrected. + (merge e417277ae9 yc/histogram-hunk-shift-fix later to maint). + + * "git diff -U" was too lenient in its command line parsing and + took an empty string as a valid . + (merge 4f6a803aba ty/doc-diff-u-wo-number later to maint). + + * The handling of the incomplete lines at the end by "git + diff-highlight" has been fixed. + + * merge-file --object-id used to trigger a BUG when run in a linked + worktree, which has been fixed. + (merge 57246b7c62 mr/merge-file-object-id-worktree-fix later to maint). + + * "git apply -p" parses more carefully now. + (merge d05d84c5f5 mf/apply-p-no-atoi later to maint). + + * A test to run a .bat file with whitespaces in the name with arguments + with whitespaces in them was flaky in that sometimes it got killed + before it produced expected side effects, which has been rewritten to + make it more robust. + (merge 3ad4921838 jk/t0061-bat-test-update later to maint). + + * "git ls-remote '+refs/tags/*:refs/tags/*' https://..." run outside a + repository would dereference a NULL while trying to see if the given + refspec is a single-object refspec, which has been corrected. + (merge 4e5dc601dd kj/refspec-parsing-outside-repository later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge d79fff4a11 jk/remote-tracking-ref-leakfix later to maint). + (merge 7a747f972d dd/t5403-modernise later to maint). + (merge 81021871ea sp/myfirstcontribution-include-update later to maint). + (merge 49223593fd ac/sparse-checkout-string-list-cleanup later to maint). + (merge a824421d36 sp/t5500-cleanup later to maint). + (merge df1c5d7ed7 kh/doc-shortlog-fix later to maint). + (merge 2d45507f15 am/doc-github-contributiong-link-to-submittingpatches later to maint). + (merge 68060b9262 hs/t9160-test-paths later to maint). + (merge 486386c687 cs/subtree-reftable-testfix later to maint). + (merge 0728012c53 jc/diff-highlight-main-master-testfix later to maint). + (merge 831989ef38 mc/doc-send-email-signed-off-by-cc later to maint). + (merge c44b3f3203 sd/doc-my1c-api-config-reference-fix later to maint). + (merge 6c21e53bad rs/version-wo-the-repository later to maint). + (merge 10c68d2577 rs/clean-includes later to maint). + (merge 168d575719 bk/t2003-modernise later to maint). + (merge 6bfef81c9a kh/doc-rerere-options-xref later to maint). + (merge aaf3cc3d8d sd/t7003-test-path-is-helpers later to maint). + (merge 2668b6bdc4 jc/doc-rerere-update later to maint). + (merge 2f99f50f2d jc/doc-cg-c-comment later to maint). + (merge a454cdca42 kh/doc-am-format-sendmail later to maint). + (merge 8b0061b5c5 jk/ref-filter-lrstrip-optim later to maint). + (merge 5133837392 ps/ci-gitlab-msvc-updates later to maint). + (merge 143e84958c db/doc-fetch-jobs-auto later to maint). + (merge 0678e01f02 ap/use-test-seq-f-more later to maint). + (merge 96286f14b0 ty/symlinks-use-unsigned-for-bitset later to maint). + (merge b10e0cb1f3 kh/doc-am-xref later to maint). + (merge ed84bc1c0d kh/doc-patch-id-4 later to maint). + (merge 7451864bfa sc/pack-redundant-leakfix later to maint). + (merge f87593ab1a cx/fetch-display-ubfix later to maint). + (merge a66c8c7f91 jk/repo-structure-cleanup later to maint). + (merge 5ee8782f87 ss/test-that-that-typofix later to maint). + (merge f31b322008 fp/t3310-test-path-is-helpers later to maint). + (merge b22ed4c4f9 kj/path-micro-code-cleanup later to maint). + (merge a56fa1ca05 lp/doc-gitprotocol-pack-fixes later to maint). + (merge 0d6bb8b541 ss/t3700-modernize later to maint). + (merge 63c00a677b ss/t9123-setup-inside-test-expect-success later to maint). + (merge beca0ca4be os/doc-git-custom-commands later to maint). + (merge 4c223571be ty/patch-ids-document-lazy-eval later to maint). + (merge 476365ac85 jc/doc-wholesale-replace-before-next later to maint). + (merge 35f220b639 ss/submodule--helper-use-xmalloc later to maint). + (merge 02cbae61df cf/constness-fixes later to maint). + (merge 69efd53c81 ms/t7605-test-path-is-helpers later to maint). + (merge d39cef3a1a ss/t0410-delete-object-cleanup later to maint). + (merge 2f05039717 rj/pack-refs-tests-path-is-helpers later to maint). + (merge 2594747ad1 jk/transport-color-leakfix later to maint). + (merge 48430e44ac mf/t0008-cleanup later to maint). + (merge fc8a4f15e7 gi/doc-boolean-config-typofix later to maint). + (merge 37182267a0 kh/doc-interpret-trailers-1 later to maint). + (merge f64c50e768 jc/rerere-modern-strbuf-handling later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index e270ccbe85b087..d570184ec84998 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -37,11 +37,36 @@ most likely to be knowledgeable enough to help you, but they have no obligation to help you (i.e. you ask them for help, you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would help you find out who they are. ++ +It is also a good idea to check whether your topic has been discussed +previously on the mailing list, or whether similar work is already in +progress. Prior discussions may contain useful context, design +considerations, or earlier attempts at solving the same problem. Being +aware of such discussions can help you avoid duplicating work and may +allow you to coordinate with other contributors working in the same +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. ++ +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. + +. These early update iterations are expected to be full replacements, + not incremental updates on top of what you posted already. If you + are correcting mistakes you made in the previous iteration that a + reviewer noticed and pointed out in their review, you _fix_ that + mistake by rewriting your history (e.g., by using "git rebase -i") + to pretend that you never made the mistake in the first place. In + other words, this is a chance to pretend to be a perfect developer, + and you are expected to take advantage of that. In the larger + picture, nobody is interested in your earlier mistakes. Just + present a logical progression made by a perfect developer who makes + no mistakes while working on the topic. . Polish, refine, and re-send your patches to the list and to the people who spent their time to improve your patch. Go back to step (2). diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in index ff9ea0a2944511..31b883a72c5739 100644 --- a/Documentation/asciidoc.conf.in +++ b/Documentation/asciidoc.conf.in @@ -81,12 +81,18 @@ endif::backend-xhtml11[] ifdef::backend-docbook[] ifdef::doctype-manpage[] +[blockdef-open] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + [paradef-default] synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::doctype-manpage[] endif::backend-docbook[] ifdef::backend-xhtml11[] +[blockdef-open] +synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" + [paradef-default] synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!\\0!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.\\\\\\*]\\+\\|…\\)!\\1\\2!g;s!<[-a-zA-Z0-9.]\\+>!\\0!g'" endif::backend-xhtml11[] diff --git a/Documentation/config/alias.adoc b/Documentation/config/alias.adoc index 80ce17d2deb269..dc6ca0ee0813cc 100644 --- a/Documentation/config/alias.adoc +++ b/Documentation/config/alias.adoc @@ -1,12 +1,47 @@ alias.*:: - Command aliases for the linkgit:git[1] command wrapper - e.g. - after defining `alias.last = cat-file commit HEAD`, the invocation - `git last` is equivalent to `git cat-file commit HEAD`. To avoid - confusion and troubles with script usage, aliases that - hide existing Git commands are ignored except for deprecated - commands. Arguments are split by - spaces, the usual shell quoting and escaping are supported. - A quote pair or a backslash can be used to quote them. +alias.*.command:: + Command aliases for the linkgit:git[1] command wrapper. Aliases + can be defined using two syntaxes: ++ +-- +1. Without a subsection, e.g., `[alias] co = checkout`. The alias + name ("co" in this example) is + limited to ASCII alphanumeric characters and `-`, + and is matched case-insensitively. +2. With a subsection, e.g., `[alias "co"] command = checkout`. The + alias name can contain any characters (except for newlines and NUL bytes), + including UTF-8, and is matched case-sensitively as raw bytes. + You define the action of the alias in the `command`. +-- ++ +Examples: ++ +---- +# Without subsection (ASCII alphanumeric and dash only) +[alias] + co = checkout + st = status + +# With subsection (allows any characters, including UTF-8) +[alias "hämta"] + command = fetch +[alias "rätta till"] + command = commit --amend +---- ++ +With a Git alias defined, e.g., ++ + $ git config --global alias.last "cat-file commit HEAD" + # Which is equivalent to + $ git config --global alias.last.command "cat-file commit HEAD" ++ +`git last` is equivalent to `git cat-file commit HEAD`. ++ +To avoid confusion and troubles with script usage, aliases that +hide existing Git commands are ignored except for deprecated +commands. Arguments are split by +spaces, the usual shell quoting and escaping are supported. +A quote pair or a backslash can be used to quote them. + Note that the first word of an alias does not necessarily have to be a command. It can be a command-line option that will be passed into the diff --git a/Documentation/config/am.adoc b/Documentation/config/am.adoc index 5bcad2efb11639..e9561e12d7467e 100644 --- a/Documentation/config/am.adoc +++ b/Documentation/config/am.adoc @@ -1,14 +1,20 @@ am.keepcr:: - If true, git-am will call git-mailsplit for patches in mbox format - with parameter `--keep-cr`. In this case git-mailsplit will + If true, linkgit:git-am[1] will call linkgit:git-mailsplit[1] + for patches in mbox format with parameter `--keep-cr`. In this + case linkgit:git-mailsplit[1] will not remove `\r` from lines ending with `\r\n`. Can be overridden by giving `--no-keep-cr` from the command line. - See linkgit:git-am[1], linkgit:git-mailsplit[1]. am.threeWay:: - By default, `git am` will fail if the patch does not apply cleanly. When - set to true, this setting tells `git am` to fall back on 3-way merge if - the patch records the identity of blobs it is supposed to apply to and - we have those blobs available locally (equivalent to giving the `--3way` - option from the command line). Defaults to `false`. - See linkgit:git-am[1]. + By default, linkgit:git-am[1] will fail if the patch does not + apply cleanly. When set to true, this setting tells + linkgit:git-am[1] to fall back on 3-way merge if the patch + records the identity of blobs it is supposed to apply to and we + have those blobs available locally (equivalent to giving the + `--3way` option from the command line). Defaults to `false`. + +am.messageId:: + Add a `Message-ID` trailer based on the email header to the + commit when using linkgit:git-am[1] (see + linkgit:git-interpret-trailers[1]). See also the `--message-id` + and `--no-message-id` options. diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc index eb8957d4daca94..cac7438e7de505 100644 --- a/Documentation/config/core.adoc +++ b/Documentation/config/core.adoc @@ -348,6 +348,17 @@ confusion unless you know what you are doing (e.g. you are creating a read-only snapshot of the same index to a location different from the repository's usual working tree). +core.lockfilePid:: + If true, Git will create a PID file alongside lock files. When a + lock acquisition fails and a PID file exists, Git can provide + additional diagnostic information about the process holding the + lock, including whether it is still running. Defaults to `false`. ++ +The PID file is named by inserting `~pid` before the `.lock` suffix. +For example, if the lock file is `index.lock`, the PID file will be +`index~pid.lock`. The file contains a single line in the format +`pid ` followed by a newline. + core.logAllRefUpdates:: Enable the reflog. Updates to a ref is logged to the file "`$GIT_DIR/logs/`", by appending the new and old diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc index 532456644b770e..be6678bb5b5585 100644 --- a/Documentation/config/extensions.adoc +++ b/Documentation/config/extensions.adoc @@ -57,10 +57,24 @@ For historical reasons, this extension is respected regardless of the `core.repositoryFormatVersion` setting. refStorage::: - Specify the ref storage format to use. The acceptable values are: + Specify the ref storage format and a corresponding payload. The value + can be either a format name or a URI: + -- +* A format name alone (e.g., `reftable` or `files`). + +* A URI format `://` explicitly specifies both the + format and payload (e.g., `reftable:///foo/bar`). + +Supported format names are: + include::../ref-storage-format.adoc[] + +The payload is passed directly to the reference backend. For the files and +reftable backends, this must be a filesystem path where the references will +be stored. Defaulting to the commondir when no payload is provided. Relative +paths are resolved relative to the `$GIT_DIR`. Future backends may support +other payload schemes, e.g., postgres://127.0.0.1:5432?database=myrepo. -- + Note that this setting should only be set by linkgit:git-init[1] or @@ -73,6 +87,35 @@ relativeWorktrees::: repaired with either the `--relative-paths` option or with the `worktree.useRelativePaths` config set to `true`. +submodulePathConfig::: + This extension is for the minority of users who: ++ +-- +* Encounter errors like `refusing to create ... in another submodule's git dir` + due to a number of reasons, like case-insensitive filesystem conflicts when + creating modules named `foo` and `Foo`. +* Require more flexible submodule layouts, for example due to nested names like + `foo`, `foo/bar` and `foo/baz` not supported by the default gitdir mechanism + which uses `.git/modules/` locations, causing further conflicts. +-- ++ +When `extensions.submodulePathConfig` is enabled, the `submodule..gitdir` +config becomes the single source of truth for all submodule gitdir paths and is +automatically set for all new submodules both during clone and init operations. ++ +Git will error out if a module does not have a corresponding +`submodule..gitdir` set. ++ +Existing (pre-extension) submodules need to be migrated by adding the missing +config entries. This can be done manually, e.g. for each submodule: +`git config submodule..gitdir .git/modules/`, or via the +`git submodule--helper migrate-gitdir-configs` command which iterates over all +submodules and attempts to migrate them. ++ +The extension can be enabled automatically for new repositories by setting +`init.defaultSubmodulePathConfig` to `true`, for example by running +`git config --global init.defaultSubmodulePathConfig true`. + worktreeConfig::: If enabled, then worktrees will load config settings from the `$GIT_DIR/config.worktree` file in addition to the diff --git a/Documentation/config/hook.adoc b/Documentation/config/hook.adoc new file mode 100644 index 00000000000000..64e845a260380d --- /dev/null +++ b/Documentation/config/hook.adoc @@ -0,0 +1,24 @@ +hook..command:: + The command to execute for `hook.`. `` is a unique + "friendly" name that identifies this hook. (The hook events that + trigger the command are configured with `hook..event`.) The + value can be an executable path or a shell oneliner. If more than + one value is specified for the same ``, only the last value + parsed is used. See linkgit:git-hook[1]. + +hook..event:: + The hook events that trigger `hook.`. The value is the name + of a hook event, like "pre-commit" or "update". (See + linkgit:githooks[5] for a complete list of hook events.) On the + specified event, the associated `hook..command` is executed. + This is a multi-valued key. To run `hook.` on multiple + events, specify the key more than once. An empty value resets + the list of events, clearing any previously defined events for + `hook.`. See linkgit:git-hook[1]. + +hook..enabled:: + Whether the hook `hook.` is enabled. Defaults to `true`. + Set to `false` to disable the hook without removing its + configuration. This is particularly useful when a hook is defined + in a system or global config file and needs to be disabled for a + specific repository. See linkgit:git-hook[1]. diff --git a/Documentation/config/http.adoc b/Documentation/config/http.adoc index 2d3ca702b63b4b..741ff5dd6eeab3 100644 --- a/Documentation/config/http.adoc +++ b/Documentation/config/http.adoc @@ -327,6 +327,32 @@ http.keepAliveCount:: unset, curl's default value is used. Can be overridden by the `GIT_HTTP_KEEPALIVE_COUNT` environment variable. +http.retryAfter:: + Default wait time in seconds before retrying when a server returns + HTTP 429 (Too Many Requests) without a Retry-After header. + Defaults to 0 (retry immediately). When a Retry-After header is + present, its value takes precedence over this setting; however, + automatic use of the server-provided `Retry-After` header requires + libcurl 7.66.0 or later. On older versions, configure this setting + manually to control the retry delay. Can be overridden by the + `GIT_HTTP_RETRY_AFTER` environment variable. + See also `http.maxRetries` and `http.maxRetryTime`. + +http.maxRetries:: + Maximum number of times to retry after receiving HTTP 429 (Too Many + Requests) responses. Set to 0 (the default) to disable retries. + Can be overridden by the `GIT_HTTP_MAX_RETRIES` environment variable. + See also `http.retryAfter` and `http.maxRetryTime`. + +http.maxRetryTime:: + Maximum time in seconds to wait for a single retry attempt when + handling HTTP 429 (Too Many Requests) responses. If the server + requests a delay (via Retry-After header) or if `http.retryAfter` + is configured with a value that exceeds this maximum, Git will fail + immediately rather than waiting. Default is 300 seconds (5 minutes). + Can be overridden by the `GIT_HTTP_MAX_RETRY_TIME` environment + variable. See also `http.retryAfter` and `http.maxRetries`. + http.noEPSV:: A boolean which disables using of EPSV ftp command by curl. This can be helpful with some "poor" ftp servers which don't diff --git a/Documentation/config/init.adoc b/Documentation/config/init.adoc index e45b2a812151dc..7b4abdaf8ba29b 100644 --- a/Documentation/config/init.adoc +++ b/Documentation/config/init.adoc @@ -18,3 +18,9 @@ endif::[] See `--ref-format=` in linkgit:git-init[1]. Both the command line option and the `GIT_DEFAULT_REF_FORMAT` environment variable take precedence over this config. + +init.defaultSubmodulePathConfig:: + A boolean that specifies if `git init` and `git clone` should + automatically set `extensions.submodulePathConfig` to `true`. This + allows all new repositories to automatically use the submodule path + extension. Defaults to `false` when unset. diff --git a/Documentation/config/maintenance.adoc b/Documentation/config/maintenance.adoc index d0c38f03fabd60..b578856dde1dd4 100644 --- a/Documentation/config/maintenance.adoc +++ b/Documentation/config/maintenance.adoc @@ -30,8 +30,7 @@ The possible strategies are: + * `none`: This strategy implies no tasks are run at all. This is the default strategy for scheduled maintenance. -* `gc`: This strategy runs the `gc` task. This is the default strategy for - manual maintenance. +* `gc`: This strategy runs the `gc` task. * `geometric`: This strategy performs geometric repacking of packfiles and keeps auxiliary data structures up-to-date. The strategy expires data in the reflog and removes worktrees that cannot be located anymore. When the @@ -40,7 +39,8 @@ The possible strategies are: are already part of a cruft pack will be expired. + This repacking strategy is a full replacement for the `gc` strategy and is -recommended for large repositories. +recommended for large repositories. This is the default strategy for manual +maintenance. * `incremental`: This setting optimizes for performing small maintenance activities that do not delete any data. This does not schedule the `gc` task, but runs the `prefetch` and `commit-graph` tasks hourly, the diff --git a/Documentation/config/pack.adoc b/Documentation/config/pack.adoc index 75402d5579d4b2..fa997c8597d5bd 100644 --- a/Documentation/config/pack.adoc +++ b/Documentation/config/pack.adoc @@ -160,12 +160,13 @@ pack.usePathWalk:: processes. See linkgit:git-pack-objects[1] for full details. pack.preferBitmapTips:: + Specifies a ref hierarchy (e.g., "refs/heads/"); can be + given multiple times to specify more than one hierarchies. When selecting which commits will receive bitmaps, prefer a - commit at the tip of any reference that is a suffix of any value - of this configuration over any other commits in the "selection - window". + commit at the tip of a reference that is contained in any of + the configured hierarchies. + -Note that setting this configuration to `refs/foo` does not mean that +Note that setting this configuration to `refs/foo/` does not mean that the commits at the tips of `refs/foo/bar` and `refs/foo/baz` will necessarily be selected. This is because commits are selected for bitmaps from within a series of windows of variable length. diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc index 93e5e0d9b55eb4..b0fa43b8393a53 100644 --- a/Documentation/config/promisor.adoc +++ b/Documentation/config/promisor.adoc @@ -89,3 +89,36 @@ variable. The fields are checked only if the `promisor.acceptFromServer` config variable is not set to "None". If set to "None", this config variable has no effect. See linkgit:gitprotocol-v2[5]. + +promisor.storeFields:: + A comma or space separated list of additional remote related + field names. If a client accepts an advertised remote, the + client will store the values associated with these field names + taken from the remote advertisement into its configuration, + and then reload its remote configuration. Currently, + "partialCloneFilter" and "token" are the only supported field + names. ++ +For example if a server advertises "partialCloneFilter=blob:limit=20k" +for remote "foo", and that remote is accepted, then "blob:limit=20k" +will be stored for the "remote.foo.partialCloneFilter" configuration +variable. ++ +If the new field value from an advertised remote is the same as the +existing field value for that remote on the client side, then no +change is made to the client configuration though. ++ +When a new value is stored, a message is printed to standard error to +let users know about this. ++ +Note that for security reasons, if the remote is not already +configured on the client side, nothing will be stored for that +remote. In any case, no new remote will be created and no URL will be +stored. ++ +Before storing a partial clone filter, it's parsed to check it's +valid. If it's not, a warning is emitted and it's not stored. ++ +Before storing a token, a check is performed to ensure it contains no +control character. If the check fails, a warning is emitted and it's +not stored. diff --git a/Documentation/config/sendemail.adoc b/Documentation/config/sendemail.adoc index 90164c734d2660..6560ecc5abe409 100644 --- a/Documentation/config/sendemail.adoc +++ b/Documentation/config/sendemail.adoc @@ -12,6 +12,22 @@ 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:: + 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:: + 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.smtpSSLClientKey` or the + `--smtp-ssl-client-cert` option. If the client key is included in the + client certificate, the choice of private key depends on the format of + the certificate. Visit https://metacpan.org/pod/IO::Socket::SSL for more + details. + sendemail..*:: Identity-specific versions of the `sendemail.*` parameters found below, taking precedence over those when this diff --git a/Documentation/config/status.adoc b/Documentation/config/status.adoc index 8caf90f51c19a3..b5dd85b761f6f9 100644 --- a/Documentation/config/status.adoc +++ b/Documentation/config/status.adoc @@ -17,6 +17,31 @@ status.aheadBehind:: `--no-ahead-behind` by default in linkgit:git-status[1] for non-porcelain status formats. Defaults to true. +status.compareBranches:: + A space-separated list of branch comparison specifiers to use in + linkgit:git-status[1]. Currently, only `@{upstream}` and `@{push}` + are supported. They are interpreted as `branch@{upstream}` and + `branch@{push}` for the current branch. ++ +If not set, the default behavior is equivalent to `@{upstream}`, which +compares against the configured upstream tracking branch. ++ +The entries are shown in the order they appear in the configuration. +Duplicate entries that resolve to the same ref are suppressed after +their first occurrence, so `@{push} @{upstream} @{push}` shows at +most two comparisons. When `@{upstream}` and `@{push}` resolve to +the same remote-tracking branch, only one comparison is shown. ++ +Example: ++ +---- +[status] + compareBranches = @{upstream} @{push} +---- ++ +This would show comparisons against both the configured upstream and push +tracking branches for the current branch. + status.displayCommentPrefix:: If set to true, linkgit:git-status[1] will insert a comment prefix before each output line (starting with diff --git a/Documentation/config/submodule.adoc b/Documentation/config/submodule.adoc index 0672d9911724d1..8dacb852c7bf99 100644 --- a/Documentation/config/submodule.adoc +++ b/Documentation/config/submodule.adoc @@ -32,15 +32,16 @@ submodule..fetchRecurseSubmodules:: submodule..ignore:: Defines under what circumstances "git status" and the diff family show - a submodule as modified. When set to "all", it will never be considered - modified (but it will nonetheless show up in the output of status and - commit when it has been staged), "dirty" will ignore all changes - to the submodule's work tree and + a submodule as modified. + When set to "all" will never consider the submodule modified. It can + nevertheless be staged using the option --force and it will then show up + in the output of status. + When set to "dirty" will ignore all changes to the submodule's work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account. "untracked" will additionally let submodules with modified tracked files in their work tree show up. - Using "none" (the default when this option is not set) also shows - submodules that have untracked files in their work tree as changed. + When set to "none"(default) It also show submodules as changed if they have + untracked files in their work tree. This setting overrides any setting made in .gitmodules for this submodule, both settings can be overridden on the command line by using the "--ignore-submodules" option. The 'git submodule' commands are not @@ -52,6 +53,13 @@ submodule..active:: submodule.active config option. See linkgit:gitsubmodules[7] for details. +submodule..gitdir:: + This sets the gitdir path for submodule . This configuration is + respected when `extensions.submodulePathConfig` is enabled, otherwise it + has no effect. When enabled, this config becomes the single source of + truth for submodule gitdir paths and Git will error if it is missing. + See linkgit:git-config[1] for details. + submodule.active:: A repeated field which contains a pathspec used to match against a submodule's path to determine if the submodule is of interest to git diff --git a/Documentation/config/trailer.adoc b/Documentation/config/trailer.adoc index 60bc221c88b801..1bc70192d3a547 100644 --- a/Documentation/config/trailer.adoc +++ b/Documentation/config/trailer.adoc @@ -1,21 +1,21 @@ -trailer.separators:: +`trailer.separators`:: This option tells which characters are recognized as trailer - separators. By default only ':' is recognized as a trailer - separator, except that '=' is always accepted on the command + separators. By default only `:` is recognized as a trailer + separator, except that `=` is always accepted on the command line for compatibility with other git commands. + The first character given by this option will be the default character used when another separator is not specified in the config for this trailer. + -For example, if the value for this option is "%=$", then only lines -using the format '' with containing '%', '=' -or '$' and then spaces will be considered trailers. And '%' will be +For example, if the value for this option is `%=$`, then only lines +using the format __ with __ containing `%`, `=` +or `$` and then spaces will be considered trailers. And `%` will be the default separator used, so by default trailers will appear like: -'% ' (one percent sign and one space will appear between +`% ` (one percent sign and one space will appear between the key and the value). -trailer.where:: +`trailer.where`:: This option tells where a new trailer will be added. + This can be `end`, which is the default, `start`, `after` or `before`. @@ -27,41 +27,41 @@ If it is `start`, then each new trailer will appear at the start, instead of the end, of the existing trailers. + If it is `after`, then each new trailer will appear just after the -last trailer with the same . +last trailer with the same __. + If it is `before`, then each new trailer will appear just before the -first trailer with the same . +first trailer with the same __. -trailer.ifexists:: +`trailer.ifexists`:: This option makes it possible to choose what action will be performed when there is already at least one trailer with the - same in the input. + same __ in the input. + The valid values for this option are: `addIfDifferentNeighbor` (this is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. + With `addIfDifferentNeighbor`, a new trailer will be added only if no -trailer with the same (, ) pair is above or below the line +trailer with the same (__, __) pair is above or below the line where the new trailer will be added. + With `addIfDifferent`, a new trailer will be added only if no trailer -with the same (, ) pair is already in the input. +with the same (__, __) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (, ) pair are already in the input. +the same (__, __) pair are already in the input. + -With `replace`, an existing trailer with the same will be +With `replace`, an existing trailer with the same __ will be deleted and the new trailer will be added. The deleted trailer will be -the closest one (with the same ) to the place where the new one +the closest one (with the same __) to the place where the new one will be added. + With `doNothing`, nothing will be done; that is no new trailer will be -added if there is already one with the same in the input. +added if there is already one with the same __ in the input. -trailer.ifmissing:: +`trailer.ifmissing`:: This option makes it possible to choose what action will be performed when there is not yet any trailer with the same - in the input. + __ in the input. + The valid values for this option are: `add` (this is the default) and `doNothing`. @@ -70,67 +70,68 @@ With `add`, a new trailer will be added. + With `doNothing`, nothing will be done. -trailer..key:: - Defines a for the . The must be a - prefix (case does not matter) of the . For example, in `git - config trailer.ack.key "Acked-by"` the "Acked-by" is the and - the "ack" is the . This configuration allows the shorter +`trailer..key`:: + Defines a __ for the __. The __ must be a + prefix (case does not matter) of the __. For example, in `git + config trailer.ack.key "Acked-by"` the `Acked-by` is the __ and + the `ack` is the __. This configuration allows the shorter `--trailer "ack:..."` invocation on the command line using the "ack" - instead of the longer `--trailer "Acked-by:..."`. + `` instead of the longer `--trailer "Acked-by:..."`. + -At the end of the , a separator can appear and then some -space characters. By default the only valid separator is ':', +At the end of the __, a separator can appear and then some +space characters. By default the only valid separator is `:`, but this can be changed using the `trailer.separators` config variable. + If there is a separator in the key, then it overrides the default separator when adding the trailer. -trailer..where:: - This option takes the same values as the 'trailer.where' +`trailer..where`:: + This option takes the same values as the `trailer.where` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..ifexists:: - This option takes the same values as the 'trailer.ifexists' +`trailer..ifexists`:: + This option takes the same values as the `trailer.ifexists` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..ifmissing:: - This option takes the same values as the 'trailer.ifmissing' +`trailer..ifmissing`:: + This option takes the same values as the `trailer.ifmissing` configuration variable and it overrides what is specified by - that option for trailers with the specified . + that option for trailers with the specified __. -trailer..command:: - Deprecated in favor of 'trailer..cmd'. - This option behaves in the same way as 'trailer..cmd', except +`trailer..command`:: + Deprecated in favor of `trailer..cmd`. + This option behaves in the same way as `trailer..cmd`, except that it doesn't pass anything as argument to the specified command. - Instead the first occurrence of substring $ARG is replaced by the - that would be passed as argument. + Instead the first occurrence of substring `$ARG` is replaced by the + __ that would be passed as argument. + -Note that $ARG in the user's command is -only replaced once and that the original way of replacing $ARG is not safe. +Note that `$ARG` in the user's command is +only replaced once and that the original way of replacing `$ARG` is not safe. + -When both 'trailer..cmd' and 'trailer..command' are given -for the same , 'trailer..cmd' is used and -'trailer..command' is ignored. +When both `trailer..cmd` and `trailer..command` are given +for the same __, `trailer..cmd` is used and +`trailer..command` is ignored. -trailer..cmd:: +`trailer..cmd`:: This option can be used to specify a shell command that will be called - once to automatically add a trailer with the specified , and then - called each time a '--trailer =' argument is specified to - modify the of the trailer that this option would produce. + once to automatically add a trailer with the specified __, and then + called each time a `--trailer =` argument is specified to + modify the __ of the trailer that this option would produce. + When the specified command is first called to add a trailer -with the specified , the behavior is as if a special -'--trailer =' argument was added at the beginning -of the "git interpret-trailers" command, where -is taken to be the standard output of the command with any -leading and trailing whitespace trimmed off. +with the specified __, the behavior is as if a special +`--trailer =` argument was added at the beginning +of linkgit:git-interpret-trailers[1], where __ is taken to be the +standard output of the command with any leading and trailing whitespace +trimmed off. + -If some '--trailer =' arguments are also passed +If some `--trailer =` arguments are also passed on the command line, the command is called again once for each -of these arguments with the same . And the part +of these arguments with the same __. And the __ part of these arguments, if any, will be passed to the command as its -first argument. This way the command can produce a computed -from the passed in the '--trailer =' argument. +first argument. This way the command can produce a __ computed +from the __ passed in the `--trailer =` +argument. diff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc index e161260358fff5..b9ace2aa4b3092 100644 --- a/Documentation/diff-context-options.adoc +++ b/Documentation/diff-context-options.adoc @@ -1,7 +1,9 @@ `-U`:: `--unified=`:: - Generate diffs with __ lines of context. Defaults to `diff.context` - or 3 if the config option is unset. + Generate diffs with __ lines of context. The number of context + lines defaults to `diff.context` or 3 if the configuration variable + is unset. (`-U` without `` is silently accepted as a synonym for + `-p` due to a historical accident). `--inter-hunk-context=`:: Show the context between diff hunks, up to the specified __ diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index 9cdad6f72a0c7d..8a63b5e164114a 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -127,8 +127,10 @@ endif::git-log[] `-U`:: `--unified=`:: - Generate diffs with __ lines of context instead of - the usual three. + Generate diffs with __ lines of context. The number of context + lines defaults to `diff.context` or 3 if the configuration variable + is unset. (`-U` without `` is silently accepted as a synonym for + `-p` due to a historical accident). ifndef::git-format-patch[] Implies `--patch`. endif::git-format-patch[] @@ -859,10 +861,18 @@ endif::git-format-patch[] Do not show any source or destination prefix. `--default-prefix`:: +ifdef::git-format-patch[] + Use the default source and destination prefixes ("a/" and "b/"). + This overrides configuration variables such as `format.noprefix`, + `diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix` + (see linkgit:git-config[1]). +endif::git-format-patch[] +ifndef::git-format-patch[] Use the default source and destination prefixes ("a/" and "b/"). This overrides configuration variables such as `diff.noprefix`, `diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix` (see linkgit:git-config[1]). +endif::git-format-patch[] `--line-prefix=`:: Prepend an additional __ to every line of output. diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc index fcba46ee9e5d61..81a9d7f9bbc11d 100644 --- a/Documentation/fetch-options.adoc +++ b/Documentation/fetch-options.adoc @@ -88,6 +88,25 @@ linkgit:git-config[1]. This is incompatible with `--recurse-submodules=(yes|on-demand)` and takes precedence over the `fetch.output` config option. +`--filter=`:: + Use the partial clone feature and request that the server sends + a subset of reachable objects according to a given object filter. + When using `--filter`, the supplied __ is used for + the partial fetch. ++ +If `--filter=auto` is used, the filter specification is determined +automatically by combining the filter specifications advertised by +the server for the promisor remotes that the client accepts (see +linkgit:gitprotocol-v2[5] and the `promisor.acceptFromServer` +configuration option in linkgit:git-config[1]). ++ +For details on all other available filter specifications, see the +`--filter=` option in linkgit:git-rev-list[1]. ++ +For example, `--filter=blob:none` will filter out all blobs (file +contents) until needed by Git. Also, `--filter=blob:limit=` will +filter out all blobs of size at least __. + ifndef::git-pull[] `--write-fetch-head`:: `--no-write-fetch-head`:: @@ -234,6 +253,8 @@ endif::git-pull[] `--jobs=`:: Parallelize all forms of fetching up to __ jobs at a time. + +A value of 0 will use some reasonable default. ++ If the `--multiple` option was specified, the different remotes will be fetched in parallel. If multiple submodules are fetched, they will be fetched in parallel. To control them independently, use the config settings diff --git a/Documentation/for-each-ref-options.adoc b/Documentation/for-each-ref-options.adoc index f13efb5f2556cf..54e2fa95c2911e 100644 --- a/Documentation/for-each-ref-options.adoc +++ b/Documentation/for-each-ref-options.adoc @@ -30,8 +30,8 @@ TAB %(refname)`. `--color[=]`:: Respect any colors specified in the `--format` option. The - _` is absent, behave as if `always` was given). + __ field must be one of `always`, `never`, or `auto` (if + __ is absent, behave as if `always` was given). `--shell`:: `--perl`:: diff --git a/Documentation/format-patch-caveats.adoc b/Documentation/format-patch-caveats.adoc new file mode 100644 index 00000000000000..807a65b885b09a --- /dev/null +++ b/Documentation/format-patch-caveats.adoc @@ -0,0 +1,33 @@ +The output from linkgit:git-format-patch[1] can lead to a different +commit message when applied with linkgit:git-am[1]. The patch that is +applied may also be different from the one that was generated, or patch +application may fail outright. +ifdef::git-am[] +See the <> section above for the syntactic rules. +endif::git-am[] + +ifndef::git-am[] +include::format-patch-end-of-commit-message.adoc[] +endif::git-am[] + +Note that this is especially problematic for unindented diffs that occur +in the commit message; the diff in the commit message might get applied +along with the patch section, or the patch application machinery might +trip up because the patch target doesn't apply. This could for example +be caused by a diff in a Markdown code block. + +The solution for this is to indent the diff or other text that could +cause problems. + +This loss of fidelity might be simple to notice if you are applying +patches directly from a mailbox. However, changes originating from Git +could be applied in bulk, in which case this would be much harder to +notice. This could for example be a Linux distribution which uses patch +files to apply changes on top of the commits from the upstream +repositories. This goes to show that this behavior does not only impact +email workflows. + +Given these limitations, one might be tempted to use a general-purpose +utility like patch(1) instead. However, patch(1) will not only look for +unindented diffs (like linkgit:git-am[1]) but will try to apply indented +diffs as well. diff --git a/Documentation/format-patch-end-of-commit-message.adoc b/Documentation/format-patch-end-of-commit-message.adoc new file mode 100644 index 00000000000000..ec1ef79f5e3308 --- /dev/null +++ b/Documentation/format-patch-end-of-commit-message.adoc @@ -0,0 +1,8 @@ +Any line that is of the form: + +* three-dashes and end-of-line, or +* a line that begins with "diff -", or +* a line that begins with "Index: " + +is taken as the beginning of a patch, and the commit log message +is terminated before the first occurrence of such a line. diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc index 6192daeb0371cf..941135dc637d90 100644 --- a/Documentation/git-add.adoc +++ b/Documentation/git-add.adoc @@ -75,7 +75,10 @@ in linkgit:gitglossary[7]. `-f`:: `--force`:: - Allow adding otherwise ignored files. + Allow adding otherwise ignored files. The option is also used when + `submodule..ignore=all` is set, but you want to stage an + update of the submodule. The `path` to the submodule must be explicitly + specified. `--sparse`:: Allow updating index entries outside of the sparse-checkout cone. diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc index 0c94776e296981..384e0cd7f9b5d5 100644 --- a/Documentation/git-am.adoc +++ b/Documentation/git-am.adoc @@ -9,7 +9,7 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--no-verify] +'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify] [--[no-]3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=] [-C] [-p] [--directory=] @@ -37,20 +37,21 @@ OPTIONS -s:: --signoff:: - Add a `Signed-off-by` trailer to the commit message, using - the committer identity of yourself. - See the signoff option in linkgit:git-commit[1] for more information. + Add a `Signed-off-by` trailer to the commit message (see + linkgit:git-interpret-trailers[1]), using the committer identity + of yourself. See the signoff option in linkgit:git-commit[1] + for more information. -k:: --keep:: - Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + Pass `-k` flag to linkgit:git-mailinfo[1]. --keep-non-patch:: - Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + Pass `-b` flag to linkgit:git-mailinfo[1]. --keep-cr:: --no-keep-cr:: - With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) + With `--keep-cr`, call linkgit:git-mailsplit[1] with the same option, to prevent it from stripping CR at the end of lines. `am.keepcr` configuration variable can be used to specify the default behaviour. `--no-keep-cr` is useful to override `am.keepcr`. @@ -65,7 +66,7 @@ OPTIONS Ignore scissors lines (see linkgit:git-mailinfo[1]). --quoted-cr=:: - This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]). + This flag will be passed down to linkgit:git-mailinfo[1]. --empty=(drop|keep|stop):: How to handle an e-mail message lacking a patch: @@ -83,10 +84,11 @@ OPTIONS -m:: --message-id:: - Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]), - so that the Message-ID header is added to the commit message. - The `am.messageid` configuration variable can be used to specify - the default behaviour. + Pass the `-m` flag to linkgit:git-mailinfo[1], so that the + `Message-ID` header is added as a trailer (see + linkgit:git-interpret-trailers[1]). The `am.messageid` + configuration variable can be used to specify the default + behaviour. --no-message-id:: Do not add the Message-ID header to the commit message. @@ -98,7 +100,7 @@ OPTIONS -u:: --utf8:: - Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + Pass `-u` flag to linkgit:git-mailinfo[1]. The proposed commit log message taken from the e-mail is re-coded into UTF-8 encoding (configuration variable `i18n.commitEncoding` can be used to specify the project's @@ -108,8 +110,7 @@ This was optional in prior versions of git, but now it is the default. You can use `--no-utf8` to override this. --no-utf8:: - Pass `-n` flag to 'git mailinfo' (see - linkgit:git-mailinfo[1]). + Pass `-n` flag to linkgit:git-mailinfo[1]. -3:: --3way:: @@ -132,9 +133,8 @@ include::rerere-options.adoc[] --exclude=:: --include=:: --reject:: - These flags are passed to the 'git apply' (see linkgit:git-apply[1]) - program that applies - the patch. + These flags are passed to the linkgit:git-apply[1] program that + applies the patch. + Valid for the `--whitespace` option are: `nowarn`, `warn`, `fix`, `error`, and `error-all`. @@ -150,11 +150,14 @@ Valid for the `--whitespace` option are: --interactive:: Run interactively. +--verify:: -n:: --no-verify:: - By default, the pre-applypatch and applypatch-msg hooks are run. - When any of `--no-verify` or `-n` is given, these are bypassed. - See also linkgit:githooks[5]. + Run the `pre-applypatch` and `applypatch-msg` hooks. This is the + default. Skip these hooks with `-n` or `--no-verify`. See also + linkgit:githooks[5]. ++ +Note that `post-applypatch` cannot be skipped. --committer-date-is-author-date:: By default the command records the date from the e-mail @@ -205,7 +208,8 @@ applying. to the screen before exiting. This overrides the standard message informing you to use `--continue` or `--skip` to handle the failure. This is solely - for internal use between 'git rebase' and 'git am'. + for internal use between linkgit:git-rebase[1] and + linkgit:git-am[1]. --abort:: Restore the original branch and abort the patching operation. @@ -223,7 +227,7 @@ applying. failure again. --show-current-patch[=(diff|raw)]:: - Show the message at which `git am` has stopped due to + Show the message at which linkgit:git-am[1] has stopped due to conflicts. If `raw` is specified, show the raw contents of the e-mail message; if `diff`, show the diff portion only. Defaults to `raw`. @@ -233,6 +237,7 @@ applying. create an empty commit with the contents of the e-mail message as its log message. +[[discussion]] DISCUSSION ---------- @@ -252,16 +257,13 @@ where the patch begins. Excess whitespace at the end of each line is automatically stripped. The patch is expected to be inline, directly following the -message. Any line that is of the form: - -* three-dashes and end-of-line, or -* a line that begins with "diff -", or -* a line that begins with "Index: " +message. +include::format-patch-end-of-commit-message.adoc[] -is taken as the beginning of a patch, and the commit log message -is terminated before the first occurrence of such a line. +This means that the contents of the commit message can inadvertently +interrupt the processing (see the <> section below). -When initially invoking `git am`, you give it the names of the mailboxes +When initially invoking linkgit:git-am[1], you give it the names of the mailboxes to process. Upon seeing the first patch that does not apply, it aborts in the middle. You can recover from this in one of two ways: @@ -279,16 +281,25 @@ names. Before any patches are applied, ORIG_HEAD is set to the tip of the current branch. This is useful if you have problems with multiple -commits, like running 'git am' on the wrong branch or an error in the -commits that is more easily fixed by changing the mailbox (e.g. +commits, like running linkgit:git-am[1] on the wrong branch or an error +in the commits that is more easily fixed by changing the mailbox (e.g. errors in the "From:" lines). +[[caveats]] +CAVEATS +------- + +:git-am: 1 +include::format-patch-caveats.adoc[] + HOOKS ----- This command can run `applypatch-msg`, `pre-applypatch`, and `post-applypatch` hooks. See linkgit:githooks[5] for more information. +See the `--verify`/`-n`/`--no-verify` options. + CONFIGURATION ------------- diff --git a/Documentation/git-clone.adoc b/Documentation/git-clone.adoc index 57cdfb7620571c..b6e1f8ada22813 100644 --- a/Documentation/git-clone.adoc +++ b/Documentation/git-clone.adoc @@ -84,7 +84,7 @@ __. with the source repository. The resulting repository starts out without any object of its own. + -*NOTE*: this is a possibly dangerous operation; do *not* use +NOTE: this is a possibly dangerous operation; do *not* use it unless you understand what it does. If you clone your repository using this option and then delete branches (or use any other Git command that makes any existing commit unreferenced) in the @@ -104,7 +104,8 @@ If you want to break the dependency of a repository cloned with `--shared` on its source repository, you can simply run `git repack -a` to copy all objects from the source repository into a pack in the cloned repository. -`--reference[-if-able] `:: +`--reference=`:: +`--reference-if-able=`:: If the reference __ is on the local machine, automatically setup `.git/objects/info/alternates` to obtain objects from the reference __. Using @@ -115,7 +116,7 @@ objects from the source repository into a pack in the cloned repository. directory is skipped with a warning instead of aborting the clone. + -*NOTE*: see the NOTE for the `--shared` option, and also the +NOTE: see the NOTE for the `--shared` option, and also the `--dissociate` option. `--dissociate`:: @@ -140,27 +141,28 @@ objects from the source repository into a pack in the cloned repository. to the standard error stream. `--progress`:: - Progress status is reported on the standard error stream - by default when it is attached to a terminal, unless `--quiet` + Report progress status on the standard error stream + by default when attached to a terminal, unless `--quiet` is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. `--server-option=