diff options
Diffstat (limited to 'Documentation')
29 files changed, 862 insertions, 232 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index f06563e981..e41654c00a 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1116,6 +1116,15 @@ $ git send-email --to=target@example.com psuh/*.patch NOTE: Check `git help send-email` for some other options which you may find valuable, such as changing the Reply-to address or adding more CC and BCC lines. +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + +not part of the core `git` binary and must be called directly. Clone the Git + +codebase and run `perl contrib/contacts/git-contacts`.] + +NOTE: If you're not sure whom to CC, running `contrib/contacts/git-contacts` can +list potential reviewers. In addition, you can do `git send-email +--cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch`{contrib-scripts} to +automatically pass this list of emails to `send-email`. + NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but please don't send your patchset from the tutorial to the real mailing list! For now, you can send it to yourself, to make sure you understand how it will look. diff --git a/Documentation/RelNotes/2.39.4.txt b/Documentation/RelNotes/2.39.4.txt new file mode 100644 index 0000000000..7f54521fea --- /dev/null +++ b/Documentation/RelNotes/2.39.4.txt @@ -0,0 +1,79 @@ +Git v2.39.4 Release Notes +========================= + +This addresses the security issues CVE-2024-32002, CVE-2024-32004, +CVE-2024-32020 and CVE-2024-32021. + +This release also backports fixes necessary to let the CI builds pass +successfully. + +Fixes since v2.39.3 +------------------- + + * CVE-2024-32002: + + Recursive clones on case-insensitive filesystems that support symbolic + links are susceptible to case confusion that can be exploited to + execute just-cloned code during the clone operation. + + * CVE-2024-32004: + + Repositories can be configured to execute arbitrary code during local + clones. To address this, the ownership checks introduced in v2.30.3 + are now extended to cover cloning local repositories. + + * CVE-2024-32020: + + Local clones may end up hardlinking files into the target repository's + object database when source and target repository reside on the same + disk. If the source repository is owned by a different user, then + those hardlinked files may be rewritten at any point in time by the + untrusted user. + + * CVE-2024-32021: + + When cloning a local source repository that contains symlinks via the + filesystem, Git may create hardlinks to arbitrary user-readable files + on the same filesystem as the target repository in the objects/ + directory. + + * CVE-2024-32465: + + It is supposed to be safe to clone untrusted repositories, even those + unpacked from zip archives or tarballs originating from untrusted + sources, but Git can be tricked to run arbitrary code as part of the + clone. + + * Defense-in-depth: submodule: require the submodule path to contain + directories only. + + * Defense-in-depth: clone: when symbolic links collide with directories, keep + the latter. + + * Defense-in-depth: clone: prevent hooks from running during a clone. + + * Defense-in-depth: core.hooksPath: add some protection while cloning. + + * Defense-in-depth: fsck: warn about symlink pointing inside a gitdir. + + * Various fix-ups on HTTP tests. + + * Test update. + + * HTTP Header redaction code has been adjusted for a newer version of + cURL library that shows its traces differently from earlier + versions. + + * Fix was added to work around a regression in libcURL 8.7.0 (which has + already been fixed in their tip of the tree). + + * Replace macos-12 used at GitHub CI with macos-13. + + * ci(linux-asan/linux-ubsan): let's save some time + + * Tests with LSan from time to time seem to emit harmless message that makes + our tests unnecessarily flakey; we work it around by filtering the + uninteresting output. + + * Update GitHub Actions jobs to avoid warnings against using deprecated + version of Node.js. diff --git a/Documentation/RelNotes/2.40.2.txt b/Documentation/RelNotes/2.40.2.txt new file mode 100644 index 0000000000..646a2cc3eb --- /dev/null +++ b/Documentation/RelNotes/2.40.2.txt @@ -0,0 +1,7 @@ +Git v2.40.2 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4 to address +the security issues CVE-2024-32002, CVE-2024-32004, CVE-2024-32020, +CVE-2024-32021 and CVE-2024-32465; see the release notes for that +version for details. diff --git a/Documentation/RelNotes/2.41.1.txt b/Documentation/RelNotes/2.41.1.txt new file mode 100644 index 0000000000..9fb4c218b2 --- /dev/null +++ b/Documentation/RelNotes/2.41.1.txt @@ -0,0 +1,7 @@ +Git v2.41.1 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4 and v2.40.2 +to address the security issues CVE-2024-32002, CVE-2024-32004, +CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.42.2.txt b/Documentation/RelNotes/2.42.2.txt new file mode 100644 index 0000000000..dbf761a01d --- /dev/null +++ b/Documentation/RelNotes/2.42.2.txt @@ -0,0 +1,7 @@ +Git v2.42.2 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4, v2.40.2 +and v2.41.1 to address the security issues CVE-2024-32002, +CVE-2024-32004, CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.43.4.txt b/Documentation/RelNotes/2.43.4.txt new file mode 100644 index 0000000000..0a842515ff --- /dev/null +++ b/Documentation/RelNotes/2.43.4.txt @@ -0,0 +1,7 @@ +Git v2.43.4 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4, v2.40.2, +v2.41.1 and v2.42.2 to address the security issues CVE-2024-32002, +CVE-2024-32004, CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.44.1.txt b/Documentation/RelNotes/2.44.1.txt new file mode 100644 index 0000000000..b5135c3281 --- /dev/null +++ b/Documentation/RelNotes/2.44.1.txt @@ -0,0 +1,8 @@ +Git v2.44.1 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4, v2.40.2, +v2.41.1, v2.42.2 and v2.43.4 to address the security issues +CVE-2024-32002, CVE-2024-32004, CVE-2024-32020, CVE-2024-32021 +and CVE-2024-32465; see the release notes for these versions +for details. diff --git a/Documentation/RelNotes/2.45.0.txt b/Documentation/RelNotes/2.45.0.txt index 0570dcd877..fec193679f 100644 --- a/Documentation/RelNotes/2.45.0.txt +++ b/Documentation/RelNotes/2.45.0.txt @@ -77,8 +77,10 @@ UI, Workflows & Features skip showing the hunk immediately after it has already been shown, and an additional action to explicitly ask to reshow the current hunk. - * "git pack-refs" learned the "--auto" option, which is a useful - addition to be triggered from "git gc --auto". + * "git pack-refs" learned the "--auto" option, which defers the decision of + whether and how to pack to the ref backend. This is used by the reftable + backend to avoid repacking of an already-optimal ref database. The new mode + is triggered from "git gc --auto". * "git add -u <pathspec>" and "git commit [-i] <pathspec>" did not diagnose a pathspec element that did not match any files in certain @@ -86,6 +88,19 @@ UI, Workflows & Features * The userdiff patterns for C# has been updated. + * Git writes a "waiting for your editor" message on an incomplete + line after launching an editor, and then append another error + message on the same line if the editor errors out. It now clears + the "waiting for..." line before giving the error message. + + * The filename used for rejected hunks "git apply --reject" creates + was limited to PATH_MAX, which has been lifted. + + * When "git bisect" reports the commit it determined to be the + culprit, we used to show it in a format that does not honor common + UI tweaks, like log.date and log.decorate. The code has been + taught to use "git show" to follow more customizations. + Performance, Internal Implementation, Development Support etc. @@ -100,7 +115,7 @@ Performance, Internal Implementation, Development Support etc. * The way placeholders are to be marked-up in documentation have been specified; use "_<placeholder>_" to typeset the word inside a pair - of <angle-brakets> emphasized. + of <angle-brackets> emphasized. * "git --no-lazy-fetch cmd" allows to run "cmd" while disabling lazy fetching of objects from the promisor remote, which may be handy @@ -110,9 +125,6 @@ Performance, Internal Implementation, Development Support etc. clean.requireForce has been simplified, together with the documentation. - * The code to iterate over refs with the reftable backend has seen - some optimization. - * Uses of xwrite() helper have been audited and updated for better error checking and simpler code. @@ -185,6 +197,19 @@ Performance, Internal Implementation, Development Support etc. operations accumulate many entries has been improved to avoid accumulating too many tables uncollected. + * The code to iterate over reftable blocks has seen some optimization + to reduce memory allocation and deallocation. + + * The way "git fast-import" handles paths described in its input has + been tightened up and more clearly documented. + + * The cvsimport tests required that the platform understands + traditional timezone notations like CST6CDT, which has been + updated to work on those systems as long as they understand + POSIX notation with explicit tz transition dates. + + * The code to format trailers have been cleaned up. + Fixes since v2.44 ----------------- @@ -231,7 +256,7 @@ Fixes since v2.44 (merge 5edd126720 jk/reflog-special-cases-fix later to maint). * An error message from "git upload-pack", which responds to "git - fetch" requests, had a trialing NUL in it, which has been + fetch" requests, had a trailing NUL in it, which has been corrected. (merge 3f4c7a0805 sg/upload-pack-error-message-fix later to maint). @@ -248,7 +273,7 @@ Fixes since v2.44 This has been corrected. (merge 199f44cb2e ps/remote-helper-repo-initialization-fix later to maint). - * Various parts of upload-pack has been updated to bound the resource + * Various parts of upload-pack have been updated to bound the resource consumption relative to the size of the repository to protect from abusive clients. (merge 6cd05e768b jk/upload-pack-bounded-resources later to maint). @@ -295,11 +320,11 @@ Fixes since v2.44 variable that is no longer used. (merge 72a8d3f027 pw/rebase-i-ignore-cherry-pick-help-environment later to maint). - * The code to find the effective end of log message can fall into an + * The code to find the effective end of log messages can fall into an endless loop, which has been corrected. (merge 2541cba2d6 fs/find-end-of-log-message-fix later to maint). - * Mark-ups used in the documentation has been improved for + * Mark-up used in the documentation has been improved for consistency. (merge 45d5ed3e50 ja/doc-markup-fixes later to maint). @@ -393,7 +418,7 @@ Fixes since v2.44 configuration variable used to leak, which has been corrected. (merge 0e0fefb29f jc/unleak-core-excludesfile later to maint). - * vreportf(), which is usede by error() and friends, has been taught + * vreportf(), which is used by error() and friends, has been taught to give the error message printf-format string when its vsnprintf() call fails, instead of showing nothing useful to identify the nature of the error. @@ -402,6 +427,20 @@ Fixes since v2.44 * Adjust to an upcoming changes to GNU make that breaks our Makefiles. (merge 227b8fd902 tb/make-indent-conditional-with-non-spaces later to maint). + * Git 2.44 introduced a regression that makes the updated code to + barf in repositories with multi-pack index written by older + versions of Git, which has been corrected. + + * When .git/rr-cache/ rerere database gets corrupted or rerere is fed to + work on a file with conflicted hunks resolved incompletely, the rerere + machinery got confused and segfaulted, which has been corrected. + (merge 167395bb47 mr/rerere-crash-fix later to maint). + + * The "receive-pack" program (which responds to "git push") was not + converted to run "git maintenance --auto" when other codepaths that + used to run "git gc --auto" were updated, which has been corrected. + (merge 7bf3057d9c ps/run-auto-maintenance-in-receive-pack later to maint). + * Other code cleanup, docfix, build fix, etc. (merge f0e578c69c rs/use-xstrncmpz later to maint). (merge 83e6eb7d7a ba/credential-test-clean-fix later to maint). @@ -432,3 +471,6 @@ Fixes since v2.44 (merge b4454d5a7b pw/t3428-cleanup later to maint). (merge 84a7c33a4b pf/commitish-committish later to maint). (merge 8882ee9d68 la/mailmap-entry later to maint). + (merge 44bdba2fa6 rs/no-openssl-compilation-fix-on-macos later to maint). + (merge f412d72c19 yb/replay-doc-linkfix later to maint). + (merge 5da40be8d7 xx/rfc2822-date-format-in-doc later to maint). diff --git a/Documentation/RelNotes/2.45.1.txt b/Documentation/RelNotes/2.45.1.txt new file mode 100644 index 0000000000..3b0d60cfa3 --- /dev/null +++ b/Documentation/RelNotes/2.45.1.txt @@ -0,0 +1,8 @@ +Git v2.45.1 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4, +v2.40.2, v2.41.1, v2.42.2, v2.43.4 and v2.44.1 to address the +security issues CVE-2024-32002, CVE-2024-32004, CVE-2024-32020, +CVE-2024-32021 and CVE-2024-32465; see the release notes for +these versions for details. diff --git a/Documentation/RelNotes/2.46.0.txt b/Documentation/RelNotes/2.46.0.txt new file mode 100644 index 0000000000..e74720d057 --- /dev/null +++ b/Documentation/RelNotes/2.46.0.txt @@ -0,0 +1,159 @@ +Git v2.46 Release Notes +======================= + +Backward Compatibility Notes + + (None at this moment) + +UI, Workflows & Features + + * The "--rfc" option of "git format-patch" learned to take an + optional string value to be used in place of "RFC" to tweak the + "[PATCH]" on the subject header. + + * The credential helper protocol, together with the HTTP layer, have + been enhanced to support authentication schemes different from + username & password pair, like Bearer and NTLM. + + * Command line completion script (in contrib/) learned to complete + "git symbolic-ref" a bit better (you need to enable plumbing + commands to be completed with GIT_COMPLETION_SHOW_ALL_COMMANDS). + + * When the user responds to a prompt given by "git add -p" with an + unsupported command, list of available commands were given, which + was too much if the user knew what they wanted to type but merely + made a typo. Now the user gets a much shorter error message. + + * The color parsing code learned to handle 12-bit RGB colors, spelled + as "#RGB" (in addition to "#RRGGBB" that is already supported). + + * The operation mode options (like "--get") the "git config" command + uses have been deprecated and replaced with subcommands (like "git + config get"). + + * "git tag" learned the "--trailer" option to futz with the trailers + in the same way as "git commit" does. + + * A new global "--no-advice" option can be used to disable all advice + messages, which is meant to be used only in scripts. + + * Updates to symbolic refs can now be made as a part of ref + transaction. + + * The trailer API has been reshuffled a bit. + + +Performance, Internal Implementation, Development Support etc. + + * Advertise "git contacts", a tool for newcomers to find people to + ask review for their patches, a bit more in our developer + documentation. + + * In addition to building the objects needed, try to link the objects + that are used in fuzzer tests, to make sure at least they build + without bitrot, in Linux CI runs. + + * Code to write out reftable has seen some optimization and + simplification. + + * Tests to ensure interoperability between reftable written by jgit + and our code have been added and enabled in CI. + + * The singleton index_state instance "the_index" has been eliminated + by always instantiating "the_repository" and replacing references + to "the_index" with references to its .index member. + + * Git-GUI has a new maintainer, Johannes Sixt. + (merge e18ad8eb26 jc/git-gui-maintainer-update later to maint). + + * The "test-tool" has been taught to run testsuite tests in parallel, + bypassing the need to use the "prove" tool. + + * The "whitespace check" task that was enabled for GitHub Actions CI + has been ported to GitLab CI. + + * The refs API lost functions that implicitly assumes to work on the + primary ref_store by forcing the callers to pass a ref_store as an + argument. + + +Fixes since v2.45 +----------------- + + * "git rebase --signoff" used to forget that it needs to add a + sign-off to the resulting commit when told to continue after a + conflict stops its operation. + (merge a6c2654f83 pw/rebase-m-signoff-fix later to maint). + + * The procedure to build multi-pack-index got confused by the + replace-refs mechanism, which has been corrected by disabling the + latter. + (merge 93e2ae1c95 xx/disable-replace-when-building-midx later to maint). + + * The "-k" and "--rfc" options of "format-patch" will now error out + when used together, as one tells us not to add anything to the + title of the commit, and the other one tells us to add "RFC" in + addition to "PATCH". + (merge cadcf58085 ds/format-patch-rfc-and-k later to maint). + + * "git stash -S" did not handle binary files correctly, which has + been corrected. + (merge 5fb7686409 aj/stash-staged-fix later to maint). + + * A scheduled "git maintenance" job is expected to work on all + repositories it knows about, but it stopped at the first one that + errored out. Now it keeps going. + (merge c75662bfc9 js/for-each-repo-keep-going later to maint). + + * zsh can pretend to be a normal shell pretty well except for some + glitches that we tickle in some of our scripts. Work them around + so that "vimdiff" and our test suite works well enough with it. + (merge fedd5c79ff bc/zsh-compatibility later to maint). + + * Command line completion support for zsh (in contrib/) has been + updated to stop exposing internal state to end-user shell + interaction. + (merge 3c20acdf46 dk/zsh-git-repo-path-fix later to maint). + + * Tests that try to corrupt in-repository files in chunked format did + not work well on macOS due to its broken "mv", which has been + worked around. + (merge 861dc19ba8 jc/test-workaround-broken-mv later to maint). + + * The maximum size of attribute files is enforced more consistently. + (merge c793f9cb08 tb/attr-limits later to maint). + + * Unbreak CI jobs so that we do not attempt to use Python 2 that has + been removed from the platform. + (merge 5ca0c455f1 ps/ci-python-2-deprecation later to maint). + + * Git 2.43 started using the tree of HEAD as the source of attributes + in a bare repository, which has severe performance implications. + For now, revert the change, without ripping out a more explicit + support for the attr.tree configuration variable. + (merge 51441e6460 jc/no-default-attr-tree-in-bare later to maint). + + * The "--exit-code" option of "git diff" command learned to work with + the "--ext-diff" option. + (merge 11be65cfa4 rs/external-diff-with-exit-code later to maint). + + * Windows CI running in GitHub Actions started complaining about the + order of arguments given to calloc(); the imported regex code uses + the wrong order almost consistently, which has been corrected. + (merge f01301aabe jc/compat-regex-calloc-fix later to maint). + + * Expose "name conflict" error when a ref creation fails due to D/F + conflict in the ref namespace, to improve an error message given by + "git fetch". + (merge 9339fca23e it/refs-name-conflict later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 4cf6e7bf5e jt/doc-submitting-rerolled-series later to maint). + (merge a5a4cb7b27 rs/diff-parseopts-cleanup later to maint). + (merge 395c130fd8 ma/win32-unix-domain-socket later to maint). + (merge 7df2405b38 jk/ci-macos-gcc13-fix later to maint). + (merge 55702c543e fa/p4-error later to maint). + (merge 2566a77774 vd/doc-merge-tree-x-option later to maint). + (merge b64b0df9da ds/scalar-reconfigure-all-fix later to maint). + (merge c81ffcff83 dm/update-index-doc-fix later to maint). + (merge fc0202b0e9 dg/fetch-pack-code-cleanup later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c647c7e1b4..20f4311e54 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -7,6 +7,73 @@ Here are some guidelines for contributing back to this project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. +[[patch-flow]] +=== A typical life cycle of a patch series + +To help us understand the reason behind various guidelines given later +in the document, first let's understand how the life cycle of a +typical patch series for this project goes. + +. You come up with an itch. You code it up. You do not need any + pre-authorization from the project to do so. ++ +Your patches will be reviewed by other contributors on the mailing +list, and the reviews will be done to assess the merit of various +things, like the general idea behind your patch (including "is it +solving a problem worth solving in the first place?"), the reason +behind the design of the solution, and the actual implementation. +The guidelines given here are there to help your patches by making +them easier to understand by the reviewers. + +. You send the patches to the list and cc people who may need to know + about the change. Your goal is *not* necessarily to convince others + that what you are building is good. Your goal is to get help in + coming up with a solution for the "itch" that is better than what + you can build alone. ++ +The people who may need to know are the ones who worked on the code +you are touching. These people happen to be the ones who are +most likely to be knowledgeable enough to help you, but +they have no obligation to help you (i.e. you ask them for help, +you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would +help you find out who they are. + +. You get comments and suggestions for improvements. You may even get + them in an "on top of your change" patch form. You are expected to + respond to them with "Reply-All" on the mailing list, while taking + them into account while preparing an updated set of patches. + +. Polish, refine, and re-send your patches to the list and to the people + who spent their time to improve your patch. Go back to step (2). + +. While the above iterations improve your patches, the maintainer may + pick the patches up from the list and queue them to the `seen` + branch, in order to make it easier for people to play with it + without having to pick up and apply the patches to their trees + themselves. Being in `seen` has no other meaning. Specifically, it + does not mean the patch was "accepted" in any way. + +. When the discussion reaches a consensus that the latest iteration of + the patches are in good enough shape, the maintainer includes the + topic in the "What's cooking" report that are sent out a few times a + week to the mailing list, marked as "Will merge to 'next'." This + decision is primarily made by the maintainer with help from those + who participated in the review discussion. + +. After the patches are merged to the 'next' branch, the discussion + can still continue to further improve them by adding more patches on + top, but by the time a topic gets merged to 'next', it is expected + that everybody agrees that the scope and the basic direction of the + topic are appropriate, so such an incremental updates are limited to + small corrections and polishing. After a topic cooks for some time + (like 7 calendar days) in 'next' without needing further tweaks on + top, it gets merged to the 'master' branch and wait to become part + of the next major release. + +In the following sections, many techniques and conventions are listed +to help your patches get reviewed effectively in such a life cycle. + + [[choose-starting-point]] === Choose a starting point. @@ -192,8 +259,9 @@ reasons: which case, they can explain why they extend your code to cover files, too). -The goal of your log message is to convey the _why_ behind your -change to help future developers. +The goal of your log message is to convey the _why_ behind your change +to help future developers. The reviewers will also make sure that +your proposed log message will serve this purpose well. The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), @@ -397,17 +465,57 @@ letter. [[send-patches]] === Sending your patches. +==== Choosing your reviewers + :security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] -Before sending any patches, please note that patches that may be +NOTE: Patches that may be security relevant should be submitted privately to the Git Security mailing list{security-ml}, instead of the public mailing list. -Learn to use format-patch and send-email if possible. These commands +:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + +not part of the core `git` binary and must be called directly. Clone the Git + +codebase and run `perl contrib/contacts/git-contacts`.] + +Send your patch with "To:" set to the mailing list, with "cc:" listing +people who are involved in the area you are touching (the `git-contacts` +script in `contrib/contacts/`{contrib-scripts} can help to +identify them), to solicit comments and reviews. Also, when you made +trial merges of your topic to `next` and `seen`, you may have noticed +work by others conflicting with your changes. There is a good possibility +that these people may know the area you are touching well. + +If you are using `send-email`, you can feed it the output of `git-contacts` like +this: + +.... + git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch +.... + +:current-maintainer: footnote:[The current maintainer: gitster@pobox.com] +:git-ml: footnote:[The mailing list: git@vger.kernel.org] + +After the list reached a consensus that it is a good idea to apply the +patch, re-send it with "To:" set to the maintainer{current-maintainer} +and "cc:" the list{git-ml} for inclusion. This is especially relevant +when the maintainer did not heavily participate in the discussion and +instead left the review to trusted others. + +Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and +`Tested-by:` lines as necessary to credit people who helped your +patch, and "cc:" them when sending such a final version for inclusion. + +==== `format-patch` and `send-email` + +Learn to use `format-patch` and `send-email` if possible. These commands are optimized for the workflow of sending patches, avoiding many ways your existing e-mail client (often optimized for "multipart/*" MIME type e-mails) might render your patches unusable. +NOTE: Here we outline the procedure using `format-patch` and +`send-email`, but you can instead use GitGitGadget to send in your +patches (see link:MyFirstContribution.html[MyFirstContribution]). + People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for a developer to be able to "quote" your changes, using standard @@ -415,10 +523,12 @@ e-mail tools, so that they may comment on specific portions of your code. For this reason, each patch should be submitted "inline" in a separate message. -Multiple related patches should be grouped into their own e-mail -thread to help readers find all parts of the series. To that end, -send them as replies to either an additional "cover letter" message -(see below), the first patch, or the respective preceding patch. +All subsequent versions of a patch series and other related patches should be +grouped into their own e-mail thread to help readers find all parts of the +series. To that end, send them as replies to either an additional "cover +letter" message (see below), the first patch, or the respective preceding patch. +Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on +how to submit updated versions of a patch series. If your log message (including your name on the `Signed-off-by` trailer) is not writable in ASCII, make sure that @@ -498,42 +608,14 @@ patch, format it as "multipart/signed", not a text/plain message that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is not a text/plain, it's something else. -:security-ml-ref: footnoteref:[security-ml] - -As mentioned at the beginning of the section, patches that may be -security relevant should not be submitted to the public mailing list -mentioned below, but should instead be sent privately to the Git -Security mailing list{security-ml-ref}. - -Send your patch with "To:" set to the mailing list, with "cc:" listing -people who are involved in the area you are touching (the `git -contacts` command in `contrib/contacts/` can help to -identify them), to solicit comments and reviews. Also, when you made -trial merges of your topic to `next` and `seen`, you may have noticed -work by others conflicting with your changes. There is a good possibility -that these people may know the area you are touching well. - -:current-maintainer: footnote:[The current maintainer: gitster@pobox.com] -:git-ml: footnote:[The mailing list: git@vger.kernel.org] - -After the list reached a consensus that it is a good idea to apply the -patch, re-send it with "To:" set to the maintainer{current-maintainer} -and "cc:" the list{git-ml} for inclusion. This is especially relevant -when the maintainer did not heavily participate in the discussion and -instead left the review to trusted others. - -Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and -`Tested-by:` lines as necessary to credit people who helped your -patch, and "cc:" them when sending such a final version for inclusion. - == Subsystems with dedicated maintainers Some parts of the system have dedicated maintainers with their own repositories. -- `git-gui/` comes from git-gui project, maintained by Pratyush Yadav: +- `git-gui/` comes from git-gui project, maintained by Johannes Sixt: - https://github.com/prati0100/git-gui.git + https://github.com/j6t/git-gui - `gitk-git/` comes from Paul Mackerras's gitk project: @@ -548,55 +630,6 @@ repositories. Patches to these parts should be based on their trees. -[[patch-flow]] -== An ideal patch flow - -Here is an ideal patch flow for this project the current maintainer -suggests to the contributors: - -. You come up with an itch. You code it up. - -. Send it to the list and cc people who may need to know about - the change. -+ -The people who may need to know are the ones whose code you -are butchering. These people happen to be the ones who are -most likely to be knowledgeable enough to help you, but -they have no obligation to help you (i.e. you ask for help, -don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would -help you find out who they are. - -. You get comments and suggestions for improvements. You may - even get them in an "on top of your change" patch form. - -. Polish, refine, and re-send to the list and the people who - spend their time to improve your patch. Go back to step (2). - -. The list forms consensus that the last round of your patch is - good. Send it to the maintainer and cc the list. - -. A topic branch is created with the patch and is merged to `next`, - and cooked further and eventually graduates to `master`. - -In any time between the (2)-(3) cycle, the maintainer may pick it up -from the list and queue it to `seen`, in order to make it easier for -people to play with it without having to pick up and apply the patch to -their trees themselves. - -[[patch-status]] -== Know the status of your patch after submission - -* You can use Git itself to find out when your patch is merged in - master. `git pull --rebase` will automatically skip already-applied - patches, and will let you know. This works only if you rebase on top - of the branch in which your patch has been merged (i.e. it will not - tell you if your patch is merged in `seen` if you rebase on top of - master). - -* Read the Git mailing list, the maintainer regularly posts messages - entitled "What's cooking in git.git" giving - the status of various proposed changes. - == GitHub CI[[GHCI]] With an account at GitHub, you can use GitHub CI to test your changes diff --git a/Documentation/config.txt b/Documentation/config.txt index 70b448b132..6f649c997c 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -316,7 +316,8 @@ terminals, this is usually not the same as setting to "white black". Colors may also be given as numbers between 0 and 255; these use ANSI 256-color mode (but note that not all terminals may support this). If your terminal supports it, you may also specify 24-bit RGB values as -hex, like `#ff0ab3`. +hex, like `#ff0ab3`, or 12-bit RGB values like `#f1b`, which is +equivalent to the 24-bit color `#ff11bb`. + The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, `italic`, and `strike` (for crossed-out or "strikethrough" letters). diff --git a/Documentation/config/receive.txt b/Documentation/config/receive.txt index c77e55b1cd..36a1e6f2d2 100644 --- a/Documentation/config/receive.txt +++ b/Documentation/config/receive.txt @@ -8,7 +8,7 @@ receive.advertisePushOptions:: capability to its clients. False by default. receive.autogc:: - By default, git-receive-pack will run "git-gc --auto" after + By default, git-receive-pack will run "git maintenance run --auto" after receiving data from git-push and updating refs. You can stop it by setting this variable to false. diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt index 67645cae64..e24517c496 100644 --- a/Documentation/date-formats.txt +++ b/Documentation/date-formats.txt @@ -11,7 +11,7 @@ Git internal format:: For example CET (which is 1 hour ahead of UTC) is `+0100`. RFC 2822:: - The standard email format as described by RFC 2822, for example + The standard date format as described by RFC 2822, for example `Thu, 07 Apr 2005 22:13:13 +0200`. ISO 8601:: diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.txt index f643585a34..5edc06c658 100644 --- a/Documentation/fsck-msgids.txt +++ b/Documentation/fsck-msgids.txt @@ -164,6 +164,18 @@ `nullSha1`:: (WARN) Tree contains entries pointing to a null sha1. +`symlinkPointsToGitDir`:: + (WARN) Symbolic link points inside a gitdir. + +`symlinkTargetBlob`:: + (ERROR) A non-blob found instead of a symbolic link's target. + +`symlinkTargetLength`:: + (WARN) Symbolic link target longer than maximum path length. + +`symlinkTargetMissing`:: + (ERROR) Unable to read symbolic link target's blob. + `treeNotSorted`:: (ERROR) A tree is not properly sorted. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index ac61113fcc..65c645d461 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,21 +9,14 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]] -'git config' [<file-option>] [--type=<type>] [--comment=<message>] --add <name> <value> -'git config' [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] --replace-all <name> <value> [<value-pattern>] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>] -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL> -'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>] -'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>] -'git config' [<file-option>] --rename-section <old-name> <new-name> -'git config' [<file-option>] --remove-section <name> -'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list -'git config' [<file-option>] --get-color <name> [<default>] +'git config list' [<file-option>] [<display-option>] [--includes] +'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp=<regexp>] [--value=<value>] [--fixed-value] [--default=<default>] <name> +'git config set' [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value> +'git config unset' [<file-option>] [--all] [--value=<value>] [--fixed-value] <name> <value> +'git config rename-section' [<file-option>] <old-name> <new-name> +'git config remove-section' [<file-option>] <name> +'git config edit' [<file-option>] 'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>] -'git config' [<file-option>] -e | --edit DESCRIPTION ----------- @@ -31,7 +24,7 @@ You can query/set/replace/unset options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped. -Multiple lines can be added to an option by using the `--add` option. +Multiple lines can be added to an option by using the `--append` option. If you want to update or unset an option which can occur on multiple lines, a `value-pattern` (which is an extended regular expression, unless the `--fixed-value` option is given) needs to be given. Only the @@ -74,6 +67,42 @@ On success, the command returns the exit code 0. A list of all available configuration variables can be obtained using the `git help --config` command. +COMMANDS +-------- + +list:: + List all variables set in config file, along with their values. + +get:: + Emits the value of the specified key. If key is present multiple times + in the configuration, emits the last value. If `--all` is specified, + emits all values associated with key. Returns error code 1 if key is + not present. + +set:: + Set value for one or more config options. By default, this command + refuses to write multi-valued config options. Passing `--all` will + replace all multi-valued config options with the new value, whereas + `--value=` will replace all config options whose values match the given + pattern. + +unset:: + Unset value for one or more config options. By default, this command + refuses to unset multi-valued keys. Passing `--all` will unset all + multi-valued config options, whereas `--value` will unset all config + options whose values match the given pattern. + +rename-section:: + Rename the given section to a new name. + +remove-section:: + Remove the given section from the configuration file. + +edit:: + Opens an editor to modify the specified config file; either + `--system`, `--global`, `--local` (default), `--worktree`, or + `--file <config-file>`. + [[OPTIONS]] OPTIONS ------- @@ -82,10 +111,9 @@ OPTIONS Default behavior is to replace at most one line. This replaces all lines matching the key (and optionally the `value-pattern`). ---add:: +--append:: Adds a new line to the option without altering any existing - values. This is the same as providing '^$' as the `value-pattern` - in `--replace-all`. + values. This is the same as providing '--value=^$' in `set`. --comment <message>:: Append a comment at the end of new or modified lines. @@ -99,22 +127,16 @@ OPTIONS not contain linefeed characters (no multi-line comments are permitted). ---get:: - Get the value for a given key (optionally filtered by a regex - matching the value). Returns error code 1 if the key was not - found and the last value if multiple key values were found. +--all:: + With `get`, return all values for a multi-valued key. ---get-all:: - Like get, but returns all values for a multi-valued key. +---regexp:: + With `get`, interpret the name as a regular expression. Regular + expression matching is currently case-sensitive and done against a + canonicalized version of the key in which section and variable names + are lowercased, but subsection names are not. ---get-regexp:: - Like --get-all, but interprets the name as a regular expression and - writes out the key names. Regular expression matching is currently - case-sensitive and done against a canonicalized version of the key - in which section and variable names are lowercased, but subsection - names are not. - ---get-urlmatch <name> <URL>:: +--url=<URL>:: When given a two-part <name> as <section>.<key>, the value for <section>.<URL>.<key> whose <URL> part matches the best to the given URL is returned (if no such key exists, the value for @@ -178,22 +200,6 @@ See also <<FILES>>. section in linkgit:gitrevisions[7] for a more complete list of ways to spell blob names. ---remove-section:: - Remove the given section from the configuration file. - ---rename-section:: - Rename the given section to a new name. - ---unset:: - Remove the line matching the key from config file. - ---unset-all:: - Remove all lines matching the key from config file. - --l:: ---list:: - List all variables set in config file, along with their values. - --fixed-value:: When used with the `value-pattern` argument, treat `value-pattern` as an exact string instead of a regular expression. This will restrict @@ -248,8 +254,8 @@ Valid `<type>`'s include: contain line breaks. --name-only:: - Output only the names of config variables for `--list` or - `--get-regexp`. + Output only the names of config variables for `list` or + `get`. --show-origin:: Augment the output of all queried config options with the @@ -273,23 +279,6 @@ Valid `<type>`'s include: When the color setting for `name` is undefined, the command uses `color.ui` as fallback. ---get-color <name> [<default>]:: - - Find the color configured for `name` (e.g. `color.diff.new`) and - output it as the ANSI color escape sequence to the standard - output. The optional `default` parameter is used instead, if - there is no color configured for `name`. -+ -`--type=color [--default=<default>]` is preferred over `--get-color` -(but note that `--get-color` will omit the trailing newline printed by -`--type=color`). - --e:: ---edit:: - Opens an editor to modify the specified config file; either - `--system`, `--global`, `--local` (default), `--worktree`, or - `--file <config-file>`. - --[no-]includes:: Respect `include.*` directives in config files when looking up values. Defaults to `off` when a specific file is given (e.g., @@ -297,14 +286,64 @@ Valid `<type>`'s include: config files. --default <value>:: - When using `--get`, and the requested variable is not found, behave as if + When using `get`, and the requested variable is not found, behave as if <value> were the value assigned to that variable. +DEPRECATED MODES +---------------- + +The following modes have been deprecated in favor of subcommands. It is +recommended to migrate to the new syntax. + +'git config <name>':: + Replaced by `git config get <name>`. + +'git config <name> <value> [<value-pattern>]':: + Replaced by `git config set [--value=<pattern>] <name> <value>`. + +-l:: +--list:: + Replaced by `git config list`. + +--get <name> [<value-pattern>]:: + Replaced by `git config get [--value=<pattern>] <name>`. + +--get-all <name> [<value-pattern>]:: + Replaced by `git config get [--value=<pattern>] --all --show-names <name>`. + +--get-regexp <name-regexp>:: + Replaced by `git config get --all --show-names --regexp <name-regexp>`. + +--get-urlmatch <name> <URL>:: + Replaced by `git config get --all --show-names --url=<URL> <name>`. + +--get-color <name> [<default>]:: + Replaced by `git config get --type=color [--default=<default>] <name>`. + +--add <name> <value>:: + Replaced by `git config set --append <name> <value>`. + +--unset <name> [<value-pattern>]:: + Replaced by `git config unset [--value=<pattern>] <name>`. + +--unset-all <name> [<value-pattern>]:: + Replaced by `git config unset [--value=<pattern>] --all <name>`. + +--rename-section <old-name> <new-name>:: + Replaced by `git config rename-section <old-name> <new-name>`. + +--remove-section <name>:: + Replaced by `git config remove-section <name>`. + +-e:: +--edit:: + Replaced by `git config edit`. + CONFIGURATION ------------- `pager.config` is only respected when listing configuration, i.e., when -using `--list` or any of the `--get-*` which may return multiple results. -The default is to use a pager. +using `list` or `get` which may return multiple results. The default is to use +a pager. [[FILES]] FILES @@ -346,8 +385,8 @@ precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used. By default, options are only written to the repository specific -configuration file. Note that this also affects options like `--replace-all` -and `--unset`. *'git config' will only ever change one file at a time*. +configuration file. Note that this also affects options like `set` +and `unset`. *'git config' will only ever change one file at a time*. You can limit which configuration sources are read from or written to by specifying the path of a file with the `--file` option, or by specifying a @@ -482,7 +521,7 @@ Given a .git/config like this: you can set the filemode to true with ------------ -% git config core.filemode true +% git config set core.filemode true ------------ The hypothetical proxy command entries actually have a postfix to discern @@ -490,7 +529,7 @@ what URL they apply to. Here is how to change the entry for kernel.org to "ssh". ------------ -% git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$' +% git config set --value='for kernel.org$' core.gitproxy '"ssh" for kernel.org' ------------ This makes sure that only the key/value pair for kernel.org is replaced. @@ -498,7 +537,7 @@ This makes sure that only the key/value pair for kernel.org is replaced. To delete the entry for renames, do ------------ -% git config --unset diff.renames +% git config unset diff.renames ------------ If you want to delete an entry for a multivar (like core.gitproxy above), @@ -507,51 +546,45 @@ you have to provide a regex matching the value of exactly one line. To query the value for a given key, do ------------ -% git config --get core.filemode ------------- - -or - ------------- -% git config core.filemode +% git config get core.filemode ------------ or, to query a multivar: ------------ -% git config --get core.gitproxy "for kernel.org$" +% git config get --value="for kernel.org$" core.gitproxy ------------ If you want to know all the values for a multivar, do: ------------ -% git config --get-all core.gitproxy +% git config get --all --show-names core.gitproxy ------------ If you like to live dangerously, you can replace *all* core.gitproxy by a new one with ------------ -% git config --replace-all core.gitproxy ssh +% git config set --all core.gitproxy ssh ------------ However, if you really only want to replace the line for the default proxy, i.e. the one without a "for ..." postfix, do something like this: ------------ -% git config core.gitproxy ssh '! for ' +% git config set --value='! for ' core.gitproxy ssh ------------ To actually match only values with an exclamation mark, you have to ------------ -% git config section.key value '[!]' +% git config set --value='[!]' section.key value ------------ To add a new proxy, without altering any of the existing ones, use ------------ -% git config --add core.gitproxy '"proxy-command" for example.com' +% git config set --append core.gitproxy '"proxy-command" for example.com' ------------ An example to use customized color from the configuration in your @@ -559,8 +592,8 @@ script: ------------ #!/bin/sh -WS=$(git config --get-color color.diff.whitespace "blue reverse") -RESET=$(git config --get-color "" "reset") +WS=$(git config get --type=color --default="blue reverse" color.diff.whitespace) +RESET=$(git config get --type=color --default="reset" "") echo "${WS}your whitespace color or blue reverse${RESET}" ------------ @@ -568,11 +601,11 @@ For URLs in `https://weak.example.com`, `http.sslVerify` is set to false, while it is set to `true` for all others: ------------ -% git config --type=bool --get-urlmatch http.sslverify https://good.example.com +% git config get --type=bool --url=https://good.example.com http.sslverify true -% git config --type=bool --get-urlmatch http.sslverify https://weak.example.com +% git config get --type=bool --url=https://weak.example.com http.sslverify false -% git config --get-urlmatch http https://weak.example.com +% git config get --url=https://weak.example.com http http.cookieFile /tmp/cookie.txt http.sslverify false ------------ diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 918a0aa42b..e41493292f 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials SYNOPSIS -------- ------------------ -'git credential' (fill|approve|reject) +'git credential' (fill|approve|reject|capability) ------------------ DESCRIPTION @@ -41,6 +41,9 @@ If the action is `reject`, git-credential will send the description to any configured credential helpers, which may erase any stored credentials matching the description. +If the action is `capability`, git-credential will announce any capabilities +it supports to standard output. + If the action is `approve` or `reject`, no output should be emitted. TYPICAL USE OF GIT CREDENTIAL @@ -111,7 +114,9 @@ attribute per line. Each attribute is specified by a key-value pair, separated by an `=` (equals) sign, followed by a newline. The key may contain any bytes except `=`, newline, or NUL. The value may -contain any bytes except newline or NUL. +contain any bytes except newline or NUL. A line, including the trailing +newline, may not exceed 65535 bytes in order to allow implementations to +parse efficiently. Attributes with keys that end with C-style array brackets `[]` can have multiple values. Each instance of a multi-valued attribute forms an @@ -178,6 +183,61 @@ empty string. Components which are missing from the URL (e.g., there is no username in the example above) will be left unset. +`authtype`:: + This indicates that the authentication scheme in question should be used. + Common values for HTTP and HTTPS include `basic`, `bearer`, and `digest`, + although the latter is insecure and should not be used. If `credential` + is used, this may be set to an arbitrary string suitable for the protocol in + question (usually HTTP). ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`credential`:: + The pre-encoded credential, suitable for the protocol in question (usually + HTTP). If this key is sent, `authtype` is mandatory, and `username` and + `password` are not used. For HTTP, Git concatenates the `authtype` value and + this value with a single space to determine the `Authorization` header. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`ephemeral`:: + This boolean value indicates, if true, that the value in the `credential` + field should not be saved by the credential helper because its usefulness is + limited in time. For example, an HTTP Digest `credential` value is computed + using a nonce and reusing it will not result in successful authentication. + This may also be used for situations with short duration (e.g., 24-hour) + credentials. The default value is false. ++ +The credential helper will still be invoked with `store` or `erase` so that it +can determine whether the operation was successful. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`state[]`:: + This value provides an opaque state that will be passed back to this helper + if it is called again. Each different credential helper may specify this + once. The value should include a prefix unique to the credential helper and + should ignore values that don't match its prefix. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. + +`continue`:: + This is a boolean value, which, if enabled, indicates that this + authentication is a non-final part of a multistage authentication step. This + is common in protocols such as NTLM and Kerberos, where two rounds of client + authentication are required, and setting this flag allows the credential + helper to implement the multistage authentication step. This flag should + only be sent if a further stage is required; that is, if another round of + authentication is expected. ++ +This value should not be sent unless the appropriate capability (see below) is +provided on input. This attribute is 'one-way' from a credential helper to +pass information to Git (or other programs invoking `git credential`). + `wwwauth[]`:: When an HTTP response is received by Git that includes one or more @@ -189,7 +249,45 @@ attribute 'wwwauth[]', where the order of the attributes is the same as they appear in the HTTP response. This attribute is 'one-way' from Git to pass additional information to credential helpers. -Unrecognised attributes are silently discarded. +`capability[]`:: + This signals that Git, or the helper, as appropriate, supports the capability + in question. This can be used to provide better, more specific data as part + of the protocol. A `capability[]` directive must precede any value depending + on it and these directives _should_ be the first item announced in the + protocol. ++ +There are two currently supported capabilities. The first is `authtype`, which +indicates that the `authtype`, `credential`, and `ephemeral` values are +understood. The second is `state`, which indicates that the `state[]` and +`continue` values are understood. ++ +It is not obligatory to use the additional features just because the capability +is supported, but they should not be provided without the capability. + +Unrecognised attributes and capabilities are silently discarded. + +[[CAPA-IOFMT]] +CAPABILITY INPUT/OUTPUT FORMAT +------------------------------ + +For `git credential capability`, the format is slightly different. First, a +`version 0` announcement is made to indicate the current version of the +protocol, and then each capability is announced with a line like `capability +authtype`. Credential helpers may also implement this format, again with the +`capability` argument. Additional lines may be added in the future; callers +should ignore lines which they don't understand. + +Because this is a new part of the credential helper protocol, older versions of +Git, as well as some credential helpers, may not support it. If a non-zero +exit status is received, or if the first line doesn't start with the word +`version` and a space, callers should assume that no capabilities are supported. + +The intention of this format is to differentiate it from the credential output +in an unambiguous way. It is possible to use very simple credential helpers +(e.g., inline shell scripts) which always produce identical output. Using a +distinct format allows users to continue to use this syntax without having to +worry about correctly implementing capability advertisements or accidentally +confusing callers querying for capabilities. GIT --- diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index b2607366b9..3d435157a6 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -303,7 +303,7 @@ and some sanity checks on the numeric values may also be performed. with e.g. bogus timezone values. `rfc2822`:: - This is the standard email format as described by RFC 2822. + This is the standard date format as described by RFC 2822. + An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git parser is accurate, but a little on the lenient side. It is the @@ -630,18 +630,28 @@ in octal. Git only supports the following modes: In both formats `<path>` is the complete path of the file to be added (if not already existing) or modified (if already existing). -A `<path>` string must use UNIX-style directory separators (forward -slash `/`), may contain any byte other than `LF`, and must not -start with double quote (`"`). - -A path can use C-style string quoting; this is accepted in all cases -and mandatory if the filename starts with double quote or contains -`LF`. In C-style quoting, the complete name should be surrounded with -double quotes, and any `LF`, backslash, or double quote characters -must be escaped by preceding them with a backslash (e.g., -`"path/with\n, \\ and \" in it"`). - -The value of `<path>` must be in canonical form. That is it must not: +A `<path>` can be written as unquoted bytes or a C-style quoted string. + +When a `<path>` does not start with a double quote (`"`), it is an +unquoted string and is parsed as literal bytes without any escape +sequences. However, if the filename contains `LF` or starts with double +quote, it cannot be represented as an unquoted string and must be +quoted. Additionally, the source `<path>` in `filecopy` or `filerename` +must be quoted if it contains SP. + +When a `<path>` starts with a double quote (`"`), it is a C-style quoted +string, where the complete filename is enclosed in a pair of double +quotes and escape sequences are used. Certain characters must be escaped +by preceding them with a backslash: `LF` is written as `\n`, backslash +as `\\`, and double quote as `\"`. Some characters may optionally be +written with escape sequences: `\a` for bell, `\b` for backspace, `\f` +for form feed, `\n` for line feed, `\r` for carriage return, `\t` for +horizontal tab, and `\v` for vertical tab. Any byte can be written with +3-digit octal codes (e.g., `\033`). All filenames can be represented as +quoted strings. + +A `<path>` must use UNIX-style directory separators (forward slash `/`) +and its value must be in canonical form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), * end with a directory separator (e.g. `foo/` is invalid), @@ -651,6 +661,7 @@ The value of `<path>` must be in canonical form. That is it must not: The root of the tree can be represented by an empty string as `<path>`. +`<path>` cannot contain NUL, either literally or escaped as `\000`. It is recommended that `<path>` always be encoded using UTF-8. `filedelete` diff --git a/Documentation/git-for-each-repo.txt b/Documentation/git-for-each-repo.txt index 94bd19da26..abe3527aac 100644 --- a/Documentation/git-for-each-repo.txt +++ b/Documentation/git-for-each-repo.txt @@ -42,6 +42,15 @@ These config values are loaded from system, global, and local Git config, as available. If `git for-each-repo` is run in a directory that is not a Git repository, then only the system and global config is used. +--keep-going:: + Continue with the remaining repositories if the command failed + on a repository. The exit code will still indicate that the + overall operation was not successful. ++ +Note that the exact exit code of the failing command is not passed +through as the exit code of the `for-each-repo` command: If the command +failed in any of the specified repositories, the overall exit code will +be 1. SUBPROCESS BEHAVIOR ------------------- diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 728bb3821c..369af2c4a7 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -20,7 +20,7 @@ SYNOPSIS [--in-reply-to=<message-id>] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--always] [--cover-from-description=<mode>] - [--rfc] [--subject-prefix=<subject-prefix>] + [--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>] [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] [--[no-]cover-letter] [--quiet] @@ -238,10 +238,21 @@ the patches (with a value of e.g. "PATCH my-project"). value of the `format.filenameMaxLength` configuration variable, or 64 if unconfigured. ---rfc:: - Prepends "RFC" to the subject prefix (producing "RFC PATCH" by - default). RFC means "Request For Comments"; use this when sending - an experimental patch for discussion rather than application. +--rfc[=<rfc>]:: + Prepends the string _<rfc>_ (defaults to "RFC") to + the subject prefix. As the subject prefix defaults to + "PATCH", you'll get "RFC PATCH" by default. ++ +RFC means "Request For Comments"; use this when sending +an experimental patch for discussion rather than application. +"--rfc=WIP" may also be a useful way to indicate that a patch +is not complete yet ("WIP" stands for "Work In Progress"). ++ +If the convention of the receiving community for a particular extra +string is to have it _after_ the subject prefix, the string _<rfc>_ +can be prefixed with a dash ("`-`") to signal that the the rest of +the _<rfc>_ string should be appended to the subject prefix instead, +e.g., `--rfc='-(WIP)'` results in "PATCH (WIP)". -v <n>:: --reroll-count=<n>:: diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index e8f3ccb433..f5b02ef114 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -114,7 +114,7 @@ of end users. The official repository of the 'git gui' project can be found at: - https://github.com/prati0100/git-gui.git/ + https://github.com/j6t/git-gui GIT --- diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index dd388fa21d..84cb2edf6d 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -72,6 +72,11 @@ OPTIONS As the merge-base is provided directly, <branch1> and <branch2> do not need to specify commits; trees are enough. +-X<option>:: +--strategy-option=<option>:: + Pass the merge strategy-specific option through to the merge strategy. + See linkgit:git-merge[1] for details. + [[OUTPUT]] OUTPUT ------ diff --git a/Documentation/git-replay.txt b/Documentation/git-replay.txt index f6c269c62d..8f3300c683 100644 --- a/Documentation/git-replay.txt +++ b/Documentation/git-replay.txt @@ -46,7 +46,7 @@ the new commits (in other words, this mimics a cherry-pick operation). Range of commits to replay. More than one <revision-range> can be passed, but in `--advance <branch>` mode, they should have a single tip, so that it's clear where <branch> should point - to. See "Specifying Ranges" in linkgit:git-rev-parse and the + to. See "Specifying Ranges" in linkgit:git-rev-parse[1] and the "Commit Limiting" options below. include::rev-list-options.txt[] diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 5fe519c31e..4494729f5e 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e] + [(--trailer <token>[(=|:)<value>])...] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... 'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>] @@ -31,8 +32,8 @@ creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. -If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` -are absent, `-a` is implied. +If `-m <msg>` or `-F <file>` or `--trailer <token>[=<value>]` is given +and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. Otherwise, a tag reference that points directly at the given object (i.e., a lightweight tag) is created. @@ -178,6 +179,17 @@ This option is only applicable when listing tags without annotation lines. Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` is given. +--trailer <token>[(=|:)<value>]:: + Specify a (<token>, <value>) pair that should be applied as a + trailer. (e.g. `git tag --trailer "Custom-Key: value"` + will add a "Custom-Key" trailer to the tag message.) + The `trailer.*` configuration variables + (linkgit:git-interpret-trailers[1]) can be used to define if + a duplicated trailer is omitted, where in the run of trailers + each trailer would appear, and other details. + The trailers can be extracted in `git tag --list`, using + `--format="%(trailers)"` placeholder. + -e:: --edit:: The message taken from file with `-F` and command line with diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 8c47890a6a..7128aed540 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -25,6 +25,7 @@ SYNOPSIS [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] [-z] [--stdin] [--index-version <n>] + [--show-index-version] [--verbose] [--] [<file>...] diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 7ad60bc348..516d1639d9 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -55,6 +55,37 @@ ENVIRONMENT admins may need to configure some transports to allow this variable to be passed. See the discussion in linkgit:git[1]. +`GIT_NO_LAZY_FETCH`:: + When cloning or fetching from a partial repository (i.e., one + itself cloned with `--filter`), the server-side `upload-pack` + may need to fetch extra objects from its upstream in order to + complete the request. By default, `upload-pack` will refuse to + perform such a lazy fetch, because `git fetch` may run arbitrary + commands specified in configuration and hooks of the source + repository (and `upload-pack` tries to be safe to run even in + untrusted `.git` directories). ++ +This is implemented by having `upload-pack` internally set the +`GIT_NO_LAZY_FETCH` variable to `1`. If you want to override it +(because you are fetching from a partial clone, and you are sure +you trust it), you can explicitly set `GIT_NO_LAZY_FETCH` to +`0`. + +SECURITY +-------- + +Most Git commands should not be run in an untrusted `.git` directory +(see the section `SECURITY` in linkgit:git[1]). `upload-pack` tries to +avoid any dangerous configuration options or hooks from the repository +it's serving, making it safe to clone an untrusted directory and run +commands on the resulting clone. + +For an extra level of safety, you may be able to run `upload-pack` as an +alternate user. The details will be platform dependent, but on many +systems you can run: + + git clone --no-local --upload-pack='sudo -u nobody git-upload-pack' ... + SEE ALSO -------- linkgit:gitnamespaces[7] diff --git a/Documentation/git.txt b/Documentation/git.txt index 7a1b112a3e..a31a70acca 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -11,9 +11,10 @@ SYNOPSIS [verse] 'git' [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] - [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare] - [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] - [--config-env=<name>=<envvar>] <command> [<args>] + [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--no-lazy-fetch] + [--no-optional-locks] [--no-advice] [--bare] [--git-dir=<path>] + [--work-tree=<path>] [--namespace=<name>] [--config-env=<name>=<envvar>] + <command> [<args>] DESCRIPTION ----------- @@ -186,6 +187,13 @@ If you just want to run git as if it was started in `<path>` then use This is equivalent to setting the `GIT_NO_LAZY_FETCH` environment variable to `1`. +--no-optional-locks:: + Do not perform optional operations that require locks. This is + equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`. + +--no-advice:: + Disable all advice hints from being printed. + --literal-pathspecs:: Treat pathspecs literally (i.e. no globbing, no pathspec magic). This is equivalent to setting the `GIT_LITERAL_PATHSPECS` environment @@ -207,10 +215,6 @@ If you just want to run git as if it was started in `<path>` then use Add "icase" magic to all pathspec. This is equivalent to setting the `GIT_ICASE_PATHSPECS` environment variable to `1`. ---no-optional-locks:: - Do not perform optional operations that require locks. This is - equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`. - --list-cmds=<group>[,<group>...]:: List commands by group. This is an internal/experimental option and may change or be removed in the future. Supported @@ -1067,6 +1071,37 @@ The index is also capable of storing multiple entries (called "stages") for a given pathname. These stages are used to hold the various unmerged version of a file when a merge is in progress. +SECURITY +-------- + +Some configuration options and hook files may cause Git to run arbitrary +shell commands. Because configuration and hooks are not copied using +`git clone`, it is generally safe to clone remote repositories with +untrusted content, inspect them with `git log`, and so on. + +However, it is not safe to run Git commands in a `.git` directory (or +the working tree that surrounds it) when that `.git` directory itself +comes from an untrusted source. The commands in its config and hooks +are executed in the usual way. + +By default, Git will refuse to run when the repository is owned by +someone other than the user running the command. See the entry for +`safe.directory` in linkgit:git-config[1]. While this can help protect +you in a multi-user environment, note that you can also acquire +untrusted repositories that are owned by you (for example, if you +extract a zip file or tarball from an untrusted source). In such cases, +you'd need to "sanitize" the untrusted repository first. + +If you have an untrusted `.git` directory, you should first clone it +with `git clone --no-local` to obtain a clean copy. Git does restrict +the set of options and hooks that will be run by `upload-pack`, which +handles the server side of a clone or fetch, but beware that the +surface area for attack against `upload-pack` is large, so this does +carry some risk. The safest thing is to serve the repository as an +unprivileged user (either via linkgit:git-daemon[1], ssh, or using +other tools to change user ids). See the discussion in the `SECURITY` +section of linkgit:git-upload-pack[1]. + FURTHER DOCUMENTATION --------------------- diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index ee9b92c90d..06e997131b 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -486,7 +486,7 @@ reference-transaction This hook is invoked by any Git command that performs reference updates. It executes whenever a reference transaction is prepared, committed or aborted and may thus get called multiple times. The hook -does not cover symbolic references (but that may change in the future). +also supports symbolic reference updates. The hook takes exactly one argument, which is the current state the given reference transaction is in: @@ -503,16 +503,20 @@ given reference transaction is in: For each reference update that was added to the transaction, the hook receives on standard input a line of the format: - <old-oid> SP <new-oid> SP <ref-name> LF + <old-value> SP <new-value> SP <ref-name> LF -where `<old-oid>` is the old object name passed into the reference -transaction, `<new-oid>` is the new object name to be stored in the +where `<old-value>` is the old object name passed into the reference +transaction, `<new-value>` is the new object name to be stored in the ref and `<ref-name>` is the full name of the ref. When force updating the reference regardless of its current value or when the reference is -to be created anew, `<old-oid>` is the all-zeroes object name. To +to be created anew, `<old-value>` is the all-zeroes object name. To distinguish these cases, you can inspect the current value of `<ref-name>` via `git rev-parse`. +For symbolic reference updates the `<old_value>` and `<new-value>` +fields could denote references instead of objects. A reference will be +denoted with a 'ref:' prefix, like `ref:<ref-target>`. + The exit status of the hook is ignored for any state except for the "prepared" state. In the "prepared" state, a non-zero exit status will cause the transaction to be aborted. The hook will not be called with diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index d71b199955..1272809e13 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -576,7 +576,8 @@ The most notable example is `HEAD`. [[def_refspec]]refspec:: A "refspec" is used by <<def_fetch,fetch>> and <<def_push,push>> to describe the mapping between remote - <<def_ref,ref>> and local ref. + <<def_ref,ref>> and local ref. See linkgit:git-fetch[1] or + linkgit:git-push[1] for details. [[def_remote]]remote repository:: A <<def_repository,repository>> which is used to track the same |