diff options
Diffstat (limited to 'Documentation')
30 files changed, 608 insertions, 126 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 9fca21cc5f..1d95a142b2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -204,10 +204,19 @@ For C programs: by e.g. "echo DEVELOPER=1 >>config.mak". - We try to support a wide range of C compilers to compile Git with, - including old ones. You should not use features from newer C + including old ones. As of Git v2.35.0 Git requires C99 (we check + "__STDC_VERSION__"). You should not use features from a newer C standard, even if your compiler groks them. - There are a few exceptions to this guideline: + New C99 features have been phased in gradually, if something's new + in C99 but not used yet don't assume that it's safe to use, some + compilers we target have only partial support for it. These are + considered safe to use: + + . since around 2007 with 2b6854c863a, we have been using + initializer elements which are not computable at load time. E.g.: + + const char *args[] = {"constant", variable, NULL}; . since early 2012 with e1327023ea, we have been using an enum definition whose last element is followed by a comma. This, like @@ -223,18 +232,24 @@ For C programs: . since early 2021 with 765dc168882, we have been using variadic macros, mostly for printf-like trace and debug macros. - These used to be forbidden, but we have not heard any breakage - report, and they are assumed to be safe. + . since late 2021 with 44ba10d6, we have had variables declared in + the for loop "for (int i = 0; i < 10; i++)". + + New C99 features that we cannot use yet: + + . %z and %zu as a printf() argument for a size_t (the %z being for + the POSIX-specific ssize_t). Instead you should use + printf("%"PRIuMAX, (uintmax_t)v). These days the MSVC version we + rely on supports %z, but the C library used by MinGW does not. + + . Shorthand like ".a.b = *c" in struct initializations is known to + trip up an older IBM XLC version, use ".a = { .b = *c }" instead. + See the 33665d98 (reftable: make assignments portable to AIX xlc + v12.01, 2022-03-28). - Variables have to be declared at the beginning of the block, before the first statement (i.e. -Wdeclaration-after-statement). - - Declaring a variable in the for loop "for (int i = 0; i < 10; i++)" - is still not allowed in this codebase. We are in the process of - allowing it by waiting to see that 44ba10d6 (revision: use C99 - declaration of variable in for() loop, 2021-11-14) does not get - complaints. Let's revisit this around November 2022. - - NULL pointers shall be written as NULL, not as 0. - When declaring pointers, the star sides with the variable diff --git a/Documentation/Makefile b/Documentation/Makefile index 849af6da30..d47acb2e25 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -21,6 +21,7 @@ MAN1_TXT += $(filter-out \ MAN1_TXT += git.txt MAN1_TXT += gitk.txt MAN1_TXT += gitweb.txt +MAN1_TXT += scalar.txt # man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt @@ -102,6 +103,7 @@ SP_ARTICLES += howto/coordinate-embargoed-releases API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) +TECH_DOCS += ReviewingGuidelines TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches @@ -116,6 +118,7 @@ TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable +TECH_DOCS += technical/scalar TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow TECH_DOCS += technical/trivial-merge diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 1da15d9ad4..1a4be8ee0a 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1160,7 +1160,7 @@ all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]", and your range-diff will be prefaced with "Range-diff against v1". -Afer you run this command, `format-patch` will output the patches to the `psuh/` +After you run this command, `format-patch` will output the patches to the `psuh/` directory, alongside the v1 patches. Using a single directory makes it easy to refer to the old v1 patches while proofreading the v2 patches, but you will need to be careful to send out only the v2 patches. We will use a pattern like diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index 8d9e85566e..eee513e86f 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -534,7 +534,7 @@ the arguments to `traverse_commit_list()`. - `void *show_data`: A context buffer which is passed in turn to `show_commit` and `show_object`. -In addition, `traverse_commit_list_filtered()` has an additional paramter: +In addition, `traverse_commit_list_filtered()` has an additional parameter: - `struct oidset *omitted`: A linked-list of object IDs which the provided filter caused to be omitted. diff --git a/Documentation/RelNotes/2.30.6.txt b/Documentation/RelNotes/2.30.6.txt new file mode 100644 index 0000000000..d649071b79 --- /dev/null +++ b/Documentation/RelNotes/2.30.6.txt @@ -0,0 +1,60 @@ +Git v2.30.6 Release Notes +========================= + +This release addresses the security issues CVE-2022-39253 and +CVE-2022-39260. + +Fixes since v2.30.5 +------------------- + + * CVE-2022-39253: + When relying on the `--local` clone optimization, Git dereferences + symbolic links in the source repository before creating hardlinks + (or copies) of the dereferenced link in the destination repository. + This can lead to surprising behavior where arbitrary files are + present in a repository's `$GIT_DIR` when cloning from a malicious + repository. + + Git will no longer dereference symbolic links via the `--local` + clone mechanism, and will instead refuse to clone repositories that + have symbolic links present in the `$GIT_DIR/objects` directory. + + Additionally, the value of `protocol.file.allow` is changed to be + "user" by default. + + * CVE-2022-39260: + An overly-long command string given to `git shell` can result in + overflow in `split_cmdline()`, leading to arbitrary heap writes and + remote code execution when `git shell` is exposed and the directory + `$HOME/git-shell-commands` exists. + + `git shell` is taught to refuse interactive commands that are + longer than 4MiB in size. `split_cmdline()` is hardened to reject + inputs larger than 2GiB. + +Credit for finding CVE-2022-39253 goes to Cory Snider of Mirantis. The +fix was authored by Taylor Blau, with help from Johannes Schindelin. + +Credit for finding CVE-2022-39260 goes to Kevin Backhouse of GitHub. +The fix was authored by Kevin Backhouse, Jeff King, and Taylor Blau. + + +Jeff King (2): + shell: add basic tests + shell: limit size of interactive commands + +Kevin Backhouse (1): + alias.c: reject too-long cmdline strings in split_cmdline() + +Taylor Blau (11): + builtin/clone.c: disallow `--local` clones with symlinks + t/lib-submodule-update.sh: allow local submodules + t/t1NNN: allow local submodules + t/2NNNN: allow local submodules + t/t3NNN: allow local submodules + t/t4NNN: allow local submodules + t/t5NNN: allow local submodules + t/t6NNN: allow local submodules + t/t7NNN: allow local submodules + t/t9NNN: allow local submodules + transport: make `protocol.file.allow` be "user" by default diff --git a/Documentation/RelNotes/2.31.5.txt b/Documentation/RelNotes/2.31.5.txt new file mode 100644 index 0000000000..0d87e6e03f --- /dev/null +++ b/Documentation/RelNotes/2.31.5.txt @@ -0,0 +1,5 @@ +Git v2.31.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.32.4.txt b/Documentation/RelNotes/2.32.4.txt new file mode 100644 index 0000000000..76c67b209e --- /dev/null +++ b/Documentation/RelNotes/2.32.4.txt @@ -0,0 +1,5 @@ +Git v2.32.4 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.33.5.txt b/Documentation/RelNotes/2.33.5.txt new file mode 100644 index 0000000000..a63652602b --- /dev/null +++ b/Documentation/RelNotes/2.33.5.txt @@ -0,0 +1,5 @@ +Git v2.33.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.34.5.txt b/Documentation/RelNotes/2.34.5.txt new file mode 100644 index 0000000000..0e8999204d --- /dev/null +++ b/Documentation/RelNotes/2.34.5.txt @@ -0,0 +1,5 @@ +Git v2.34.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.35.5.txt b/Documentation/RelNotes/2.35.5.txt new file mode 100644 index 0000000000..e19cc48b33 --- /dev/null +++ b/Documentation/RelNotes/2.35.5.txt @@ -0,0 +1,5 @@ +Git v2.35.5 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.36.3.txt b/Documentation/RelNotes/2.36.3.txt new file mode 100644 index 0000000000..56db77b5bd --- /dev/null +++ b/Documentation/RelNotes/2.36.3.txt @@ -0,0 +1,5 @@ +Git v2.36.3 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.37.4.txt b/Documentation/RelNotes/2.37.4.txt index 732176376f..e42a5c1620 100644 --- a/Documentation/RelNotes/2.37.4.txt +++ b/Documentation/RelNotes/2.37.4.txt @@ -2,11 +2,45 @@ Git 2.37.4 Release Notes ======================== This primarily is to backport various fixes accumulated on the 'master' -front since 2.37.3. +front since 2.37.3, and also includes the same security fixes as in +v2.30.6. Fixes since v2.37.3 ------------------- + * CVE-2022-39253: + When relying on the `--local` clone optimization, Git dereferences + symbolic links in the source repository before creating hardlinks + (or copies) of the dereferenced link in the destination repository. + This can lead to surprising behavior where arbitrary files are + present in a repository's `$GIT_DIR` when cloning from a malicious + repository. + + Git will no longer dereference symbolic links via the `--local` + clone mechanism, and will instead refuse to clone repositories that + have symbolic links present in the `$GIT_DIR/objects` directory. + + Additionally, the value of `protocol.file.allow` is changed to be + "user" by default. + + Credit for finding CVE-2022-39253 goes to Cory Snider of Mirantis. + The fix was authored by Taylor Blau, with help from Johannes + Schindelin. + + * CVE-2022-39260: + An overly-long command string given to `git shell` can result in + overflow in `split_cmdline()`, leading to arbitrary heap writes and + remote code execution when `git shell` is exposed and the directory + `$HOME/git-shell-commands` exists. + + `git shell` is taught to refuse interactive commands that are + longer than 4MiB in size. `split_cmdline()` is hardened to reject + inputs larger than 2GiB. + + Credit for finding CVE-2022-39260 goes to Kevin Backhouse of + GitHub. The fix was authored by Kevin Backhouse, Jeff King, and + Taylor Blau. + * An earlier optimization discarded a tree-object buffer that is still in use, which has been corrected. diff --git a/Documentation/RelNotes/2.38.0.txt b/Documentation/RelNotes/2.38.0.txt index 01617baa98..870581fc57 100644 --- a/Documentation/RelNotes/2.38.0.txt +++ b/Documentation/RelNotes/2.38.0.txt @@ -6,7 +6,7 @@ UI, Workflows & Features * "git remote show [-n] frotz" now pays attention to negative pathspec. - * "git push" sometimes perform poorly when reachability bitmaps are + * "git push" sometimes performs poorly when reachability bitmaps are used, even in a repository where other operations are helped by bitmaps. The push.useBitmaps configuration variable is introduced to allow disabling use of reachability bitmaps only for "git push". @@ -27,7 +27,7 @@ UI, Workflows & Features what locale they are in by sending Accept-Language HTTP header, but this was done only for some requests but not others. - * Introduce a discovery.barerepository configuration variable that + * Introduce a safe.barerepository configuration variable that allows users to forbid discovery of bare repositories. * Various messages that come from the pack-bitmap codepaths have been @@ -79,12 +79,15 @@ UI, Workflows & Features * "git format-patch --from=<ident>" can be told to add an in-body "From:" line even for commits that are authored by the given - <ident> with "--force-in-body-from"option. + <ident> with "--force-in-body-from" option. * The built-in fsmonitor refuses to work on a network mounted repositories; a configuration knob for users to override this has been introduced. + * The "scalar" addition from Microsoft is now part of the core Git + installation. + Performance, Internal Implementation, Development Support etc. @@ -127,7 +130,7 @@ Performance, Internal Implementation, Development Support etc. * The way "git multi-pack" uses parse-options API has been improved. - * A coccinelle rule (in contrib/) to encourage use of COPY_ARRAY + * A Coccinelle rule (in contrib/) to encourage use of COPY_ARRAY macro has been improved. * API tweak to make it easier to run fuzz testing on commit-graph parser. @@ -172,6 +175,12 @@ Performance, Internal Implementation, Development Support etc. * Share the text used to explain configuration variables used by "git <subcmd>" in "git help <subcmd>" with the text from "git help config". + * "git mv A B" in a sparsely populated working tree can be asked to + move a path from a directory that is "in cone" to another directory + that is "out of cone". Handling of such a case has been improved. + + * The chainlint script for our tests has been revamped. + Fixes since v2.37 ----------------- @@ -297,7 +306,7 @@ Fixes since v2.37 * "git fsck" reads mode from tree objects but canonicalizes the mode before passing it to the logic to check object sanity, which has hid broken tree objects from the checking logic. This has been - corrected, but to help exiting projects with broken tree objects + corrected, but to help existing projects with broken tree objects that they cannot fix retroactively, the severity of anomalies this code detects has been demoted to "info" for now. @@ -306,12 +315,10 @@ Fixes since v2.37 * An earlier optimization discarded a tree-object buffer that is still in use, which has been corrected. - (merge 1490d7d82d jk/is-promisor-object-keep-tree-in-use later to maint). * Fix deadlocks between main Git process and subprocess spawned via the pipe_command() API, that can kill "git add -p" that was reimplemented in C recently. - (merge 716c1f649e jk/pipe-command-nonblock later to maint). * The sequencer machinery translated messages left in the reflog by mistake, which has been corrected. @@ -319,20 +326,16 @@ Fixes since v2.37 * xcalloc(), imitating calloc(), takes "number of elements of the array", and "size of a single element", in this order. A call that does not follow this ordering has been corrected. - (merge c4bbd9bb8f sg/xcalloc-cocci-fix later to maint). * The preload-index codepath made copies of pathspec to give to multiple threads, which were left leaked. - (merge 23578904da ad/preload-plug-memleak later to maint). * Update the version of Ubuntu used for GitHub Actions CI from 18.04 to 22.04. - (merge ef46584831 ds/github-actions-use-newer-ubuntu later to maint). * The auto-stashed local changes created by "git merge --autostash" was mixed into a conflicted state left in the working tree, which has been corrected. - (merge d3a9295ada en/merge-unstash-only-on-clean-merge later to maint). * Multi-pack index got corrupted when preferred pack changed from one pack to another in a certain way, which has been corrected. @@ -387,6 +390,14 @@ Fixes since v2.37 been corrected. (merge 49ca2fba39 jk/proto-v2-ref-prefix-fix later to maint). + * A result from opendir() was leaking in the commit-graph expiration + codepath, which has been plugged. + (merge 12f1ae5324 ml/commit-graph-expire-dir-leak-fix later to maint). + + * Just like we have coding guidelines, we now have guidelines for + reviewers. + (merge e01b851923 vd/doc-reviewing-guidelines later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 77b9e85c0f vd/fix-perf-tests later to maint). (merge 0682bc43f5 jk/test-crontab-fixes later to maint). diff --git a/Documentation/RelNotes/2.38.1.txt b/Documentation/RelNotes/2.38.1.txt new file mode 100644 index 0000000000..b2b5854aac --- /dev/null +++ b/Documentation/RelNotes/2.38.1.txt @@ -0,0 +1,5 @@ +Git v2.38.1 Release Notes +========================= + +This release merges the security fix that appears in v2.30.6; see +the release notes for that version for details. diff --git a/Documentation/RelNotes/2.38.2.txt b/Documentation/RelNotes/2.38.2.txt new file mode 100644 index 0000000000..00d4b77655 --- /dev/null +++ b/Documentation/RelNotes/2.38.2.txt @@ -0,0 +1,47 @@ +Git 2.38.2 Release Notes +======================== + +This is to backport various fixes accumulated during the development +towards Git 2.39, the next feature release. + + +Fixes since v2.38.1 +------------------- + + * Update CodingGuidelines to clarify what features to use and avoid + in C99. + + * The codepath that reads from the index v4 had unaligned memory + accesses, which has been corrected. + + * "git remote rename" failed to rename a remote without fetch + refspec, which has been corrected. + + * "git clone" did not like to see the "--bare" and the "--origin" + options used together without a good reason. + + * Fix messages incorrectly marked for translation. + + * "git fsck" failed to release contents of tree objects already used + from the memory, which has been fixed. + + * "git rebase -i" can mistakenly attempt to apply a fixup to a commit + itself, which has been corrected. + + * In read-only repositories, "git merge-tree" tried to come up with a + merge result tree object, which it failed (which is not wrong) and + led to a segfault (which is bad), which has been corrected. + + * Force C locale while running tests around httpd to make sure we can + find expected error messages in the log. + + * Fix a logic in "mailinfo -b" that miscomputed the length of a + substring, which lead to an out-of-bounds access. + + * The codepath to sign learned to report errors when it fails to read + from "ssh-keygen". + + * "GIT_EDITOR=: git branch --edit-description" resulted in failure, + which has been corrected. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt new file mode 100644 index 0000000000..0e323d5477 --- /dev/null +++ b/Documentation/ReviewingGuidelines.txt @@ -0,0 +1,162 @@ +Reviewing Patches in the Git Project +==================================== + +Introduction +------------ +The Git development community is a widely distributed, diverse, ever-changing +group of individuals. Asynchronous communication via the Git mailing list poses +unique challenges when reviewing or discussing patches. This document contains +some guiding principles and helpful tools you can use to make your reviews both +more efficient for yourself and more effective for other contributors. + +Note that none of the recommendations here are binding or in any way a +requirement of participation in the Git community. They are provided as a +resource to supplement your skills as a contributor. + +Principles +---------- + +Selecting patch(es) to review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you are looking for a patch series in need of review, start by checking +latest "What's cooking in git.git" email +(https://lore.kernel.org/git/xmqqilm1yp3m.fsf@gitster.g/[example]). The "What's +cooking" emails & replies can be found using the query `s:"What's cooking"` on +the https://lore.kernel.org/git/[`lore.kernel.org` mailing list archive]; +alternatively, you can find the contents of the "What's cooking" email tracked +in `whats-cooking.txt` on the `todo` branch of Git. Topics tagged with "Needs +review" and those in the "[New Topics]" section are typically those that would +benefit the most from additional review. + +Patches can also be searched manually in the mailing list archive using a query +like `s:"PATCH" -s:"Re:"`. You can browse these results for topics relevant to +your expertise or interest. + +If you've already contributed to Git, you may also be CC'd in another +contributor's patch series. These are topics where the author feels that your +attention is warranted. This may be because their patch changes something you +wrote previously (making you a good judge of whether the new approach does or +doesn't work), or because you have the expertise to provide an exceptionally +helpful review. There is no requirement to review these patches but, in the +spirit of open source collaboration, you should strongly consider doing so. + +Reviewing patches +~~~~~~~~~~~~~~~~~ +While every contributor takes their own approach to reviewing patches, here are +some general pieces of advice to make your reviews as clear and helpful as +possible. The advice is broken into two rough categories: high-level reviewing +guidance, and concrete tips for interacting with patches on the mailing list. + +==== High-level guidance +- Remember to review the content of commit messages for correctness and clarity, + in addition to the code change in the patch's diff. The commit message of a + patch should accurately and fully explain the code change being made in the + diff. + +- Reviewing test coverage is an important - but easy to overlook - component of + reviews. A patch's changes may be covered by existing tests, or new tests may + be introduced to exercise new behavior. Checking out a patch or series locally + allows you to manually mutate lines of new & existing tests to verify expected + pass/fail behavior. You can use this information to verify proper coverage or + to suggest additional tests the author could add. + +- When providing a recommendation, be as clear as possible about whether you + consider it "blocking" (the code would be broken or otherwise made worse if an + issue isn't fixed) or "non-blocking" (the patch could be made better by taking + the recommendation, but acceptance of the series does not require it). + Non-blocking recommendations can be particularly ambiguous when they are + related to - but outside the scope of - a series ("nice-to-have"s), or when + they represent only stylistic differences between the author and reviewer. + +- When commenting on an issue, try to include suggestions for how the author + could fix it. This not only helps the author to understand and fix the issue, + it also deepens and improves your understanding of the topic. + +- Reviews do not need to exclusively point out problems. Feel free to "think out + loud" in your review: describe how you read & understood a complex section of + a patch, ask a question about something that confused you, point out something + you found exceptionally well-written, etc. In particular, uplifting feedback + goes a long way towards encouraging contributors to participate more actively + in the Git community. + +==== Performing your review +- Provide your review comments per-patch in a plaintext "Reply-All" email to the + relevant patch. Comments should be made inline, immediately below the relevant + section(s). + +- You may find that the limited context provided in the patch diff is sometimes + insufficient for a thorough review. In such cases, you can review patches in + your local tree by either applying patches with linkgit:git-am[1] or checking + out the associated branch from https://github.com/gitster/git once the series + is tracked there. + +- Large, complicated patch diffs are sometimes unavoidable, such as when they + refactor existing code. If you find such a patch difficult to parse, try + reviewing the diff produced with the `--color-moved` and/or + `--ignore-space-change` options. + +- If a patch is long, you are encouraged to delete parts of it that are + unrelated to your review from the email reply. Make sure to leave enough + context for readers to understand your comments! + +- If you cannot complete a full review of a series all at once, consider letting + the author know (on- or off-list) if/when you plan to review the rest of the + series. + +Completing a review +~~~~~~~~~~~~~~~~~~~ +Once each patch of a series is reviewed, the author (and/or other contributors) +may discuss the review(s). This may result in no changes being applied, or the +author will send a new version of their patch(es). + +After a series is rerolled in response to your or others' review, make sure to +re-review the updates. If you are happy with the state of the patch series, +explicitly indicate your approval (typically with a reply to the latest +version's cover letter). Optionally, you can let the author know that they can +add a "Reviewed-by: <you>" trailer if they resubmit the reviewed patch verbatim +in a later iteration of the series. + +Finally, subsequent "What's cooking" emails may explicitly ask whether a +reviewed topic is ready for merging to the `next` branch (typically phrased +"Will merge to \'next\'?"). You can help the maintainer and author by responding +with a short description of the state of your (and others', if applicable) +review, including the links to the relevant thread(s). + +Terminology +----------- +nit: :: + Denotes a small issue that should be fixed, such as a typographical error + or mis-alignment of conditions in an `if()` statement. + +aside: :: +optional: :: +non-blocking: :: + Indicates to the reader that the following comment should not block the + acceptance of the patch or series. These are typically recommendations + related to code organization & style, or musings about topics related to + the patch in question, but beyond its scope. + +s/<before>/<after>/:: + Shorthand for "you wrote <before>, but I think you meant <after>," usually + for misspellings or other typographical errors. The syntax is a reference + to "substitute" command commonly found in Unix tools such as `ed`, `sed`, + `vim`, and `perl`. + +cover letter:: + The "Patch 0" of a multi-patch series. This email describes the + high-level intent and structure of the patch series to readers on the + Git mailing list. It is also where the changelog notes and range-diff of + subsequent versions are provided by the author. ++ +On single-patch submissions, cover letter content is typically not sent as a +separate email. Instead, it is inserted between the end of the patch's commit +message (after the `---`) and the beginning of the diff. + +#leftoverbits:: + Used by either an author or a reviewer to describe features or suggested + changes that are out-of-scope of a given patch or series, but are relevant + to the topic for the sake of discussion. + +See Also +-------- +link:MyFirstContribution.html[MyFirstContribution] diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index af5da45d28..755a110bc4 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -10,7 +10,7 @@ sub format_one { $state = 0; open I, '<', "$name.txt" or die "No such file $name.txt"; while (<I>) { - if (/^git[a-z0-9-]*\(([0-9])\)$/) { + if (/^(?:git|scalar)[a-z0-9-]*\(([0-9])\)$/) { $mansection = $1; next; } diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt index 90b3809700..e779a122d8 100644 --- a/Documentation/config/mergetool.txt +++ b/Documentation/config/mergetool.txt @@ -59,7 +59,7 @@ mergetool.hideResolved:: possible and write the 'MERGED' file containing conflict markers around any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally represent the versions of the file from before Git's conflict - resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwriten so + resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so that only the unresolved conflicts are presented to the merge tool. Can be configured per-tool via the `mergetool.<tool>.hideResolved` configuration variable. Defaults to `false`. diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index 5760381851..a9bf187a93 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -1,10 +1,10 @@ protocol.allow:: If set, provide a user defined default policy for all protocols which don't explicitly have a policy (`protocol.<name>.allow`). By default, - if unset, known-safe protocols (http, https, git, ssh, file) have a + if unset, known-safe protocols (http, https, git, ssh) have a default policy of `always`, known-dangerous protocols (ext) have a - default policy of `never`, and all other protocols have a default - policy of `user`. Supported policies: + default policy of `never`, and all other protocols (including file) + have a default policy of `user`. Supported policies: + -- diff --git a/Documentation/git.txt b/Documentation/git.txt index 0ef7f5e4ec..1d33e083ab 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -344,7 +344,7 @@ Repository, command and file interfaces This documentation discusses repository and command interfaces which users are expected to interact with directly. See `--user-formats` in -linkgit:git-help[1] for more details on the critera. +linkgit:git-help[1] for more details on the criteria. include::cmds-userinterfaces.txt[] @@ -458,7 +458,12 @@ Please see linkgit:gitglossary[7]. Environment Variables --------------------- -Various Git commands use the following environment variables: +Various Git commands pay attention to environment variables and change +their behavior. The environment variables marked as "Boolean" take +their values the same way as Boolean valued configuration variables, e.g. +"true", "yes", "on" and positive numbers are taken as "yes". + +Here are the variables: The Git Repository ~~~~~~~~~~~~~~~~~~ @@ -467,13 +472,13 @@ is worth noting that they may be used/overridden by SCMS sitting above Git so take care if using a foreign front-end. `GIT_INDEX_FILE`:: - This environment allows the specification of an alternate + This environment variable specifies an alternate index file. If not specified, the default of `$GIT_DIR/index` is used. `GIT_INDEX_VERSION`:: - This environment variable allows the specification of an index - version for new repositories. It won't affect existing index + This environment variable specifies what index version is used + when writing the index file out. It won't affect existing index files. By default index file version 2 or 3 is used. See linkgit:git-update-index[1] for more information. @@ -530,7 +535,7 @@ double-quotes and respecting backslash escapes. E.g., the value When run in a directory that does not have ".git" repository directory, Git tries to find such a directory in the parent directories to find the top of the working tree, but by default it - does not cross filesystem boundaries. This environment variable + does not cross filesystem boundaries. This Boolean environment variable can be set to true to tell Git not to stop at filesystem boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect an explicit repository directory set via `GIT_DIR` or on the @@ -682,6 +687,11 @@ for further details. plink or tortoiseplink. This variable overrides the config setting `ssh.variant` that serves the same purpose. +`GIT_SSL_NO_VERIFY`:: + Setting and exporting this environment variable to any value + tells Git not to verify the SSL certificate when fetching or + pushing over HTTPS. + `GIT_ASKPASS`:: If this environment variable is set, then Git commands which need to acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) @@ -690,7 +700,7 @@ for further details. option in linkgit:git-config[1]. `GIT_TERMINAL_PROMPT`:: - If this environment variable is set to `0`, git will not prompt + If this Boolean environment variable is set to false, git will not prompt on the terminal (e.g., when asking for HTTP authentication). `GIT_CONFIG_GLOBAL`:: @@ -705,13 +715,14 @@ for further details. `GIT_CONFIG_NOSYSTEM`:: Whether to skip reading settings from the system-wide - `$(prefix)/etc/gitconfig` file. This environment variable can + `$(prefix)/etc/gitconfig` file. This Boolean environment variable can be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a predictable environment for a picky script, or you can set it - temporarily to avoid using a buggy `/etc/gitconfig` file while + to true to temporarily avoid using a buggy `/etc/gitconfig` file while waiting for someone with sufficient permissions to fix it. `GIT_FLUSH`:: +// NEEDSWORK: make it into a usual Boolean environment variable If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', 'git check-attr' and 'git check-ignore' will @@ -852,11 +863,11 @@ for full details. `GIT_TRACE_REDACT`:: By default, when tracing is activated, Git redacts the values of cookies, the "Authorization:" header, the "Proxy-Authorization:" - header and packfile URIs. Set this variable to `0` to prevent this + header and packfile URIs. Set this Boolean environment variable to false to prevent this redaction. `GIT_LITERAL_PATHSPECS`:: - Setting this variable to `1` will cause Git to treat all + Setting this Boolean environment variable to true will cause Git to treat all pathspecs literally, rather than as glob patterns. For example, running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search for commits that touch the path `*.c`, not any paths that the @@ -865,15 +876,15 @@ for full details. `git ls-tree`, `--raw` diff output, etc). `GIT_GLOB_PATHSPECS`:: - Setting this variable to `1` will cause Git to treat all + Setting this Boolean environment variable to true will cause Git to treat all pathspecs as glob patterns (aka "glob" magic). `GIT_NOGLOB_PATHSPECS`:: - Setting this variable to `1` will cause Git to treat all + Setting this Boolean environment variable to true will cause Git to treat all pathspecs as literal (aka "literal" magic). `GIT_ICASE_PATHSPECS`:: - Setting this variable to `1` will cause Git to treat all + Setting this Boolean environment variable to true will cause Git to treat all pathspecs as case-insensitive. `GIT_REFLOG_ACTION`:: @@ -887,7 +898,7 @@ for full details. end user, to be recorded in the body of the reflog. `GIT_REF_PARANOIA`:: - If set to `0`, ignore broken or badly named refs when iterating + If this Boolean environment variable is set to false, ignore broken or badly named refs when iterating over lists of refs. Normally Git will try to include any such refs, which may cause some operations to fail. This is usually preferable, as potentially destructive operations (e.g., @@ -906,7 +917,7 @@ for full details. `protocol.allow` in linkgit:git-config[1] for more details. `GIT_PROTOCOL_FROM_USER`:: - Set to 0 to prevent protocols used by fetch/push/clone which are + Set this Boolean environment variable to false to prevent protocols used by fetch/push/clone which are configured to the `user` state. This is useful to restrict recursive submodule initialization from an untrusted repository or for programs which feed potentially-untrusted URLS to git commands. See @@ -934,7 +945,7 @@ only affects clones and fetches; it is not yet used for pushes (but may be in the future). `GIT_OPTIONAL_LOCKS`:: - If set to `0`, Git will complete any requested operation without + If this Boolean environment variable is set to false, Git will complete any requested operation without performing any optional sub-operations that require taking a lock. For example, this will prevent `git status` from refreshing the index as a side effect. This is useful for processes running in diff --git a/Documentation/gitprotocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt index c6dcc7d565..0fb5ea0c1c 100644 --- a/Documentation/gitprotocol-capabilities.txt +++ b/Documentation/gitprotocol-capabilities.txt @@ -388,8 +388,8 @@ the server as well. Session IDs should be unique to a given process. They must fit within a packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see -link:api-trace2.html[api-trace2] for details), but this may change and users of -the session ID should not rely on this fact. +link:technical/api-trace2.html[api-trace2] for details), but this may change +and users of the session ID should not rely on this fact. GIT --- diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt index c9c0f9160b..59bf41cefb 100644 --- a/Documentation/gitprotocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -544,8 +544,8 @@ the server as well. Session IDs should be unique to a given process. They must fit within a packet-line, and must not contain non-printable or whitespace characters. The current implementation uses trace2 session IDs (see -link:api-trace2.html[api-trace2] for details), but this may change and users of -the session ID should not rely on this fact. +link:technical/api-trace2.html[api-trace2] for details), but this may change +and users of the session ID should not rely on this fact. object-info ~~~~~~~~~~~ diff --git a/Documentation/scalar.txt b/Documentation/scalar.txt new file mode 100644 index 0000000000..f33436c7f6 --- /dev/null +++ b/Documentation/scalar.txt @@ -0,0 +1,166 @@ +scalar(1) +========= + +NAME +---- +scalar - A tool for managing large Git repositories + +SYNOPSIS +-------- +[verse] +scalar clone [--single-branch] [--branch <main-branch>] [--full-clone] <url> [<enlistment>] +scalar list +scalar register [<enlistment>] +scalar unregister [<enlistment>] +scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>] +scalar reconfigure [ --all | <enlistment> ] +scalar diagnose [<enlistment>] +scalar delete <enlistment> + +DESCRIPTION +----------- + +Scalar is a repository management tool that optimizes Git for use in large +repositories. Scalar improves performance by configuring advanced Git settings, +maintaining repositories in the background, and helping to reduce data sent +across the network. + +An important Scalar concept is the enlistment: this is the top-level directory +of the project. It usually contains the subdirectory `src/` which is a Git +worktree. This encourages the separation between tracked files (inside `src/`) +and untracked files, such as build artifacts (outside `src/`). When registering +an existing Git worktree with Scalar whose name is not `src`, the enlistment +will be identical to the worktree. + +The `scalar` command implements various subcommands, and different options +depending on the subcommand. With the exception of `clone`, `list` and +`reconfigure --all`, all subcommands expect to be run in an enlistment. + +The following options can be specified _before_ the subcommand: + +-C <directory>:: + Before running the subcommand, change the working directory. This + option imitates the same option of linkgit:git[1]. + +-c <key>=<value>:: + For the duration of running the specified subcommand, configure this + setting. This option imitates the same option of linkgit:git[1]. + +COMMANDS +-------- + +Clone +~~~~~ + +clone [<options>] <url> [<enlistment>]:: + Clones the specified repository, similar to linkgit:git-clone[1]. By + default, only commit and tree objects are cloned. Once finished, the + worktree is located at `<enlistment>/src`. ++ +The sparse-checkout feature is enabled (except when run with `--full-clone`) +and the only files present are those in the top-level directory. Use +`git sparse-checkout set` to expand the set of directories you want to see, +or `git sparse-checkout disable` to expand to all files (see +linkgit:git-sparse-checkout[1] for more details). You can explore the +subdirectories outside your sparse-checkout by using `git ls-tree +HEAD[:<directory>]`. + +-b <name>:: +--branch <name>:: + Instead of checking out the branch pointed to by the cloned + repository's HEAD, check out the `<name>` branch instead. + +--[no-]single-branch:: + Clone only the history leading to the tip of a single branch, either + specified by the `--branch` option or the primary branch remote's + `HEAD` points at. ++ +Further fetches into the resulting repository will only update the +remote-tracking branch for the branch this option was used for the initial +cloning. If the HEAD at the remote did not point at any branch when +`--single-branch` clone was made, no remote-tracking branch is created. + +--[no-]full-clone:: + A sparse-checkout is initialized by default. This behavior can be + turned off via `--full-clone`. + +List +~~~~ + +list:: + List enlistments that are currently registered by Scalar. This + subcommand does not need to be run inside an enlistment. + +Register +~~~~~~~~ + +register [<enlistment>]:: + Adds the enlistment's repository to the list of registered repositories + and starts background maintenance. If `<enlistment>` is not provided, + then the enlistment associated with the current working directory is + registered. ++ +Note: when this subcommand is called in a worktree that is called `src/`, its +parent directory is considered to be the Scalar enlistment. If the worktree is +_not_ called `src/`, it itself will be considered to be the Scalar enlistment. + +Unregister +~~~~~~~~~~ + +unregister [<enlistment>]:: + Remove the specified repository from the list of repositories + registered with Scalar and stop the scheduled background maintenance. + +Run +~~~ + +scalar run ( all | config | commit-graph | fetch | loose-objects | pack-files ) [<enlistment>]:: + Run the given maintenance task (or all tasks, if `all` was specified). + Except for `all` and `config`, this subcommand simply hands off to + linkgit:git-maintenance[1] (mapping `fetch` to `prefetch` and + `pack-files` to `incremental-repack`). ++ +These tasks are run automatically as part of the scheduled maintenance, +as soon as the repository is registered with Scalar. It should therefore +not be necessary to run this subcommand manually. ++ +The `config` task is specific to Scalar and configures all those +opinionated default settings that make Git work more efficiently with +large repositories. As this task is run as part of `scalar clone` +automatically, explicit invocations of this task are rarely needed. + +Reconfigure +~~~~~~~~~~~ + +After a Scalar upgrade, or when the configuration of a Scalar enlistment +was somehow corrupted or changed by mistake, this subcommand allows to +reconfigure the enlistment. + +With the `--all` option, all enlistments currently registered with Scalar +will be reconfigured. Use this option after each Scalar upgrade. + +Diagnose +~~~~~~~~ + +diagnose [<enlistment>]:: + When reporting issues with Scalar, it is often helpful to provide the + information gathered by this command, including logs and certain + statistics describing the data shape of the current enlistment. ++ +The output of this command is a `.zip` file that is written into +a directory adjacent to the worktree in the `src` directory. + +Delete +~~~~~~ + +delete <enlistment>:: + This subcommand lets you delete an existing Scalar enlistment from your + local file system, unregistering the repository. + +SEE ALSO +-------- +linkgit:git-clone[1], linkgit:git-maintenance[1]. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/technical/api-error-handling.txt b/Documentation/technical/api-error-handling.txt index 70bf1d3e52..665c4960b4 100644 --- a/Documentation/technical/api-error-handling.txt +++ b/Documentation/technical/api-error-handling.txt @@ -46,7 +46,7 @@ parse-options.c. returns -1 after reporting the situation to the caller. These reports will be logged via the trace2 facility. See the "error" -event in link:api-trace2.txt[trace2 API]. +event in link:api-trace2.html[trace2 API]. Customizable error handlers --------------------------- diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index c2a5e42914..61fa6ee167 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -60,7 +60,7 @@ Subcommands are special in a couple of ways: * All arguments following the subcommand are considered to be arguments of the subcommand, and, conversely, arguments meant for the subcommand may - not preceed the subcommand. + not precede the subcommand. Therefore, if the options array contains at least one subcommand and `parse_options()` encounters the first dashless argument, it will either: diff --git a/Documentation/technical/bundle-uri.txt b/Documentation/technical/bundle-uri.txt index c25c42378a..b78d01d9ad 100644 --- a/Documentation/technical/bundle-uri.txt +++ b/Documentation/technical/bundle-uri.txt @@ -3,8 +3,7 @@ Bundle URIs Git bundles are files that store a pack-file along with some extra metadata, including a set of refs and a (possibly empty) set of necessary commits. See -linkgit:git-bundle[1] and link:bundle-format.txt[the bundle format] for more -information. +linkgit:git-bundle[1] and linkgit:gitformat-bundle[5] for more information. Bundle URIs are locations where Git can download one or more bundles in order to bootstrap the object database in advance of fetching the remaining @@ -154,8 +153,8 @@ bundle.<id>.filter:: bundle.<id>.creationToken:: This value is a nonnegative 64-bit integer used for sorting the bundles - the list. This is used to download a subset of bundles during a fetch - when `bundle.heuristic=creationToken`. + list. This is used to download a subset of bundles during a fetch when + `bundle.heuristic=creationToken`. bundle.<id>.location:: This string value advertises a real-world location from where the bundle @@ -235,8 +234,8 @@ will interact with bundle URIs according to the following flow: making those OIDs present. When all required OIDs are present, the client unbundles that data using a refspec. The default refspec is `+refs/heads/*:refs/bundles/*`, but this can be configured. These refs - are stored so that later `git fetch` negotiations can communicate the - bundled refs as `have`s, reducing the size of the fetch over the Git + are stored so that later `git fetch` negotiations can communicate each + bundled ref as a `have`, reducing the size of the fetch over the Git protocol. To allow pruning refs from this ref namespace, Git may introduce a numbered namespace (such as `refs/bundles/<i>/*`) such that stale bundle refs can be deleted. @@ -290,7 +289,7 @@ expect that the process will end when all prerequisite commit OIDs in a thin bundle are already in the object database. When using the `creationToken` heuristic, the client can avoid downloading -any bundles if their creation tokenss are not larger than the stored +any bundles if their creation tokens are not larger than the stored creation token. After fetching new bundles, Git updates this local creation token. @@ -319,7 +318,7 @@ Here are a few example error conditions: Git's other HTTP protocols in terms of handling specific 400-level errors. -* The server reports any other failure reponse. +* The server reports any other failure response. * The client receives data that is not parsable as a bundle or bundle list. @@ -447,7 +446,7 @@ created every hour, and then once a day those "hourly" bundles could be merged into a "daily" bundle. The daily bundles are merged into the oldest bundle after 30 days. -It is recommened that this bundle strategy is repeated with the `blob:none` +It is recommended that this bundle strategy is repeated with the `blob:none` filter if clients of this repository are expecting to use blobless partial clones. This list of blobless bundles stays in the same list as the full bundles, but uses the `bundle.<id>.filter` key to separate the two groups. diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index f05e7bda1a..90c9760c23 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -40,7 +40,7 @@ Values 1-4 satisfy the requirements of parse_commit_gently(). There are two definitions of generation number: 1. Corrected committer dates (generation number v2) -2. Topological levels (generation nummber v1) +2. Topological levels (generation number v1) Define "corrected committer date" of a commit recursively as follows: @@ -48,7 +48,7 @@ Define "corrected committer date" of a commit recursively as follows: equal to its committer date. * A commit with at least one parent has corrected committer date equal to - the maximum of its commiter date and one more than the largest corrected + the maximum of its committer date and one more than the largest corrected committer date among its parents. * As a special case, a root commit with timestamp zero has corrected commit diff --git a/Documentation/technical/remembering-renames.txt b/Documentation/technical/remembering-renames.txt index af091a7556..1e34d91390 100644 --- a/Documentation/technical/remembering-renames.txt +++ b/Documentation/technical/remembering-renames.txt @@ -407,7 +407,7 @@ considered to be "irrelevant". See for example the following commits: no longer relevant", 2021-03-13) Relevance is always determined by what the _other_ side of history has -done, in terms of modifing a file that our side renamed, or adding a +done, in terms of modifying a file that our side renamed, or adding a file to a directory which our side renamed. This means that a path that is "irrelevant" when picking the first commit of a series in a rebase or cherry-pick, may suddenly become "relevant" when picking the diff --git a/Documentation/technical/scalar.txt b/Documentation/technical/scalar.txt index 0600150b3a..921cb104c3 100644 --- a/Documentation/technical/scalar.txt +++ b/Documentation/technical/scalar.txt @@ -64,64 +64,3 @@ some "global" `git` options (e.g., `-c` and `-C`). Because `scalar` is not invoked as a Git subcommand (like `git scalar`), it is built and installed as its own executable in the `bin/` directory, alongside `git`, `git-gui`, etc. - -Roadmap -------- - -NOTE: this section will be removed once the remaining tasks outlined in this -roadmap are complete. - -Scalar is a large enough project that it is being upstreamed incrementally, -living in `contrib/` until it is feature-complete. So far, the following patch -series have been accepted: - -- `scalar-the-beginning`: The initial patch series which sets up - `contrib/scalar/` and populates it with a minimal `scalar` command that - demonstrates the fundamental ideas. - -- `scalar-c-and-C`: The `scalar` command learns about two options that can be - specified before the command, `-c <key>=<value>` and `-C <directory>`. - -- `scalar-diagnose`: The `scalar` command is taught the `diagnose` subcommand. - -- `scalar-generalize-diagnose`: Move the functionality of `scalar diagnose` - into `git diagnose` and `git bugreport --diagnose`. - -- 'scalar-add-fsmonitor: Enable the built-in FSMonitor in Scalar - enlistments. At the end of this series, Scalar should be feature-complete - from the perspective of a user. - -Roughly speaking (and subject to change), the following series are needed to -"finish" this initial version of Scalar: - -- Move Scalar to toplevel: Move Scalar out of `contrib/` and into the root of - `git`. This includes a variety of related updates, including: - - building & installing Scalar in the Git root-level 'make [install]'. - - builing & testing Scalar as part of CI. - - moving and expanding test coverage of Scalar (including perf tests). - - implementing 'scalar help'/'git help scalar' to display scalar - documentation. - -Finally, there are two additional patch series that exist in Microsoft's fork of -Git, but there is no current plan to upstream them. There are some interesting -ideas there, but the implementation is too specific to Azure Repos and/or VFS -for Git to be of much help in general. - -These still exist mainly because the GVFS protocol is what Azure Repos has -instead of partial clone, while Git is focused on improving partial clone: - -- `scalar-with-gvfs`: The primary purpose of this patch series is to support - existing Scalar users whose repositories are hosted in Azure Repos (which does - not support Git's partial clones, but supports its predecessor, the GVFS - protocol, which is used by Scalar to emulate the partial clone). - - Since the GVFS protocol will never be supported by core Git, this patch series - will remain in Microsoft's fork of Git. - -- `run-scalar-functional-tests`: The Scalar project developed a quite - comprehensive set of integration tests (or, "Functional Tests"). They are the - sole remaining part of the original C#-based Scalar project, and this patch - adds a GitHub workflow that runs them all. - - Since the tests partially depend on features that are only provided in the - `scalar-with-gvfs` patch series, this patch cannot be upstreamed. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index ca9decdd95..dc9c6a663a 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -3133,7 +3133,7 @@ those "loose" objects. You can save space and make Git faster by moving these loose objects in to a "pack file", which stores a group of objects in an efficient compressed format; the details of how pack files are formatted can be -found in link:gitformat-pack[5]. +found in linkgit:gitformat-pack[5]. To put the loose objects into a pack, just run git repack: |