diff options
Diffstat (limited to 'Documentation')
27 files changed, 822 insertions, 34 deletions
diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt index 0532bfcf7f..2b64665694 100644 --- a/Documentation/BreakingChanges.txt +++ b/Documentation/BreakingChanges.txt @@ -115,6 +115,26 @@ info/grafts as outdated, 2014-03-05) and will be removed. + Cf. <20140304174806.GA11561@sigill.intra.peff.net>. +* The git-pack-redundant(1) command can be used to remove redundant pack files. + The subcommand is unusably slow and the reason why nobody reports it as a + performance bug is suspected to be the absense of users. We have nominated + the command for removal and have started to emit a user-visible warning in + c3b58472be (pack-redundant: gauge the usage before proposing its removal, + 2020-08-25) whenever the command is executed. ++ +So far there was a single complaint about somebody still using the command, but +that complaint did not cause us to reverse course. On the contrary, we have +doubled down on the deprecation and starting with 4406522b76 (pack-redundant: +escalate deprecation warning to an error, 2023-03-23), the command dies unless +the user passes the `--i-still-use-this` option. ++ +There have not been any subsequent complaints, so this command will finally be +removed. ++ +Cf. <xmqq1rjuz6n3.fsf_-_@gitster.c.googlers.com>, + <CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com>, + <20230323204047.GA9290@coredump.intra.peff.net>, + == Superseded features that will not be deprecated Some features have gained newer replacements that aim to improve the design in diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 5edd3a0b9d..3263245b03 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -241,6 +241,16 @@ For C programs: - We use tabs to indent, and interpret tabs as taking up to 8 spaces. + - Nested C preprocessor directives are indented after the hash by one + space per nesting level. + + #if FOO + # include <foo.h> + # if BAR + # include <bar.h> + # endif + #endif + - We try to keep to at most 80 characters per line. - As a Git developer we assume you have a reasonably modern compiler @@ -248,6 +258,14 @@ For C programs: ensure your patch is clear of all compiler warnings we care about, by e.g. "echo DEVELOPER=1 >>config.mak". + - When using DEVELOPER=1 mode, you may see warnings from the compiler + like "error: unused parameter 'foo' [-Werror=unused-parameter]", + which indicates that a function ignores its argument. If the unused + parameter can't be removed (e.g., because the function is used as a + callback and has to match a certain interface), you can annotate + the individual parameters with the UNUSED (or MAYBE_UNUSED) + keyword, like "int foo UNUSED". + - We try to support a wide range of C compilers to compile Git with, 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 @@ -261,7 +279,7 @@ For C programs: . 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}; + 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 @@ -567,6 +585,42 @@ For C programs: use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + - The primary data structure that a subsystem 'S' deals with is called + `struct S`. Functions that operate on `struct S` are named + `S_<verb>()` and should generally receive a pointer to `struct S` as + first parameter. E.g. + + struct strbuf; + + void strbuf_add(struct strbuf *buf, ...); + + void strbuf_reset(struct strbuf *buf); + + is preferred over: + + struct strbuf; + + void add_string(struct strbuf *buf, ...); + + void reset_strbuf(struct strbuf *buf); + + - There are several common idiomatic names for functions performing + specific tasks on a structure `S`: + + - `S_init()` initializes a structure without allocating the + structure itself. + + - `S_release()` releases a structure's contents without freeing the + structure. + + - `S_clear()` is equivalent to `S_release()` followed by `S_init()` + such that the structure is directly usable after clearing it. When + `S_clear()` is provided, `S_init()` shall not allocate resources + that need to be released again. + + - `S_free()` releases a structure's contents and frees the + structure. + For Perl programs: - Most of the C guidelines above apply. diff --git a/Documentation/Makefile b/Documentation/Makefile index 1bd23fbeef..0f55baa252 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -118,6 +118,7 @@ TECH_DOCS += technical/multi-pack-index TECH_DOCS += technical/pack-heuristics TECH_DOCS += technical/parallel-checkout TECH_DOCS += technical/partial-clone +TECH_DOCS += technical/platform-support TECH_DOCS += technical/racy-git TECH_DOCS += technical/reftable TECH_DOCS += technical/scalar diff --git a/Documentation/RelNotes/2.47.0.txt b/Documentation/RelNotes/2.47.0.txt new file mode 100644 index 0000000000..ffc0c5c4a2 --- /dev/null +++ b/Documentation/RelNotes/2.47.0.txt @@ -0,0 +1,243 @@ +Git v2.47 Release Notes +======================= + +UI, Workflows & Features +------------------------ + + * Many Porcelain commands that internally use the merge machinery + were taught to consistently honor the diff.algorithm configuration. + + * A few descriptions in "git show-ref -h" have been clarified. + + * A 'P' command to "git add -p" that passes the patch hunk to the + pager has been added. + + * "git grep -W" omits blank lines that follow the found function at + the end of the file, just like it omits blank lines before the next + function. + + * The value of http.proxy can have "path" at the end for a socks + proxy that listens to a unix-domain socket, but we started to + discard it when we taught proxy auth code path to use the + credential helpers, which has been corrected. + + * The code paths to compact multiple reftable files have been updated + to correctly deal with multiple compaction triggering at the same + time. + + * Support to specify ref backend for submodules has been enhanced. + + * "git svn" has been taught about svn:global-ignores property + recent versions of Subversion has. + + * The default object hash and ref backend format used to be settable + only with explicit command line option to "git init" and + environment variables, but now they can be configured in the user's + global and system wide configuration. + + * "git send-email" learned "--translate-aliases" option that reads + addresses from the standard input and emits the result of applying + aliases on them to the standard output. + + * 'git for-each-ref' learned a new "--format" atom to find the branch + that the history leading to a given commit "%(is-base:<commit>)" is + likely based on. + + * The command line prompt support used to be littered with bash-isms, + which has been corrected to work with more shells. + + * Support for the RUNTIME_PREFIX feature has been added to z/OS port. + + * "git send-email" learned "--mailmap" option to allow rewriting the + recipient addresses. + + * "git mergetool" learned to use VSCode as a merge backend. + + * "git pack-redundant" has been marked for removal in Git 3.0. + + * One-line messages to "die" and other helper functions will get LF + added by these helper functions, but many existing messages had an + unnecessary LF at the end, which have been corrected. + + * The "scalar clone" command learned the "--no-tags" option. + + * The environment GIT_ADVICE has been intentionally kept undocumented + to discourage its use by interactive users. Add documentation to + help tool writers. + +Performance, Internal Implementation, Development Support etc. +-------------------------------------------------------------- + + * A build tweak knob has been simplified by not setting the value + that is already the default; another unused one has been removed. + + * A CI job that use clang-format to check coding style issues in new + code has been added. + + * The reviewing guidelines document now explicitly encourages people + to give positive reviews and how. + + * Test script linter has been updated to catch an attempt to use + one-shot export construct "VAR=VAL func" for shell functions (which + does not work for some shells) better. + + * Some project conventions have been added to CodingGuidelines. + + * In the refs subsystem, implicit reliance of the_repository has been + eliminated; the repository associated with the ref store object is + used instead. + + * Various tests in reftable library have been rewritten using the unit test + framework. + + * A test that fails on an unusually slow machine was found, and made + less likely to cause trouble by lengthening the expiry value it + uses. + + * An existing test of hashmap API has been rewritten with the + unit-test framework. + + * A policy document that describes platform support levels and + expectation on platform stakeholders has been introduced. + + * The refs API has been taught to give symref target information to + the users of ref iterators, allowing for-each-ref and friends to + avoid an extra ref_resolve_* API call per a symbolic ref. + + * Unit-test framework has learned a simple control structure to allow + embedding test statements in-line instead of having to create a new + function to contain them. + + * Incremental updates of multi-pack index files is getting worked on. + + * Use of API functions that implicitly depend on the_repository + object in the config subsystem has been rewritten to pass a + repository object through the callchain. + + * Unused parameters have been either marked as UNUSED to squelch + -Wunused warnings or dropped from many functions.. + + * The code in the reftable library has been cleaned up by discarding + unused "generic" interface. + + * The underlying machinery for "git diff-index" has long been made to + expand the sparse index as needed, but the command fully expanded + the sparse index upfront, which now has been taught not to do. + + * More trace2 events at key points on push and fetch code paths have + been added. + + * Make our codebase compilable with the -Werror=unused-parameter + option. + + * "git cat-file" works well with the sparse-index, and gets marked as + such. + + +Fixes since v2.46 +----------------- + + * "git add -p" by users with diff.suppressBlankEmpty set to true + failed to parse the patch that represents an unmodified empty line + with an empty line (not a line with a single space on it), which + has been corrected. + + * "git checkout --ours" (no other arguments) complained that the + option is incompatible with branch switching, which is technically + correct, but found confusing by some users. It now says that the + user needs to give pathspec to specify what paths to checkout. + + * It has been documented that we avoid "VAR=VAL shell_func" and why. + + * "git rebase --help" referred to "offset" (the difference between + the location a change was taken from and the change gets replaced) + incorrectly and called it "fuzz", which has been corrected. + + * "git notes add -m '' --allow-empty" and friends that take prepared + data to create notes should not invoke an editor, but it started + doing so since Git 2.42, which has been corrected. + + * An expensive operation to prepare tracing was done in re-encoding + code path even when the tracing was not requested, which has been + corrected. + + * More leakfixes. + + * The credential helper to talk to OSX keychain sometimes sent + garbage bytes after the username, which has been corrected. + + * A recent update broke "git ls-remote" used outside a repository, + which has been corrected. + + * The patch parser in 'git apply' has been a bit more lenient against + unexpected mode bits, like 100664, recorded on extended header lines. + + * "git config --value=foo --fixed-value section.key newvalue" barfed + when the existing value in the configuration file used the + valueless true syntax, which has been corrected. + + * The patch parser in "git patch-id" has been tightened to avoid + getting confused by lines that look like a patch header in the log + message. + + * "git reflog expire" failed to honor annotated tags when computing + reachable commits. + + * A flakey test and incorrect calls to strtoX() functions have been + fixed. + + * Follow-up on 2.45.1 regression fix. + + * "git rev-list ... | git diff-tree -p --remerge-diff --stdin" should + behave more or less like "git log -p --remerge-diff" but instead it + crashed, forgetting to prepare a temporary object store needed. + + * "git bundle unbundle" outside a repository triggered a BUG() + unnecessarily, which has been corrected. + + * Maintenance tasks other than "gc" now properly go background when + "git maintenance" runs them. + + * We created a useless pseudo-merge reachability bitmap that is about + 0 commits, and attempted to include commits that are not in packs, + which made no sense. These bugs have been corrected. + (merge a72dfab8b8 tb/pseudo-merge-bitmap-fixes later to maint). + + * "git rebase -x --quiet" was not quiet, which was corrected. + + * The code path for compacting reftable files saw some bugfixes + against concurrent operation. + + * The code forgot to discard unnecessary in-core commit buffer data + for commits that "git log --skip=<number>" traversed but omitted + from the output, which has been corrected. + + * "git verify-pack" and "git index-pack" started dying outside a + repository, which has been corrected. + + * A data corruption bug when multi-pack-index is used and the same + objects are stored in multiple packfiles has been corrected. + + * "git pack-refs --auto" for the files backend was too aggressive, + which has been a bit tamed. + (merge c3459ae9ef ps/pack-refs-auto-heuristics later to maint). + + * A file descriptor left open is now properly closed when "git + sparse-checkout" updates the sparse patterns. + + * In a few corner cases "git diff --exit-code" failed to report + "changes" (e.g., renamed without any content change), which has + been corrected. + (merge 11591850dd rs/diff-exit-code-fix later to maint). + + * Cygwin does have /dev/tty support that is needed by things like + single-key input mode. + (merge 39ba986b0e rj/cygwin-has-dev-tty later to maint). + + * The interpret-trailers command failed to recognise the end of the + message when the commit log ends in an incomplete line. + (merge c02414a997 bl/trailers-and-incomplete-last-line-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge be10ac7037 jc/mailinfo-header-cleanup later to maint). + (merge 9a36ea37ae jc/doc-skip-fetch-all-and-prefetch later to maint). diff --git a/Documentation/ReviewingGuidelines.txt b/Documentation/ReviewingGuidelines.txt index 515d470d23..6534643cff 100644 --- a/Documentation/ReviewingGuidelines.txt +++ b/Documentation/ReviewingGuidelines.txt @@ -72,12 +72,29 @@ guidance, and concrete tips for interacting with patches on the mailing list. 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 +- Reviews do not need to exclusively point out problems. Positive + reviews indicate that it is not only the original author of the + patches who care about the issue the patches address, and are + highly encouraged. + +- Do not hesitate to give positive reviews on a series from your + work colleague. If your positive review is written well, it will + not make you look as if you two are representing corporate + interest on a series that is otherwise uninteresting to other + community members and shoving it down their throat. + +- Write a positive review in such a way that others can understand + why you support the goal, the approach, and the implementation the + patches took. Make sure to demonstrate that you did thoroughly read + the series and understood problem area well enough to be able to + say that the patches are written well. 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. + 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 diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 0ba8989820..257db58918 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -2,7 +2,13 @@ advice.*:: These variables control various optional help messages designed to aid new users. When left unconfigured, Git will give the message alongside instructions on how to squelch it. You can tell Git - that you do not need the help message by setting these to `false`: + that you have understood the issue and no longer need a specific + help message by setting the corresponding variable to `false`. ++ +As they are intended to help human users, these messages are output to +the standard error. When tools that run Git as a subprocess find them +disruptive, they can set `GIT_ADVICE=0` in the environment to squelch +all advice messages. + -- addEmbeddedRepo:: diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 664a3c2874..1d4f9470ea 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -40,7 +40,8 @@ use, it'll affect how the auto pack limit works. gc.autoDetach:: Make `git gc --auto` return immediately and run in the background - if the system supports it. Default is true. + if the system supports it. Default is true. This config variable acts + as a fallback in case `maintenance.autoDetach` is not set. gc.bigPackThreshold:: If non-zero, all non-cruft packs larger than this limit are kept diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 162b33fc52..a14371b5c9 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -5,8 +5,8 @@ http.proxy:: proxy string with a user name but no password, in which case git will attempt to acquire one in the same way it does for other credentials. See linkgit:gitcredentials[7] for more information. The syntax thus is - '[protocol://][user[:password]@]proxyhost[:port]'. This can be overridden - on a per-remote basis; see remote.<name>.proxy + '[protocol://][user[:password]@]proxyhost[:port][/path]'. This can be + overridden on a per-remote basis; see remote.<name>.proxy + Any proxy, however configured, must be completely transparent and must not modify, transform, or buffer the request or response in any way. Proxies which diff --git a/Documentation/config/init.txt b/Documentation/config/init.txt index af03acdbcb..e45b2a8121 100644 --- a/Documentation/config/init.txt +++ b/Documentation/config/init.txt @@ -8,3 +8,13 @@ endif::[] `init.defaultBranch`:: Allows overriding the default branch name e.g. when initializing a new repository. +`init.defaultObjectFormat`:: + Allows overriding the default object format for new repositories. See + `--object-format=` in linkgit:git-init[1]. Both the command line option + and the `GIT_DEFAULT_HASH` environment variable take precedence over + this config. +`init.defaultRefFormat`:: + Allows overriding the default ref storage format for new repositories. + See `--ref-format=` in linkgit:git-init[1]. Both the command line + option and the `GIT_DEFAULT_REF_FORMAT` environment variable take + precedence over this config. diff --git a/Documentation/config/maintenance.txt b/Documentation/config/maintenance.txt index 69a4f05153..72a9d6cf81 100644 --- a/Documentation/config/maintenance.txt +++ b/Documentation/config/maintenance.txt @@ -3,6 +3,17 @@ maintenance.auto:: `git maintenance run --auto` after doing their normal work. Defaults to true. +maintenance.autoDetach:: + Many Git commands trigger automatic maintenance after they have + written data into the repository. This boolean config option + controls whether this automatic maintenance shall happen in the + foreground or whether the maintenance process shall detach and + continue to run in the background. ++ +If unset, the value of `gc.autoDetach` is used as a fallback. Defaults +to true if both are unset, meaning that the maintenance process will +detach. + maintenance.strategy:: This string config option provides a way to specify one of a few recommended schedules for background maintenance. This only affects diff --git a/Documentation/config/remote.txt b/Documentation/config/remote.txt index 8efc53e836..36e771556c 100644 --- a/Documentation/config/remote.txt +++ b/Documentation/config/remote.txt @@ -42,14 +42,15 @@ remote.<name>.mirror:: as if the `--mirror` option was given on the command line. remote.<name>.skipDefaultUpdate:: - If true, this remote will be skipped by default when updating - using linkgit:git-fetch[1] or the `update` subcommand of - linkgit:git-remote[1]. + A deprecated synonym to `remote.<name>.skipFetchAll` (if + both are set in the configuration files with different + values, the value of the last occurrence will be used). remote.<name>.skipFetchAll:: - If true, this remote will be skipped by default when updating - using linkgit:git-fetch[1] or the `update` subcommand of - linkgit:git-remote[1]. + If true, this remote will be skipped when updating + using linkgit:git-fetch[1], the `update` subcommand of + linkgit:git-remote[1], and ignored by the prefetch task + of `git maitenance`. remote.<name>.receivepack:: The default program to execute on the remote side when pushing. See diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index e22b217fba..80838fe37e 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -1,6 +1,7 @@ --[no-]all:: - Fetch all remotes. This overrides the configuration variable - `fetch.all`. + Fetch all remotes, except for the ones that has the + `remote.<name>.skipFetchAll` configuration variable set. + This overrides the configuration variable fetch.all`. -a:: --append:: diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.txt index f643585a34..68a2801f15 100644 --- a/Documentation/fsck-msgids.txt +++ b/Documentation/fsck-msgids.txt @@ -19,6 +19,12 @@ `badParentSha1`:: (ERROR) A commit object has a bad parent sha1. +`badRefFiletype`:: + (ERROR) A ref has a bad file type. + +`badRefName`:: + (ERROR) A ref has an invalid format. + `badTagName`:: (INFO) A tag has an invalid format. diff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.txt index 02f4418323..966c91c46a 100644 --- a/Documentation/git-check-mailmap.txt +++ b/Documentation/git-check-mailmap.txt @@ -15,10 +15,10 @@ SYNOPSIS DESCRIPTION ----------- -For each ``Name $$<user@host>$$'' or ``$$<user@host>$$'' from the command-line -or standard input (when using `--stdin`), look up the person's canonical name -and email address (see "Mapping Authors" below). If found, print them; -otherwise print the input as-is. +For each ``Name $$<user@host>$$'', ``$$<user@host>$$'', or ``$$user@host$$'' +from the command-line or standard input (when using `--stdin`), look up the +person's canonical name and email address (see "Mapping Authors" below). If +found, print them; otherwise print the input as-is. OPTIONS @@ -27,6 +27,16 @@ OPTIONS Read contacts, one per line, from the standard input after exhausting contacts provided on the command-line. +--mailmap-file=<file>:: + In addition to any configured mailmap files, read the specified + mailmap file. Entries in this file take precedence over entries in + either the default mailmap file or any configured mailmap file. + +--mailmap-blob=<blob>:: + Like `--mailmap-file`, but consider the value as a reference to a + blob in the repository. If both `--mailmap-file` and + `--mailmap-blob` are specified, entries in `--mailmap-file` will + take precedence. OUTPUT ------ diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index c1dd12b93c..d3764401a2 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -264,6 +264,48 @@ ahead-behind:<committish>:: commits ahead and behind, respectively, when comparing the output ref to the `<committish>` specified in the format. +is-base:<committish>:: + In at most one row, `(<committish>)` will appear to indicate the ref + that is most likely the ref used as a starting point for the branch + that produced `<committish>`. This choice is made using a heuristic: + choose the ref that minimizes the number of commits in the + first-parent history of `<committish>` and not in the first-parent + history of the ref. ++ +For example, consider the following figure of first-parent histories of +several refs: ++ +---- +*--*--*--*--*--* refs/heads/A +\ + \ + *--*--*--* refs/heads/B + \ \ + \ \ + * * refs/heads/C + \ + \ + *--* refs/heads/D +---- ++ +Here, if `A`, `B`, and `C` are the filtered references, and the format +string is `%(refname):%(is-base:D)`, then the output would be ++ +---- +refs/heads/A: +refs/heads/B:(D) +refs/heads/C: +---- ++ +This is because the first-parent history of `D` has its earliest +intersection with the first-parent histories of the filtered refs at a +common first-parent ancestor of `B` and `C` and ties are broken by the +earliest ref in the sorted order. ++ +Note that this token will not appear if the first-parent history of +`<committish>` does not intersect the first-parent histories of the +filtered refs. + describe[:options]:: A human-readable name, like linkgit:git-describe[1]; empty string for undescribable commits. The `describe` string may diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index b5561c458a..370e22faae 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -9,7 +9,7 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- [verse] -'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack] +'git gc' [--aggressive] [--auto] [--[no-]detach] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack] DESCRIPTION ----------- @@ -53,6 +53,9 @@ configuration options such as `gc.auto` and `gc.autoPackLimit`, all other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. +--[no-]detach:: + Run in the background if the system supports it. This option overrides + the `gc.autoDetach` config. --[no-]cruft:: When expiring unreachable objects, pack them separately into a diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index 51d0f7e94b..9d96819133 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -107,6 +107,9 @@ with the prefetch task, the objects necessary to complete a later real fetch would already be obtained, making the real fetch faster. In the ideal case, it will just become an update to a bunch of remote-tracking branches without any object transfer. ++ +The `remote.<name>.skipFetchAll` configuration can be used to +exclude a particular remote from getting prefetched. gc:: Clean up unnecessary files and optimize the local repository. "GC" diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index 3696506eb3..631d5c7d15 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -64,6 +64,12 @@ The file given at `<path>` is expected to be readable, and can contain duplicates. (If a given OID is given more than once, it is marked as preferred if at least one instance of it begins with the special `+` marker). + + --incremental:: + Write an incremental MIDX file containing only objects + and packs not present in an existing MIDX layer. + Migrates non-incremental MIDXs to incremental ones when + necessary. Incompatible with `--bitmap`. -- verify:: @@ -74,6 +80,8 @@ expire:: have no objects referenced by the MIDX (with the exception of `.keep` packs and cruft packs). Rewrite the MIDX file afterward to remove all references to these pack-files. ++ +NOTE: this mode is incompatible with incremental MIDX files. repack:: Create a new pack-file containing objects in small pack-files @@ -95,7 +103,8 @@ repack:: + If `repack.packKeptObjects` is `false`, then any pack-files with an associated `.keep` file will not be selected for the batch to repack. - ++ +NOTE: this mode is incompatible with incremental MIDX files. EXAMPLES -------- diff --git a/Documentation/git-refs.txt b/Documentation/git-refs.txt index 5b99e04385..ce31f93061 100644 --- a/Documentation/git-refs.txt +++ b/Documentation/git-refs.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git refs migrate' --ref-format=<format> [--dry-run] +'git refs verify' [--strict] [--verbose] DESCRIPTION ----------- @@ -22,6 +23,9 @@ COMMANDS migrate:: Migrate ref store between different formats. +verify:: + Verify reference database consistency. + OPTIONS ------- @@ -39,6 +43,15 @@ include::ref-storage-format.txt[] can be used to double check that the migration works as expected before performing the actual migration. +The following options are specific to 'git refs verify': + +--strict:: + Enable stricter error checking. This will cause warnings to be + reported as errors. See linkgit:git-fsck[1]. + +--verbose:: + When verifying the reference database consistency, be chatty. + KNOWN LIMITATIONS ----------------- diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index c5d664f451..2e6f1d63ae 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git send-email' [<options>] (<file>|<directory>)... 'git send-email' [<options>] <format-patch-options> 'git send-email' --dump-aliases +'git send-email' --translate-aliases DESCRIPTION @@ -475,6 +476,12 @@ Information that this only includes the alias name and not its expanded email addresses. See 'sendemail.aliasesFile' for more information about aliases. +--translate-aliases:: + Instead of the normal operation, read from standard input and + interpret each line as an email alias. Translate it according to the + configured alias file(s). Output each translated name and email + address to standard output, one per line. See 'sendemail.aliasFile' + for more information about aliases. CONFIGURATION ------------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index ca0347a37b..87d8e0f0c5 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -34,7 +34,7 @@ COMMANDS With no arguments, shows the status of existing submodules. Several subcommands are available to perform operations on the submodules. -add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]:: +add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]:: Add the given repository as a submodule at the given path to the changeset to be committed next to the current project: the current project is termed the "superproject". @@ -71,6 +71,9 @@ submodule repositories will be kept together in the same relative location, and only the superproject's URL needs to be provided. git-submodule will correctly locate the submodule using the relative URL in `.gitmodules`. ++ +If `--ref-format <format>` is specified, the ref storage format of newly +cloned submodules will be set accordingly. status [--cached] [--recursive] [--] [<path>...]:: Show the status of the submodules. This will print the SHA-1 of the @@ -136,7 +139,7 @@ If you really want to remove a submodule from the repository and commit that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal options. -update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]:: +update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]:: + -- Update the registered submodules to match what the superproject @@ -185,6 +188,9 @@ submodule with the `--init` option. If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. +If `--ref-format <format>` is specified, the ref storage format of newly +cloned submodules will be set accordingly. + If `--filter <filter-spec>` is specified, the given partial clone filter will be applied to the submodule. See linkgit:git-rev-list[1] for details on filter specifications. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 43c68c2ec4..bcf7d84a87 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -431,14 +431,14 @@ Any other arguments are passed directly to 'git log' independently of 'git svn' functions. 'create-ignore':: - Recursively finds the svn:ignore property on directories and - creates matching .gitignore files. The resulting files are staged to - be committed, but are not committed. Use -r/--revision to refer to a - specific revision. + Recursively finds the svn:ignore and svn:global-ignores properties + on directories and creates matching .gitignore files. The resulting + files are staged to be committed, but are not committed. Use + -r/--revision to refer to a specific revision. 'show-ignore':: - Recursively finds and lists the svn:ignore property on - directories. The output is suitable for appending to + Recursively finds and lists the svn:ignore and svn:global-ignores + properties on directories. The output is suitable for appending to the $GIT_DIR/info/exclude file. 'mkdirs':: @@ -871,7 +871,7 @@ Tracking and contributing to the trunk of a Subversion-managed project # Now commit your changes (that were committed previously using Git) to SVN, # as well as automatically updating your working HEAD: git svn dcommit -# Append svn:ignore settings to the default Git exclude file: +# Append svn:ignore and svn:global-ignores settings to the default Git exclude file: git svn show-ignore >> .git/info/exclude ------------------------------------------------------------------------ diff --git a/Documentation/git.txt b/Documentation/git.txt index 4489e2297a..d15a869762 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -1027,6 +1027,17 @@ standard output. adequate and support for it is likely to be removed in the foreseeable future (along with the variable). +`GIT_ADVICE`:: + If set to `0`, then disable all advice messages. These messages are + intended to provide hints to human users that may help them get out of + problematic situations or take advantage of new features. Users can + disable individual messages using the `advice.*` config keys. These + messages may be disruptive to tools that execute Git processes, so this + variable is available to disable the messages. (The `--no-advice` + global option is also available, but old Git versions may fail when + this option is not understood. The environment variable will be ignored + by Git versions that do not understand it.) + Discussion[[Discussion]] ------------------------ diff --git a/Documentation/scalar.txt b/Documentation/scalar.txt index 361f51a647..7e4259c674 100644 --- a/Documentation/scalar.txt +++ b/Documentation/scalar.txt @@ -86,6 +86,13 @@ cloning. If the HEAD at the remote did not point at any branch when `<entlistment>/src` directory. Use `--no-src` to place the cloned repository directly in the `<enlistment>` directory. +--[no-]tags:: + By default, `scalar clone` will fetch the tag objects advertised by + the remote and future `git fetch` commands will do the same. Use + `--no-tags` to avoid fetching tags in `scalar clone` and to configure + the repository to avoid fetching tags in the future. To fetch tags after + cloning with `--no-tags`, run `git fetch --tags`. + --[no-]full-clone:: A sparse-checkout is initialized by default. This behavior can be turned off via `--full-clone`. diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index de5fc25059..5817b18310 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -128,7 +128,7 @@ yields ------------ $ cat ~/log.event -{"event":"version","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"3","exe":"2.20.1.155.g426c96fcdb"} +{"event":"version","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"4","exe":"2.20.1.155.g426c96fcdb"} {"event":"start","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621027Z","file":"common-main.c","line":39,"t_abs":0.001173,"argv":["git","version"]} {"event":"cmd_name","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621122Z","file":"git.c","line":432,"name":"version","hierarchy":"version"} {"event":"exit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621236Z","file":"git.c","line":662,"t_abs":0.001227,"code":0} @@ -344,7 +344,7 @@ only present on the "start" and "atexit" events. { "event":"version", ... - "evt":"3", # EVENT format version + "evt":"4", # EVENT format version "exe":"2.20.1.155.g426c96fcdb" # git version } ------------ @@ -835,6 +835,19 @@ The "value" field may be an integer or a string. } ------------ +`"printf"`:: + This event logs a human-readable message with no particular formatting + guidelines. ++ +------------ +{ + "event":"printf", + ... + "t_abs":0.015905, # elapsed time in seconds + "msg":"Hello world" # optional +} +------------ + == Example Trace2 API Usage diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt index f2221d2b44..cc063b30be 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/technical/multi-pack-index.txt @@ -61,6 +61,109 @@ Design Details - The MIDX file format uses a chunk-based approach (similar to the commit-graph file) that allows optional data to be added. +Incremental multi-pack indexes +------------------------------ + +As repositories grow in size, it becomes more expensive to write a +multi-pack index (MIDX) that includes all packfiles. To accommodate +this, the "incremental multi-pack indexes" feature allows for combining +a "chain" of multi-pack indexes. + +Each individual component of the chain need only contain a small number +of packfiles. Appending to the chain does not invalidate earlier parts +of the chain, so repositories can control how much time is spent +updating the MIDX chain by determining the number of packs in each layer +of the MIDX chain. + +=== Design state + +At present, the incremental multi-pack indexes feature is missing two +important components: + + - The ability to rewrite earlier portions of the MIDX chain (i.e., to + "compact" some collection of adjacent MIDX layers into a single + MIDX). At present the only supported way of shrinking a MIDX chain + is to rewrite the entire chain from scratch without the `--split` + flag. ++ +There are no fundamental limitations that stand in the way of being able +to implement this feature. It is omitted from the initial implementation +in order to reduce the complexity, but will be added later. + + - Support for reachability bitmaps. The classic single MIDX + implementation does support reachability bitmaps (see the section + titled "multi-pack-index reverse indexes" in + linkgit:gitformat-pack[5] for more details). ++ +As above, there are no fundamental limitations that stand in the way of +extending the incremental MIDX format to support reachability bitmaps. +The design below specifically takes this into account, and support for +reachability bitmaps will be added in a future patch series. It is +omitted from the current implementation for the same reason as above. ++ +In brief, to support reachability bitmaps with the incremental MIDX +feature, the concept of the pseudo-pack order is extended across each +layer of the incremental MIDX chain to form a concatenated pseudo-pack +order. This concatenation takes place in the same order as the chain +itself (in other words, the concatenated pseudo-pack order for a chain +`{$H1, $H2, $H3}` would be the pseudo-pack order for `$H1`, followed by +the pseudo-pack order for `$H2`, followed by the pseudo-pack order for +`$H3`). ++ +The layout will then be extended so that each layer of the incremental +MIDX chain can write a `*.bitmap`. The objects in each layer's bitmap +are offset by the number of objects in the previous layers of the chain. + +=== File layout + +Instead of storing a single `multi-pack-index` file (with an optional +`.rev` and `.bitmap` extension) in `$GIT_DIR/objects/pack`, incremental +MIDXs are stored in the following layout: + +---- +$GIT_DIR/objects/pack/multi-pack-index.d/ +$GIT_DIR/objects/pack/multi-pack-index.d/multi-pack-index-chain +$GIT_DIR/objects/pack/multi-pack-index.d/multi-pack-index-$H1.midx +$GIT_DIR/objects/pack/multi-pack-index.d/multi-pack-index-$H2.midx +$GIT_DIR/objects/pack/multi-pack-index.d/multi-pack-index-$H3.midx +---- + +The `multi-pack-index-chain` file contains a list of the incremental +MIDX files in the chain, in order. The above example shows a chain whose +`multi-pack-index-chain` file would contain the following lines: + +---- +$H1 +$H2 +$H3 +---- + +The `multi-pack-index-$H1.midx` file contains the first layer of the +multi-pack-index chain. The `multi-pack-index-$H2.midx` file contains +the second layer of the chain, and so on. + +When both an incremental- and non-incremental MIDX are present, the +non-incremental MIDX is always read first. + +=== Object positions for incremental MIDXs + +In the original multi-pack-index design, we refer to objects via their +lexicographic position (by object IDs) within the repository's singular +multi-pack-index. In the incremental multi-pack-index design, we refer +to objects via their index into a concatenated lexicographic ordering +among each component in the MIDX chain. + +If `objects_nr()` is a function that returns the number of objects in a +given MIDX layer, then the index of an object at lexicographic position +`i` within, say, $H3 is defined as: + +---- +objects_nr($H2) + objects_nr($H1) + i +---- + +(in the C implementation, this is often computed as `i + +m->num_objects_in_base`). + Future Work ----------- diff --git a/Documentation/technical/platform-support.txt b/Documentation/technical/platform-support.txt new file mode 100644 index 0000000000..a227c363d7 --- /dev/null +++ b/Documentation/technical/platform-support.txt @@ -0,0 +1,190 @@ +Platform Support Policy +======================= + +Git has a history of providing broad "support" for exotic platforms and older +platforms, without an explicit commitment. Stakeholders of these platforms may +want a more predictable support commitment. This is only possible when platform +stakeholders supply Git developers with adequate tooling, so we can test for +compatibility or develop workarounds for platform-specific quirks on our own. +Various levels of platform-specific tooling will allow us to make more solid +commitments around Git's compatibility with that platform. + +Note that this document is about maintaining existing support for a platform +that has generally worked in the past; for adding support to a platform which +doesn't generally work with Git, the stakeholders for that platform are expected +to do the bulk of that work themselves. We will consider such patches if they +don't make life harder for other supported platforms or for Git contributors. +Some contributors may volunteer to help with the initial or continued support, +but that's not a given. Support work which is too intrusive or difficult for the +project to maintain may still not be accepted. + +Minimum Requirements +-------------------- + +The rest of this doc describes best practices for platforms to make themselves +easy to support. However, before considering support at all, platforms need to +meet the following minimum requirements: + +* Has C99 or C11 + +* Uses versions of dependencies which are generally accepted as stable and + supportable, e.g., in line with the version used by other long-term-support + distributions + +* Has active security support (taking security releases of dependencies, etc) + +These requirements are a starting point, and not sufficient on their own for the +Git community to be enthusiastic about supporting your platform. Maintainers of +platforms which do meet these requirements can follow the steps below to make it +more likely that Git updates will respect the platform's needs. + +Compatible by next release +-------------------------- + +To increase probability that compatibility issues introduced in a release +will be fixed in a later release: + +* You should send a bug report as soon as you notice the breakage on your + platform. The sooner you notice, the better; watching `seen` means you can + notice problems before they are considered "done with review"; whereas + watching `master` means the stable branch could break for your platform, but + you have a decent chance of avoiding a tagged release breaking you. See "The + Policy" in link:../howto/maintain-git.txt["How to maintain Git"] for an + overview of which branches are used in the Git project, and how. + +* The bug report should include information about what platform you are using. + +* You should also use linkgit:git-bisect[1] and determine which commit + introduced the breakage. + +* Please include any information you have about the nature of the breakage: is + it a memory alignment issue? Is an underlying library missing or broken for + your platform? Is there some quirk about your platform which means typical + practices (like malloc) behave strangely? + +* If possible, build Git from the exact same source both for your platform and + for a mainstream platform, to see if the problem you noticed appears only + on your platform. If the problem appears in both, then it's not a + compatibility issue, but we of course appreciate hearing about it in a bug + report anyway, to benefit users of every platform. If it appears only on your + platform, mention clearly that it is a compatibility issue in your report. + +* Once we begin to fix the issue, please work closely with the contributor + working on it to test the proposed fix against your platform. + +Example: NonStop +https://lore.kernel.org/git/01bd01da681a$b8d70a70$2a851f50$@nexbridge.com/[reports +problems] when they're noticed. + +Compatible on `master` and releases +----------------------------------- + +To make sure all stable builds and regular releases work for your platform the +first time, help us avoid breaking `master` for your platform: + +* You should run regular tests against the `next` branch and + publish breakage reports to the mailing list immediately when they happen. + +** Ideally, these tests should run daily. They must run more often than + weekly, as topics generally spend at least 7 days in `next` before graduating + to `master`, and it takes time to put the brakes on a patch once it lands in + `next`. + +** You may want to ask to join the mailto:git-security@googlegroups.com[security + mailing list] in order to run tests against the fixes proposed there, too. + +* It may make sense to automate these; if you do, make sure they are not noisy + (you don't need to send a report when everything works, only when something + breaks; you don't need to send repeated reports for the same breakage night + after night). + +* Breakage reports should be actionable - include clear error messages that can + help developers who may not have access to test directly on your platform. + +* You should use git-bisect and determine which commit introduced the breakage; + if you can't do this with automation, you should do this yourself manually as + soon as you notice a breakage report was sent. + +* You should either: + +** Provide on-demand access to your platform to a trusted developer working to + fix the issue, so they can test their fix, OR + +** Work closely with the developer fixing the issue; the turnaround to check + that their proposed fix works for your platform should be fast enough that it + doesn't hinder the developer working on that fix. Slow testing turnarounds + may cause the fix to miss the next release, or the developer may lose + interest in working on the fix at all. + +Example: +https://lore.kernel.org/git/CAHd-oW6X4cwD_yLNFONPnXXUAFPxgDoccv2SOdpeLrqmHCJB4Q@mail.gmail.com/[AIX] +provides a build farm and runs tests against release candidates. + +Compatible on `next` +-------------------- + +To avoid reactive debugging and fixing when changes hit a release or stable, you +can aim to ensure `next` always works for your platform. (See "The Policy" in +link:../howto/maintain-git.txt["How to maintain Git"] for an overview of how +`next` is used in the Git project.) To do that: + +* You should add a runner for your platform to the GitHub Actions or GitLab CI + suite. This suite is run when any Git developer proposes a new patch, and + having a runner for your platform/configuration means every developer will + know if they break you, immediately. + +** If adding it to an existing CI suite is infeasible (due to architecture + constraints or for performance reasons), any other method which runs as + automatically and quickly as possible works, too. For example, a service + which snoops on the mailing list and automatically runs tests on new [PATCH] + emails, replying to the author with the results, would also be within the + spirit of this requirement. + +* If you rely on Git avoiding a specific pattern that doesn't work well with + your platform (like a certain malloc pattern), raise it on the mailing list. + We'll work case-by-case to look for a solution that doesn't unnecessarily + constrain other platforms to keep compatibility with yours. + +* If you rely on some configuration or behavior, add a test for it. Untested + behavior is subject to breakage at any time. + +** Clearly label these tests as necessary for platform compatibility. Add them + to an isolated compatibility-related test suite, like a new t* file or unit + test suite, so that they're easy to remove when compatibility is no longer + required. If the specific compatibility need is gated behind an issue with + another project, link to documentation of that issue (like a bug or email + thread) to make it easier to tell when that compatibility need goes away. + +** Include a comment with an expiration date for these tests no more than 1 year + from now. You can update the expiration date if your platform still needs + that assurance down the road, but we need to know you still care about that + compatibility case and are working to make it unnecessary. + +Example: We run our +https://git.kernel.org/pub/scm/git/git.git/tree/.github/workflows/main.yml[CI +suite] on Windows, Ubuntu, Mac, and others. + +Getting help writing platform support patches +--------------------------------------------- + +In general, when sending patches to fix platform support problems, follow +these guidelines to make sure the patch is reviewed with the appropriate level +of urgency: + +* Clearly state in the commit message that you are fixing a platform breakage, + and for which platform. + +* Use the CI and test suite to ensure that the fix for your platform doesn't + break other platforms. + +* If possible, add a test ensuring this regression doesn't happen again. If + it's not possible to add a test, explain why in the commit message. + +Platform Maintainers +-------------------- + +If you maintain a platform, or Git for that platform, and intend to work with +the Git project to ensure compatibility, please send a patch to add yourself to +this list. + +NonStop: Randall S. Becker <rsbecker@nexbridge.com> |