diff options
Diffstat (limited to '')
131 files changed, 2901 insertions, 814 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8d3a467..1d92b2d 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -188,6 +188,22 @@ For shell scripts specifically (not exhaustive): hopefully nobody starts using "local" before they are reimplemented in C ;-) + - Some versions of shell do not understand "export variable=value", + so we write "variable=value" and then "export variable" on two + separate lines. + + - Some versions of dash have broken variable assignment when prefixed + with "local", "export", and "readonly", in that the value to be + assigned goes through field splitting at $IFS unless quoted. + + (incorrect) + local variable=$value + local variable=$(command args) + + (correct) + local variable="$value" + local variable="$(command args)" + - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g. "\xc2\xa2") in printf format strings, since hexadecimal escape sequences are not portable. @@ -446,12 +462,41 @@ For C programs: detail. - The first #include in C files, except in platform specific compat/ - implementations and sha1dc/, must be either "git-compat-util.h" or - one of the approved headers that includes it first for you. (The - approved headers currently include "builtin.h", - "t/helper/test-tool.h", "xdiff/xinclude.h", or - "reftable/system.h"). You do not have to include more than one of - these. + implementations and sha1dc/, must be <git-compat-util.h>. This + header file insulates other header files and source files from + platform differences, like which system header files must be + included in what order, and what C preprocessor feature macros must + be defined to trigger certain features we expect out of the system. + A collorary to this is that C files should not directly include + system header files themselves. + + There are some exceptions, because certain group of files that + implement an API all have to include the same header file that + defines the API and it is convenient to include <git-compat-util.h> + there. Namely: + + - the implementation of the built-in commands in the "builtin/" + directory that include "builtin.h" for the cmd_foo() prototype + definition, + + - the test helper programs in the "t/helper/" directory that include + "t/helper/test-tool.h" for the cmd__foo() prototype definition, + + - the xdiff implementation in the "xdiff/" directory that includes + "xdiff/xinclude.h" for the xdiff machinery internals, + + - the unit test programs in "t/unit-tests/" directory that include + "t/unit-tests/test-lib.h" that gives them the unit-tests + framework, and + + - the source files that implement reftable in the "reftable/" + directory that include "reftable/system.h" for the reftable + internals, + + are allowed to assume that they do not have to include + <git-compat-util.h> themselves, as it is included as the first + '#include' in these header files. These headers must be the first + header file to be "#include"d in them, though. - A C file must directly include the header files that declare the functions and the types it uses, except for the functions and types @@ -490,7 +535,7 @@ For Perl programs: - Most of the C guidelines above apply. - - We try to support Perl 5.8 and later ("use Perl 5.008"). + - We try to support Perl 5.8.1 and later ("use Perl 5.008001"). - use strict and use warnings are strongly preferred. @@ -518,7 +563,7 @@ For Perl programs: For Python scripts: - - We follow PEP-8 (http://www.python.org/dev/peps/pep-0008/). + - We follow PEP-8 (https://peps.python.org/pep-0008/). - As a minimum, we aim to be compatible with Python 2.7. @@ -578,7 +623,7 @@ Externally Visible Names . The variable name describes the effect of tweaking this knob. The section and variable names that consist of multiple words are - formed by concatenating the words without punctuations (e.g. `-`), + formed by concatenating the words without punctuation marks (e.g. `-`), and are broken using bumpyCaps in documentation as a hint to the reader. @@ -612,15 +657,15 @@ Writing Documentation: - Prefer succinctness and matter-of-factly describing functionality in the abstract. E.g. - --short:: Emit output in the short-format. + `--short`:: Emit output in the short-format. and avoid something like these overly verbose alternatives: - --short:: Use this to emit output in the short-format. - --short:: You can use this to get output in the short-format. - --short:: A user who prefers shorter output could.... - --short:: Should a person and/or program want shorter output, he - she/they/it can... + `--short`:: Use this to emit output in the short-format. + `--short`:: You can use this to get output in the short-format. + `--short`:: A user who prefers shorter output could.... + `--short`:: Should a person and/or program want shorter output, he + she/they/it can... This practice often eliminates the need to involve human actors in your description, but it is a good practice regardless of the @@ -630,12 +675,12 @@ Writing Documentation: addressing the hypothetical user, and possibly "we" when discussing how the program might react to the user. E.g. - You can use this option instead of --xyz, but we might remove + You can use this option instead of `--xyz`, but we might remove support for it in future versions. while keeping in mind that you can probably be less verbose, e.g. - Use this instead of --xyz. This option might be removed in future + Use this instead of `--xyz`. This option might be removed in future versions. - If you still need to refer to an example person that is @@ -653,63 +698,118 @@ Writing Documentation: The same general rule as for code applies -- imitate the existing conventions. - A few commented examples follow to provide reference when writing or - modifying command usage strings and synopsis sections in the manual - pages: - Placeholders are spelled in lowercase and enclosed in angle brackets: - <file> - --sort=<key> - --abbrev[=<n>] +Markup: + + Literal parts (e.g. use of command-line options, command names, + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset as verbatim (i.e. wrapped with + backticks): + `--pretty=oneline` + `git rev-list` + `remote.pushDefault` + `http://git.example.com` + `.git/config` + `GIT_DIR` + `HEAD` + `umask`(2) + + An environment variable must be prefixed with "$" only when referring to its + value and not when referring to the variable itself, in this case there is + nothing to add except the backticks: + `GIT_DIR` is specified + `$GIT_DIR/hooks/pre-receive` + + Word phrases enclosed in `backtick characters` are rendered literally + and will not be further expanded. The use of `backticks` to achieve the + previous rule means that literal examples should not use AsciiDoc + escapes. + Correct: + `--pretty=oneline` + Incorrect: + `\--pretty=oneline` + + Placeholders are spelled in lowercase and enclosed in + angle brackets surrounded by underscores: + _<file>_ + _<commit>_ If a placeholder has multiple words, they are separated by dashes: - <new-branch-name> - --template=<template-directory> + _<new-branch-name>_ + _<template-directory>_ + + A placeholder is not enclosed in backticks, as it is not a literal. + + When needed, use a distinctive identifier for placeholders, usually + made of a qualification and a type: + _<git-dir>_ + _<key-id>_ + + When literal and placeholders are mixed, each markup is applied for + each sub-entity. If they are stuck, a special markup, called + unconstrained formatting is required. + Unconstrained formating for placeholders is __<like-this>__ + Unconstrained formatting for literal formatting is ++like this++ + `--jobs` _<n>_ + ++--sort=++__<key>__ + __<directory>__++/.git++ + ++remote.++__<name>__++.mirror++ + + caveat: ++ unconstrained format is not verbatim and may expand + content. Use Asciidoc escapes inside them. + +Synopsis Syntax + + Syntax grammar is formatted neither as literal nor as placeholder. + + A few commented examples follow to provide reference when writing or + modifying command usage strings and synopsis sections in the manual + pages: Possibility of multiple occurrences is indicated by three dots: - <file>... + _<file>_... (One or more of <file>.) Optional parts are enclosed in square brackets: - [<file>...] + [_<file>_...] (Zero or more of <file>.) - --exec-path[=<path>] + ++--exec-path++[++=++__<path>__] (Option with an optional argument. Note that the "=" is inside the brackets.) - [<patch>...] + [_<patch>_...] (Zero or more of <patch>. Note that the dots are inside, not outside the brackets.) Multiple alternatives are indicated with vertical bars: - [-q | --quiet] - [--utf8 | --no-utf8] + [`-q` | `--quiet`] + [`--utf8` | `--no-utf8`] Use spacing around "|" token(s), but not immediately after opening or before closing a [] or () pair: - Do: [-q | --quiet] - Don't: [-q|--quiet] + Do: [`-q` | `--quiet`] + Don't: [`-q`|`--quiet`] Don't use spacing around "|" tokens when they're used to separate the alternate arguments of an option: - Do: --track[=(direct|inherit)] - Don't: --track[=(direct | inherit)] + Do: ++--track++[++=++(`direct`|`inherit`)]` + Don't: ++--track++[++=++(`direct` | `inherit`)] Parentheses are used for grouping: - [(<rev> | <range>)...] + [(_<rev>_ | _<range>_)...] (Any number of either <rev> or <range>. Parens are needed to make it clear that "..." pertains to both <rev> and <range>.) - [(-p <parent>)...] + [(`-p` _<parent>_)...] (Any number of option -p, each with one <parent> argument.) - git remote set-head <name> (-a | -d | <branch>) + `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_) (One and only one of "-a", "-d" or "<branch>" _must_ (no square brackets) be provided.) And a somewhat more contrived example: - --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] + `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]` Here "=" is outside the brackets, because "--diff-filter=" is a valid usage. "*" has its own pair of brackets, because it can (optionally) be specified only when one or more of the letters is @@ -720,37 +820,6 @@ Writing Documentation: the user would type into a shell and use 'Git' (uppercase first letter) when talking about the version control system and its properties. - A few commented examples follow to provide reference when writing or - modifying paragraphs or option/command explanations that contain options - or commands: - - Literal examples (e.g. use of command-line options, command names, - branch names, URLs, pathnames (files and directories), configuration and - environment variables) must be typeset in monospace (i.e. wrapped with - backticks): - `--pretty=oneline` - `git rev-list` - `remote.pushDefault` - `http://git.example.com` - `.git/config` - `GIT_DIR` - `HEAD` - - An environment variable must be prefixed with "$" only when referring to its - value and not when referring to the variable itself, in this case there is - nothing to add except the backticks: - `GIT_DIR` is specified - `$GIT_DIR/hooks/pre-receive` - - Word phrases enclosed in `backtick characters` are rendered literally - and will not be further expanded. The use of `backticks` to achieve the - previous rule means that literal examples should not use AsciiDoc - escapes. - Correct: - `--pretty=oneline` - Incorrect: - `\--pretty=oneline` - If some place in the documentation needs to typeset a command usage example with inline substitutions, it is fine to use +monospaced and inline substituted text+ instead of `monospaced literal text`, and with diff --git a/Documentation/Makefile b/Documentation/Makefile index b629176..3f2383a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -122,6 +122,7 @@ TECH_DOCS += technical/scalar TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow TECH_DOCS += technical/trivial-merge +TECH_DOCS += technical/unit-tests SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 7cfed60..f06563e 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -35,8 +35,9 @@ announcements, design discussions, and more take place. Those interested in contributing are welcome to post questions here. The Git list requires plain-text-only emails and prefers inline and bottom-posting when replying to mail; you will be CC'd in all replies to you. Optionally, you can subscribe to -the list by sending an email to majordomo@vger.kernel.org with "subscribe git" -in the body. The https://lore.kernel.org/git[archive] of this mailing list is +the list by sending an email to <git+subscribe@vger.kernel.org> +(see https://subspace.kernel.org/subscribing.html for details). +The https://lore.kernel.org/git[archive] of this mailing list is available to view in a browser. ==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com] @@ -833,7 +834,7 @@ Johannes Schindelin to make life as a Git contributor easier for those used to the GitHub PR workflow. It allows contributors to open pull requests against its mirror of the Git project, and does some magic to turn the PR into a set of emails and send them out for you. It also runs the Git continuous integration -suite for you. It's documented at http://gitgitgadget.github.io. +suite for you. It's documented at https://gitgitgadget.github.io/. [[create-fork]] === Forking `git/git` on GitHub diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index c68cdb1..dec8afe 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -210,13 +210,14 @@ We'll also need to include the `config.h` header: ... -static int git_walken_config(const char *var, const char *value, void *cb) +static int git_walken_config(const char *var, const char *value, + const struct config_context *ctx, void *cb) { /* * For now, we don't have any custom configuration, so fall back to * the default config. */ - return git_default_config(var, value, cb); + return git_default_config(var, value, ctx, cb); } ---- @@ -389,10 +390,11 @@ modifying `rev_info.grep_filter`, which is a `struct grep_opt`. First some setup. Add `grep_config()` to `git_walken_config()`: ---- -static int git_walken_config(const char *var, const char *value, void *cb) +static int git_walken_config(const char *var, const char *value, + const struct config_context *ctx, void *cb) { - grep_config(var, value, cb); - return git_default_config(var, value, cb); + grep_config(var, value, ctx, cb); + return git_default_config(var, value, ctx, cb); } ---- @@ -523,7 +525,7 @@ about each one. We can base our work on an example. `git pack-objects` prepares all kinds of objects for packing into a bitmap or packfile. The work we are interested in -resides in `builtins/pack-objects.c:get_object_list()`; examination of that +resides in `builtin/pack-objects.c:get_object_list()`; examination of that function shows that the all-object walk is being performed by `traverse_commit_list()` or `traverse_commit_list_filtered()`. Those two functions reside in `list-objects.c`; examining the source shows that, despite @@ -732,8 +734,8 @@ walk we've just performed: } else { trace_printf( _("Filtered object walk with filterspec 'tree:1'.\n")); - CALLOC_ARRAY(rev->filter, 1); - parse_list_objects_filter(rev->filter, "tree:1"); + + parse_list_objects_filter(&rev->filter, "tree:1"); } traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL); @@ -752,10 +754,12 @@ points to the same tree object as its grandparent.) === Counting Omitted Objects We also have the capability to enumerate all objects which were omitted by a -filter, like with `git log --filter=<spec> --filter-print-omitted`. Asking -`traverse_commit_list_filtered()` to populate the `omitted` list means that our -object walk does not perform any better than an unfiltered object walk; all -reachable objects are walked in order to populate the list. +filter, like with `git log --filter=<spec> --filter-print-omitted`. To do this, +change `traverse_commit_list()` to `traverse_commit_list_filtered()`, which is +able to populate an `omitted` list. Asking for this list of filtered objects +may cause performance degradations, however, because in this case, despite +filtering objects, the possibly much larger set of all reachable objects must +be processed in order to populate that list. First, add the `struct oidset` and related items we will use to iterate it: @@ -776,8 +780,9 @@ static void walken_object_walk( ... ---- -Modify the call to `traverse_commit_list_filtered()` to include your `omitted` -object: +Replace the call to `traverse_commit_list()` with +`traverse_commit_list_filtered()` and pass a pointer to the `omitted` oidset +defined and initialized above: ---- ... @@ -843,7 +848,7 @@ those lines without having to recompile. With only that change, run again (but save yourself some scrollback): ---- -$ GIT_TRACE=1 ./bin-wrappers/git walken | head -n 10 +$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | head -n 10 ---- Take a look at the top commit with `git show` and the object ID you printed; it @@ -871,7 +876,7 @@ of the first handful: ---- $ make -$ GIT_TRACE=1 ./bin-wrappers git walken | tail -n 10 +$ GIT_TRACE=1 ./bin-wrappers/git walken 2>&1 | tail -n 10 ---- The last commit object given should have the same OID as the one we saw at the diff --git a/Documentation/RelNotes/1.6.2.txt b/Documentation/RelNotes/1.6.2.txt index 980adfb..166d73c 100644 --- a/Documentation/RelNotes/1.6.2.txt +++ b/Documentation/RelNotes/1.6.2.txt @@ -10,7 +10,7 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/1.6.3.txt b/Documentation/RelNotes/1.6.3.txt index 4bcff94..bbf177f 100644 --- a/Documentation/RelNotes/1.6.3.txt +++ b/Documentation/RelNotes/1.6.3.txt @@ -10,7 +10,7 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/1.6.4.txt b/Documentation/RelNotes/1.6.4.txt index a2a34b4..0fccfb0 100644 --- a/Documentation/RelNotes/1.6.4.txt +++ b/Documentation/RelNotes/1.6.4.txt @@ -10,7 +10,7 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/1.6.5.txt b/Documentation/RelNotes/1.6.5.txt index 6c7f7da..79cb1b2 100644 --- a/Documentation/RelNotes/1.6.5.txt +++ b/Documentation/RelNotes/1.6.5.txt @@ -21,7 +21,7 @@ To ease the transition plan, the receiving repository of such a push running this release will issue a big warning when the configuration variable is missing. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/1.6.6.txt b/Documentation/RelNotes/1.6.6.txt index 3ed1e01..88b86a8 100644 --- a/Documentation/RelNotes/1.6.6.txt +++ b/Documentation/RelNotes/1.6.6.txt @@ -63,7 +63,7 @@ users will fare this time. Please refer to: - http://git.or.cz/gitwiki/GitFaq#non-bare + https://archive.kernel.org/oldwiki/git.wiki.kernel.org/index.php/GitFaq.html#non-bare https://lore.kernel.org/git/7vbptlsuyv.fsf@gitster.siamese.dyndns.org/ for more details on the reason why this change is needed and the diff --git a/Documentation/RelNotes/2.39.4.txt b/Documentation/RelNotes/2.39.4.txt new file mode 100644 index 0000000..7f54521 --- /dev/null +++ b/Documentation/RelNotes/2.39.4.txt @@ -0,0 +1,79 @@ +Git v2.39.4 Release Notes +========================= + +This addresses the security issues CVE-2024-32002, CVE-2024-32004, +CVE-2024-32020 and CVE-2024-32021. + +This release also backports fixes necessary to let the CI builds pass +successfully. + +Fixes since v2.39.3 +------------------- + + * CVE-2024-32002: + + Recursive clones on case-insensitive filesystems that support symbolic + links are susceptible to case confusion that can be exploited to + execute just-cloned code during the clone operation. + + * CVE-2024-32004: + + Repositories can be configured to execute arbitrary code during local + clones. To address this, the ownership checks introduced in v2.30.3 + are now extended to cover cloning local repositories. + + * CVE-2024-32020: + + Local clones may end up hardlinking files into the target repository's + object database when source and target repository reside on the same + disk. If the source repository is owned by a different user, then + those hardlinked files may be rewritten at any point in time by the + untrusted user. + + * CVE-2024-32021: + + When cloning a local source repository that contains symlinks via the + filesystem, Git may create hardlinks to arbitrary user-readable files + on the same filesystem as the target repository in the objects/ + directory. + + * CVE-2024-32465: + + It is supposed to be safe to clone untrusted repositories, even those + unpacked from zip archives or tarballs originating from untrusted + sources, but Git can be tricked to run arbitrary code as part of the + clone. + + * Defense-in-depth: submodule: require the submodule path to contain + directories only. + + * Defense-in-depth: clone: when symbolic links collide with directories, keep + the latter. + + * Defense-in-depth: clone: prevent hooks from running during a clone. + + * Defense-in-depth: core.hooksPath: add some protection while cloning. + + * Defense-in-depth: fsck: warn about symlink pointing inside a gitdir. + + * Various fix-ups on HTTP tests. + + * Test update. + + * HTTP Header redaction code has been adjusted for a newer version of + cURL library that shows its traces differently from earlier + versions. + + * Fix was added to work around a regression in libcURL 8.7.0 (which has + already been fixed in their tip of the tree). + + * Replace macos-12 used at GitHub CI with macos-13. + + * ci(linux-asan/linux-ubsan): let's save some time + + * Tests with LSan from time to time seem to emit harmless message that makes + our tests unnecessarily flakey; we work it around by filtering the + uninteresting output. + + * Update GitHub Actions jobs to avoid warnings against using deprecated + version of Node.js. diff --git a/Documentation/RelNotes/2.40.2.txt b/Documentation/RelNotes/2.40.2.txt new file mode 100644 index 0000000..646a2cc --- /dev/null +++ b/Documentation/RelNotes/2.40.2.txt @@ -0,0 +1,7 @@ +Git v2.40.2 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4 to address +the security issues CVE-2024-32002, CVE-2024-32004, CVE-2024-32020, +CVE-2024-32021 and CVE-2024-32465; see the release notes for that +version for details. diff --git a/Documentation/RelNotes/2.41.1.txt b/Documentation/RelNotes/2.41.1.txt new file mode 100644 index 0000000..9fb4c21 --- /dev/null +++ b/Documentation/RelNotes/2.41.1.txt @@ -0,0 +1,7 @@ +Git v2.41.1 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4 and v2.40.2 +to address the security issues CVE-2024-32002, CVE-2024-32004, +CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.42.2.txt b/Documentation/RelNotes/2.42.2.txt new file mode 100644 index 0000000..dbf761a --- /dev/null +++ b/Documentation/RelNotes/2.42.2.txt @@ -0,0 +1,7 @@ +Git v2.42.2 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4, v2.40.2 +and v2.41.1 to address the security issues CVE-2024-32002, +CVE-2024-32004, CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.43.1.txt b/Documentation/RelNotes/2.43.1.txt new file mode 100644 index 0000000..20e96f2 --- /dev/null +++ b/Documentation/RelNotes/2.43.1.txt @@ -0,0 +1,82 @@ +Git 2.43.1 Release Notes +======================== + +There is nothing exciting to see here. Relative to Git 2.43, this +release contains the fixes that have already been merged to the +'master' branch of the development towards the next major release. + +Fixes since Git 2.43.0 +---------------------- + + * The way CI testing used "prove" could lead to running the test + suite twice needlessly, which has been corrected. + + * Newer versions of Getopt::Long started giving warnings against our + (ab)use of it in "git send-email". Bump the minimum version + requirement for Perl to 5.8.1 (from September 2002) to allow + simplifying our implementation. + + * Earlier we stopped relying on commit-graph that (still) records + information about commits that are lost from the object store, + which has negative performance implications. The default has been + flipped to disable this pessimization. + + * Stale URLs have been updated to their current counterparts (or + archive.org) and HTTP links are replaced with working HTTPS links. + + * trace2 streams used to record the URLs that potentially embed + authentication material, which has been corrected. + + * The sample pre-commit hook that tries to catch introduction of new + paths that use potentially non-portable characters did not notice + an existing path getting renamed to such a problematic path, when + rename detection was enabled. + + * The command line parser for the "log" family of commands was too + loose when parsing certain numbers, e.g., silently ignoring the + extra 'q' in "git log -n 1q" without complaining, which has been + tightened up. + + * "git $cmd --end-of-options --rev -- --path" for some $cmd failed + to interpret "--rev" as a rev, and "--path" as a path. This was + fixed for many programs like "reset" and "checkout". + + * "git bisect reset" has been taught to clean up state files and refs + even when BISECT_START file is gone. + + * Some codepaths did not correctly parse configuration variables + specified with valueless "true", which has been corrected. + + * Code clean-up for sanity checking of command line options for "git + show-ref". + + * The code to parse the From e-mail header has been updated to avoid + recursion. + + * "git fetch --atomic" issued an unnecessary empty error message, + which has been corrected. + + * Command line completion script (in contrib/) learned to work better + with the reftable backend. + + * "git status" is taught to show both the branch being bisected and + being rebased when both are in effect at the same time. + cf. <xmqqil76kyov.fsf@gitster.g> + + * "git archive --list extra garbage" silently ignored excess command + line parameters, which has been corrected. + + * "git sparse-checkout set" added default patterns even when the + patterns are being fed from the standard input, which has been + corrected. + + * Unlike other environment variables that took the usual + true/false/yes/no as well as 0/1, GIT_FLUSH only understood 0/1, + which has been corrected. + + * Clearing in-core repository (happens during e.g., "git fetch + --recurse-submodules" with commit graph enabled) made in-core + commit object in an inconsistent state by discarding the necessary + data from commit-graph too early, which has been corrected. + +Also contains various documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.43.2.txt b/Documentation/RelNotes/2.43.2.txt new file mode 100644 index 0000000..5895e23 --- /dev/null +++ b/Documentation/RelNotes/2.43.2.txt @@ -0,0 +1,37 @@ +Git 2.43.2 Release Notes +======================== + +Relative to Git 2.43.1, this release has two important fixes to allow +"git imap-send" to be built with NO_CURL defined, and to restore the +forced flushing behaviour when GIT_FLUSH=1 is set. It also contains +other, unexciting, fixes that have already been merged to the 'master' +branch of the development towards the next major release. + +Fixes since Git 2.43.1 +---------------------- + + * Update to a new feature recently added, "git show-ref --exists". + + * Rename detection logic ignored the final line of a file if it is an + incomplete line. + + * "git diff --no-rename A B" did not disable rename detection but did + not trigger an error from the command line parser. + + * "git diff --no-index file1 file2" segfaulted while invoking the + external diff driver, which has been corrected. + + * Rewrite //-comments to /* comments */ in files whose comments + prevalently use the latter. + + * A failed "git tag -s" did not necessarily result in an error + depending on the crypto backend, which has been corrected. + + * "git stash" sometimes was silent even when it failed due to + unwritable index file, which has been corrected. + + * Recent conversion to allow more than 0/1 in GIT_FLUSH broke the + mechanism by flipping what yes/no means by mistake, which has been + corrected. + +Also contains documentation updates, code clean-ups and minor fixups. diff --git a/Documentation/RelNotes/2.43.3.txt b/Documentation/RelNotes/2.43.3.txt new file mode 100644 index 0000000..924f205 --- /dev/null +++ b/Documentation/RelNotes/2.43.3.txt @@ -0,0 +1,12 @@ +Git 2.43.3 Release Notes +======================== + +Relative to Git 2.43.2, this release fixes one regression that +manifests while running "git commit -v --trailer". + +Fixes since Git 2.43.2 +---------------------- + + * "git commit -v --trailer=..." was broken with recent update and + placed the trailer _after_ the divider line, which has been + corrected. diff --git a/Documentation/RelNotes/2.43.4.txt b/Documentation/RelNotes/2.43.4.txt new file mode 100644 index 0000000..0a84251 --- /dev/null +++ b/Documentation/RelNotes/2.43.4.txt @@ -0,0 +1,7 @@ +Git v2.43.4 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4, v2.40.2, +v2.41.1 and v2.42.2 to address the security issues CVE-2024-32002, +CVE-2024-32004, CVE-2024-32020, CVE-2024-32021 and CVE-2024-32465; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.44.0.txt b/Documentation/RelNotes/2.44.0.txt new file mode 100644 index 0000000..14f9ce8 --- /dev/null +++ b/Documentation/RelNotes/2.44.0.txt @@ -0,0 +1,334 @@ +Git v2.44 Release Notes +======================= + +Backward Compatibility Notes + + * "git checkout -B <branch>" used to allow switching to a branch that + is in use on another worktree, but this was by mistake. The users + need to use "--ignore-other-worktrees" option. + + +UI, Workflows & Features + + * "git add" and "git stash" learned to support the ":(attr:...)" + magic pathspec. + + * "git rebase --autosquash" is now enabled for non-interactive rebase, + but it is still incompatible with the apply backend. + + * Introduce "git replay", a tool meant on the server side without + working tree to recreate a history. + + * "git merge-file" learned to take the "--diff-algorithm" option to + use algorithm different from the default "myers" diff. + + * Command line completion (in contrib/) learned to complete path + arguments to the "add/set" subcommands of "git sparse-checkout" + better. + + * "git checkout -B <branch> [<start-point>]" allowed a branch that is + in use in another worktree to be updated and checked out, which + might be a bit unexpected. The rule has been tightened, which is a + breaking change. "--ignore-other-worktrees" option is required to + unbreak you, if you are used to the current behaviour that "-B" + overrides the safety. + + * The builtin_objectmode attribute is populated for each path + without adding anything in .gitattributes files, which would be + useful in magic pathspec, e.g., ":(attr:builtin_objectmode=100755)" + to limit to executables. + + * "git fetch" learned to pay attention to "fetch.all" configuration + variable, which pretends as if "--all" was passed from the command + line when no remote parameter was given. + + * In addition to (rather cryptic) Security Identifiers, show username + and domain in the error message when we barf on mismatch between + the Git directory and the current user on Windows. + + * The error message given when "git branch -d branch" fails due to + commits unique to the branch has been split into an error and a new + conditional advice message. + + * When given an existing but unreadable file as a configuration file, + gitweb behaved as if the file did not exist at all, but now it + errors out. This is a change that may break backward compatibility. + + * When $HOME/.gitconfig is missing but XDG config file is available, we + should write into the latter, not former. "git gc" and "git + maintenance" wrote into a wrong "global config" file, which have + been corrected. + + * Define "special ref" as a very narrow set that consists of + FETCH_HEAD and MERGE_HEAD, and clarify everything else that used to + be classified as such are actually just pseudorefs. + + * All conditional "advice" messages show how to turn them off, which + becomes repetitive. Setting advice.* configuration explicitly on + now omits the instruction part. + + * The "disable repository discovery of a bare repository" check, + triggered by setting safe.bareRepository configuration variable to + 'explicit', has been loosened to exclude the ".git/" directory inside + a non-bare repository from the check. So you can do "cd .git && + git cmd" to run a Git command that works on a bare repository without + explicitly specifying $GIT_DIR now. + + * The completion script (in contrib/) learned more options that can + be used with "git log". + + * The labels on conflict markers for the common ancestor, our version, + and the other version are available to custom 3-way merge driver + via %S, %X, and %Y placeholders. + + * The write codepath for the reftable data learned to honor + core.fsync configuration. + + * The "--fsck-objects" option of "git index-pack" now can take the + optional parameter to tweak severity of different fsck errors. + + * The wincred credential backend has been taught to support oauth + refresh token the same way as credential-cache and + credential-libsecret backends. + + * Command line completion support (in contrib/) has been + updated for "git bisect". + + * "git branch" and friends learned to use the formatted text as + sorting key, not the underlying timestamp value, when the --sort + option is used with author or committer timestamp with a format + specifier (e.g., "--sort=creatordate:format:%H:%M:%S"). + + * The command line completion script (in contrib/) learned to + complete configuration variable names better. + + +Performance, Internal Implementation, Development Support etc. + + * Process to add some form of low-level unit tests has started. + + * Add support for GitLab CI. + + * "git for-each-ref --no-sort" still sorted the refs alphabetically + which paid non-trivial cost. It has been redefined to show output + in an unspecified order, to allow certain optimizations to take + advantage of. + + * Simplify API implementation to delete references by eliminating + duplication. + + * Subject approxidate() and show_date() machinery to OSS-Fuzz. + + * A new helper to let us pretend that we called lstat() when we know + our cache_entry is up-to-date via fsmonitor. + + * The optimization based on fsmonitor in the "diff --cached" + codepath is resurrected with the "fake-lstat" introduced earlier. + + * Test balloon to use C99 "bool" type from <stdbool.h> has been + added. + + * "git clone" has been prepared to allow cloning a repository with + non-default hash function into a repository that uses the reftable + backend. + + * Streaming spans of packfile data used to be done only from a + single, primary, pack in a repository with multiple packfiles. It + has been extended to allow reuse from other packfiles, too. + + * Comment updates to help developers not to attempt to modify + messages from plumbing commands that must stay constant. + + It might make sense to reassess the plumbing needs every few years, + but that should be done as a separate effort. + + * Move test-ctype helper to the unit-test framework. + + * Instead of manually creating refs/ hierarchy on disk upon a + creation of a secondary worktree, which is only usable via the + files backend, use the refs API to populate it. + + * CI for GitLab learned to drive macOS jobs. + + * A few tests to "git commit -o <pathspec>" and "git commit -i + <pathspec>" has been added. + + * Tests on ref API are moved around to prepare for reftable. + + * The Makefile often had to say "-L$(path) -R$(path)" that repeats + the path to the same library directory for link time and runtime. + A Makefile template is used to reduce such repetition. + + * The priority queue test has been migrated to the unit testing + framework. + + * Setting `feature.experimental` opts the user into multi-pack reuse + experiment + + * Squelch node.js 16 deprecation warnings from GitHub Actions CI + by updating actions/github-script and actions/checkout that use + node.js 20. + + * The mechanism to report the filename in the source code, used by + the unit-test machinery, assumed that the compiler expanded __FILE__ + to the path to the source given to the $(CC), but some compilers + give full path, breaking the output. This has been corrected. + + +Fixes since v2.43 +----------------- + + * The way CI testing used "prove" could lead to running the test + suite twice needlessly, which has been corrected. + + * Update ref-related tests. + + * "git format-patch --encode-email-headers" ignored the option when + preparing the cover letter, which has been corrected. + + * Newer versions of Getopt::Long started giving warnings against our + (ab)use of it in "git send-email". Bump the minimum version + requirement for Perl to 5.8.1 (from September 2002) to allow + simplifying our implementation. + + * Earlier we stopped relying on commit-graph that (still) records + information about commits that are lost from the object store, + which has negative performance implications. The default has been + flipped to disable this pessimization. + + * Stale URLs have been updated to their current counterparts (or + archive.org) and HTTP links are replaced with working HTTPS links. + + * trace2 streams used to record the URLs that potentially embed + authentication material, which has been corrected. + + * The sample pre-commit hook that tries to catch introduction of new + paths that use potentially non-portable characters did not notice + an existing path getting renamed to such a problematic path, when + rename detection was enabled. + + * The command line parser for the "log" family of commands was too + loose when parsing certain numbers, e.g., silently ignoring the + extra 'q' in "git log -n 1q" without complaining, which has been + tightened up. + + * "git $cmd --end-of-options --rev -- --path" for some $cmd failed + to interpret "--rev" as a rev, and "--path" as a path. This was + fixed for many programs like "reset" and "checkout". + + * "git bisect reset" has been taught to clean up state files and refs + even when BISECT_START file is gone. + + * Some codepaths did not correctly parse configuration variables + specified with valueless "true", which has been corrected. + + * Code clean-up for sanity checking of command line options for "git + show-ref". + + * The code to parse the From e-mail header has been updated to avoid + recursion. + + * "git fetch --atomic" issued an unnecessary empty error message, + which has been corrected. + + * Command line completion script (in contrib/) learned to work better + with the reftable backend. + + * "git status" is taught to show both the branch being bisected and + being rebased when both are in effect at the same time. + + * "git archive --list extra garbage" silently ignored excess command + line parameters, which has been corrected. + + * "git sparse-checkout set" added default patterns even when the + patterns are being fed from the standard input, which has been + corrected. + + * "git sparse-checkout (add|set) --[no-]cone --end-of-options" did + not handle "--end-of-options" correctly after a recent update. + + * Unlike other environment variables that took the usual + true/false/yes/no as well as 0/1, GIT_FLUSH only understood 0/1, + which has been corrected. + + * Clearing in-core repository (happens during e.g., "git fetch + --recurse-submodules" with commit graph enabled) made in-core + commit object in an inconsistent state by discarding the necessary + data from commit-graph too early, which has been corrected. + + * Update to a new feature recently added, "git show-ref --exists". + + * oss-fuzz tests are built and run in CI. + (merge c4a9cf1df3 js/oss-fuzz-build-in-ci later to maint). + + * Rename detection logic ignored the final line of a file if it is an + incomplete line. + + * GitHub CI update. + (merge 0188b2c8e0 pb/ci-github-skip-logs-for-broken-tests later to maint). + + * "git diff --no-rename A B" did not disable rename detection but did + not trigger an error from the command line parser. + + * "git archive --remote=<remote>" learned to talk over the smart + http (aka stateless) transport. + (merge 176cd68634 jx/remote-archive-over-smart-http later to maint). + + * Fetching via protocol v0 over Smart HTTP transport sometimes failed + to correctly auto-follow tags. + (merge fba732c462 jk/fetch-auto-tag-following-fix later to maint). + + * The documentation for the --exclude-per-directory option marked it + as deprecated, which confused readers into thinking there may be a + plan to remove it in the future, which was not our intention. + (merge 0009542cab jc/ls-files-doc-update later to maint). + + * "git diff --no-index file1 file2" segfaulted while invoking the + external diff driver, which has been corrected. + + * Rewrite //-comments to /* comments */ in files whose comments + prevalently use the latter. + + * Cirrus CI jobs started breaking because we specified version of + FreeBSD that is no longer available, which has been corrected. + (merge 81fffb66d3 cb/use-freebsd-13-2-at-cirrus-ci later to maint). + + * A caller called index_file_exists() that takes a string expressed + as <ptr, length> with a wrong length, which has been corrected. + (merge 156e28b36d jh/sparse-index-expand-to-path-fix later to maint). + + * A failed "git tag -s" did not necessarily result in an error + depending on the crypto backend, which has been corrected. + + * "git stash" sometimes was silent even when it failed due to + unwritable index file, which has been corrected. + + * "git show-ref --verify" did not show things like "CHERRY_PICK_HEAD", + which has been corrected. + + * Recent conversion to allow more than 0/1 in GIT_FLUSH broke the + mechanism by flipping what yes/no means by mistake, which has been + corrected. + + * The sequencer machinery does not use the ref API and instead + records names of certain objects it needs for its correct operation + in temporary files, which makes these objects susceptible to loss + by garbage collection. These temporary files have been added as + starting points for reachability analysis to fix this. + (merge bc7f5db896 pw/gc-during-rebase later to maint). + + * "git cherry-pick" invoked during "git rebase -i" session lost + the authorship information, which has been corrected. + (merge e4301f73ff vn/rebase-with-cherry-pick-authorship later to maint). + + * The code paths that call repo_read_object_file() have been + tightened to react to errors. + (merge 568459bf5e js/check-null-from-read-object-file later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 5aea3955bc rj/clarify-branch-doc-m later to maint). + (merge 9cce3be2df bk/bisect-doc-fix later to maint). + (merge 8430b438f6 vd/fsck-submodule-url-test later to maint). + (merge 3cb4384683 jc/t0091-with-unknown-git later to maint). + (merge 020456cb74 rs/receive-pack-remove-find-header later to maint). + (merge bc47139f4f la/trailer-cleanups later to maint). diff --git a/Documentation/RelNotes/2.44.1.txt b/Documentation/RelNotes/2.44.1.txt new file mode 100644 index 0000000..b5135c3 --- /dev/null +++ b/Documentation/RelNotes/2.44.1.txt @@ -0,0 +1,8 @@ +Git v2.44.1 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4, v2.40.2, +v2.41.1, v2.42.2 and v2.43.4 to address the security issues +CVE-2024-32002, CVE-2024-32004, CVE-2024-32020, CVE-2024-32021 +and CVE-2024-32465; see the release notes for these versions +for details. diff --git a/Documentation/RelNotes/2.45.0.txt b/Documentation/RelNotes/2.45.0.txt new file mode 100644 index 0000000..fec1936 --- /dev/null +++ b/Documentation/RelNotes/2.45.0.txt @@ -0,0 +1,476 @@ +Git v2.45 Release Notes +======================= + +Backward Compatibility Notes + +UI, Workflows & Features + + * Integrate the reftable code into the refs framework as a backend. + With "git init --ref-format=reftable", hopefully it would be a lot + more efficient to manage a repository with many references. + + * "git checkout -p" and friends learned that that "@" is a synonym + for "HEAD". + + * Variants of vimdiff learned to honor mergetool.<variant>.layout + settings. + + * "git reflog" learned a "list" subcommand that enumerates known reflogs. + + * When a merge conflicted at a submodule, merge-ort backend used to + unconditionally give a lengthy message to suggest how to resolve + it. Now the message can be squelched as an advice message. + + * "git for-each-ref" learned "--include-root-refs" option to show + even the stuff outside the 'refs/' hierarchy. + + * "git rev-list --missing=print" has learned to optionally take + "--allow-missing-tips", which allows the objects at the starting + points to be missing. + + * "git merge-tree" has learned that the three trees involved in the + 3-way merge only need to be trees, not necessarily commits. + + * "git log --merge" learned to pay attention to CHERRY_PICK_HEAD and + other kinds of *_HEAD pseudorefs. + + * Platform specific tweaks for OS/390 has been added to + config.mak.uname. + + * Users with safe.bareRepository=explicit can still work from within + $GIT_DIR of a seconary worktree (which resides at .git/worktrees/$name/) + of the primary worktree without explicitly specifying the $GIT_DIR + environment variable or the --git-dir=<path> option. + + * The output format for dates "iso-strict" has been tweaked to show + a time in the Zulu timezone with "Z" suffix, instead of "+00:00". + + * "git diff" and friends learned two extra configuration variables, + diff.srcPrefix and diff.dstPrefix. + + * The status.showUntrackedFiles configuration variable had a name + that tempts users to set a Boolean value expressed in our usual + "false", "off", and "0", but it only took "no". This has been + corrected so "true" and its synonyms are taken as "normal", while + "false" and its synonyms are taken as "no". + + * Remove an ancient and not well maintained Hg-to-git migration + script from contrib/. + + * Hints that suggest what to do after resolving conflicts can now be + squelched by disabling advice.mergeConflict. + + * Allow git-cherry-pick(1) to automatically drop redundant commits via + a new `--empty` option, similar to the `--empty` options for + git-rebase(1) and git-am(1). Includes a soft deprecation of + `--keep-redundant-commits` as well as some related docs changes and + sequencer code cleanup. + + * "git config" learned "--comment=<message>" option to leave a + comment immediately after the "variable = value" on the same line + in the configuration file. + + * core.commentChar used to be limited to a single byte, but has been + updated to allow an arbitrary multi-byte sequence. + + * "git add -p" and other "interactive hunk selection" UI has learned to + skip showing the hunk immediately after it has already been shown, and + an additional action to explicitly ask to reshow the current hunk. + + * "git pack-refs" learned the "--auto" option, which defers the decision of + whether and how to pack to the ref backend. This is used by the reftable + backend to avoid repacking of an already-optimal ref database. The new mode + is triggered from "git gc --auto". + + * "git add -u <pathspec>" and "git commit [-i] <pathspec>" did not + diagnose a pathspec element that did not match any files in certain + situations, unlike "git add <pathspec>" did. + + * The userdiff patterns for C# has been updated. + + * Git writes a "waiting for your editor" message on an incomplete + line after launching an editor, and then append another error + message on the same line if the editor errors out. It now clears + the "waiting for..." line before giving the error message. + + * The filename used for rejected hunks "git apply --reject" creates + was limited to PATH_MAX, which has been lifted. + + * When "git bisect" reports the commit it determined to be the + culprit, we used to show it in a format that does not honor common + UI tweaks, like log.date and log.decorate. The code has been + taught to use "git show" to follow more customizations. + + +Performance, Internal Implementation, Development Support etc. + + * The code to iterate over refs with the reftable backend has seen + some optimization. + + * More tests that are marked as "ref-files only" have been updated to + improve test coverage of reftable backend. + + * Some parts of command line completion script (in contrib/) have + been micro-optimized. + + * The way placeholders are to be marked-up in documentation have been + specified; use "_<placeholder>_" to typeset the word inside a pair + of <angle-brackets> emphasized. + + * "git --no-lazy-fetch cmd" allows to run "cmd" while disabling lazy + fetching of objects from the promisor remote, which may be handy + for debugging. + + * The implementation in "git clean" that makes "-n" and "-i" ignore + clean.requireForce has been simplified, together with the + documentation. + + * Uses of xwrite() helper have been audited and updated for better + error checking and simpler code. + + * Some trace2 events that lacked def_param have learned to show it, + enriching the output. + + * The parse-options code that deals with abbreviated long option + names have been cleaned up. + + * The code in reftable backend that creates new table files works + better with the tempfile framework to avoid leaving cruft after a + failure. + + * The reftable code has its own custom binary search function whose + comparison callback has an unusual interface, which caused the + binary search to degenerate into a linear search, which has been + corrected. + + * The code to iterate over reflogs in the reftable has been optimized + to reduce memory allocation and deallocation. + + * Work to support a repository that work with both SHA-1 and SHA-256 + hash algorithms has started. + + * A new fuzz target that exercises config parsing code has been + added. + + * Fix the way recently added tests interpolate variables defined + outside them, and document the best practice to help future + developers. + + * Introduce an experimental protocol for contributors to propose the + topic description to be used in the "What's cooking" report, the + merge commit message for the topic, and in the release notes and + document it in the SubmittingPatches document. + + * The t/README file now gives a hint on running individual tests in + the "t/" directory with "make t<num>-*.sh t<num>-*.sh". + (merge 8d383806fc pb/test-scripts-are-build-targets later to maint). + + * The "hint:" messages given by the advice mechanism, when given a + message with a blank line, left a line with trailing whitespace, + which has been cleansed. + + * Documentation rules has been explicitly described how to mark-up + literal parts and a few manual pages have been updated as examples. + + * The .editorconfig file has been taught that a Makefile uses HT + indentation. + + * t-prio-queue test has been cleaned up by using C99 compound + literals; this is meant to also serve as a weather-balloon to smoke + out folks with compilers who have trouble compiling code that uses + the feature. + + * Windows binary used to decide the use of unix-domain socket at + build time, but it learned to make the decision at runtime instead. + + * The "shared repository" test in the t0610 reftable test failed + under restrictive umask setting (e.g. 007), which has been + corrected. + + * Document and apply workaround for a buggy version of dash that + mishandles "local var=val" construct. + + * The codepaths that reach date_mode_from_type() have been updated to + pass "struct date_mode" by value to make them thread safe. + + * The strategy to compact multiple tables of reftables after many + operations accumulate many entries has been improved to avoid + accumulating too many tables uncollected. + + * The code to iterate over reftable blocks has seen some optimization + to reduce memory allocation and deallocation. + + * The way "git fast-import" handles paths described in its input has + been tightened up and more clearly documented. + + * The cvsimport tests required that the platform understands + traditional timezone notations like CST6CDT, which has been + updated to work on those systems as long as they understand + POSIX notation with explicit tz transition dates. + + * The code to format trailers have been cleaned up. + + +Fixes since v2.44 +----------------- + + * "git apply" on a filesystem without filemode support have learned + to take a hint from what is in the index for the path, even when + not working with the "--index" or "--cached" option, when checking + the executable bit match what is required by the preimage in the + patch. + (merge 45b625142d cp/apply-core-filemode later to maint). + + * "git column" has been taught to reject negative padding value, as + it would lead to nonsense behaviour including division by zero. + (merge 76fb807faa kh/column-reject-negative-padding later to maint). + + * "git am --help" now tells readers what actions are available in + "git am --whitespace=<action>", in addition to saying that the + option is passed through to the underlying "git apply". + (merge a171dac734 jc/am-whitespace-doc later to maint). + + * "git tag --column" failed to check the exit status of its "git + column" invocation, which has been corrected. + (merge 92e66478fc rj/tag-column-fix later to maint). + + * Credential helper based on libsecret (in contrib/) has been updated + to handle an empty password correctly. + (merge 8f1f2023b7 mh/libsecret-empty-password-fix later to maint). + + * "git difftool --dir-diff" learned to honor the "--trust-exit-code" + option; it used to always exit with 0 and signalled success. + (merge eb84c8b6ce ps/difftool-dir-diff-exit-code later to maint). + + * The code incorrectly attempted to use textconv cache when asked, + even when we are not running in a repository, which has been + corrected. + (merge affe355fe7 jk/textconv-cache-outside-repo-fix later to maint). + + * Remove an empty file that shouldn't have been added in the first + place. + (merge 4f66942215 js/remove-cruft-files later to maint). + + * The logic to access reflog entries by date and number had ugly + corner cases at the boundaries, which have been cleaned up. + (merge 5edd126720 jk/reflog-special-cases-fix later to maint). + + * An error message from "git upload-pack", which responds to "git + fetch" requests, had a trailing NUL in it, which has been + corrected. + (merge 3f4c7a0805 sg/upload-pack-error-message-fix later to maint). + + * Clarify wording in the CodingGuidelines that requires <git-compat-util.h> + to be the first header file. + (merge 4e89f0e07c jc/doc-compat-util later to maint). + + * "git commit -v --cleanup=scissors" used to add the scissors line + twice in the log message buffer, which has been corrected. + (merge e90cc075cc jt/commit-redundant-scissors-fix later to maint). + + * A custom remote helper no longer cannot access the newly created + repository during "git clone", which is a regression in Git 2.44. + This has been corrected. + (merge 199f44cb2e ps/remote-helper-repo-initialization-fix later to maint). + + * Various parts of upload-pack have been updated to bound the resource + consumption relative to the size of the repository to protect from + abusive clients. + (merge 6cd05e768b jk/upload-pack-bounded-resources later to maint). + + * The upload-pack program, when talking over v2, accepted the + packfile-uris protocol extension from the client, even if it did + not advertise the capability, which has been corrected. + (merge a922bfa3b5 jk/upload-pack-v2-capability-cleanup later to maint). + + * Make sure failure return from merge_bases_many() is properly caught. + (merge 25fd20eb44 js/merge-base-with-missing-commit later to maint). + + * FSMonitor client code was confused when FSEvents were given in a + different case on a case-insensitive filesystem, which has been + corrected. + (merge 29c139ce78 jh/fsmonitor-icase-corner-case-fix later to maint). + + * The "core.commentChar" configuration variable only allows an ASCII + character, which was not clearly documented, which has been + corrected. + (merge fb7c556f58 kh/doc-commentchar-is-a-byte later to maint). + + * With release 2.44 we got rid of all uses of test_i18ngrep and there + is no in-flight topic that adds a new use of it. Make a call to + test_i18ngrep a hard failure, so that we can remove it at the end + of this release cycle. + (merge 381a83dfa3 jc/test-i18ngrep later to maint). + + * The command line completion script (in contrib/) learned to + complete "git reflog" better. + (merge 1284f9cc11 rj/complete-reflog later to maint). + + * The logic to complete the command line arguments to "git worktree" + subcommand (in contrib/) has been updated to correctly honor things + like "git -C dir" etc. + (merge 3574816d98 rj/complete-worktree-paths-fix later to maint). + + * When git refuses to create a branch because the proposed branch + name is not a valid refname, an advice message is given to refer + the user to exact naming rules. + (merge 8fbd903e58 kh/branch-ref-syntax-advice later to maint). + + * Code simplification by getting rid of code that sets an environment + variable that is no longer used. + (merge 72a8d3f027 pw/rebase-i-ignore-cherry-pick-help-environment later to maint). + + * The code to find the effective end of log messages can fall into an + endless loop, which has been corrected. + (merge 2541cba2d6 fs/find-end-of-log-message-fix later to maint). + + * Mark-up used in the documentation has been improved for + consistency. + (merge 45d5ed3e50 ja/doc-markup-fixes later to maint). + + * The status.showUntrackedFiles configuration variable was + incorrectly documented to accept "false", which has been corrected. + + * Leaks from "git restore" have been plugged. + (merge 2f64da0790 rj/restore-plug-leaks later to maint). + + * "git bugreport --no-suffix" was not supported and instead + segfaulted, which has been corrected. + (merge b3b57c69da js/bugreport-no-suffix-fix later to maint). + + * The documentation for "%(trailers[:options])" placeholder in the + "--pretty" option of commands in the "git log" family has been + updated. + (merge bff85a338c bl/doc-key-val-sep-fix later to maint). + + * "git checkout --conflict=bad" reported a bad conflictStyle as if it + were given to a configuration variable; it has been corrected to + report that the command line option is bad. + (merge 5a99c1ac1a pw/checkout-conflict-errorfix later to maint). + + * Code clean-up in the "git log" machinery that implements custom log + message formatting. + (merge 1c10b8e5b0 jk/pretty-subject-cleanup later to maint). + + * "git config" corrupted literal HT characters written in the + configuration file as part of a value, which has been corrected. + (merge e6895c3f97 ds/config-internal-whitespace-fix later to maint). + + * A unit test for reftable code tried to enumerate all files in a + directory after reftable operations and expected to see nothing but + the files it wanted to leave there, but was fooled by .nfs* cruft + files left, which has been corrected. + (merge 0068aa7946 ps/reftable-unit-test-nfs-workaround later to maint). + + * The implementation and documentation of "object-format" option + exchange between the Git itself and its remote helpers did not + quite match, which has been corrected. + + * The "--pretty=<shortHand>" option of the commands in the "git log" + family, defined as "[pretty] shortHand = <expansion>" should have + been looked up case insensitively, but was not, which has been + corrected. + (merge f999d5188b bl/pretty-shorthand-config-fix later to maint). + + * "git apply" failed to extract the filename the patch applied to, + when the change was about an empty file created in or deleted from + a directory whose name ends with a SP, which has been corrected. + (merge 776ffd1a30 jc/apply-parse-diff-git-header-names-fix later to maint). + + * Update a more recent tutorial doc. + (merge 95ab557b4b dg/myfirstobjectwalk-updates later to maint). + + * The test script had an incomplete and ineffective attempt to avoid + clobbering the testing user's real crontab (and its equivalents), + which has been completed. + (merge 73cb87773b es/test-cron-safety later to maint). + + * Use advice_if_enabled() API to rewrite a simple pattern to + call advise() after checking advice_enabled(). + (merge 6412d01527 rj/use-adv-if-enabled later to maint). + + * Another "set -u" fix for the bash prompt (in contrib/) script. + (merge d7805bc743 vs/complete-with-set-u-fix later to maint). + + * "git checkout/switch --detach foo", after switching to the detached + HEAD state, gave the tracking information for the 'foo' branch, + which was pointless. + + * "git apply" has been updated to lift the hardcoded pathname length + limit, which in turn allowed a mksnpath() function that is no + longer used. + (merge 708f7e0590 rs/apply-lift-path-length-limit later to maint). + + * A file descriptor leak in an error codepath, used when "git apply + --reject" fails to create the *.rej file, has been corrected. + (merge 2b1f456adf rs/apply-reject-fd-leakfix later to maint). + + * A config parser callback function fell through instead of returning + after recognising and processing a variable, wasting cycles, which + has been corrected. + (merge a816ccd642 ds/fetch-config-parse-microfix later to maint). + + * Fix was added to work around a regression in libcURL 8.7.0 (which has + already been fixed in their tip of the tree). + (merge 92a209bf24 jk/libcurl-8.7-regression-workaround later to maint). + + * The variable that holds the value read from the core.excludefile + configuration variable used to leak, which has been corrected. + (merge 0e0fefb29f jc/unleak-core-excludesfile later to maint). + + * vreportf(), which is used by error() and friends, has been taught + to give the error message printf-format string when its vsnprintf() + call fails, instead of showing nothing useful to identify the + nature of the error. + (merge c63adab961 rs/usage-fallback-to-show-message-format later to maint). + + * Adjust to an upcoming changes to GNU make that breaks our Makefiles. + (merge 227b8fd902 tb/make-indent-conditional-with-non-spaces later to maint). + + * Git 2.44 introduced a regression that makes the updated code to + barf in repositories with multi-pack index written by older + versions of Git, which has been corrected. + + * When .git/rr-cache/ rerere database gets corrupted or rerere is fed to + work on a file with conflicted hunks resolved incompletely, the rerere + machinery got confused and segfaulted, which has been corrected. + (merge 167395bb47 mr/rerere-crash-fix later to maint). + + * The "receive-pack" program (which responds to "git push") was not + converted to run "git maintenance --auto" when other codepaths that + used to run "git gc --auto" were updated, which has been corrected. + (merge 7bf3057d9c ps/run-auto-maintenance-in-receive-pack later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge f0e578c69c rs/use-xstrncmpz later to maint). + (merge 83e6eb7d7a ba/credential-test-clean-fix later to maint). + (merge 64562d784d jb/doc-interactive-singlekey-do-not-need-perl later to maint). + (merge c431a235e2 cp/t9146-use-test-path-helpers later to maint). + (merge 82d75402d5 ds/doc-send-email-capitalization later to maint). + (merge 41bff66e35 jc/doc-add-placeholder-fix later to maint). + (merge 6835f0efe9 jw/remote-doc-typofix later to maint). + (merge 244001aa20 hs/rebase-not-in-progress later to maint). + (merge 2ca6c07db2 jc/no-include-of-compat-util-from-headers later to maint). + (merge 87bd7fbb9c rs/fetch-simplify-with-starts-with later to maint). + (merge f39addd0d9 rs/name-rev-with-mempool later to maint). + (merge 9a97b43e03 rs/submodule-prefix-simplify later to maint). + (merge 40b8076462 ak/rebase-autosquash later to maint). + (merge 3223204456 eg/add-uflags later to maint). + (merge 5f78d52dce es/config-doc-sort-sections later to maint). + (merge 781fb7b4c2 as/option-names-in-messages later to maint). + (merge 51d41dc243 jk/doc-remote-helpers-markup-fix later to maint). + (merge e1aaf309db pb/ci-win-artifact-names-fix later to maint). + (merge ad538c61da jc/index-pack-fsck-levels later to maint). + (merge 67471bc704 ja/doc-formatting-fix later to maint). + (merge 86f9ce7dd6 bl/doc-config-fixes later to maint). + (merge 0d527842b7 az/grep-group-error-message-update later to maint). + (merge 7c43bdf07b rs/strbuf-expand-bad-format later to maint). + (merge 8b68b48d5c ds/typofix-core-config-doc later to maint). + (merge 39bb692152 rs/imap-send-use-xsnprintf later to maint). + (merge 8d320cec60 jc/t2104-style-fixes later to maint). + (merge b4454d5a7b pw/t3428-cleanup later to maint). + (merge 84a7c33a4b pf/commitish-committish later to maint). + (merge 8882ee9d68 la/mailmap-entry later to maint). + (merge 44bdba2fa6 rs/no-openssl-compilation-fix-on-macos later to maint). + (merge f412d72c19 yb/replay-doc-linkfix later to maint). + (merge 5da40be8d7 xx/rfc2822-date-format-in-doc later to maint). diff --git a/Documentation/RelNotes/2.45.1.txt b/Documentation/RelNotes/2.45.1.txt new file mode 100644 index 0000000..3b0d60c --- /dev/null +++ b/Documentation/RelNotes/2.45.1.txt @@ -0,0 +1,8 @@ +Git v2.45.1 Release Notes +========================= + +This release merges up the fix that appears in v2.39.4, +v2.40.2, v2.41.1, v2.42.2, v2.43.4 and v2.44.1 to address the +security issues CVE-2024-32002, CVE-2024-32004, CVE-2024-32020, +CVE-2024-32021 and CVE-2024-32465; see the release notes for +these versions for details. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index bce7f97..c647c7e 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -355,9 +355,21 @@ If you like, you can put extra tags at the end: patch after a detailed analysis. . `Tested-by:` is used to indicate that the person applied the patch and found it to have the desired effect. - -You can also create your own tag or use one that's in common usage -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". +. `Co-authored-by:` is used to indicate that people exchanged drafts + of a patch before submitting it. +. `Helped-by:` is used to credit someone who suggested ideas for + changes without providing the precise changes in patch form. +. `Mentored-by:` is used to credit someone with helping develop a + patch as part of a mentorship program (e.g., GSoC or Outreachy). +. `Suggested-by:` is used to credit someone with suggesting the idea + for a patch. + +While you can also create your own trailer if the situation warrants it, we +encourage you to instead use one of the common trailers in this project +highlighted above. + +Only capitalize the very first letter of tags, i.e. favor +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". [[git-tools]] === Generate your patch using Git tools out of your commits. @@ -447,6 +459,18 @@ an explanation of changes between each iteration can be kept in Git-notes and inserted automatically following the three-dash line via `git format-patch --notes`. +[[the-topic-summary]] +*This is EXPERIMENTAL*. + +When sending a topic, you can propose a one-paragraph summary that +should appear in the "What's cooking" report when it is picked up to +explain the topic. If you choose to do so, please write a 2-5 line +paragraph that will fit well in our release notes (see many bulleted +entries in the Documentation/RelNotes/* files for examples), and make +it the first paragraph of the cover letter. For a single-patch +series, use the space between the three-dash line and the diffstat, as +described earlier. + [[attachment]] Do not attach the patch as a MIME attachment, compressed or not. Do not let your e-mail client send quoted-printable. Do not let @@ -570,7 +594,7 @@ their trees themselves. master). * Read the Git mailing list, the maintainer regularly posts messages - entitled "What's cooking in git.git" and "What's in git.git" giving + entitled "What's cooking in git.git" giving the status of various proposed changes. == GitHub CI[[GHCI]] @@ -590,11 +614,12 @@ After the initial setup, CI will run whenever you push new changes to your fork of Git on GitHub. You can monitor the test state of all your branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml` -If a branch did not pass all test cases then it is marked with a red -cross. In that case you can click on the failing job and navigate to -"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You -can also download "Artifacts" which are tarred (or zipped) archives -with test data relevant for debugging. +If a branch does not pass all test cases then it will be marked with a +red +x+, instead of a green check. In that case, you can click on the +failing job and navigate to "ci/run-build-and-tests.sh" and/or +"ci/print-test-failures.sh". You can also download "Artifacts" which +are zip archives containing tarred (or zipped) archives with test data +relevant for debugging. Then fix the problem and push your fix to your GitHub fork. This will trigger a new CI build to ensure all tests pass. @@ -686,7 +711,7 @@ message to an external program, and this is a handy way to drive `git am`. However, if the message is MIME encoded, what is piped into the program is the representation you see in your `*Article*` buffer after unwrapping MIME. This is often not what -you would want for two reasons. It tends to screw up non ASCII +you would want for two reasons. It tends to screw up non-ASCII characters (most notably in people's names), and also whitespaces (fatal in patches). Running "C-u g" to display the message in raw form before using "|" to run the pipe can work diff --git a/Documentation/config.txt b/Documentation/config.txt index e3a74dd..70b448b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -22,9 +22,10 @@ multivalued. Syntax ~~~~~~ -The syntax is fairly flexible and permissive; whitespaces are mostly -ignored. The '#' and ';' characters begin comments to the end of line, -blank lines are ignored. +The syntax is fairly flexible and permissive. Whitespace characters, +which in this context are the space character (SP) and the horizontal +tabulation (HT), are mostly ignored. The '#' and ';' characters begin +comments to the end of line. Blank lines are ignored. The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next @@ -63,16 +64,17 @@ the variable is the boolean "true"). The variable names are case-insensitive, allow only alphanumeric characters and `-`, and must start with an alphabetic character. -A line that defines a value can be continued to the next line by -ending it with a `\`; the backslash and the end-of-line are -stripped. Leading whitespaces after 'name =', the remainder of the -line after the first comment character '#' or ';', and trailing -whitespaces of the line are discarded unless they are enclosed in -double quotes. Internal whitespaces within the value are retained -verbatim. +Whitespace characters surrounding `name`, `=` and `value` are discarded. +Internal whitespace characters within 'value' are retained verbatim. +Comments starting with either `#` or `;` and extending to the end of line +are discarded. A line that defines a value can be continued to the next +line by ending it with a backslash (`\`); the backslash and the end-of-line +characters are discarded. -Inside double quotes, double quote `"` and backslash `\` characters -must be escaped: use `\"` for `"` and `\\` for `\`. +If `value` needs to contain leading or trailing whitespace characters, +it must be enclosed in double quotation marks (`"`). Inside double quotation +marks, double quote (`"`) and backslash (`\`) characters must be escaped: +use `\"` for `"` and `\\` for `\`. The following escape sequences (beside `\"` and `\\`) are recognized: `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB) @@ -369,20 +371,18 @@ inventing new variables for use in your own tool, make sure their names do not conflict with those that are used by Git itself and other popular tools, and describe them in your documentation. -include::config/advice.txt[] - -include::config/attr.txt[] - -include::config/core.txt[] - include::config/add.txt[] +include::config/advice.txt[] + include::config/alias.txt[] include::config/am.txt[] include::config/apply.txt[] +include::config/attr.txt[] + include::config/blame.txt[] include::config/branch.txt[] @@ -405,10 +405,12 @@ include::config/commit.txt[] include::config/commitgraph.txt[] -include::config/credential.txt[] - include::config/completion.txt[] +include::config/core.txt[] + +include::config/credential.txt[] + include::config/diff.txt[] include::config/difftool.txt[] @@ -421,10 +423,10 @@ include::config/feature.txt[] include::config/fetch.txt[] -include::config/format.txt[] - include::config/filter.txt[] +include::config/format.txt[] + include::config/fsck.txt[] include::config/fsmonitor--daemon.txt[] @@ -435,10 +437,10 @@ include::config/gitcvs.txt[] include::config/gitweb.txt[] -include::config/grep.txt[] - include::config/gpg.txt[] +include::config/grep.txt[] + include::config/gui.txt[] include::config/guitool.txt[] @@ -519,10 +521,10 @@ include::config/splitindex.txt[] include::config/ssh.txt[] -include::config/status.txt[] - include::config/stash.txt[] +include::config/status.txt[] + include::config/submodule.txt[] include::config/tag.txt[] diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 2737381..0e35ae5 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -1,30 +1,65 @@ advice.*:: These variables control various optional help messages designed to - aid new users. All 'advice.*' variables default to 'true', and you - can tell Git that you do not need help by setting these to 'false': + 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`: + -- + addEmbeddedRepo:: + Shown when the user accidentally adds one + git repo inside of another. + addEmptyPathspec:: + Shown when the user runs `git add` without providing + the pathspec parameter. + addIgnoredFile:: + Shown when the user attempts to add an ignored file to + the index. + amWorkDir:: + Shown when linkgit:git-am[1] fails to apply a patch + file, to tell the user the location of the file. ambiguousFetchRefspec:: - Advice shown when a fetch refspec for multiple remotes maps to + Shown when a fetch refspec for multiple remotes maps to the same remote-tracking branch namespace and causes branch tracking set-up to fail. + checkoutAmbiguousRemoteBranchName:: + Shown when the argument to + linkgit:git-checkout[1] and linkgit:git-switch[1] + ambiguously resolves to a + remote tracking branch on more than one remote in + situations where an unambiguous argument would have + otherwise caused a remote-tracking branch to be + checked out. See the `checkout.defaultRemote` + configuration variable for how to set a given remote + to be used by default in some situations where this + advice would be printed. + commitBeforeMerge:: + Shown when linkgit:git-merge[1] refuses to + merge to avoid overwriting local changes. + detachedHead:: + Shown when the user uses + linkgit:git-switch[1] or linkgit:git-checkout[1] + to move to the detached HEAD state, to tell the user how + to create a local branch after the fact. + diverging:: + Shown when a fast-forward is not possible. fetchShowForcedUpdates:: - Advice shown when linkgit:git-fetch[1] takes a long time + Shown when linkgit:git-fetch[1] takes a long time to calculate forced updates after ref updates, or to warn that the check is disabled. - pushUpdateRejected:: - Set this variable to 'false' if you want to disable - 'pushNonFFCurrent', 'pushNonFFMatching', 'pushAlreadyExists', - 'pushFetchFirst', 'pushNeedsForce', and 'pushRefNeedsUpdate' - simultaneously. - pushNonFFCurrent:: - Advice shown when linkgit:git-push[1] fails due to a - non-fast-forward update to the current branch. - pushNonFFMatching:: - Advice shown when you ran linkgit:git-push[1] and pushed - 'matching refs' explicitly (i.e. you used ':', or - specified a refspec that isn't your current branch) and - it resulted in a non-fast-forward error. + forceDeleteBranch:: + Shown when the user tries to delete a not fully merged + branch without the force option set. + ignoredHook:: + Shown when a hook is ignored because the hook is not + set as executable. + implicitIdentity:: + Shown when the user's information is guessed from the + system username and domain name, to tell the user how to + set their identity configuration. + mergeConflict:: + Shown when various commands stop because of conflicts. + nestedTag:: + Shown when a user attempts to recursively tag a tag object. pushAlreadyExists:: Shown when linkgit:git-push[1] rejects an update that does not qualify for fast-forwarding (e.g., a tag.) @@ -37,17 +72,45 @@ advice.*:: tries to overwrite a remote ref that points at an object that is not a commit-ish, or make the remote ref point at an object that is not a commit-ish. + pushNonFFCurrent:: + Shown when linkgit:git-push[1] fails due to a + non-fast-forward update to the current branch. + pushNonFFMatching:: + Shown when the user ran linkgit:git-push[1] and pushed + "matching refs" explicitly (i.e. used `:`, or + specified a refspec that isn't the current branch) and + it resulted in a non-fast-forward error. + pushRefNeedsUpdate:: + Shown when linkgit:git-push[1] rejects a forced update of + a branch when its remote-tracking ref has updates that we + do not have locally. pushUnqualifiedRefname:: Shown when linkgit:git-push[1] gives up trying to guess based on the source and destination refs what remote ref namespace the source belongs in, but where we can still suggest that the user push to either - refs/heads/* or refs/tags/* based on the type of the + `refs/heads/*` or `refs/tags/*` based on the type of the source object. - pushRefNeedsUpdate:: - Shown when linkgit:git-push[1] rejects a forced update of - a branch when its remote-tracking ref has updates that we - do not have locally. + pushUpdateRejected:: + Set this variable to `false` if you want to disable + `pushNonFFCurrent`, `pushNonFFMatching`, `pushAlreadyExists`, + `pushFetchFirst`, `pushNeedsForce`, and `pushRefNeedsUpdate` + simultaneously. + refSyntax:: + Shown when the user provides an illegal ref name, to + tell the user about the ref syntax documentation. + resetNoRefresh:: + Shown when linkgit:git-reset[1] takes more than 2 + seconds to refresh the index after reset, to tell the user + that they can use the `--no-refresh` option. + resolveConflict:: + Shown by various commands when conflicts + prevent the operation from being performed. + rmHints:: + Shown on failure in the output of linkgit:git-rm[1], to + give directions on how to proceed from the current state. + sequencerInUse:: + Shown when a sequencer command is already in progress. skippedCherryPicks:: Shown when linkgit:git-rebase[1] skips a commit that has already been cherry-picked onto the upstream branch. @@ -65,81 +128,30 @@ advice.*:: by linkgit:git-switch[1] or linkgit:git-checkout[1] when switching branches. statusUoption:: - Advise to consider using the `-u` option to linkgit:git-status[1] - when the command takes more than 2 seconds to enumerate untracked - files. - commitBeforeMerge:: - Advice shown when linkgit:git-merge[1] refuses to - merge to avoid overwriting local changes. - resetNoRefresh:: - Advice to consider using the `--no-refresh` option to - linkgit:git-reset[1] when the command takes more than 2 seconds - to refresh the index after reset. - resolveConflict:: - Advice shown by various commands when conflicts - prevent the operation from being performed. - sequencerInUse:: - Advice shown when a sequencer command is already in progress. - implicitIdentity:: - Advice on how to set your identity configuration when - your information is guessed from the system username and - domain name. - detachedHead:: - Advice shown when you used - linkgit:git-switch[1] or linkgit:git-checkout[1] - to move to the detached HEAD state, to instruct how to - create a local branch after the fact. - suggestDetachingHead:: - Advice shown when linkgit:git-switch[1] refuses to detach HEAD - without the explicit `--detach` option. - checkoutAmbiguousRemoteBranchName:: - Advice shown when the argument to - linkgit:git-checkout[1] and linkgit:git-switch[1] - ambiguously resolves to a - remote tracking branch on more than one remote in - situations where an unambiguous argument would have - otherwise caused a remote-tracking branch to be - checked out. See the `checkout.defaultRemote` - configuration variable for how to set a given remote - to be used by default in some situations where this - advice would be printed. - amWorkDir:: - Advice that shows the location of the patch file when - linkgit:git-am[1] fails to apply it. - rmHints:: - In case of failure in the output of linkgit:git-rm[1], - show directions on how to proceed from the current state. - addEmbeddedRepo:: - Advice on what to do when you've accidentally added one - git repo inside of another. - ignoredHook:: - Advice shown if a hook is ignored because the hook is not - set as executable. - waitingForEditor:: - Print a message to the terminal whenever Git is waiting for - editor input from the user. - nestedTag:: - Advice shown if a user attempts to recursively tag a tag object. + Shown when linkgit:git-status[1] takes more than 2 + seconds to enumerate untracked files, to tell the user that + they can use the `-u` option. submoduleAlternateErrorStrategyDie:: - Advice shown when a submodule.alternateErrorStrategy option + Shown when a submodule.alternateErrorStrategy option configured to "die" causes a fatal error. + submoduleMergeConflict:: + Advice shown when a non-trivial submodule merge conflict is + encountered. submodulesNotUpdated:: - Advice shown when a user runs a submodule command that fails + Shown when a user runs a submodule command that fails because `git submodule update --init` was not run. - addIgnoredFile:: - Advice shown if a user attempts to add an ignored file to - the index. - addEmptyPathspec:: - Advice shown if a user runs the add command without providing - the pathspec parameter. + suggestDetachingHead:: + Shown when linkgit:git-switch[1] refuses to detach HEAD + without the explicit `--detach` option. updateSparsePath:: - Advice shown when either linkgit:git-add[1] or linkgit:git-rm[1] + Shown when either linkgit:git-add[1] or linkgit:git-rm[1] is asked to update index entries outside the current sparse checkout. - diverging:: - Advice shown when a fast-forward is not possible. + waitingForEditor:: + Shown when Git is waiting for editor input. Relevant + when e.g. the editor is not launched inside the terminal. worktreeAddOrphan:: - Advice shown when a user tries to create a worktree from an - invalid reference, to instruct how to create a new orphan + Shown when the user tries to create a worktree from an + invalid reference, to tell the user how to create a new unborn branch instead. -- diff --git a/Documentation/config/clean.txt b/Documentation/config/clean.txt index f05b940..c0188ea 100644 --- a/Documentation/config/clean.txt +++ b/Documentation/config/clean.txt @@ -1,3 +1,3 @@ clean.requireForce:: - A boolean to make git-clean do nothing unless given -f, - -i, or -n. Defaults to true. + A boolean to make git-clean refuse to delete files unless -f + is given. Defaults to true. diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt index d037b57..0a10efd 100644 --- a/Documentation/config/clone.txt +++ b/Documentation/config/clone.txt @@ -1,13 +1,23 @@ -clone.defaultRemoteName:: +`clone.defaultRemoteName`:: The name of the remote to create when cloning a repository. Defaults to - `origin`, and can be overridden by passing the `--origin` command-line + `origin`. +ifdef::git-clone[] + It can be overridden by passing the `--origin` command-line + option. +endif::[] +ifndef::git-clone[] + It can be overridden by passing the `--origin` command-line option to linkgit:git-clone[1]. +endif::[] -clone.rejectShallow:: +`clone.rejectShallow`:: Reject cloning a repository if it is a shallow one; this can be overridden by - passing the `--reject-shallow` option on the command line. See linkgit:git-clone[1] + passing the `--reject-shallow` option on the command line. +ifndef::git-clone[] + See linkgit:git-clone[1]. +endif::[] -clone.filterSubmodules:: +`clone.filterSubmodules`:: If a partial clone filter is provided (see `--filter` in linkgit:git-rev-list[1]) and `--recurse-submodules` is used, also apply the filter to submodules. diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 0e8c283..93d65e1 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -520,6 +520,7 @@ core.editor:: `GIT_EDITOR` is not set. See linkgit:git-var[1]. core.commentChar:: +core.commentString:: Commands such as `commit` and `tag` that let you edit messages consider a line that begins with this character commented, and removes them after the editor returns @@ -527,6 +528,20 @@ core.commentChar:: + If set to "auto", `git-commit` would select a character that is not the beginning character of any line in existing commit messages. ++ +Note that these two variables are aliases of each other, and in modern +versions of Git you are free to use a string (e.g., `//` or `⁑⁕⁑`) with +`commentChar`. Versions of Git prior to v2.45.0 will ignore +`commentString` but will reject a value of `commentChar` that consists +of more than a single ASCII byte. If you plan to use your config with +older and newer versions of Git, you may want to specify both: ++ + [core] + # single character for older versions + commentChar = "#" + # string for newer versions (which will override commentChar + # because it comes later in the file) + commentString = "//" core.filesRefLockTimeout:: The length of time, in milliseconds, to retry when trying to @@ -688,7 +703,7 @@ core.createObject:: will not overwrite existing objects. + On some file system/operating system combinations, this is unreliable. -Set this config setting to 'rename' there; However, This will remove the +Set this config setting to 'rename' there; however, this will remove the check that makes sure that existing object files will not get overwritten. core.notesRef:: diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index bd5ae0c..5ce7b91 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -108,9 +108,15 @@ diff.mnemonicPrefix:: `git diff --no-index a b`;; compares two non-git things (1) and (2). -diff.noprefix:: +diff.noPrefix:: If set, 'git diff' does not show any source or destination prefix. +diff.srcPrefix:: + If set, 'git diff' uses this source prefix. Defaults to "a/". + +diff.dstPrefix:: + If set, 'git diff' uses this destination prefix. Defaults to "b/". + diff.relative:: If set to 'true', 'git diff' does not show changes outside of the directory and show pathnames relative to the current directory. @@ -223,5 +229,5 @@ diff.colorMoved:: diff.colorMovedWS:: When moved lines are colored using e.g. the `diff.colorMoved` setting, - this option controls the `<mode>` how spaces are treated - for details of valid modes see '--color-moved-ws' in linkgit:git-diff[1]. + this option controls the `<mode>` how spaces are treated. + For details of valid modes see '--color-moved-ws' in linkgit:git-diff[1]. diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt index bccaec7..38dce3d 100644 --- a/Documentation/config/extensions.txt +++ b/Documentation/config/extensions.txt @@ -7,6 +7,29 @@ Note that this setting should only be set by linkgit:git-init[1] or linkgit:git-clone[1]. Trying to change it after initialization will not work and will produce hard-to-diagnose issues. +extensions.compatObjectFormat:: + + Specify a compatitbility hash algorithm to use. The acceptable values + are `sha1` and `sha256`. The value specified must be different from the + value of extensions.objectFormat. This allows client level + interoperability between git repositories whose objectFormat matches + this compatObjectFormat. In particular when fully implemented the + pushes and pulls from a repository in whose objectFormat matches + compatObjectFormat. As well as being able to use oids encoded in + compatObjectFormat in addition to oids encoded with objectFormat to + locally specify objects. + +extensions.refStorage:: + Specify the ref storage format to use. The acceptable values are: ++ +include::../ref-storage-format.txt[] ++ +It is an error to specify this key unless `core.repositoryFormatVersion` is 1. ++ +Note that this setting should only be set by linkgit:git-init[1] or +linkgit:git-clone[1]. Trying to change it after initialization will not +work and will produce hard-to-diagnose issues. + extensions.worktreeConfig:: If enabled, then worktrees will load config settings from the `$GIT_DIR/config.worktree` file in addition to the diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index bf9546f..f061b64 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -17,6 +17,9 @@ skipping more commits at a time, reducing the number of round trips. + * `pack.useBitmapBoundaryTraversal=true` may improve bitmap traversal times by walking fewer objects. ++ +* `pack.allowPackReuse=multi` may improve the time it takes to create a pack by +reusing objects from multiple packs instead of just one. feature.manyFiles:: Enable config options that optimize for repos with many files in the diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index aea5b97..d7dc461 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -50,6 +50,12 @@ fetch.pruneTags:: refs. See also `remote.<name>.pruneTags` and the PRUNING section of linkgit:git-fetch[1]. +fetch.all:: + If true, fetch will attempt to update all available remotes. + This behavior can be overridden by passing `--no-all` or by + explicitly specifying one or more remote(s) to fetch from. + Defaults to false. + fetch.output:: Control how ref update status is printed. Valid values are `full` and `compact`. Default value is `full`. See the diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt index c98412b..7410e93 100644 --- a/Documentation/config/format.txt +++ b/Documentation/config/format.txt @@ -119,7 +119,7 @@ format.notes:: `--notes=<ref>`, where `ref` is the non-boolean value. Defaults to false. + -If one wishes to use the ref `ref/notes/true`, please use that literal +If one wishes to use the ref `refs/notes/true`, please use that literal instead. + This configuration can be specified multiple times in order to allow diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt index e521f20..10041f2 100644 --- a/Documentation/config/grep.txt +++ b/Documentation/config/grep.txt @@ -24,5 +24,5 @@ grep.fullName:: If set to true, enable `--full-name` option by default. grep.fallbackToNoIndex:: - If set to true, fall back to git grep --no-index if git grep + If set to true, fall back to `git grep --no-index` if `git grep` is executed outside of a git repository. Defaults to false. diff --git a/Documentation/config/init.txt b/Documentation/config/init.txt index 79c79d6..af03acd 100644 --- a/Documentation/config/init.txt +++ b/Documentation/config/init.txt @@ -1,7 +1,10 @@ -init.templateDir:: - Specify the directory from which templates will be copied. - (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) +:see-git-init: +ifndef::git-init[] +:see-git-init: (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) +endif::[] -init.defaultBranch:: +`init.templateDir`:: + Specify the directory from which templates will be copied. {see-git-init} +`init.defaultBranch`:: Allows overriding the default branch name e.g. when initializing a new repository. diff --git a/Documentation/config/interactive.txt b/Documentation/config/interactive.txt index a2d3c7e..5cc2655 100644 --- a/Documentation/config/interactive.txt +++ b/Documentation/config/interactive.txt @@ -4,9 +4,7 @@ interactive.singleKey:: Currently this is used by the `--patch` mode of linkgit:git-add[1], linkgit:git-checkout[1], linkgit:git-restore[1], linkgit:git-commit[1], - linkgit:git-reset[1], and linkgit:git-stash[1]. Note that this - setting is silently ignored if portable keystroke input - is not available; requires the Perl module Term::ReadKey. + linkgit:git-reset[1], and linkgit:git-stash[1]. interactive.diffFilter:: When an interactive command (such as `git add --patch`) shows diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt index 294f61e..00bf665 100644 --- a/Documentation/config/mergetool.txt +++ b/Documentation/config/mergetool.txt @@ -45,14 +45,21 @@ mergetool.meld.useAutoMerge:: value of `false` avoids using `--auto-merge` altogether, and is the default value. -mergetool.vimdiff.layout:: - The vimdiff backend uses this variable to control how its split - windows appear. Applies even if you are using Neovim (`nvim`) or - gVim (`gvim`) as the merge tool. See BACKEND SPECIFIC HINTS section +mergetool.<vimdiff variant>.layout:: + Configure the split window layout for vimdiff's `<variant>`, which is any of `vimdiff`, + `nvimdiff`, `gvimdiff`. + Upon launching `git mergetool` with `--tool=<variant>` (or without `--tool` + if `merge.tool` is configured as `<variant>`), Git will consult + `mergetool.<variant>.layout` to determine the tool's layout. If the + variant-specific configuration is not available, `vimdiff`'s is used as + fallback. If that too is not available, a default layout with 4 windows + will be used. To configure the layout, see the `BACKEND SPECIFIC HINTS` +ifdef::git-mergetool[] + section. +endif::[] ifndef::git-mergetool[] - in linkgit:git-mergetool[1]. + section in linkgit:git-mergetool[1]. endif::[] - for details. mergetool.hideResolved:: During a merge, Git will automatically resolve as many conflicts as diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index f50df9d..da52737 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -28,11 +28,16 @@ all existing objects. You can force recompression by passing the -F option to linkgit:git-repack[1]. pack.allowPackReuse:: - When true, and when reachability bitmaps are enabled, - pack-objects will try to send parts of the bitmapped packfile - verbatim. This can reduce memory and CPU usage to serve fetches, - but might result in sending a slightly larger pack. Defaults to - true. + When true or "single", and when reachability bitmaps are + enabled, pack-objects will try to send parts of the bitmapped + packfile verbatim. When "multi", and when a multi-pack + reachability bitmap is available, pack-objects will try to send + parts of all packs in the MIDX. ++ +If only a single pack bitmap is available, and `pack.allowPackReuse` +is set to "multi", reuse parts of just the bitmapped packfile. This +can reduce memory and CPU usage to serve fetches, but might result in +sending a slightly larger pack. Defaults to true. pack.island:: An extended regular expression configuring a set of delta diff --git a/Documentation/config/rebase.txt b/Documentation/config/rebase.txt index 9c248ac..c6187ab 100644 --- a/Documentation/config/rebase.txt +++ b/Documentation/config/rebase.txt @@ -9,7 +9,9 @@ rebase.stat:: rebase. False by default. rebase.autoSquash:: - If set to true enable `--autosquash` option by default. + If set to true, enable the `--autosquash` option of + linkgit:git-rebase[1] by default for interactive mode. + This can be overridden with the `--no-autosquash` option. rebase.autoStash:: When set to true, automatically create a temporary stash entry @@ -38,7 +40,7 @@ rebase.missingCommitsCheck:: rebase.instructionFormat:: A format string, as specified in linkgit:git-log[1], to be used for the todo list during an interactive rebase. The format will - automatically have the long commit hash prepended to the format. + automatically have the commit hash prepended to the format. rebase.abbreviateCommands:: If set to true, `git rebase` will use abbreviated command names in the diff --git a/Documentation/config/receive.txt b/Documentation/config/receive.txt index c77e55b..36a1e6f 100644 --- a/Documentation/config/receive.txt +++ b/Documentation/config/receive.txt @@ -8,7 +8,7 @@ receive.advertisePushOptions:: capability to its clients. False by default. receive.autogc:: - By default, git-receive-pack will run "git-gc --auto" after + By default, git-receive-pack will run "git maintenance run --auto" after receiving data from git-push and updating refs. You can stop it by setting this variable to false. diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt index 7fc770e..6a869d6 100644 --- a/Documentation/config/sendemail.txt +++ b/Documentation/config/sendemail.txt @@ -8,7 +8,7 @@ sendemail.smtpEncryption:: See linkgit:git-send-email[1] for description. Note that this setting is not subject to the 'identity' mechanism. -sendemail.smtpsslcertpath:: +sendemail.smtpSSLCertPath:: Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification. @@ -62,12 +62,12 @@ sendemail.chainReplyTo:: sendemail.envelopeSender:: sendemail.from:: sendemail.headerCmd:: -sendemail.signedoffbycc:: +sendemail.signedOffByCc:: sendemail.smtpPass:: -sendemail.suppresscc:: +sendemail.suppressCc:: sendemail.suppressFrom:: sendemail.to:: -sendemail.tocmd:: +sendemail.toCmd:: sendemail.smtpDomain:: sendemail.smtpServer:: sendemail.smtpServerPort:: @@ -81,8 +81,8 @@ sendemail.xmailer:: linkgit:git-send-email[1] command-line options. See its documentation for details. -sendemail.signedoffcc (deprecated):: - Deprecated alias for `sendemail.signedoffbycc`. +sendemail.signedOffCc (deprecated):: + Deprecated alias for `sendemail.signedOffByCc`. sendemail.smtpBatchSize:: Number of messages to be sent per connection, after that a relogin diff --git a/Documentation/config/status.txt b/Documentation/config/status.txt index 2ff8237..8caf90f 100644 --- a/Documentation/config/status.txt +++ b/Documentation/config/status.txt @@ -57,6 +57,8 @@ status.showUntrackedFiles:: -- + If this variable is not specified, it defaults to 'normal'. +All usual spellings for Boolean value `true` are taken as `normal` +and `false` as `no`. This variable can be overridden with the -u|--untracked-files option of linkgit:git-status[1] and linkgit:git-commit[1]. diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt index a9cbdb8..f1ce50f 100644 --- a/Documentation/config/transfer.txt +++ b/Documentation/config/transfer.txt @@ -121,3 +121,7 @@ transfer.bundleURI:: information from the remote server (if advertised) and download bundles before continuing the clone through the Git protocol. Defaults to `false`. + +transfer.advertiseObjectInfo:: + When `true`, the `object-info` capability is advertised by + servers. Defaults to false. diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt index 67645ca..e24517c 100644 --- a/Documentation/date-formats.txt +++ b/Documentation/date-formats.txt @@ -11,7 +11,7 @@ Git internal format:: For example CET (which is 1 hour ahead of UTC) is `+0100`. RFC 2822:: - The standard email format as described by RFC 2822, for example + The standard date format as described by RFC 2822, for example `Thu, 07 Apr 2005 22:13:13 +0200`. ISO 8601:: diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 53ec3c9..0e94569 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -299,7 +299,7 @@ and accumulating child directory counts in the parent directories: Synonym for --dirstat=cumulative --dirstat-by-file[=<param1,param2>...]:: - Synonym for --dirstat=files,param1,param2... + Synonym for --dirstat=files,<param1>,<param2>... --summary:: Output a condensed summary of extended header information @@ -865,8 +865,9 @@ endif::git-format-patch[] --default-prefix:: Use the default source and destination prefixes ("a/" and "b/"). - This is usually the default already, but may be used to override - config such as `diff.noprefix`. + This overrides configuration variables such as `diff.noprefix`, + `diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix` + (see `git-config`(1)). --line-prefix=<prefix>:: Prepend an additional prefix to every line of output. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index a1d6633..e22b217 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -1,5 +1,6 @@ ---all:: - Fetch all remotes. +--[no-]all:: + Fetch all remotes. This overrides the configuration variable + `fetch.all`. -a:: --append:: @@ -201,7 +202,7 @@ endif::git-pull[] destination of an explicit refspec; see `--prune`). ifndef::git-pull[] ---recurse-submodules[=yes|on-demand|no]:: +--recurse-submodules[=(yes|on-demand|no)]:: This option controls if and under what conditions new commits of submodules should be fetched too. When recursing through submodules, `git fetch` always attempts to fetch "changed" submodules, that is, a diff --git a/Documentation/fsck-msgids.txt b/Documentation/fsck-msgids.txt index f643585..5edc06c 100644 --- a/Documentation/fsck-msgids.txt +++ b/Documentation/fsck-msgids.txt @@ -164,6 +164,18 @@ `nullSha1`:: (WARN) Tree contains entries pointing to a null sha1. +`symlinkPointsToGitDir`:: + (WARN) Symbolic link points inside a gitdir. + +`symlinkTargetBlob`:: + (ERROR) A non-blob found instead of a symbolic link's target. + +`symlinkTargetLength`:: + (WARN) Symbolic link target longer than maximum path length. + +`symlinkTargetMissing`:: + (ERROR) Unable to read symbolic link target's blob. + `treeNotSorted`:: (ERROR) A tree is not properly sorted. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index ed44c1c..aceaa02 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] - [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--sparse] + [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize] [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...] @@ -63,7 +63,7 @@ OPTIONS to ignore removed files; use `--no-all` option if you want to add modified or new files but ignore removed ones. + -For more details about the <pathspec> syntax, see the 'pathspec' entry +For more details about the _<pathspec>_ syntax, see the 'pathspec' entry in linkgit:gitglossary[7]. -n:: @@ -119,10 +119,10 @@ apply to the index. See EDITING PATCHES below. -u:: --update:: Update the index just where it already has an entry matching - <pathspec>. This removes as well as modifies index entries to + _<pathspec>_. This removes as well as modifies index entries to match the working tree, but adds no new files. + -If no <pathspec> is given when `-u` option is used, all +If no _<pathspec>_ is given when `-u` option is used, all tracked files in the entire working tree are updated (old versions of Git used to limit the update to the current directory and its subdirectories). @@ -131,11 +131,11 @@ subdirectories). --all:: --no-ignore-removal:: Update the index not only where the working tree has a file - matching <pathspec> but also where the index already has an + matching _<pathspec>_ but also where the index already has an entry. This adds, modifies, and removes index entries to match the working tree. + -If no <pathspec> is given when `-A` option is used, all +If no _<pathspec>_ is given when `-A` option is used, all files in the entire working tree are updated (old versions of Git used to limit the update to the current directory and its subdirectories). @@ -145,11 +145,11 @@ subdirectories). Update the index by adding new files that are unknown to the index and files modified in the working tree, but ignore files that have been removed from the working tree. This - option is a no-op when no <pathspec> is used. + option is a no-op when no _<pathspec>_ is used. + This option is primarily to help users who are used to older -versions of Git, whose "git add <pathspec>..." was a synonym -for "git add --no-all <pathspec>...", i.e. ignored removed files. +versions of Git, whose "git add _<pathspec>_..." was a synonym +for "git add --no-all _<pathspec>_...", i.e. ignored removed files. -N:: --intent-to-add:: @@ -198,8 +198,8 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files. unchanged. --pathspec-from-file=<file>:: - Pathspec is passed in `<file>` instead of commandline args. If - `<file>` is exactly `-` then standard input is used. Pathspec + Pathspec is passed in _<file>_ instead of commandline args. If + _<file>_ is exactly `-` then standard input is used. Pathspec elements are separated by LF or CR/LF. Pathspec elements can be quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). See also `--pathspec-file-nul` and @@ -348,6 +348,7 @@ patch:: K - leave this hunk undecided, see previous hunk s - split the current hunk into smaller hunks e - manually edit the current hunk + p - print the current hunk ? - print help + After deciding the fate for all hunks, if there is any hunk diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index e080458..624a6e6 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -66,13 +66,19 @@ OPTIONS --quoted-cr=<action>:: This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]). ---empty=(stop|drop|keep):: - By default, or when the option is set to 'stop', the command - errors out on an input e-mail message lacking a patch - and stops in the middle of the current am session. When this - option is set to 'drop', skip such an e-mail message instead. - When this option is set to 'keep', create an empty commit, - recording the contents of the e-mail message as its log. +--empty=(drop|keep|stop):: + How to handle an e-mail message lacking a patch: ++ +-- +`drop`;; + The e-mail message will be skipped. +`keep`;; + An empty commit will be created, with the contents of the e-mail + message as its log. +`stop`;; + The command will fail, stopping in the middle of the current `am` + session. This is the default behavior. +-- -m:: --message-id:: @@ -128,6 +134,9 @@ include::rerere-options.txt[] These flags are passed to the 'git apply' (see linkgit:git-apply[1]) program that applies the patch. ++ +Valid <action> for the `--whitespace` option are: +`nowarn`, `warn`, `fix`, `error`, and `error-all`. --patch-format:: By default the command will try to detect the patch format diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 191b4a4..82f944d 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -16,11 +16,11 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: - git bisect start [--term-(new|bad)=<term-new> --term-(old|good)=<term-old>] - [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...] + git bisect start [--term-(bad|new)=<term-new> --term-(good|old)=<term-old>] + [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<pathspec>...] git bisect (bad|new|<term-new>) [<rev>] git bisect (good|old|<term-old>) [<rev>...] - git bisect terms [--term-good | --term-bad] + git bisect terms [--term-(good|old) | --term-(bad|new)] git bisect skip [(<rev>|<range>)...] git bisect reset [<commit>] git bisect (visualize|view) @@ -165,8 +165,10 @@ To get a reminder of the currently used terms, use git bisect terms ------------------------------------------------ -You can get just the old (respectively new) term with `git bisect terms ---term-old` or `git bisect terms --term-good`. +You can get just the old term with `git bisect terms --term-old` +or `git bisect terms --term-good`; `git bisect terms --term-new` +and `git bisect terms --term-bad` can be used to learn how to call +the commits more recent than the sought change. If you would like to use your own terms instead of "bad"/"good" or "new"/"old", you can choose any names you like (except existing bisect @@ -299,7 +301,7 @@ Cutting down bisection by giving more parameters to bisect start You can further cut down the number of trials, if you know what part of the tree is involved in the problem you are tracking down, by specifying -path parameters when issuing the `bisect start` command: +pathspec parameters when issuing the `bisect start` command: ------------ $ git bisect start -- arch/i386 include/asm-i386 @@ -362,7 +364,7 @@ OPTIONS --no-checkout:: + Do not checkout the new working tree at each iteration of the bisection -process. Instead just update a special reference named `BISECT_HEAD` to make +process. Instead just update the reference named `BISECT_HEAD` to make it point to the commit that should be tested. + This option may be useful when the test you would perform in each step diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 5720d04..b1d7fb5 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -210,7 +210,7 @@ annotated. . Each blame entry always starts with a line of: - <40-byte hex sha1> <sourceline> <resultline> <num_lines> + <40-byte-hex-sha1> <sourceline> <resultline> <num-lines> + Line numbers count from 1. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 4395aa9..0b08442 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -312,7 +312,8 @@ superproject's "origin/main", but tracks the submodule's "origin/main". option is omitted, the current HEAD will be used instead. <oldbranch>:: - The name of an existing branch to rename. + The name of an existing branch. If this option is omitted, + the name of the current branch will be used instead. <newbranch>:: The new name for an existing branch. The same restrictions as for diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt index 392d9eb..112658b 100644 --- a/Documentation/git-bugreport.txt +++ b/Documentation/git-bugreport.txt @@ -8,7 +8,8 @@ git-bugreport - Collect information for user to file a bug report SYNOPSIS -------- [verse] -'git bugreport' [(-o | --output-directory) <path>] [(-s | --suffix) <format>] +'git bugreport' [(-o | --output-directory) <path>] + [(-s | --suffix) <format> | --no-suffix] [--diagnose[=<mode>]] DESCRIPTION @@ -51,16 +52,19 @@ OPTIONS -s <format>:: --suffix <format>:: +--no-suffix:: Specify an alternate suffix for the bugreport name, to create a file - named 'git-bugreport-<formatted suffix>'. This should take the form of a + named 'git-bugreport-<formatted-suffix>'. This should take the form of a strftime(3) format string; the current local time will be used. + `--no-suffix` disables the suffix and the file is just named + `git-bugreport` without any disambiguation measure. --no-diagnose:: --diagnose[=<mode>]:: Create a zip archive of supplemental information about the user's machine, Git client, and repository state. The archive is written to the same output directory as the bug report and is named - 'git-diagnostics-<formatted suffix>'. + 'git-diagnostics-<formatted-suffix>'. + Without `mode` specified, the diagnostic archive will contain the default set of statistics reported by `git diagnose`. An optional `mode` value may be specified diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 240c546..8bdfa54 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -63,7 +63,9 @@ $ git checkout <branch> ------------ + that is to say, the branch is not reset/created unless "git checkout" is -successful. +successful (e.g., when the branch is in use in another worktree, not +just the current branch stays the same, but the branch is not reset to +the start-point, either). 'git checkout' --detach [<branch>]:: 'git checkout' [--detach] <commit>:: @@ -215,7 +217,7 @@ variable. below for details. --orphan <new-branch>:: - Create a new 'orphan' branch, named `<new-branch>`, started from + Create a new unborn branch, named `<new-branch>`, started from `<start-point>` and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new history totally disconnected from all the other branches and diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index fdcad3d..81ace90 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -131,20 +131,36 @@ effect to your index in a row. even without this option. Note also, that use of this option only keeps commits that were initially empty (i.e. the commit recorded the same tree as its parent). Commits which are made empty due to a - previous commit are dropped. To force the inclusion of those commits - use `--keep-redundant-commits`. + previous commit will cause the cherry-pick to fail. To force the + inclusion of those commits, use `--empty=keep`. --allow-empty-message:: By default, cherry-picking a commit with an empty message will fail. This option overrides that behavior, allowing commits with empty messages to be cherry picked. +--empty=(drop|keep|stop):: + How to handle commits being cherry-picked that are redundant with + changes already in the current history. ++ +-- +`drop`;; + The commit will be dropped. +`keep`;; + The commit will be kept. Implies `--allow-empty`. +`stop`;; + The cherry-pick will stop when the commit is applied, allowing + you to examine the commit. This is the default behavior. +-- ++ +Note that `--empty=drop` and `--empty=stop` only specify how to handle a +commit that was not initially empty, but rather became empty due to a previous +commit. Commits that were initially empty will still cause the cherry-pick to +fail unless one of `--empty=keep` or `--allow-empty` are specified. ++ + --keep-redundant-commits:: - If a commit being cherry picked duplicates a commit already in the - current history, it will become empty. By default these - redundant commits cause `cherry-pick` to stop so the user can - examine the commit. This option overrides that behavior and - creates an empty commit object. Implies `--allow-empty`. + Deprecated synonym for `--empty=keep`. --strategy=<strategy>:: Use the given merge strategy. Should only be used once. diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 69331e3..fd17165 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -37,7 +37,7 @@ OPTIONS --force:: If the Git configuration variable clean.requireForce is not set to false, 'git clean' will refuse to delete files or directories - unless given -f or -i. Git will refuse to modify untracked + unless given -f. Git will refuse to modify untracked nested git repositories (directories with a .git subdirectory) unless a second -f is given. @@ -45,10 +45,14 @@ OPTIONS --interactive:: Show what would be done and clean files interactively. See ``Interactive mode'' for details. + Configuration variable `clean.requireForce` is ignored, as + this mode gives its own safety protection by going interactive. -n:: --dry-run:: Don't actually remove anything, just show what would be done. + Configuration variable `clean.requireForce` is ignored, as + nothing will be deleted anyway. -q:: --quiet:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index c37c4a3..5de18de 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,15 +9,15 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- [verse] -'git clone' [--template=<template-directory>] - [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] - [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] - [--dissociate] [--separate-git-dir <git-dir>] - [--depth <depth>] [--[no-]single-branch] [--no-tags] - [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules] - [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow] - [--filter=<filter> [--also-filter-submodules]] [--] <repository> - [<directory>] +`git clone` [++--template=++__<template-directory>__] + [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`] + [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_] + [`--dissociate`] [`--separate-git-dir` _<git-dir>_] + [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`] + [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`] + [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`] + [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_ + [_<directory>_] DESCRIPTION ----------- @@ -31,7 +31,7 @@ currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without arguments will in addition merge the remote master branch into the -current master branch, if any (this is untrue when "--single-branch" +current master branch, if any (this is untrue when `--single-branch` is given; see below). This default configuration is achieved by creating references to @@ -42,12 +42,12 @@ configuration variables. OPTIONS ------- --l:: ---local:: +`-l`:: +`--local`:: When the repository to clone from is on a local machine, this flag bypasses the normal "Git aware" transport mechanism and clones the repository by making a copy of - HEAD and everything under objects and refs directories. + `HEAD` and everything under objects and refs directories. The files under `.git/objects/` directory are hardlinked to save space when possible. + @@ -67,14 +67,14 @@ links. source repository, similar to running `cp -r src dst` while modifying `src`. ---no-hardlinks:: +`--no-hardlinks`:: Force the cloning process from a repository on a local filesystem to copy the files under the `.git/objects` directory instead of using hardlinks. This may be desirable if you are trying to make a back-up of your repository. --s:: ---shared:: +`-s`:: +`--shared`:: When the repository to clone is on the local machine, instead of using hard links, automatically setup `.git/objects/info/alternates` to share the objects @@ -101,10 +101,10 @@ If you want to break the dependency of a repository cloned with `--shared` on its source repository, you can simply run `git repack -a` to copy all objects from the source repository into a pack in the cloned repository. ---reference[-if-able] <repository>:: - If the reference repository is on the local machine, +`--reference`[`-if-able`] _<repository>_:: + If the reference _<repository>_ is on the local machine, automatically setup `.git/objects/info/alternates` to - obtain objects from the reference repository. Using + obtain objects from the reference _<repository>_. Using an already existing repository as an alternate will require fewer objects to be copied from the repository being cloned, reducing network and local storage costs. @@ -115,7 +115,7 @@ objects from the source repository into a pack in the cloned repository. *NOTE*: see the NOTE for the `--shared` option, and also the `--dissociate` option. ---dissociate:: +`--dissociate`:: Borrow the objects from reference repositories specified with the `--reference` options only to reduce network transfer, and stop borrowing from them after a clone is made @@ -126,43 +126,43 @@ objects from the source repository into a pack in the cloned repository. same repository, and this option can be used to stop the borrowing. --q:: ---quiet:: +`-q`:: +`--quiet`:: Operate quietly. Progress is not reported to the standard error stream. --v:: ---verbose:: +`-v`:: +`--verbose`:: Run verbosely. Does not affect the reporting of progress status to the standard error stream. ---progress:: +`--progress`:: Progress status is reported on the standard error stream by default when it is attached to a terminal, unless `--quiet` is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. ---server-option=<option>:: +++--server-option=++__<option>__:: Transmit the given string to the server when communicating using protocol version 2. The given string must not contain a NUL or LF character. The server's handling of server options, including unknown ones, is server-specific. - When multiple `--server-option=<option>` are given, they are all + When multiple ++--server-option=++__<option>__ are given, they are all sent to the other side in the order listed on the command line. --n:: ---no-checkout:: +`-n`:: +`--no-checkout`:: No checkout of HEAD is performed after the clone is complete. ---[no-]reject-shallow:: +`--`[`no-`]`reject-shallow`:: Fail if the source repository is a shallow repository. - The 'clone.rejectShallow' configuration variable can be used to + The `clone.rejectShallow` configuration variable can be used to specify the default. ---bare:: +`--bare`:: Make a 'bare' Git repository. That is, instead of - creating `<directory>` and placing the administrative - files in `<directory>/.git`, make the `<directory>` + creating _<directory>_ and placing the administrative + files in _<directory>_`/.git`, make the _<directory>_ itself the `$GIT_DIR`. This obviously implies the `--no-checkout` because there is nowhere to check out the working tree. Also the branch heads at the remote are copied directly @@ -171,28 +171,28 @@ objects from the source repository into a pack in the cloned repository. used, neither remote-tracking branches nor the related configuration variables are created. ---sparse:: +`--sparse`:: Employ a sparse-checkout, with only files in the toplevel directory initially being present. The linkgit:git-sparse-checkout[1] command can be used to grow the working directory as needed. ---filter=<filter-spec>:: +++--filter=++__<filter-spec>__:: Use the partial clone feature and request that the server sends a subset of reachable objects according to a given object filter. - When using `--filter`, the supplied `<filter-spec>` is used for + When using `--filter`, the supplied _<filter-spec>_ is used for the partial clone filter. For example, `--filter=blob:none` will filter out all blobs (file contents) until needed by Git. Also, - `--filter=blob:limit=<size>` will filter out all blobs of size - at least `<size>`. For more details on filter specifications, see + ++--filter=blob:limit=++__<size>__ will filter out all blobs of size + at least _<size>_. For more details on filter specifications, see the `--filter` option in linkgit:git-rev-list[1]. ---also-filter-submodules:: +`--also-filter-submodules`:: Also apply the partial clone filter to any submodules in the repository. Requires `--filter` and `--recurse-submodules`. This can be turned on by default by setting the `clone.filterSubmodules` config option. ---mirror:: +`--mirror`:: Set up a mirror of the source repository. This implies `--bare`. Compared to `--bare`, `--mirror` not only maps local branches of the source to local branches of the target, it maps all refs (including @@ -200,37 +200,37 @@ objects from the source repository into a pack in the cloned repository. that all these refs are overwritten by a `git remote update` in the target repository. --o <name>:: ---origin <name>:: +`-o` _<name>_:: +`--origin` _<name>_:: Instead of using the remote name `origin` to keep track of the upstream - repository, use `<name>`. Overrides `clone.defaultRemoteName` from the + repository, use _<name>_. Overrides `clone.defaultRemoteName` from the config. --b <name>:: ---branch <name>:: +`-b` _<name>_:: +`--branch` _<name>_:: Instead of pointing the newly created HEAD to the branch pointed - to by the cloned repository's HEAD, point to `<name>` branch + to by the cloned repository's HEAD, point to _<name>_ branch instead. In a non-bare repository, this is the branch that will be checked out. `--branch` can also take tags and detaches the HEAD at that commit in the resulting repository. --u <upload-pack>:: ---upload-pack <upload-pack>:: +`-u` _<upload-pack>_:: +`--upload-pack` _<upload-pack>_:: When given, and the repository to clone from is accessed via ssh, this specifies a non-default path for the command run on the other end. ---template=<template-directory>:: +++--template=++__<template-directory>__:: Specify the directory from which templates will be used; (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) --c <key>=<value>:: ---config <key>=<value>:: +`-c` __<key>__++=++__<value>__:: +`--config` __<key>__++=++__<value>__:: Set a configuration variable in the newly-created repository; this takes effect immediately after the repository is initialized, but before the remote history is fetched or any - files checked out. The key is in the same format as expected by + files checked out. The _<key>_ is in the same format as expected by linkgit:git-config[1] (e.g., `core.eol=true`). If multiple values are given for the same key, each value will be written to the config file. This makes it safe, for example, to add @@ -239,35 +239,35 @@ objects from the source repository into a pack in the cloned repository. Due to limitations of the current implementation, some configuration variables do not take effect until after the initial fetch and checkout. Configuration variables known to not take effect are: -`remote.<name>.mirror` and `remote.<name>.tagOpt`. Use the +++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++. Use the corresponding `--mirror` and `--no-tags` options instead. ---depth <depth>:: +`--depth` _<depth>_:: Create a 'shallow' clone with a history truncated to the specified number of commits. Implies `--single-branch` unless `--no-single-branch` is given to fetch the histories near the tips of all branches. If you want to clone submodules shallowly, also pass `--shallow-submodules`. ---shallow-since=<date>:: +++--shallow-since=++__<date>__:: Create a shallow clone with a history after the specified time. ---shallow-exclude=<revision>:: +++--shallow-exclude=++__<revision>__:: Create a shallow clone with a history, excluding commits reachable from a specified remote branch or tag. This option can be specified multiple times. ---[no-]single-branch:: +`--`[`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 + 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-tags:: +`--no-tags`:: Don't clone any tags, and set `remote.<remote>.tagOpt=--no-tags` in the config, ensuring that future `git pull` and `git fetch` operations won't follow @@ -279,9 +279,9 @@ maintain a branch with no references other than a single cloned branch. This is useful e.g. to maintain minimal clones of the default branch of some repository for search indexing. ---recurse-submodules[=<pathspec>]:: +`--recurse-submodules`[`=`{empty}__<pathspec>__]:: After the clone is created, initialize and clone submodules - within based on the provided pathspec. If no pathspec is + within based on the provided _<pathspec>_. If no _=<pathspec>_ is provided, all submodules are initialized and cloned. This option can be given multiple times for pathspecs consisting of multiple entries. The resulting clone has `submodule.active` set to @@ -295,42 +295,48 @@ the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) ---[no-]shallow-submodules:: +`--`[`no-`]`shallow-submodules`:: All submodules which are cloned will be shallow with a depth of 1. ---[no-]remote-submodules:: +`--`[`no-`]`remote-submodules`:: All submodules which are cloned will use the status of the submodule's remote-tracking branch to update the submodule, rather than the superproject's recorded SHA-1. Equivalent to passing `--remote` to `git submodule update`. ---separate-git-dir=<git-dir>:: +`--separate-git-dir=`{empty}__<git-dir>__:: Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, then make a filesystem-agnostic Git symbolic link to there. The result is Git repository can be separated from working tree. --j <n>:: ---jobs <n>:: +`--ref-format=`{empty}__<ref-format>__:: + +Specify the given ref storage format for the repository. The valid values are: ++ +include::ref-storage-format.txt[] + +`-j` _<n>_:: +`--jobs` _<n>_:: The number of submodules fetched at the same time. Defaults to the `submodule.fetchJobs` option. -<repository>:: - The (possibly remote) repository to clone from. See the +_<repository>_:: + The (possibly remote) _<repository>_ to clone from. See the <<URLS,GIT URLS>> section below for more information on specifying repositories. -<directory>:: +_<directory>_:: The name of a new directory to clone into. The "humanish" - part of the source repository is used if no directory is + part of the source repository is used if no _<directory>_ is explicitly given (`repo` for `/path/to/repo.git` and `foo` for `host.xz:foo/.git`). Cloning into an existing directory is only allowed if the directory is empty. ---bundle-uri=<uri>:: +`--bundle-uri=`{empty}__<uri>__:: Before fetching from the remote, fetch a bundle from the given - `<uri>` and unbundle the data into the local repository. The refs + _<uri>_ and unbundle the data into the local repository. The refs in the bundle will be stored under the hidden `refs/bundle/*` namespace. This option is incompatible with `--depth`, `--shallow-since`, and `--shallow-exclude`. diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index c8dbceb..903b168 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -13,7 +13,7 @@ SYNOPSIS 'git commit-graph write' [--object-dir <dir>] [--append] [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits] [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress] - <split options> + <split-options> DESCRIPTION diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index a6cef5d..89ecfc6 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -347,6 +347,8 @@ The possible options are: - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. +All usual spellings for Boolean value `true` are taken as `normal` +and `false` as `no`. The default can be changed using the status.showUntrackedFiles configuration variable documented in linkgit:git-config[1]. -- diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index b1caac8..ac61113 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,9 +9,9 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]] -'git config' [<file-option>] [--type=<type>] --add <name> <value> -'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>] +'git config' [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]] +'git config' [<file-option>] [--type=<type>] [--comment=<message>] --add <name> <value> +'git config' [<file-option>] [--type=<type>] [--comment=<message>] [--fixed-value] --replace-all <name> <value> [<value-pattern>] 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>] 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>] 'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>] @@ -87,6 +87,18 @@ OPTIONS values. This is the same as providing '^$' as the `value-pattern` in `--replace-all`. +--comment <message>:: + Append a comment at the end of new or modified lines. + + If _<message>_ begins with one or more whitespaces followed + by "#", it is used as-is. If it begins with "#", a space is + prepended before it is used. Otherwise, a string " # " (a + space followed by a hash followed by a space) is prepended + to it. And the resulting string is placed immediately after + the value defined for the variable. The _<message>_ must + not contain linefeed characters (no multi-line comments are + permitted). + --get:: Get the value for a given key (optionally filtered by a regex matching the value). Returns error code 1 if the key was not @@ -103,11 +115,11 @@ OPTIONS names are not. --get-urlmatch <name> <URL>:: - When given a two-part name section.key, the value for - section.<URL>.key whose <URL> part matches the best to the + When given a two-part <name> as <section>.<key>, the value for + <section>.<URL>.<key> whose <URL> part matches the best to the given URL is returned (if no such key exists, the value for - section.key is used as a fallback). When given just the - section as name, do so for all the keys in the section and + <section>.<key> is used as a fallback). When given just the + <section> as name, do so for all the keys in the section and list them. Returns error code 1 if no value is found. --global:: @@ -275,7 +287,8 @@ Valid `<type>`'s include: -e:: --edit:: Opens an editor to modify the specified config file; either - `--system`, `--global`, or repository (default). + `--system`, `--global`, `--local` (default), `--worktree`, or + `--file <config-file>`. --[no-]includes:: Respect `include.*` directives in config files when looking up @@ -285,7 +298,7 @@ Valid `<type>`'s include: --default <value>:: When using `--get`, and the requested variable is not found, behave as if - <value> were the value assigned to the that variable. + <value> were the value assigned to that variable. CONFIGURATION ------------- diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index b3f2767..90fdc25 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -22,7 +22,7 @@ DESCRIPTION deprecated; it does not work with cvsps version 3 and later. If you are performing a one-shot import of a CVS repository consider using http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or -http://www.catb.org/esr/cvs-fast-export/[cvs-fast-export]. +https://gitlab.com/esr/cvs-fast-export[cvs-fast-export]. Imports a CVS repository into Git. It will either create a new repository, or incrementally import into an existing one. @@ -221,7 +221,7 @@ Problems related to tags: If you suspect that any of these issues may apply to the repository you want to import, consider using cvs2git: -* cvs2git (part of cvs2svn), `http://subversion.apache.org/` +* cvs2git (part of cvs2svn), `https://subversion.apache.org/` GIT --- diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index cf4a5a2..4c475ef 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -197,7 +197,7 @@ allowing access over SSH. 5. Clients should now be able to check out the project. Use the CVS 'module' name to indicate what Git 'head' you want to check out. This also sets the name of your newly checked-out directory, unless you tell it otherwise with - `-d <dir_name>`. For example, this checks out 'master' branch to the + `-d <dir-name>`. For example, this checks out 'master' branch to the `project-master` directory: + ------ @@ -224,7 +224,7 @@ the database to work reliably (otherwise you need to make sure that the database is up to date any time 'git-cvsserver' is executed). By default it uses SQLite databases in the Git directory, named -`gitcvs.<module_name>.sqlite`. Note that the SQLite backend creates +`gitcvs.<module-name>.sqlite`. Note that the SQLite backend creates temporary files in the same directory as the database file on write so it might not be enough to grant the users using 'git-cvsserver' write access to the database file without granting diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index e064f91..ede7b93 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -18,7 +18,7 @@ SYNOPSIS [--allow-override=<service>] [--forbid-override=<service>] [--access-hook=<path>] [--[no-]informative-errors] [--inetd | - [--listen=<host_or_ipaddr>] [--port=<n>] + [--listen=<host-or-ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]]] [--log-destination=(stderr|syslog|none)] [<directory>...] @@ -86,10 +86,10 @@ OPTIONS Incompatible with --detach, --port, --listen, --user and --group options. ---listen=<host_or_ipaddr>:: +--listen=<host-or-ipaddr>:: Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 - is not supported, then --listen=hostname is also not supported and + is not supported, then --listen=<hostname> is also not supported and --listen must be given an IPv4 address. Can be given more than once. Incompatible with `--inetd` option. @@ -141,8 +141,8 @@ otherwise `stderr`. specified with no parameter, a request to git://host/{tilde}alice/foo is taken as a request to access 'foo' repository in the home directory of user `alice`. - If `--user-path=path` is specified, the same request is - taken as a request to access `path/foo` repository in + If `--user-path=<path>` is specified, the same request is + taken as a request to access `<path>/foo` repository in the home directory of user `alice`. --verbose:: diff --git a/Documentation/git-diagnose.txt b/Documentation/git-diagnose.txt index 3ec8cc7..0711959 100644 --- a/Documentation/git-diagnose.txt +++ b/Documentation/git-diagnose.txt @@ -45,7 +45,7 @@ OPTIONS -s <format>:: --suffix <format>:: Specify an alternate suffix for the diagnostics archive name, to create - a file named 'git-diagnostics-<formatted suffix>'. This should take the + a file named 'git-diagnostics-<formatted-suffix>'. This should take the form of a strftime(3) format string; the current local time will be used. diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 08087ff..c065f02 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -103,7 +103,7 @@ Just in case you are doing something exotic, it should be noted that all of the <commit> in the above description, except in the `--merge-base` case and in the last two forms that use `..` notations, can be any <tree>. A tree of interest is the one pointed to -by the special ref `AUTO_MERGE`, which is written by the 'ort' merge +by the ref named `AUTO_MERGE`, which is written by the 'ort' merge strategy upon hitting merge conflicts (see linkgit:git-merge[1]). Comparing the working tree with `AUTO_MERGE` shows changes you've made so far to resolve textual conflicts (see the examples below). diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 50cb080..a616f8b 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -90,7 +90,7 @@ instead. `--no-symlinks` is the default on Windows. --extcmd=<command>:: Specify a custom command for viewing diffs. 'git-difftool' ignores the configured defaults and runs - `$command $LOCAL $REMOTE` when this option is specified. + `<command> $LOCAL $REMOTE` when this option is specified. Additionally, `$BASE` is set in the environment. -g:: @@ -105,7 +105,6 @@ instead. `--no-symlinks` is the default on Windows. `merge.tool` until a tool is found. --[no-]trust-exit-code:: - 'git-difftool' invokes a diff tool individually on each file. Errors reported by the diff tool are ignored by default. Use `--trust-exit-code` to make 'git-difftool' exit when an invoked diff tool returns a non-zero exit code. diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 4643ddb..752e4b9 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -48,7 +48,7 @@ When asking to 'abort' (which is the default), this program will die when encountering such a tag. With 'drop' it will omit such tags from the output. With 'rewrite', if the tagged object is a commit, it will rewrite the tag to tag an ancestor commit (via parent rewriting; see -linkgit:git-rev-list[1]) +linkgit:git-rev-list[1]). -M:: -C:: diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index bd7b1e0..3d43515 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -303,7 +303,7 @@ and some sanity checks on the numeric values may also be performed. with e.g. bogus timezone values. `rfc2822`:: - This is the standard email format as described by RFC 2822. + This is the standard date format as described by RFC 2822. + An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git parser is accurate, but a little on the lenient side. It is the @@ -630,18 +630,28 @@ in octal. Git only supports the following modes: In both formats `<path>` is the complete path of the file to be added (if not already existing) or modified (if already existing). -A `<path>` string must use UNIX-style directory separators (forward -slash `/`), may contain any byte other than `LF`, and must not -start with double quote (`"`). - -A path can use C-style string quoting; this is accepted in all cases -and mandatory if the filename starts with double quote or contains -`LF`. In C-style quoting, the complete name should be surrounded with -double quotes, and any `LF`, backslash, or double quote characters -must be escaped by preceding them with a backslash (e.g., -`"path/with\n, \\ and \" in it"`). - -The value of `<path>` must be in canonical form. That is it must not: +A `<path>` can be written as unquoted bytes or a C-style quoted string. + +When a `<path>` does not start with a double quote (`"`), it is an +unquoted string and is parsed as literal bytes without any escape +sequences. However, if the filename contains `LF` or starts with double +quote, it cannot be represented as an unquoted string and must be +quoted. Additionally, the source `<path>` in `filecopy` or `filerename` +must be quoted if it contains SP. + +When a `<path>` starts with a double quote (`"`), it is a C-style quoted +string, where the complete filename is enclosed in a pair of double +quotes and escape sequences are used. Certain characters must be escaped +by preceding them with a backslash: `LF` is written as `\n`, backslash +as `\\`, and double quote as `\"`. Some characters may optionally be +written with escape sequences: `\a` for bell, `\b` for backspace, `\f` +for form feed, `\n` for line feed, `\r` for carriage return, `\t` for +horizontal tab, and `\v` for vertical tab. Any byte can be written with +3-digit octal codes (e.g., `\033`). All filenames can be represented as +quoted strings. + +A `<path>` must use UNIX-style directory separators (forward slash `/`) +and its value must be in canonical form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), * end with a directory separator (e.g. `foo/` is invalid), @@ -651,6 +661,7 @@ The value of `<path>` must be in canonical form. That is it must not: The root of the tree can be represented by an empty string as `<path>`. +`<path>` cannot contain NUL, either literally or escaped as `\000`. It is recommended that `<path>` always be encoded using UTF-8. `filedelete` @@ -745,11 +756,11 @@ paths for a commit are encouraged to do so. `notemodify` ^^^^^^^^^^^^ -Included in a `commit` `<notes_ref>` command to add a new note +Included in a `commit` `<notes-ref>` command to add a new note annotating a `<commit-ish>` or change this annotation contents. Internally it is similar to filemodify 100644 on `<commit-ish>` path (maybe split into subdirectories). It's not advised to -use any other commands to write to the `<notes_ref>` tree except +use any other commands to write to the `<notes-ref>` tree except `filedeleteall` to delete all existing notes in this tree. This command has two different means of specifying the content of the note. diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index f123139..50900a5 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -186,8 +186,8 @@ origin: ------------------------------------------------ $ git fetch origin --prune --prune-tags $ git fetch origin --prune 'refs/tags/*:refs/tags/*' -$ git fetch <url of origin> --prune --prune-tags -$ git fetch <url of origin> --prune 'refs/tags/*:refs/tags/*' +$ git fetch <url-of-origin> --prune --prune-tags +$ git fetch <url-of-origin> --prune 'refs/tags/*:refs/tags/*' ------------------------------------------------ OUTPUT diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 62e482a..5a4f853 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -14,7 +14,7 @@ SYNOPSIS [--msg-filter <command>] [--commit-filter <command>] [--tag-name-filter <command>] [--prune-empty] [--original <namespace>] [-d <directory>] [-f | --force] - [--state-branch <branch>] [--] [<rev-list options>...] + [--state-branch <branch>] [--] [<rev-list-options>...] WARNING ------- @@ -32,7 +32,7 @@ listed there as reasonably possible. DESCRIPTION ----------- Lets you rewrite Git revision history by rewriting the branches mentioned -in the <rev-list options>, applying custom filters on each revision. +in the <rev-list-options>, applying custom filters on each revision. Those filters can modify each tree (e.g. removing a file or running a perl rewrite on all files) or information about each commit. Otherwise, all information (including original commit times or merge @@ -624,7 +624,7 @@ with: real backup; it dereferences tags first.) ** Running git-filter-branch with either --tags or --all in your - <rev-list options>. In order to retain annotated tags as + <rev-list-options>. In order to retain annotated tags as annotated, you must use --tag-name-filter (and must not have restored from refs/original/ in a previously botched rewrite). diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index e86d570..c1dd12b 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] - [ --stdin | <pattern>... ] + [--include-root-refs] [ --stdin | <pattern>... ] [--points-at=<object>] [--merged[=<object>]] [--no-merged[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]] @@ -51,17 +51,14 @@ OPTIONS key. --format=<format>:: - A string that interpolates `%(fieldname)` from a ref being shown - and the object it points at. If `fieldname` - is prefixed with an asterisk (`*`) and the ref points - at a tag object, use the value for the field in the object - which the tag object refers to (instead of the field in the tag object). - When unspecified, `<format>` defaults to - `%(objectname) SPC %(objecttype) TAB %(refname)`. - It also interpolates `%%` to `%`, and `%xx` where `xx` - are hex digits interpolates to character with hex code - `xx`; for example `%00` interpolates to `\0` (NUL), - `%09` to `\t` (TAB) and `%0a` to `\n` (LF). + A string that interpolates `%(fieldname)` from a ref being shown and + the object it points at. In addition, the string literal `%%` + renders as `%` and `%xx` - where `xx` are hex digits - renders as + the character with hex code `xx`. For example, `%00` interpolates to + `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF). ++ +When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype) +TAB %(refname)`. --color[=<when>]:: Respect any colors specified in the `--format` option. The @@ -108,6 +105,9 @@ OPTIONS any excluded pattern(s) are shown. Matching is done using the same rules as `<pattern>` above. +--include-root-refs:: + List root refs (HEAD and pseudorefs) apart from regular refs. + FIELD NAMES ----------- @@ -298,6 +298,10 @@ fields will correspond to the appropriate date or name-email-date tuple from the `committer` or `tagger` fields depending on the object type. These are intended for working on a mix of annotated and lightweight tags. +For tag objects, a `fieldname` prefixed with an asterisk (`*`) expands to +the `fieldname` value of the peeled object, rather than that of the tag +object itself. + Fields that have name-email-date tuple as its value (`author`, `committer`, and `tagger`) can be suffixed with `name`, `email`, and `date` to extract the named component. For email fields (`authoremail`, @@ -358,9 +362,11 @@ In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error. It returns an empty string instead. -As a special case for the date-type fields, you may specify a format for -the date by adding `:` followed by date format name (see the -values the `--date` option to linkgit:git-rev-list[1] takes). +As a special case for the date-type fields, you may specify a format for the +date by adding `:` followed by date format name (see the values the `--date` +option to linkgit:git-rev-list[1] takes). If this formatting is provided in +a `--sort` key, references will be sorted according to the byte-value of the +formatted string rather than the numeric value of the underlying timestamp. Some atoms like %(align) and %(if) always require a matching %(end). We call them "opening atoms" and sometimes denote them as %($open). diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index aaafce2..728bb38 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -17,10 +17,10 @@ SYNOPSIS [--signature-file=<file>] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] - [--in-reply-to=<message id>] [--suffix=.<sfx>] + [--in-reply-to=<message-id>] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--always] [--cover-from-description=<mode>] - [--rfc] [--subject-prefix=<subject prefix>] + [--rfc] [--subject-prefix=<subject-prefix>] [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] [--[no-]cover-letter] [--quiet] @@ -30,8 +30,8 @@ SYNOPSIS [--range-diff=<previous> [--creation-factor=<percent>]] [--filename-max-length=<n>] [--progress] - [<common diff options>] - [ <since> | <revision range> ] + [<common-diff-options>] + [ <since> | <revision-range> ] DESCRIPTION ----------- @@ -64,7 +64,7 @@ There are two ways to specify which commits to operate on. to the tip of the current branch that are not in the history that leads to the <since> to be output. -2. Generic <revision range> expression (see "SPECIFYING +2. Generic <revision-range> expression (see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]) means the commits in the specified range. @@ -179,9 +179,9 @@ Beware that the default for 'git send-email' is to thread emails itself. If you want `git format-patch` to take care of threading, you will want to ensure that threading is disabled for `git send-email`. ---in-reply-to=<message id>:: +--in-reply-to=<message-id>:: Make the first mail (or all the mails with `--no-thread`) appear as a - reply to the given <message id>, which avoids breaking threads to + reply to the given <message-id>, which avoids breaking threads to provide a new patch series. --ignore-if-in-upstream:: @@ -219,9 +219,9 @@ populated with placeholder text. Use the contents of <file> instead of the branch's description for generating the cover letter. ---subject-prefix=<subject prefix>:: +--subject-prefix=<subject-prefix>:: Instead of the standard '[PATCH]' prefix in the subject - line, instead use '[<subject prefix>]'. This can be used + line, instead use '[<subject-prefix>]'. This can be used to name a patch series, and can be combined with the `--numbered` option. + @@ -403,7 +403,7 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. `format.useAutoBase` configuration. --root:: - Treat the revision argument as a <revision range>, even if it + Treat the revision argument as a <revision-range>, even if it is just a single commit (that would normally be treated as a <since>). Note that root commits included in the specified range are always formatted as creation patches, independently @@ -610,8 +610,8 @@ Approach #3 (external editor) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following Thunderbird extensions are needed: -AboutConfig from http://aboutconfig.mozdev.org/ and -External Editor from http://globs.org/articles.php?lng=en&pg=8 +AboutConfig from https://mjg.github.io/AboutConfig/ and +External Editor from https://globs.org/articles.php?lng=en&pg=8 1. Prepare the patch as a text file using your method of choice. diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 0d0103c..1e6d7b6 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -28,7 +28,7 @@ SYNOPSIS [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] [--recurse-submodules] [--parent-basename <basename>] - [ [--[no-]exclude-standard] [--cached | --no-index | --untracked] | <tree>...] + [ [--[no-]exclude-standard] [--cached | --untracked | --no-index] | <tree>...] [--] [<pathspec>...] DESCRIPTION @@ -45,13 +45,21 @@ OPTIONS Instead of searching tracked files in the working tree, search blobs registered in the index file. ---no-index:: - Search files in the current directory that is not managed by Git. - --untracked:: In addition to searching in the tracked files in the working tree, search also in untracked files. +--no-index:: + Search files in the current directory that is not managed by Git, + or by ignoring that the current directory is managed by Git. This + is rather similar to running the regular `grep(1)` utility with its + `-r` option specified, but with some additional benefits, such as + using pathspec patterns to limit paths; see the 'pathspec' entry + in linkgit:gitglossary[7] for more information. ++ +This option cannot be used together with `--cached` or `--untracked`. +See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below. + --no-exclude-standard:: Also search in ignored files by not honoring the `.gitignore` mechanism. Only useful with `--untracked`. @@ -64,9 +72,9 @@ OPTIONS --recurse-submodules:: Recursively search in each submodule that is active and checked out in the repository. When used in combination with the - <tree> option the prefix of all submodule output will be the name of - the parent project's <tree> object. This option has no effect - if `--no-index` is given. + _<tree>_ option the prefix of all submodule output will be the name of + the parent project's _<tree>_ object. This option cannot be used together + with `--untracked`, and it has no effect if `--no-index` is specified. -a:: --text:: @@ -178,7 +186,7 @@ providing this option will cause it to die. Use \0 as the delimiter for pathnames in the output, and print them verbatim. Without this option, pathnames with "unusual" characters are quoted as explained for the configuration - variable core.quotePath (see linkgit:git-config[1]). + variable `core.quotePath` (see linkgit:git-config[1]). -o:: --only-matching:: @@ -248,8 +256,8 @@ providing this option will cause it to die. a non-zero status. --threads <num>:: - Number of grep worker threads to use. - See `grep.threads` in 'CONFIGURATION' for more information. + Number of `grep` worker threads to use. See 'NOTES ON THREADS' + and `grep.threads` in 'CONFIGURATION' for more information. -f <file>:: Read patterns from <file>, one per line. @@ -332,13 +340,13 @@ EXAMPLES NOTES ON THREADS ---------------- -The `--threads` option (and the grep.threads configuration) will be ignored when +The `--threads` option (and the `grep.threads` configuration) will be ignored when `--open-files-in-pager` is used, forcing a single-threaded execution. When grepping the object store (with `--cached` or giving tree objects), running -with multiple threads might perform slower than single threaded if `--textconv` -is given and there are too many text conversions. So if you experience low -performance in this case, it might be desirable to use `--threads=1`. +with multiple threads might perform slower than single-threaded if `--textconv` +is given and there are too many text conversions. Thus, if low performance is +experienced in this case, it might be desirable to use `--threads=1`. CONFIGURATION ------------- diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index f7b1851..c8a89d7 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -135,7 +135,7 @@ flames ridiculing you if you don't check this. Thunderbird in particular is known to be problematic. Thunderbird users may wish to visit this web page for more information: - http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email + https://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email SEE ALSO -------- diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 6486620..5a20dee 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -79,8 +79,13 @@ OPTIONS to force the version for the generated pack index, and to force 64-bit index entries on objects located above the given offset. ---strict:: - Die, if the pack contains broken objects or links. +--strict[=<msg-id>=<severity>...]:: + Die, if the pack contains broken objects or links. An optional + comma-separated list of `<msg-id>=<severity>` can be passed to change + the severity of some possible issues, e.g., + `--strict="missingEmail=ignore,badTagName=error"`. See the entry for the + `fsck.<msg-id>` configuration options in linkgit:git-fsck[1] for more + information on the possible values of `<msg-id>` and `<severity>`. --progress-title:: For internal use only. @@ -91,13 +96,18 @@ default and "Indexing objects" when `--stdin` is specified. --check-self-contained-and-connected:: Die if the pack contains broken links. For internal use only. ---fsck-objects:: - For internal use only. +--fsck-objects[=<msg-id>=<severity>...]:: + Die if the pack contains broken objects, but unlike `--strict`, don't + choke on broken links. If the pack contains a tree pointing to a + .gitmodules blob that does not exist, prints the hash of that blob + (for the caller to check) after the hash that goes into the name of the + pack/idx file (see "Notes"). + -Die if the pack contains broken objects. If the pack contains a tree -pointing to a .gitmodules blob that does not exist, prints the hash of -that blob (for the caller to check) after the hash that goes into the -name of the pack/idx file (see "Notes"). +An optional comma-separated list of `<msg-id>=<severity>` can be passed to +change the severity of some possible issues, e.g., +`--fsck-objects="missingEmail=ignore,badTagName=ignore"`. See the entry for the +`fsck.<msg-id>` configuration options in linkgit:git-fsck[1] for more +information on the possible values of `<msg-id>` and `<severity>`. --threads=<n>:: Specifies the number of threads to spawn when resolving diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 6f0d297..daff93b 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -9,10 +9,11 @@ git-init - Create an empty Git repository or reinitialize an existing one SYNOPSIS -------- [verse] -'git init' [-q | --quiet] [--bare] [--template=<template-directory>] - [--separate-git-dir <git-dir>] [--object-format=<format>] - [-b <branch-name> | --initial-branch=<branch-name>] - [--shared[=<permissions>]] [<directory>] +`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__] + [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__] + [++--ref-format=++__<format>__] + [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__] + [++--shared++[++=++__<permissions>__]] [_<directory>_] DESCRIPTION @@ -32,37 +33,43 @@ If the object storage directory is specified via the are created underneath; otherwise, the default `$GIT_DIR/objects` directory is used. -Running 'git init' in an existing repository is safe. It will not +Running `git init` in an existing repository is safe. It will not overwrite things that are already there. The primary reason for -rerunning 'git init' is to pick up newly added templates (or to move -the repository to another place if --separate-git-dir is given). +rerunning `git init` is to pick up newly added templates (or to move +the repository to another place if `--separate-git-dir` is given). OPTIONS ------- --q:: ---quiet:: +`-q`:: +`--quiet`:: Only print error and warning messages; all other output will be suppressed. ---bare:: +`--bare`:: Create a bare repository. If `GIT_DIR` environment is not set, it is set to the current working directory. ---object-format=<format>:: +++--object-format=++__<format>__:: -Specify the given object format (hash algorithm) for the repository. The valid -values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default. +Specify the given object _<format>_ (hash algorithm) for the repository. The valid +values are `sha1` and (if enabled) `sha256`. `sha1` is the default. + include::object-format-disclaimer.txt[] ---template=<template-directory>:: +++--ref-format=++__<format>__:: + +Specify the given ref storage _<format>_ for the repository. The valid values are: ++ +include::ref-storage-format.txt[] + +++--template=++__<template-directory>__:: Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) ---separate-git-dir=<git-dir>:: +++--separate-git-dir=++__<git-dir>__:: Instead of initializing the repository as a directory to either `$GIT_DIR` or `./.git/`, create a text file there containing the path to the actual @@ -71,52 +78,56 @@ repository. + If this is a reinitialization, the repository will be moved to the specified path. --b <branch-name>:: ---initial-branch=<branch-name>:: +`-b` _<branch-name>_:: +++--initial-branch=++__<branch-name>__:: -Use the specified name for the initial branch in the newly created +Use _<branch-name>_ for the initial branch in the newly created repository. If not specified, fall back to the default name (currently `master`, but this is subject to change in the future; the name can be customized via the `init.defaultBranch` configuration variable). ---shared[=(false|true|umask|group|all|world|everybody|<perm>)]:: +++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]:: Specify that the Git repository is to be shared amongst several users. This allows users belonging to the same group to push into that -repository. When specified, the config variable "core.sharedRepository" is +repository. When specified, the config variable `core.sharedRepository` is set so that files and directories under `$GIT_DIR` are created with the requested permissions. When not specified, Git will use permissions reported -by umask(2). +by `umask`(2). + -The option can have the following values, defaulting to 'group' if no value +The option can have the following values, defaulting to `group` if no value is given: + -- -'umask' (or 'false'):: +`umask`:: +`false`:: -Use permissions reported by umask(2). The default, when `--shared` is not +Use permissions reported by `umask`(2). The default, when `--shared` is not specified. -'group' (or 'true'):: +`group`:: +`true`:: -Make the repository group-writable, (and g+sx, since the git group may not be +Make the repository group-writable, (and `g+sx`, since the git group may not be the primary group of all users). This is used to loosen the permissions of an -otherwise safe umask(2) value. Note that the umask still applies to the other -permission bits (e.g. if umask is '0022', using 'group' will not remove read -privileges from other (non-group) users). See '0xxx' for how to exactly specify +otherwise safe `umask`(2) value. Note that the umask still applies to the other +permission bits (e.g. if umask is `0022`, using `group` will not remove read +privileges from other (non-group) users). See `0xxx` for how to exactly specify the repository permissions. -'all' (or 'world' or 'everybody'):: +`all`:: +`world`:: +`everybody`:: -Same as 'group', but make the repository readable by all users. +Same as `group`, but make the repository readable by all users. -'<perm>':: +_<perm>_:: -'<perm>' is a 3-digit octal number prefixed with `0` and each file -will have mode '<perm>'. '<perm>' will override users' umask(2) -value (and not only loosen permissions as 'group' and 'all' -do). '0640' will create a repository which is group-readable, but -not group-writable or accessible to others. '0660' will create a repo +_<perm>_ is a 3-digit octal number prefixed with `0` and each file +will have mode _<perm>_. _<perm>_ will override users' `umask`(2) +value (and not only loosen permissions as `group` and `all` +do). `0640` will create a repository which is group-readable, but +not group-writable or accessible to others. `0660` will create a repo that is readable and writable to the current user and group, but inaccessible to others (directories and executable files get their `x` bit from the `r` bit for corresponding classes of users). @@ -126,7 +137,7 @@ By default, the configuration flag `receive.denyNonFastForwards` is enabled in shared repositories, so that you cannot force a non fast-forwarding push into it. -If you provide a 'directory', the command is run inside it. If this directory +If you provide a _<directory>_, the command is run inside it. If this directory does not exist, it will be created. TEMPLATE DIRECTORY @@ -165,7 +176,7 @@ $ git add . <2> $ git commit <3> ---------------- + -<1> Create a /path/to/my/codebase/.git directory. +<1> Create a `/path/to/my/codebase/.git` directory. <2> Add all existing files to the index. <3> Record the pristine state as the first commit in the history. @@ -174,6 +185,8 @@ CONFIGURATION include::includes/cmd-config-section-all.txt[] +:git-init: + include::config/init.txt[] GIT diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 418265f..d9dfb75 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git interpret-trailers' [--in-place] [--trim-empty] - [(--trailer (<key>|<keyAlias>)[(=|:)<value>])...] + [(--trailer (<key>|<key-alias>)[(=|:)<value>])...] [--parse] [<file>...] DESCRIPTION @@ -67,9 +67,9 @@ key: value This means that the trimmed <key> and <value> will be separated by `': '` (one colon followed by one space). -For convenience, a <keyAlias> can be configured to make using `--trailer` +For convenience, a <key-alias> can be configured to make using `--trailer` shorter to type on the command line. This can be configured using the -'trailer.<keyAlias>.key' configuration variable. The <keyAlias> must be a prefix +'trailer.<key-alias>.key' configuration variable. The <keyAlias> must be a prefix of the full <key> string, although case sensitivity does not matter. For example, if you have diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index f65a8cd..d08c7da 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -119,8 +119,10 @@ OPTIONS --exclude-per-directory=<file>:: Read additional exclude patterns that apply only to the - directory and its subdirectories in <file>. Deprecated; use - --exclude-standard instead. + directory and its subdirectories in <file>. If you are + trying to emulate the way Porcelain commands work, using + the `--exclude-standard` option instead is easier and more + thorough. --exclude-standard:: Add the standard Git exclusions: .git/info/exclude, .gitignore @@ -298,9 +300,8 @@ traversing the directory tree and finding files to show when the flags --others or --ignored are specified. linkgit:gitignore[5] specifies the format of exclude patterns. -Generally, you should just use --exclude-standard, but for historical -reasons the exclude patterns can be specified from the following -places, in order: +These exclude patterns can be specified from the following places, +in order: 1. The command-line flag --exclude=<pattern> specifies a single pattern. Patterns are ordered in the same order @@ -322,6 +323,18 @@ top of the directory tree. A pattern read from a file specified by --exclude-per-directory is relative to the directory that the pattern file appears in. +Generally, you should be able to use `--exclude-standard` when you +want the exclude rules applied the same way as what Porcelain +commands do. To emulate what `--exclude-standard` specifies, you +can give `--exclude-per-directory=.gitignore`, and then specify: + + 1. The file specified by the `core.excludesfile` configuration + variable, if exists, or the `$XDG_CONFIG_HOME/git/ignore` file. + + 2. The `$GIT_DIR/info/exclude` file. + +via the `--exclude-from=` option. + SEE ALSO -------- linkgit:git-read-tree[1], linkgit:gitignore[5] diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 6a081ea..71915a0 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -92,6 +92,12 @@ object store and the object ID of its blob is written to standard output. Instead of leaving conflicts in the file, resolve conflicts favouring our (or their or both) side of the lines. +--diff-algorithm={patience|minimal|histogram|myers}:: + Use a different diff algorithm while merging. The current default is "myers", + but selecting more recent algorithm such as "histogram" can help + avoid mismerges that occur due to unimportant matching lines + (such as braces from distinct functions). See also + linkgit:git-diff[1] `--diff-algorithm`. EXAMPLES -------- diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index b50acac..dd388fa 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -64,10 +64,13 @@ OPTIONS share no common history. This flag can be given to override that check and make the merge proceed anyway. ---merge-base=<commit>:: +--merge-base=<tree-ish>:: Instead of finding the merge-bases for <branch1> and <branch2>, specify a merge-base for the merge, and specifying multiple bases is currently not supported. This option is incompatible with `--stdin`. ++ +As the merge-base is provided directly, <branch1> and <branch2> do not need +to specify commits; trees are enough. [[OUTPUT]] OUTPUT diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index e8ab340..1ab69f6 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -20,12 +20,12 @@ DESCRIPTION ----------- Incorporates changes from the named commits (since the time their histories diverged from the current branch) into the current -branch. This command is used by 'git pull' to incorporate changes +branch. This command is used by `git pull` to incorporate changes from another repository and can be used by hand to merge changes from one branch into another. Assume the following history exists and the current branch is -"`master`": +`master`: ------------ A---B---C topic @@ -33,7 +33,7 @@ Assume the following history exists and the current branch is D---E---F---G master ------------ -Then "`git merge topic`" will replay the changes made on the +Then `git merge topic` will replay the changes made on the `topic` branch since it diverged from `master` (i.e., `E`) until its current commit (`C`) on top of `master`, and record the result in a new commit along with the names of the two parent commits and @@ -46,21 +46,21 @@ a log message from the user describing the changes. Before the operation, D---E---F---G---H master ------------ -The second syntax ("`git merge --abort`") can only be run after the -merge has resulted in conflicts. 'git merge --abort' will abort the -merge process and try to reconstruct the pre-merge state. However, -if there were uncommitted changes when the merge started (and -especially if those changes were further modified after the merge -was started), 'git merge --abort' will in some cases be unable to -reconstruct the original (pre-merge) changes. Therefore: +A merge stops if there's a conflict that cannot be resolved +automatically or if `--no-commit` was provided when initiating the +merge. At that point you can run `git merge --abort` or `git merge +--continue`. -*Warning*: Running 'git merge' with non-trivial uncommitted changes is +`git merge --abort` will abort the merge process and try to reconstruct +the pre-merge state. However, if there were uncommitted changes when the +merge started (and especially if those changes were further modified +after the merge was started), `git merge --abort` will in some cases be +unable to reconstruct the original (pre-merge) changes. Therefore: + +*Warning*: Running `git merge` with non-trivial uncommitted changes is discouraged: while possible, it may leave you in a state that is hard to back out of in the case of a conflict. -The third syntax ("`git merge --continue`") can only be run after the -merge has resulted in conflicts. - OPTIONS ------- :git-merge: 1 @@ -74,8 +74,8 @@ include::merge-options.txt[] If `--log` is specified, a shortlog of the commits being merged will be appended to the specified message. + -The 'git fmt-merge-msg' command can be -used to give a good default for automated 'git merge' +The `git fmt-merge-msg` command can be +used to give a good default for automated `git merge` invocations. The automated message can include the branch description. --into-name <branch>:: @@ -104,14 +104,14 @@ include::rerere-options.txt[] present, apply it to the worktree. + If there were uncommitted worktree changes present when the merge -started, 'git merge --abort' will in some cases be unable to +started, `git merge --abort` will in some cases be unable to reconstruct these changes. It is therefore recommended to always -commit or stash your changes before running 'git merge'. +commit or stash your changes before running `git merge`. + -'git merge --abort' is equivalent to 'git reset --merge' when +`git merge --abort` is equivalent to `git reset --merge` when `MERGE_HEAD` is present unless `MERGE_AUTOSTASH` is also present in -which case 'git merge --abort' applies the stash entry to the worktree -whereas 'git reset --merge' will save the stashed changes in the stash +which case `git merge --abort` applies the stash entry to the worktree +whereas `git reset --merge` will save the stashed changes in the stash list. --quit:: @@ -120,8 +120,8 @@ list. stash entry will be saved to the stash list. --continue:: - After a 'git merge' stops due to conflicts you can conclude the - merge by running 'git merge --continue' (see "HOW TO RESOLVE + After a `git merge` stops due to conflicts you can conclude the + merge by running `git merge --continue` (see "HOW TO RESOLVE CONFLICTS" section below). <commit>...:: @@ -144,25 +144,25 @@ PRE-MERGE CHECKS Before applying outside changes, you should get your own work in good shape and committed locally, so it will not be clobbered if there are conflicts. See also linkgit:git-stash[1]. -'git pull' and 'git merge' will stop without doing anything when -local uncommitted changes overlap with files that 'git pull'/'git -merge' may need to update. +`git pull` and `git merge` will stop without doing anything when +local uncommitted changes overlap with files that `git pull`/`git +merge` may need to update. To avoid recording unrelated changes in the merge commit, -'git pull' and 'git merge' will also abort if there are any changes +`git pull` and `git merge` will also abort if there are any changes registered in the index relative to the `HEAD` commit. (Special narrow exceptions to this rule may exist depending on which merge strategy is in use, but generally, the index must match HEAD.) -If all named commits are already ancestors of `HEAD`, 'git merge' +If all named commits are already ancestors of `HEAD`, `git merge` will exit early with the message "Already up to date." FAST-FORWARD MERGE ------------------ Often the current branch head is an ancestor of the named commit. -This is the most common case especially when invoked from 'git -pull': you are tracking an upstream repository, you have committed +This is the most common case especially when invoked from `git +pull`: you are tracking an upstream repository, you have committed no local changes, and now you want to update to a newer upstream revision. In this case, a new commit is not needed to store the combined history; instead, the `HEAD` (along with the index) is @@ -196,7 +196,7 @@ happens: can inspect the stages with `git ls-files -u`). The working tree files contain the result of the merge operation; i.e. 3-way merge results with familiar conflict markers `<<<` `===` `>>>`. -5. A special ref `AUTO_MERGE` is written, pointing to a tree +5. A ref named `AUTO_MERGE` is written, pointing to a tree corresponding to the current content of the working tree (including conflict markers for textual conflicts). Note that this ref is only written when the 'ort' merge strategy is used (the default). @@ -269,7 +269,7 @@ Barbie's remark on your side. The only thing you can tell is that your side wants to say it is hard and you'd prefer to go shopping, while the other side wants to claim it is easy. -An alternative style can be used by setting the "merge.conflictStyle" +An alternative style can be used by setting the `merge.conflictStyle` configuration variable to either "diff3" or "zdiff3". In "diff3" style, the above conflict may look like this: @@ -328,10 +328,10 @@ After seeing a conflict, you can do two things: * Resolve the conflicts. Git will mark the conflicts in the working tree. Edit the files into shape and - 'git add' them to the index. Use 'git commit' or - 'git merge --continue' to seal the deal. The latter command + `git add` them to the index. Use `git commit` or + `git merge --continue` to seal the deal. The latter command checks whether there is a (interrupted) merge in progress - before calling 'git commit'. + before calling `git commit`. You can work through the conflict with a number of tools: @@ -392,7 +392,7 @@ CONFIGURATION branch.<name>.mergeOptions:: Sets default options for merging into branch <name>. The syntax and - supported options are the same as those of 'git merge', but option + supported options are the same as those of `git merge`, but option values containing whitespace characters are currently not supported. include::includes/cmd-config-section-rest.txt[] diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index 7f991a3..dc1bf61 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -16,7 +16,7 @@ DESCRIPTION Move or rename a file, directory, or symlink. git mv [-v] [-f] [-n] [-k] <source> <destination> - git mv [-v] [-f] [-n] [-k] <source> ... <destination directory> + git mv [-v] [-f] [-n] [-k] <source> ... <destination-directory> In the first form, it renames <source>, which must exist and be either a file, symlink or directory, to <destination>. diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index f8310e5..c9221a6 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -56,7 +56,7 @@ SUBCOMMANDS list:: List the notes object for a given object. If no object is given, show a list of all note objects and the objects they - annotate (in the format "<note object> <annotated object>"). + annotate (in the format "<note-object> <annotated-object>"). This is the default subcommand if no subcommand is given. add:: diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 284956a..2dcabaf 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -8,7 +8,7 @@ git-pack-refs - Pack heads and tags for efficient repository access SYNOPSIS -------- [verse] -'git pack-refs' [--all] [--no-prune] [--include <pattern>] [--exclude <pattern>] +'git pack-refs' [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>] DESCRIPTION ----------- @@ -60,6 +60,19 @@ with many branches of historical interests. The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. +--auto:: + +Pack refs as needed depending on the current state of the ref database. The +behavior depends on the ref format used by the repository and may change in the +future. ++ + - "files": No special handling for `--auto` has been implemented. ++ + - "reftable": Tables are compacted such that they form a geometric + sequence. For two tables N and N+1, where N+1 is newer, this + maintains the property that N is at least twice as big as N+1. Only + tables that violate this property are compacted. + --include <pattern>:: Pack refs based on a `glob(7)` pattern. Repetitions of this option diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 0e14f8b..b2ae496 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -87,7 +87,7 @@ OPTIONS --verbose:: Pass --verbose to git-fetch and git-merge. ---[no-]recurse-submodules[=yes|on-demand|no]:: +--[no-]recurse-submodules[=(yes|on-demand|no)]:: This option controls if new commits of populated submodules should be fetched, and if the working trees of active submodules should be updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and @@ -105,7 +105,7 @@ Options related to merging include::merge-options.txt[] -r:: ---rebase[=false|true|merges|interactive]:: +--rebase[=(false|true|merges|interactive)]:: When true, rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to the upstream branch and the upstream branch diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index b4526ca..74df345 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -12,7 +12,7 @@ SYNOPSIS [--onto <newbase> | --keep-base] [<upstream> [<branch>]] 'git rebase' [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>] --root [<branch>] -'git rebase' (--continue | --skip | --abort | --quit | --edit-todo | --show-current-patch) +'git rebase' (--continue|--skip|--abort|--quit|--edit-todo|--show-current-patch) DESCRIPTION ----------- @@ -289,17 +289,25 @@ See also INCOMPATIBLE OPTIONS below. + See also INCOMPATIBLE OPTIONS below. ---empty=(drop|keep|ask):: +--empty=(drop|keep|stop):: How to handle commits that are not empty to start and are not clean cherry-picks of any upstream commit, but which become empty after rebasing (because they contain a subset of already - upstream changes). With drop (the default), commits that - become empty are dropped. With keep, such commits are kept. - With ask (implied by `--interactive`), the rebase will halt when - an empty commit is applied allowing you to choose whether to - drop it, edit files more, or just commit the empty changes. - Other options, like `--exec`, will use the default of drop unless - `-i`/`--interactive` is explicitly specified. + upstream changes): ++ +-- +`drop`;; + The commit will be dropped. This is the default behavior. +`keep`;; + The commit will be kept. This option is implied when `--exec` is + specified unless `-i`/`--interactive` is also specified. +`stop`;; +`ask`;; + The rebase will halt when the commit is applied, allowing you to + choose whether to drop it, edit files more, or just commit the empty + changes. This option is implied when `-i`/`--interactive` is + specified. `ask` is a deprecated synonym of `stop`. +-- + Note that commits which start empty are kept (unless `--no-keep-empty` is specified), and commits which are clean cherry-picks (as determined @@ -523,7 +531,7 @@ See also INCOMPATIBLE OPTIONS below. + The commit list format can be changed by setting the configuration option rebase.instructionFormat. A customized instruction format will automatically -have the long commit hash prepended to the format. +have the commit hash prepended to the format. + See also INCOMPATIBLE OPTIONS below. @@ -589,21 +597,27 @@ See also INCOMPATIBLE OPTIONS below. --autosquash:: --no-autosquash:: - When the commit log message begins with "squash! ..." or "fixup! ..." - or "amend! ...", and there is already a commit in the todo list that - matches the same `...`, automatically modify the todo list of - `rebase -i`, so that the commit marked for squashing comes right after - the commit to be modified, and change the action of the moved commit - from `pick` to `squash` or `fixup` or `fixup -C` respectively. A commit - matches the `...` if the commit subject matches, or if the `...` refers - to the commit's hash. As a fall-back, partial matches of the commit - subject work, too. The recommended way to create fixup/amend/squash - commits is by using the `--fixup`, `--fixup=amend:` or `--fixup=reword:` - and `--squash` options respectively of linkgit:git-commit[1]. + Automatically squash commits with specially formatted messages into + previous commits being rebased. If a commit message starts with + "squash! ", "fixup! " or "amend! ", the remainder of the subject line + is taken as a commit specifier, which matches a previous commit if it + matches the subject line or the hash of that commit. If no commit + matches fully, matches of the specifier with the start of commit + subjects are considered. ++ +In the rebase todo list, the actions of squash, fixup and amend commits are +changed from `pick` to `squash`, `fixup` or `fixup -C`, respectively, and they +are moved right after the commit they modify. The `--interactive` option can +be used to review and edit the todo list before proceeding. + -If the `--autosquash` option is enabled by default using the -configuration variable `rebase.autoSquash`, this option can be -used to override and disable this setting. +The recommended way to create commits with squash markers is by using the +`--squash`, `--fixup`, `--fixup=amend:` or `--fixup=reword:` options of +linkgit:git-commit[1], which take the target commit as an argument and +automatically fill in the subject line of the new commit from that. ++ +Setting configuration variable `rebase.autoSquash` to true enables +auto-squashing by default for interactive rebase. The `--no-autosquash` +option can be used to override that setting. + See also INCOMPATIBLE OPTIONS below. @@ -620,13 +634,16 @@ See also INCOMPATIBLE OPTIONS below. Automatically reschedule `exec` commands that failed. This only makes sense in interactive mode (or when an `--exec` option was provided). + -Even though this option applies once a rebase is started, it's set for -the whole rebase at the start based on either the -`rebase.rescheduleFailedExec` configuration (see linkgit:git-config[1] -or "CONFIGURATION" below) or whether this option is -provided. Otherwise an explicit `--no-reschedule-failed-exec` at the -start would be overridden by the presence of -`rebase.rescheduleFailedExec=true` configuration. +This option applies once a rebase is started. It is preserved for the whole +rebase based on, in order, the command line option provided to the initial `git +rebase`, the `rebase.rescheduleFailedExec` configuration (see +linkgit:git-config[1] or "CONFIGURATION" below), or it defaults to false. ++ +Recording this option for the whole rebase is a convenience feature. Otherwise +an explicit `--no-reschedule-failed-exec` at the start would be overridden by +the presence of a `rebase.rescheduleFailedExec=true` configuration when `git +rebase --continue` is invoked. Currently, you cannot pass +`--[no-]reschedule-failed-exec` to `git rebase --continue`. --update-refs:: --no-update-refs:: @@ -695,7 +712,7 @@ be dropped automatically with `--no-keep-empty`). Similar to the apply backend, by default the merge backend drops commits that become empty unless `-i`/`--interactive` is specified (in which case it stops and asks the user what to do). The merge backend -also has an `--empty=(drop|keep|ask)` option for changing the behavior +also has an `--empty=(drop|keep|stop)` option for changing the behavior of handling commits that become empty. Directory rename detection @@ -957,10 +974,9 @@ The interactive rebase will stop when a command fails (i.e. exits with non-0 status) to give you an opportunity to fix the problem. You can continue with `git rebase --continue`. -The "exec" command launches the command in a shell (the one specified -in `$SHELL`, or the default shell if `$SHELL` is not set), so you can -use shell features (like "cd", ">", ";" ...). The command is run from -the root of the working tree. +The "exec" command launches the command in a shell (the default one, usually +/bin/sh), so you can use shell features (like "cd", ">", ";" ...). The command +is run from the root of the working tree. ---------------------------------- $ git rebase -i --exec "make test" diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index ec64cbf..a929c52 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git reflog' [show] [<log-options>] [<ref>] +'git reflog list' 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>] [--rewrite] [--updateref] [--stale-fix] [--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...] @@ -39,6 +40,8 @@ actions, and in addition the `HEAD` reflog records branch switching. `git reflog show` is an alias for `git log -g --abbrev-commit --pretty=oneline`; see linkgit:git-log[1] for more information. +The "list" subcommand lists all refs which have a corresponding reflog. + The "expire" subcommand prunes older reflog entries. Entries older than `expire` time, or entries older than `expire-unreachable` time and not reachable from the current tip, are removed from the reflog. diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 1dec314..932a5c3 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -35,7 +35,7 @@ OPTIONS -v:: --verbose:: Be a little more verbose and show remote url after name. - For promisor remotes, also show which filter (`blob:none` etc.) + For promisor remotes, also show which filters (`blob:none` etc.) are configured. NOTE: This must be placed between `remote` and subcommand. diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 4f25712..0a65460 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -114,11 +114,11 @@ FORMATS The following formats are available: * 'short': - <replaced sha1> + <replaced-sha1> * 'medium': - <replaced sha1> -> <replacement sha1> + <replaced-sha1> -> <replacement-sha1> * 'long': - <replaced sha1> (<replaced type>) -> <replacement sha1> (<replacement type>) + <replaced-sha1> (<replaced-type>) -> <replacement-sha1> (<replacement-type>) CREATING REPLACEMENT OBJECTS ---------------------------- diff --git a/Documentation/git-replay.txt b/Documentation/git-replay.txt new file mode 100644 index 0000000..8f3300c --- /dev/null +++ b/Documentation/git-replay.txt @@ -0,0 +1,127 @@ +git-replay(1) +============= + +NAME +---- +git-replay - EXPERIMENTAL: Replay commits on a new base, works with bare repos too + + +SYNOPSIS +-------- +[verse] +(EXPERIMENTAL!) 'git replay' ([--contained] --onto <newbase> | --advance <branch>) <revision-range>... + +DESCRIPTION +----------- + +Takes ranges of commits and replays them onto a new location. Leaves +the working tree and the index untouched, and updates no references. +The output of this command is meant to be used as input to +`git update-ref --stdin`, which would update the relevant branches +(see the OUTPUT section below). + +THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. + +OPTIONS +------- + +--onto <newbase>:: + Starting point at which to create the new commits. May be any + valid commit, and not just an existing branch name. ++ +When `--onto` is specified, the update-ref command(s) in the output will +update the branch(es) in the revision range to point at the new +commits, similar to the way how `git rebase --update-refs` updates +multiple branches in the affected range. + +--advance <branch>:: + Starting point at which to create the new commits; must be a + branch name. ++ +When `--advance` is specified, the update-ref command(s) in the output +will update the branch passed as an argument to `--advance` to point at +the new commits (in other words, this mimics a cherry-pick operation). + +<revision-range>:: + Range of commits to replay. More than one <revision-range> can + be passed, but in `--advance <branch>` mode, they should have + a single tip, so that it's clear where <branch> should point + to. See "Specifying Ranges" in linkgit:git-rev-parse[1] and the + "Commit Limiting" options below. + +include::rev-list-options.txt[] + +OUTPUT +------ + +When there are no conflicts, the output of this command is usable as +input to `git update-ref --stdin`. It is of the form: + + update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH} + update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH} + update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH} + +where the number of refs updated depends on the arguments passed and +the shape of the history being replayed. When using `--advance`, the +number of refs updated is always one, but for `--onto`, it can be one +or more (rebasing multiple branches simultaneously is supported). + +EXIT STATUS +----------- + +For a successful, non-conflicted replay, the exit status is 0. When +the replay has conflicts, the exit status is 1. If the replay is not +able to complete (or start) due to some kind of error, the exit status +is something other than 0 or 1. + +EXAMPLES +-------- + +To simply rebase `mybranch` onto `target`: + +------------ +$ git replay --onto target origin/main..mybranch +update refs/heads/mybranch ${NEW_mybranch_HASH} ${OLD_mybranch_HASH} +------------ + +To cherry-pick the commits from mybranch onto target: + +------------ +$ git replay --advance target origin/main..mybranch +update refs/heads/target ${NEW_target_HASH} ${OLD_target_HASH} +------------ + +Note that the first two examples replay the exact same commits and on +top of the exact same new base, they only differ in that the first +provides instructions to make mybranch point at the new commits and +the second provides instructions to make target point at them. + +What if you have a stack of branches, one depending upon another, and +you'd really like to rebase the whole set? + +------------ +$ git replay --contained --onto origin/main origin/main..tipbranch +update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH} +update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH} +update refs/heads/tipbranch ${NEW_tipbranch_HASH} ${OLD_tipbranch_HASH} +------------ + +When calling `git replay`, one does not need to specify a range of +commits to replay using the syntax `A..B`; any range expression will +do: + +------------ +$ git replay --onto origin/main ^base branch1 branch2 branch3 +update refs/heads/branch1 ${NEW_branch1_HASH} ${OLD_branch1_HASH} +update refs/heads/branch2 ${NEW_branch2_HASH} ${OLD_branch2_HASH} +update refs/heads/branch3 ${NEW_branch3_HASH} ${OLD_branch3_HASH} +------------ + +This will simultaneously rebase `branch1`, `branch2`, and `branch3`, +all commits they have since `base`, playing them on top of +`origin/main`. These three branches may have commits on top of `base` +that they have in common, but that does not need to be the case. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 912fab9..f9d5a35 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -9,7 +9,7 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- [verse] -'git rev-parse' [<options>] <args>... +'git rev-parse' [<options>] <arg>... DESCRIPTION ----------- @@ -130,7 +130,7 @@ for another option. 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, the command input is still interpreted as usual. ---short[=length]:: +--short[=<length>]:: Same as `--verify` but shortens the object name to a unique prefix with at least `length` characters. The minimum length is 4, the default is the effective value of the `core.abbrev` @@ -159,15 +159,27 @@ for another option. unfortunately named tag "master"), and shows them as full refnames (e.g. "refs/heads/master"). +--output-object-format=(sha1|sha256|storage):: + + Allow oids to be input from any object format that the current + repository supports. + + Specifying "sha1" translates if necessary and returns a sha1 oid. + + Specifying "sha256" translates if necessary and returns a sha256 oid. + + Specifying "storage" translates if necessary and returns an oid in + encoded in the storage hash algorithm. + Options for Objects ~~~~~~~~~~~~~~~~~~~ --all:: Show all refs found in `refs/`. ---branches[=pattern]:: ---tags[=pattern]:: ---remotes[=pattern]:: +--branches[=<pattern>]:: +--tags[=<pattern>]:: +--remotes[=<pattern>]:: Show all branches, tags, or remote-tracking branches, respectively (i.e., refs found in `refs/heads`, `refs/tags`, or `refs/remotes`, respectively). @@ -176,7 +188,7 @@ If a `pattern` is given, only refs matching the given shell glob are shown. If the pattern does not contain a globbing character (`?`, `*`, or `[`), it is turned into a prefix match by appending `/*`. ---glob=pattern:: +--glob=<pattern>:: Show all refs matching the shell glob pattern `pattern`. If the pattern does not start with `refs/`, this is automatically prepended. If the pattern does not contain a globbing @@ -197,7 +209,7 @@ respectively, and they must begin with `refs/` when applied to `--glob` or `--all`. If a trailing '/{asterisk}' is intended, it must be given explicitly. ---exclude-hidden=[fetch|receive|uploadpack]:: +--exclude-hidden=(fetch|receive|uploadpack):: Do not include refs that would be hidden by `git-fetch`, `git-receive-pack` or `git-upload-pack` by consulting the appropriate `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` @@ -307,21 +319,24 @@ The following options are unaffected by `--path-format`: input, multiple algorithms may be printed, space-separated. If not specified, the default is "storage". +--show-ref-format:: + Show the reference storage format used for the repository. + Other Options ~~~~~~~~~~~~~ ---since=datestring:: ---after=datestring:: +--since=<datestring>:: +--after=<datestring>:: Parse the date string, and output the corresponding --max-age= parameter for 'git rev-list'. ---until=datestring:: ---before=datestring:: +--until=<datestring>:: +--before=<datestring>:: Parse the date string, and output the corresponding --min-age= parameter for 'git rev-list'. -<args>...:: +<arg>...:: Flags and parameters to be parsed. diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index cbe0208..568925d 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -116,7 +116,7 @@ include::rerere-options.txt[] --reference:: Instead of starting the body of the log message with "This - reverts <full object name of the commit being reverted>.", + reverts <full-object-name-of-the-commit-being-reverted>.", refer to the commit using "--pretty=reference" format (cf. linkgit:git-log[1]). The `revert.reference` configuration variable can be used to enable this option by @@ -149,7 +149,7 @@ While git creates a basic commit message automatically, it is _strongly_ recommended to explain why the original commit is being reverted. In addition, repeatedly reverting reverts will result in increasingly -unwieldy subject lines, for example 'Reapply "Reapply "<original subject>""'. +unwieldy subject lines, for example 'Reapply "Reapply "<original-subject>""'. Please consider rewording these to be shorter and more unique. CONFIGURATION diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 465011b..c5d664f 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -9,8 +9,8 @@ git-send-email - Send a collection of patches as emails SYNOPSIS -------- [verse] -'git send-email' [<options>] <file|directory>... -'git send-email' [<options>] <format-patch options> +'git send-email' [<options>] (<file>|<directory>)... +'git send-email' [<options>] <format-patch-options> 'git send-email' --dump-aliases @@ -138,7 +138,7 @@ Note that no attempts whatsoever are made to validate the encoding. --compose-encoding=<encoding>:: Specify encoding of compose message. Default is the value of the - 'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed. + 'sendemail.composeEncoding'; if that is unspecified, UTF-8 is assumed. --transfer-encoding=(7bit|8bit|quoted-printable|base64|auto):: Specify the transfer encoding to be used to send the message over SMTP. @@ -174,7 +174,7 @@ Sending Specify a command to run to send the email. The command should be sendmail-like; specifically, it must support the `-i` option. The command will be executed in the shell if necessary. Default - is the value of `sendemail.sendmailcmd`. If unspecified, and if + is the value of `sendemail.sendmailCmd`. If unspecified, and if --smtp-server is also unspecified, git-send-email will search for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH. @@ -269,7 +269,7 @@ must be used for each option. certificates concatenated together: see verify(1) -CAfile and -CApath for more information on these). Set it to an empty string to disable certificate verification. Defaults to the value of the - `sendemail.smtpsslcertpath` configuration variable, if set, or the + `sendemail.smtpSSLCertPath` configuration variable, if set, or the backing SSL library's compiled-in default otherwise (which should be the best choice on most platforms). @@ -278,7 +278,7 @@ must be used for each option. if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`), then authentication is not attempted. ---smtp-debug=0|1:: +--smtp-debug=(0|1):: Enable (1) or disable (0) debug output. If enabled, SMTP commands and replies will be printed. Useful to debug TLS connection and authentication problems. @@ -301,7 +301,9 @@ must be used for each option. Automating ~~~~~~~~~~ ---no-[to|cc|bcc]:: +--no-to:: +--no-cc:: +--no-bcc:: Clears any list of "To:", "Cc:", "Bcc:" addresses previously set via config. @@ -313,7 +315,7 @@ Automating Specify a command to execute once per patch file which should generate patch file specific "To:" entries. Output of this command must be single email address per line. - Default is the value of 'sendemail.tocmd' configuration value. + Default is the value of 'sendemail.toCmd' configuration value. --cc-cmd=<command>:: Specify a command to execute once per patch file which @@ -348,19 +350,19 @@ Automating --[no-]signed-off-by-cc:: If this is set, add emails found in the `Signed-off-by` trailer or Cc: lines to the - cc list. Default is the value of `sendemail.signedoffbycc` configuration + cc list. Default is the value of `sendemail.signedOffByCc` configuration value; if that is unspecified, default to --signed-off-by-cc. --[no-]cc-cover:: If this is set, emails found in Cc: headers in the first patch of the series (typically the cover letter) are added to the cc list - for each email set. Default is the value of 'sendemail.cccover' + for each email set. Default is the value of 'sendemail.ccCover' configuration value; if that is unspecified, default to --no-cc-cover. --[no-]to-cover:: If this is set, emails found in To: headers in the first patch of the series (typically the cover letter) are added to the to list - for each email set. Default is the value of 'sendemail.tocover' + for each email set. Default is the value of 'sendemail.toCover' configuration value; if that is unspecified, default to --no-to-cover. --suppress-cc=<category>:: @@ -384,7 +386,7 @@ Automating - 'all' will suppress all auto cc values. -- + -Default is the value of `sendemail.suppresscc` configuration value; if +Default is the value of `sendemail.suppressCc` configuration value; if that is unspecified, default to 'self' if --suppress-from is specified, as well as 'body' if --no-signed-off-cc is specified. @@ -454,7 +456,7 @@ have been specified, in which case default to 'compose'. 998 characters unless a suitable transfer encoding ('auto', 'base64', or 'quoted-printable') is used; this is due to SMTP limits as described by - http://www.ietf.org/rfc/rfc5322.txt. + https://www.ietf.org/rfc/rfc5322.txt. -- + Default is the value of `sendemail.validate`; if this is not set, @@ -471,7 +473,7 @@ Information Instead of the normal operation, dump the shorthand alias names from the configured alias file(s), one per line in alphabetical order. Note that this only includes the alias name and not its expanded email addresses. - See 'sendemail.aliasesfile' for more information about aliases. + See 'sendemail.aliasesFile' for more information about aliases. CONFIGURATION diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 10fecc5..9a37688 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -79,6 +79,8 @@ Consider enabling untracked cache and split index if supported (see `git update-index --untracked-cache` and `git update-index --split-index`), Otherwise you can use `no` to have `git status` return more quickly without showing untracked files. +All usual spellings for Boolean value `true` are taken as `normal` +and `false` as `no`. The default can be changed using the status.showUntrackedFiles configuration variable documented in linkgit:git-config[1]. @@ -309,7 +311,7 @@ Line Notes ------------------------------------------------------------ # branch.oid <commit> | (initial) Current commit. # branch.head <branch> | (detached) Current branch. -# branch.upstream <upstream_branch> If upstream is set. +# branch.upstream <upstream-branch> If upstream is set. # branch.ab +<ahead> -<behind> If upstream is set and the commit is present. ------------------------------------------------------------ @@ -472,7 +474,7 @@ again, because your configuration may already be caching `git status` results, so it could be faster on subsequent runs. * The `--untracked-files=no` flag or the - `status.showUntrackedfiles=false` config (see above for both): + `status.showUntrackedFiles=no` config (see above for both): indicate that `git status` should not report untracked files. This is the fastest option. `git status` will not list the untracked files, so you need to be careful to remember if @@ -502,7 +504,7 @@ results, so it could be faster on subsequent runs. usually worth the additional size. * `core.untrackedCache=true` and `core.fsmonitor=true` or - `core.fsmonitor=<hook_command_pathname>` (see + `core.fsmonitor=<hook-command-pathname>` (see linkgit:git-update-index[1]): enable both the untracked cache and FSMonitor features and only search directories that have been modified since the previous `git status` command. This diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 6957306..ca0347a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -136,7 +136,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>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]:: + -- Update the registered submodules to match what the superproject @@ -185,7 +185,7 @@ submodule with the `--init` option. If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. -If `--filter <filter spec>` is specified, the given partial clone filter will be +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 4e92308..43c68c2 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -37,12 +37,12 @@ COMMANDS argument. Normally this command initializes the current directory. --T<trunk_subdir>;; ---trunk=<trunk_subdir>;; --t<tags_subdir>;; ---tags=<tags_subdir>;; --b<branches_subdir>;; ---branches=<branches_subdir>;; +-T<trunk-subdir>;; +--trunk=<trunk-subdir>;; +-t<tags-subdir>;; +--tags=<tags-subdir>;; +-b<branches-subdir>;; +--branches=<branches-subdir>;; -s;; --stdlayout;; These are optional command-line options for init. Each of @@ -726,9 +726,9 @@ ADVANCED OPTIONS when tracking a single URL. The 'log' and 'dcommit' commands no longer require this switch as an argument. --R<remote name>:: ---svn-remote <remote name>:: - Specify the [svn-remote "<remote name>"] section to use, +-R<remote-name>:: +--svn-remote <remote-name>:: + Specify the [svn-remote "<remote-name>"] section to use, this allows SVN multiple repositories to be tracked. Default: "svn" diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt index c60fc9c..f38e4c8 100644 --- a/Documentation/git-switch.txt +++ b/Documentation/git-switch.txt @@ -59,13 +59,18 @@ out at most one of `A` and `B`, in which case it defaults to `HEAD`. -c <new-branch>:: --create <new-branch>:: Create a new branch named `<new-branch>` starting at - `<start-point>` before switching to the branch. This is a - convenient shortcut for: + `<start-point>` before switching to the branch. This is the + transactional equivalent of + ------------ $ git branch <new-branch> $ git switch <new-branch> ------------ ++ +that is to say, the branch is not reset/created unless "git switch" is +successful (e.g., when the branch is in use in another worktree, not +just the current branch stays the same, but the branch is not reset to +the start-point, either). -C <new-branch>:: --force-create <new-branch>:: @@ -171,7 +176,7 @@ name, the guessing is aborted. You can explicitly give a name with `branch.autoSetupMerge` configuration variable is true. --orphan <new-branch>:: - Create a new 'orphan' branch, named `<new-branch>`. All + Create a new unborn branch, named `<new-branch>`. All tracked files are removed. --ignore-other-worktrees:: diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index d42efb3..5fe519c 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -224,7 +224,7 @@ it in the repository configuration as follows: ------------------------------------- [user] - signingKey = <gpg-key_id> + signingKey = <gpg-key-id> ------------------------------------- `pager.tag` is only respected when listing tags, i.e., when `-l` is diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 0561808..374a2eb 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -8,21 +8,21 @@ git-update-ref - Update the object name stored in a ref safely SYNOPSIS -------- [verse] -'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<oldvalue>] | [--create-reflog] <ref> <newvalue> [<oldvalue>] | --stdin [-z]) +'git update-ref' [-m <reason>] [--no-deref] (-d <ref> [<old-oid>] | [--create-reflog] <ref> <new-oid> [<old-oid>] | --stdin [-z]) DESCRIPTION ----------- -Given two arguments, stores the <newvalue> in the <ref>, possibly +Given two arguments, stores the <new-oid> in the <ref>, possibly dereferencing the symbolic refs. E.g. `git update-ref HEAD -<newvalue>` updates the current branch head to the new object. +<new-oid>` updates the current branch head to the new object. -Given three arguments, stores the <newvalue> in the <ref>, +Given three arguments, stores the <new-oid> in the <ref>, possibly dereferencing the symbolic refs, after verifying that -the current value of the <ref> matches <oldvalue>. -E.g. `git update-ref refs/heads/master <newvalue> <oldvalue>` -updates the master branch head to <newvalue> only if its current -value is <oldvalue>. You can specify 40 "0" or an empty string -as <oldvalue> to make sure that the ref you are creating does +the current value of the <ref> matches <old-oid>. +E.g. `git update-ref refs/heads/master <new-oid> <old-oid>` +updates the master branch head to <new-oid> only if its current +value is <old-oid>. You can specify 40 "0" or an empty string +as <old-oid> to make sure that the ref you are creating does not exist. It also allows a "ref" file to be a symbolic pointer to another @@ -56,15 +56,15 @@ ref symlink to some other tree, if you have copied a whole archive by creating a symlink tree). With `-d` flag, it deletes the named <ref> after verifying it -still contains <oldvalue>. +still contains <old-oid>. With `--stdin`, update-ref reads instructions from standard input and performs all modifications together. Specify commands of the form: - update SP <ref> SP <newvalue> [SP <oldvalue>] LF - create SP <ref> SP <newvalue> LF - delete SP <ref> [SP <oldvalue>] LF - verify SP <ref> [SP <oldvalue>] LF + update SP <ref> SP <new-oid> [SP <old-oid>] LF + create SP <ref> SP <new-oid> LF + delete SP <ref> [SP <old-oid>] LF + verify SP <ref> [SP <old-oid>] LF option SP <opt> LF start LF prepare LF @@ -82,10 +82,10 @@ specify a missing value, omit the value and its preceding SP entirely. Alternatively, use `-z` to specify in NUL-terminated format, without quoting: - update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL - create SP <ref> NUL <newvalue> NUL - delete SP <ref> NUL [<oldvalue>] NUL - verify SP <ref> NUL [<oldvalue>] NUL + update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL + create SP <ref> NUL <new-oid> NUL + delete SP <ref> NUL [<old-oid>] NUL + verify SP <ref> NUL [<old-oid>] NUL option SP <opt> NUL start NUL prepare NUL @@ -100,22 +100,22 @@ recognizes as an object name. Commands in any other format or a repeated <ref> produce an error. Command meanings are: update:: - Set <ref> to <newvalue> after verifying <oldvalue>, if given. - Specify a zero <newvalue> to ensure the ref does not exist - after the update and/or a zero <oldvalue> to make sure the + Set <ref> to <new-oid> after verifying <old-oid>, if given. + Specify a zero <new-oid> to ensure the ref does not exist + after the update and/or a zero <old-oid> to make sure the ref does not exist before the update. create:: - Create <ref> with <newvalue> after verifying it does not - exist. The given <newvalue> may not be zero. + Create <ref> with <new-oid> after verifying it does not + exist. The given <new-oid> may not be zero. delete:: - Delete <ref> after verifying it exists with <oldvalue>, if - given. If given, <oldvalue> may not be zero. + Delete <ref> after verifying it exists with <old-oid>, if + given. If given, <old-oid> may not be zero. verify:: - Verify <ref> against <oldvalue> but do not change it. If - <oldvalue> is zero or missing, the ref must not exist. + Verify <ref> against <old-oid> but do not change it. If + <old-oid> is zero or missing, the ref must not exist. option:: Modify the behavior of the next command naming a <ref>. @@ -141,7 +141,7 @@ abort:: Abort the transaction, releasing all locks if the transaction is in prepared state. -If all <ref>s can be locked with matching <oldvalue>s +If all <ref>s can be locked with matching <old-oid>s simultaneously, all modifications are performed. Otherwise, no modifications are performed. Note that while each individual <ref> is updated or deleted atomically, a concurrent reader may @@ -161,7 +161,7 @@ formatted as: Where "oldsha1" is the 40 character hexadecimal value previously stored in <ref>, "newsha1" is the 40 character hexadecimal value of -<newvalue> and "committer" is the committer's name, email address +<new-oid> and "committer" is the committer's name, email address and date in the standard Git committer ident format. Optionally with -m: diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 7ad60bc..516d163 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -55,6 +55,37 @@ ENVIRONMENT admins may need to configure some transports to allow this variable to be passed. See the discussion in linkgit:git[1]. +`GIT_NO_LAZY_FETCH`:: + When cloning or fetching from a partial repository (i.e., one + itself cloned with `--filter`), the server-side `upload-pack` + may need to fetch extra objects from its upstream in order to + complete the request. By default, `upload-pack` will refuse to + perform such a lazy fetch, because `git fetch` may run arbitrary + commands specified in configuration and hooks of the source + repository (and `upload-pack` tries to be safe to run even in + untrusted `.git` directories). ++ +This is implemented by having `upload-pack` internally set the +`GIT_NO_LAZY_FETCH` variable to `1`. If you want to override it +(because you are fetching from a partial clone, and you are sure +you trust it), you can explicitly set `GIT_NO_LAZY_FETCH` to +`0`. + +SECURITY +-------- + +Most Git commands should not be run in an untrusted `.git` directory +(see the section `SECURITY` in linkgit:git[1]). `upload-pack` tries to +avoid any dangerous configuration options or hooks from the repository +it's serving, making it safe to clone an untrusted directory and run +commands on the resulting clone. + +For an extra level of safety, you may be able to run `upload-pack` as an +alternate user. The details will be platform dependent, but on many +systems you can run: + + git clone --no-local --upload-pack='sudo -u nobody git-upload-pack' ... + SEE ALSO -------- linkgit:gitnamespaces[7] diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 93d76f5..2a240f5 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -99,7 +99,7 @@ command will refuse to create the worktree (unless `--force` is used). If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is used, and there are no valid local branches (or remote branches if `--guess-remote` is specified) then, as a convenience, the new worktree is -associated with a new orphan branch named `<branch>` (after +associated with a new unborn branch named `<branch>` (after `$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was passed to the command. In the event the repository has a remote and `--guess-remote` is used, but no remote or local branches exist, then the @@ -234,7 +234,7 @@ This can also be set up as the default behaviour by using the --orphan:: With `add`, make the new worktree and index empty, associating - the worktree with a new orphan/unborn branch named `<new-branch>`. + the worktree with a new unborn branch named `<new-branch>`. --porcelain:: With `list`, output in an easy-to-parse format for scripts. diff --git a/Documentation/git.txt b/Documentation/git.txt index 2535a30..024a01d 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -174,8 +174,17 @@ If you just want to run git as if it was started in `<path>` then use directory. --no-replace-objects:: - Do not use replacement refs to replace Git objects. See - linkgit:git-replace[1] for more information. + Do not use replacement refs to replace Git objects. + This is equivalent to exporting the `GIT_NO_REPLACE_OBJECTS` + environment variable with any value. + See linkgit:git-replace[1] for more information. + +--no-lazy-fetch:: + Do not fetch missing objects from the promisor remote on + demand. Useful together with `git cat-file -e <object>` to + see if the object is locally available. + This is equivalent to setting the `GIT_NO_LAZY_FETCH` + environment variable to `1`. --literal-pathspecs:: Treat pathspecs literally (i.e. no globbing, no pathspec magic). @@ -202,7 +211,7 @@ If you just want to run git as if it was started in `<path>` then use Do not perform optional operations that require locks. This is equivalent to setting the `GIT_OPTIONAL_LOCKS` to `0`. ---list-cmds=group[,group...]:: +--list-cmds=<group>[,<group>...]:: List commands by group. This is an internal/experimental option and may change or be removed in the future. Supported groups are: builtins, parseopt (builtin commands that use @@ -556,6 +565,11 @@ double-quotes and respecting backslash escapes. E.g., the value is always used. The default is "sha1". See `--object-format` in linkgit:git-init[1]. +`GIT_DEFAULT_REF_FORMAT`:: + If this variable is set, the default reference backend format for new + repositories will be set to this value. The default is "files". + See `--ref-format` in linkgit:git-init[1]. + Git Commits ~~~~~~~~~~~ `GIT_AUTHOR_NAME`:: @@ -724,13 +738,12 @@ for further details. 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 + If this Boolean environment variable is set to true, then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', 'git check-attr' and 'git check-ignore' will force a flush of the output stream after each record have been flushed. If this - variable is set to "0", the output of these commands will be done + variable is set to false, the output of these commands will be done using completely buffered I/O. If this environment variable is not set, Git will choose buffered or record-oriented flushing based on whether stdout appears to be redirected to a file or not. @@ -838,7 +851,7 @@ of the SID and an optional counter (to avoid filename collisions). + In addition, if the variable is set to -`af_unix:[<socket_type>:]<absolute-pathname>`, Git will try +`af_unix:[<socket-type>:]<absolute-pathname>`, Git will try to open the path as a Unix Domain Socket. The socket type can be either `stream` or `dgram`. + @@ -868,6 +881,10 @@ for full details. header and packfile URIs. Set this Boolean environment variable to false to prevent this redaction. +`GIT_NO_REPLACE_OBJECTS`:: + Setting and exporting this environment variable tells Git to + ignore replacement refs and do not replace Git objects. + `GIT_LITERAL_PATHSPECS`:: Setting this Boolean environment variable to true will cause Git to treat all pathspecs literally, rather than as glob patterns. For example, @@ -889,6 +906,11 @@ for full details. Setting this Boolean environment variable to true will cause Git to treat all pathspecs as case-insensitive. +`GIT_NO_LAZY_FETCH`:: + Setting this Boolean environment variable to true tells Git + not to lazily fetch missing objects from the promisor remote + on demand. + `GIT_REFLOG_ACTION`:: When a ref is updated, reflog entries are created to keep track of the reason why the ref was updated (which is @@ -917,9 +939,9 @@ for full details. avoid issues with stale commit-graphs that contain references to already-deleted commits, but comes with a performance penalty. + -The default is "true", which enables the aforementioned behavior. -Setting this to "false" disables the existence check. This can lead to -a performance improvement at the cost of consistency. +The default is "false", which disables the aforementioned behavior. +Setting this to "true" enables the existence check so that stale commits +will never be returned from the commit-graph at the cost of performance. `GIT_ALLOW_PROTOCOL`:: If set to a colon-separated list of protocols, behave as if @@ -938,7 +960,7 @@ a performance improvement at the cost of consistency. `GIT_PROTOCOL`:: For internal use only. Used in handshaking the wire protocol. Contains a colon ':' separated list of keys with optional values - 'key[=value]'. Presence of unknown keys and values must be + '<key>[=<value>]'. Presence of unknown keys and values must be ignored. + Note that servers may need to be configured to allow this variable to @@ -1025,10 +1047,11 @@ When first created, objects are stored in individual files, but for efficiency may later be compressed together into "pack files". Named pointers called refs mark interesting points in history. A ref -may contain the SHA-1 name of an object or the name of another ref. Refs -with names beginning `ref/head/` contain the SHA-1 name of the most +may contain the SHA-1 name of an object or the name of another ref (the +latter is called a "symbolic ref"). +Refs with names beginning `refs/head/` contain the SHA-1 name of the most recent commit (or "head") of a branch under development. SHA-1 names of -tags of interest are stored under `ref/tags/`. A special ref named +tags of interest are stored under `refs/tags/`. A symbolic ref named `HEAD` contains the name of the currently checked-out branch. The index file is initialized with a list of all paths and, for each @@ -1044,6 +1067,37 @@ The index is also capable of storing multiple entries (called "stages") for a given pathname. These stages are used to hold the various unmerged version of a file when a merge is in progress. +SECURITY +-------- + +Some configuration options and hook files may cause Git to run arbitrary +shell commands. Because configuration and hooks are not copied using +`git clone`, it is generally safe to clone remote repositories with +untrusted content, inspect them with `git log`, and so on. + +However, it is not safe to run Git commands in a `.git` directory (or +the working tree that surrounds it) when that `.git` directory itself +comes from an untrusted source. The commands in its config and hooks +are executed in the usual way. + +By default, Git will refuse to run when the repository is owned by +someone other than the user running the command. See the entry for +`safe.directory` in linkgit:git-config[1]. While this can help protect +you in a multi-user environment, note that you can also acquire +untrusted repositories that are owned by you (for example, if you +extract a zip file or tarball from an untrusted source). In such cases, +you'd need to "sanitize" the untrusted repository first. + +If you have an untrusted `.git` directory, you should first clone it +with `git clone --no-local` to obtain a clean copy. Git does restrict +the set of options and hooks that will be run by `upload-pack`, which +handles the server side of a clone or fetch, but beware that the +surface area for attack against `upload-pack` is large, so this does +carry some risk. The safest thing is to serve the repository as an +unprivileged user (either via linkgit:git-daemon[1], ssh, or using +other tools to change user ids). See the discussion in the `SECURITY` +section of linkgit:git-upload-pack[1]. + FURTHER DOCUMENTATION --------------------- @@ -1071,7 +1125,7 @@ Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio C Hamano. Numerous contributions have come from the Git mailing list -<git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary +<git@vger.kernel.org>. https://openhub.net/p/git/contributors/summary gives you a more complete list of contributors. If you have a clone of git.git itself, the diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 8c1793c..4338d02 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -100,6 +100,21 @@ for a path to `Unspecified` state. This can be done by listing the name of the attribute prefixed with an exclamation point `!`. +RESERVED BUILTIN_* ATTRIBUTES +----------------------------- + +builtin_* is a reserved namespace for builtin attribute values. Any +user defined attributes under this namespace will be ignored and +trigger a warning. + +`builtin_objectmode` +~~~~~~~~~~~~~~~~~~~~ +This attribute is for filtering files by their file bit modes (40000, +120000, 160000, 100755, 100644). e.g. ':(attr:builtin_objectmode=160000)'. +You may also check these values with `git check-attr builtin_objectmode -- <file>`. +If the object is not in the index `git check-attr --cached` will return unspecified. + + EFFECTS ------- @@ -1122,11 +1137,11 @@ The `merge.*.name` variable gives the driver a human-readable name. The `merge.*.driver` variable's value is used to construct a -command to run to merge ancestor's version (`%O`), current +command to run to common ancestor's version (`%O`), current version (`%A`) and the other branches' version (`%B`). These three tokens are replaced with the names of temporary files that hold the contents of these versions when the command line is -built. Additionally, %L will be replaced with the conflict marker +built. Additionally, `%L` will be replaced with the conflict marker size (see below). The merge driver is expected to leave the result of the merge in @@ -1144,8 +1159,9 @@ When left unspecified, the driver itself is used for both internal merge and the final merge. The merge driver can learn the pathname in which the merged result -will be stored via placeholder `%P`. - +will be stored via placeholder `%P`. The conflict labels to be used +for the common ancestor, local head and other head can be passed by +using '%S', '%X' and '%Y` respectively. `conflict-marker-size` ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index e5fac94..7c70932 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -81,9 +81,6 @@ you will. Here are the rules regarding the "flags" that you should follow when you are scripting Git: - * It's preferred to use the non-dashed form of Git commands, which means that - you should prefer `git foo` to `git-foo`. - * Splitting short options to separate words (prefer `git foo -a -b` to `git foo -ab`, the latter may not even work). diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index c0b9525..2122aeb 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1089,7 +1089,7 @@ the remote repository URL in the local repository's config file like this: ------------------------------------------------ -$ git config remote.linus.url http://www.kernel.org/pub/scm/git/git.git/ +$ git config remote.linus.url https://git.kernel.org/pub/scm/git/git.git/ ------------------------------------------------ and use the "linus" keyword with 'git pull' instead of the full URL. diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 3cda2e0..642c512 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -245,20 +245,20 @@ diffcore-pickaxe: For Detecting Addition/Deletion of Specified String This transformation limits the set of filepairs to those that change specified strings between the preimage and the postimage in a certain -way. -S<block of text> and -G<regular expression> options are used to +way. -S<block-of-text> and -G<regular-expression> options are used to specify different ways these strings are sought. -"-S<block of text>" detects filepairs whose preimage and postimage +"-S<block-of-text>" detects filepairs whose preimage and postimage have different number of occurrences of the specified block of text. By definition, it will not detect in-file moves. Also, when a changeset moves a file wholesale without affecting the interesting string, diffcore-rename kicks in as usual, and `-S` omits the filepair (since the number of occurrences of that string didn't change in that rename-detected filepair). When used with `--pickaxe-regex`, treat -the <block of text> as an extended POSIX regular expression to match, +the <block-of-text> as an extended POSIX regular expression to match, instead of a literal string. -"-G<regular expression>" (mnemonic: grep) detects filepairs whose +"-G<regular-expression>" (mnemonic: grep) detects filepairs whose textual diff has an added or a deleted line that matches the given regular expression. This means that it will detect in-file (or what rename-detection considers the same file) moves, which is noise. The diff --git a/Documentation/gitformat-index.txt b/Documentation/gitformat-index.txt index 0773e5c..145cace 100644 --- a/Documentation/gitformat-index.txt +++ b/Documentation/gitformat-index.txt @@ -386,8 +386,8 @@ The remaining data of each directory block is grouped by type: long, "REUC" extension that is M-bytes long, followed by "EOIE", then the hash would be: - Hash("TREE" + <binary representation of N> + - "REUC" + <binary representation of M>) + Hash("TREE" + <binary-representation-of-N> + + "REUC" + <binary-representation-of-M>) == Index Entry Offset Table diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt index 9fcb29a..d6ae229 100644 --- a/Documentation/gitformat-pack.txt +++ b/Documentation/gitformat-pack.txt @@ -396,6 +396,15 @@ CHUNK DATA: is padded at the end with between 0 and 3 NUL bytes to make the chunk size a multiple of 4 bytes. + Bitmapped Packfiles (ID: {'B', 'T', 'M', 'P'}) + Stores a table of two 4-byte unsigned integers in network order. + Each table entry corresponds to a single pack (in the order that + they appear above in the `PNAM` chunk). The values for each table + entry are as follows: + - The first bit position (in pseudo-pack order, see below) to + contain an object from that pack. + - The number of bits whose objects are selected from that pack. + OID Fanout (ID: {'O', 'I', 'D', 'F'}) The ith entry, F[i], stores the number of OIDs with first byte at most i. Thus F[255] stores the total @@ -509,6 +518,73 @@ packs arranged in MIDX order (with the preferred pack coming first). The MIDX's reverse index is stored in the optional 'RIDX' chunk within the MIDX itself. +=== `BTMP` chunk + +The Bitmapped Packfiles (`BTMP`) chunk encodes additional information +about the objects in the multi-pack index's reachability bitmap. Recall +that objects from the MIDX are arranged in "pseudo-pack" order (see +above) for reachability bitmaps. + +From the example above, suppose we have packs "a", "b", and "c", with +10, 15, and 20 objects, respectively. In pseudo-pack order, those would +be arranged as follows: + + |a,0|a,1|...|a,9|b,0|b,1|...|b,14|c,0|c,1|...|c,19| + +When working with single-pack bitmaps (or, equivalently, multi-pack +reachability bitmaps with a preferred pack), linkgit:git-pack-objects[1] +performs ``verbatim'' reuse, attempting to reuse chunks of the bitmapped +or preferred packfile instead of adding objects to the packing list. + +When a chunk of bytes is reused from an existing pack, any objects +contained therein do not need to be added to the packing list, saving +memory and CPU time. But a chunk from an existing packfile can only be +reused when the following conditions are met: + + - The chunk contains only objects which were requested by the caller + (i.e. does not contain any objects which the caller didn't ask for + explicitly or implicitly). + + - All objects stored in non-thin packs as offset- or reference-deltas + also include their base object in the resulting pack. + +The `BTMP` chunk encodes the necessary information in order to implement +multi-pack reuse over a set of packfiles as described above. +Specifically, the `BTMP` chunk encodes three pieces of information (all +32-bit unsigned integers in network byte-order) for each packfile `p` +that is stored in the MIDX, as follows: + +`bitmap_pos`:: The first bit position (in pseudo-pack order) in the + multi-pack index's reachability bitmap occupied by an object from `p`. + +`bitmap_nr`:: The number of bit positions (including the one at + `bitmap_pos`) that encode objects from that pack `p`. + +For example, the `BTMP` chunk corresponding to the above example (with +packs ``a'', ``b'', and ``c'') would look like: + +[cols="1,2,2"] +|=== +| |`bitmap_pos` |`bitmap_nr` + +|packfile ``a'' +|`0` +|`10` + +|packfile ``b'' +|`10` +|`15` + +|packfile ``c'' +|`25` +|`20` +|=== + +With this information in place, we can treat each packfile as +individually reusable in the same fashion as verbatim pack reuse is +performed on individual packs prior to the implementation of the `BTMP` +chunk. + == cruft packs The cruft packs feature offer an alternative to Git's traditional mechanism of diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 883982e..ee9b92c 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -243,7 +243,7 @@ named remote is not being used both values will be the same. Information about what is to be pushed is provided on the hook's standard input with lines of the form: - <local ref> SP <local object name> SP <remote ref> SP <remote object name> LF + <local-ref> SP <local-object-name> SP <remote-ref> SP <remote-object-name> LF For instance, if the command +git push origin master:foreign+ were run the hook would receive a line like the following: @@ -251,9 +251,9 @@ hook would receive a line like the following: refs/heads/master 67890 refs/heads/foreign 12345 although the full object name would be supplied. If the foreign ref does not -yet exist the `<remote object name>` will be the all-zeroes object name. If a -ref is to be deleted, the `<local ref>` will be supplied as `(delete)` and the -`<local object name>` will be the all-zeroes object name. If the local commit +yet exist the `<remote-object-name>` will be the all-zeroes object name. If a +ref is to be deleted, the `<local-ref>` will be supplied as `(delete)` and the +`<local-object-name>` will be the all-zeroes object name. If the local commit was specified by something other than a name which could be expanded (such as `HEAD~`, or an object name) it will be supplied as it was originally given. @@ -275,12 +275,12 @@ This hook executes once for the receive operation. It takes no arguments, but for each ref to be updated it receives on standard input a line of the format: - <old-value> SP <new-value> SP <ref-name> LF + <old-oid> SP <new-oid> SP <ref-name> LF -where `<old-value>` is the old object name stored in the ref, -`<new-value>` is the new object name to be stored in the ref and +where `<old-oid>` is the old object name stored in the ref, +`<new-oid>` is the new object name to be stored in the ref and `<ref-name>` is the full name of the ref. -When creating a new ref, `<old-value>` is the all-zeroes object name. +When creating a new ref, `<old-oid>` is the all-zeroes object name. If the hook exits with non-zero status, none of the refs will be updated. If the hook exits with zero, updating of individual refs can @@ -503,13 +503,13 @@ given reference transaction is in: For each reference update that was added to the transaction, the hook receives on standard input a line of the format: - <old-value> SP <new-value> SP <ref-name> LF + <old-oid> SP <new-oid> SP <ref-name> LF -where `<old-value>` is the old object name passed into the reference -transaction, `<new-value>` is the new object name to be stored in the +where `<old-oid>` is the old object name passed into the reference +transaction, `<new-oid>` is the new object name to be stored in the ref and `<ref-name>` is the full name of the ref. When force updating the reference regardless of its current value or when the reference is -to be created anew, `<old-value>` is the all-zeroes object name. To +to be created anew, `<old-oid>` is the all-zeroes object name. To distinguish these cases, you can inspect the current value of `<ref-name>` via `git rev-parse`. diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index c2213bb..35b3996 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -8,7 +8,7 @@ gitk - The Git repository browser SYNOPSIS -------- [verse] -'gitk' [<options>] [<revision range>] [--] [<path>...] +'gitk' [<options>] [<revision-range>] [--] [<path>...] DESCRIPTION ----------- @@ -124,7 +124,7 @@ gitk-specific options range to show. The command is expected to print on its standard output a list of additional revisions to be shown, one per line. Use this instead of explicitly specifying a - '<revision range>' if the set of commits to show may vary + '<revision-range>' if the set of commits to show may vary between refreshes. --select-commit=<ref>:: diff --git a/Documentation/gitprotocol-capabilities.txt b/Documentation/gitprotocol-capabilities.txt index d6c6eff..2cf7735 100644 --- a/Documentation/gitprotocol-capabilities.txt +++ b/Documentation/gitprotocol-capabilities.txt @@ -378,7 +378,7 @@ fetch-pack may send "filter" commands to request a partial clone or partial fetch and request that the server omit various objects from the packfile. -session-id=<session id> +session-id=<session-id> ----------------------- The server may advertise a session ID that can be used to identify this process diff --git a/Documentation/gitprotocol-http.txt b/Documentation/gitprotocol-http.txt index 21b73b7..ec40a55 100644 --- a/Documentation/gitprotocol-http.txt +++ b/Documentation/gitprotocol-http.txt @@ -391,14 +391,14 @@ C: Start a queue, `c_pending`, ordered by commit time (popping newest C: Send one `$GIT_URL/git-upload-pack` request: - C: 0032want <want #1>............................... - C: 0032want <want #2>............................... + C: 0032want <want-#1>............................... + C: 0032want <want-#2>............................... .... - C: 0032have <common #1>............................. - C: 0032have <common #2>............................. + C: 0032have <common-#1>............................. + C: 0032have <common-#2>............................. .... - C: 0032have <have #1>............................... - C: 0032have <have #2>............................... + C: 0032have <have-#1>............................... + C: 0032have <have-#2>............................... .... C: 0000 @@ -512,7 +512,7 @@ Within the command portion of the request body clients SHOULD send the id obtained through ref discovery as old_id. update_request = command_list - "PACK" <binary data> + "PACK" <binary-data> command_list = PKT-LINE(command NUL cap_list LF) *(command_pkt) @@ -529,8 +529,8 @@ TODO: Document this further. REFERENCES ---------- -http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] -http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] +https://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)] +https://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1] SEE ALSO -------- diff --git a/Documentation/gitprotocol-v2.txt b/Documentation/gitprotocol-v2.txt index 8c1e7c6..414bc62 100644 --- a/Documentation/gitprotocol-v2.txt +++ b/Documentation/gitprotocol-v2.txt @@ -199,7 +199,7 @@ which can be used to limit the refs sent from the server. Additional features not supported in the base command will be advertised as the value of the command in the capability advertisement in the form -of a space separated list of features: "<command>=<feature 1> <feature 2>" +of a space separated list of features: "<command>=<feature-1> <feature-2>" ls-refs takes in the following arguments: @@ -245,7 +245,7 @@ addition of future extensions. Additional features not supported in the base command will be advertised as the value of the command in the capability advertisement in the form -of a space separated list of features: "<command>=<feature 1> <feature 2>" +of a space separated list of features: "<command>=<feature-1> <feature-2>" A `fetch` request can take the following arguments: @@ -346,7 +346,8 @@ the 'wanted-refs' section in the server's response as explained below. want-ref <ref> Indicates to the server that the client wants to retrieve a particular ref, where <ref> is the full name of a ref on the - server. + server. It is a protocol error to send want-ref for the + same ref more than once. If the 'sideband-all' feature is advertised, the following argument can be included in the client's request: @@ -361,9 +362,10 @@ included in the client's request: If the 'packfile-uris' feature is advertised, the following argument can be included in the client's request as well as the potential addition of the 'packfile-uris' section in the server's response as -explained below. +explained below. Note that at most one `packfile-uris` line can be sent +to the server. - packfile-uris <comma-separated list of protocols> + packfile-uris <comma-separated-list-of-protocols> Indicates to the server that the client is willing to receive URIs of any of the given protocols in place of objects in the sent packfile. Before performing the connectivity check, the @@ -534,7 +536,7 @@ with objects using hash algorithm X. If not specified, the server is assumed to only handle SHA-1. If the client would like to use a hash algorithm other than SHA-1, it should specify its object-format string. -session-id=<session id> +session-id=<session-id> ~~~~~~~~~~~~~~~~~~~~~~~ The server may advertise a session ID that can be used to identify this process diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index ed8da42..d0be008 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -479,14 +479,14 @@ set by Git if the remote helper has the 'option' capability. 'option depth' <depth>:: Deepens the history of a shallow repository. -'option deepen-since <timestamp>:: +'option deepen-since' <timestamp>:: Deepens the history of a shallow repository based on time. -'option deepen-not <ref>:: +'option deepen-not' <ref>:: Deepens the history of a shallow repository excluding ref. Multiple options add up. -'option deepen-relative {'true'|'false'}:: +'option deepen-relative' {'true'|'false'}:: Deepens the history of a shallow repository relative to current boundary. Only valid when used with "option depth". @@ -526,7 +526,7 @@ set by Git if the remote helper has the 'option' capability. 'option pushcert' {'true'|'false'}:: GPG sign pushes. -'option push-option <string>:: +'option push-option' <string>:: Transmit <string> as a push option. As the push option must not contain LF or NUL characters, the string is not encoded. @@ -542,13 +542,10 @@ set by Git if the remote helper has the 'option' capability. transaction. If successful, all refs will be updated, or none will. If the remote side does not support this capability, the push will fail. -'option object-format' {'true'|algorithm}:: - If 'true', indicate that the caller wants hash algorithm information +'option object-format true':: + Indicate that the caller wants hash algorithm information to be passed back from the remote. This mode is used when fetching refs. -+ -If set to an algorithm, indicate that the caller wants to interact with -the remote side using that algorithm. SEE ALSO -------- diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 1a2ef4c..949cd8a 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -23,7 +23,9 @@ A Git repository comes in two different flavours: *Note*: Also you can have a plain text file `.git` at the root of your working tree, containing `gitdir: <path>` to point at the real -directory that has the repository. This mechanism is often used for +directory that has the repository. +This mechanism is called a 'gitfile' and is usually managed via the +`git submodule` and `git worktree` commands. It is often used for a working tree of a submodule checkout, to allow you in the containing superproject to `git checkout` a branch that does not have the submodule. The `checkout` has to remove the entire diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index 8400d59..f7b5a25 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -151,7 +151,7 @@ the superproject's `$GIT_DIR/config` file, so the superproject's history is not affected. This can be undone using `git submodule init`. * Deleted submodule: A submodule can be deleted by running -`git rm <submodule path> && git commit`. This can be undone +`git rm <submodule-path> && git commit`. This can be undone using `git revert`. + The deletion removes the superproject's tracking data, which are @@ -229,7 +229,7 @@ Workflow for a third party library git submodule add <URL> <path> # Occasionally update the submodule to a new version: - git -C <path> checkout <new version> + git -C <path> checkout <new-version> git add <path> git commit -m "update submodule to new version" diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index b078fef..8598358 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -242,7 +242,7 @@ $mimetypes_file:: $highlight_bin:: Path to the highlight executable to use (it must be the one from - http://www.andre-simon.de[] due to assumptions about parameters and output). + http://andre-simon.de/zip/download.php[] due to assumptions about parameters and output). By default set to 'highlight'; set it to full path to highlight executable if it is not installed on your web server's PATH. Note that 'highlight' feature must be set for gitweb to actually @@ -343,7 +343,7 @@ $home_link_str:: Label for the "home link" at the top of all pages, leading to `$home_link` (usually the main gitweb page, which contains the projects list). It is used as the first component of gitweb's "breadcrumb trail": - `<home link> / <project> / <action>`. Can be set at build time using + `<home-link> / <project> / <action>`. Can be set at build time using the `GITWEB_HOME_LINK_STR` variable. By default it is set to "projects", as this link leads to the list of projects. Another popular choice is to set it to the name of site. Note that it is treated as raw HTML so it @@ -604,9 +604,9 @@ Many gitweb features can be enabled (or disabled) and configured using the Each `%feature` hash element is a hash reference and has the following structure: ---------------------------------------------------------------------- -"<feature_name>" => { - "sub" => <feature-sub (subroutine)>, - "override" => <allow-override (boolean)>, +"<feature-name>" => { + "sub" => <feature-sub-(subroutine)>, + "override" => <allow-override-(boolean)>, "default" => [ <options>... ] }, ---------------------------------------------------------------------- @@ -614,7 +614,7 @@ Some features cannot be overridden per project. For those features the structure of appropriate `%feature` hash element has a simpler form: ---------------------------------------------------------------------- -"<feature_name>" => { +"<feature-name>" => { "override" => 0, "default" => [ <options>... ] }, @@ -820,7 +820,7 @@ filesystem (i.e. "$projectroot/$project"), `%h` to the current hash (\'h' gitweb parameter) and `%b` to the current hash base (\'hb' gitweb parameter); `%%` expands to \'%'. + -For example, at the time this page was written, the http://repo.or.cz[] +For example, at the time this page was written, the https://repo.or.cz[] Git hosting site set it to the following to enable graphical log (using the third party tool *git-browser*): + diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index 1030e96..56d24a3 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -28,7 +28,7 @@ Gitweb provides a web interface to Git repositories. Its features include: revisions one at a time, viewing the history of the repository. * Finding commits whose commit messages match a given search term. -See http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, +See https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code, browsed using gitweb itself. @@ -305,7 +305,7 @@ pathnames. In most general form such path_info (component) based gitweb URL looks like this: ----------------------------------------------------------------------- -.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments> +.../gitweb.cgi/<repo>/<action>/<revision-from>:/<path-from>..<revision-to>:/<path-to>?<arguments> ----------------------------------------------------------------------- diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 59d8ab8..d71b199 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -202,6 +202,8 @@ current branch integrates with) obviously do not work, as there is no [[def_gitfile]]gitfile:: A plain file `.git` at the root of a working tree that points at the directory that is the real repository. + For proper use see linkgit:git-worktree[1] or linkgit:git-submodule[1]. + For syntax see linkgit:gitrepository-layout[5]. [[def_grafts]]grafts:: Grafts enable two otherwise different lines of development to be joined @@ -312,6 +314,12 @@ This commit is referred to as a "merge commit", or sometimes just a [[def_octopus]]octopus:: To <<def_merge,merge>> more than two <<def_branch,branches>>. +[[def_orphan]]orphan:: + The act of getting on a <<def_branch,branch>> that does not + exist yet (i.e., an <<def_unborn,unborn>> branch). After + such an operation, the commit first created becomes a commit + without a parent, starting a new history. + [[def_origin]]origin:: The default upstream <<def_repository,repository>>. Most projects have at least one upstream project which they track. By default @@ -630,6 +638,20 @@ The most notable example is `HEAD`. An <<def_object,object>> used to temporarily store the contents of a <<def_dirty,dirty>> working directory and the index for future reuse. +[[def_special_ref]]special ref:: + A ref that has different semantics than normal refs. These refs can be + accessed via normal Git commands but may not behave the same as a + normal ref in some cases. ++ +The following special refs are known to Git: + + - "`FETCH_HEAD`" is written by linkgit:git-fetch[1] or linkgit:git-pull[1]. It + may refer to multiple object IDs. Each object ID is annotated with metadata + indicating where it was fetched from and its fetch status. + + - "`MERGE_HEAD`" is written by linkgit:git-merge[1] when resolving merge + conflicts. It contains all commit IDs which are being merged. + [[def_submodule]]submodule:: A <<def_repository,repository>> that holds the history of a separate project inside another repository (the latter of @@ -695,6 +717,18 @@ The most notable example is `HEAD`. object, etc. +[[def_unborn]]unborn:: + The <<def_HEAD,HEAD>> can point at a <<def_branch,branch>> + that does not yet exist and that does not have any commit on + it yet, and such a branch is called an unborn branch. The + most typical way users encounter an unborn branch is by + creating a repository anew without cloning from elsewhere. + The HEAD would point at the 'main' (or 'master', depending + on your configuration) branch that is yet to be born. Also + some operations can get you on an unborn branch with their + <<def_orphan,orphan>> option. + + [[def_unmerged_index]]unmerged index:: An <<def_index,index>> which contains unmerged <<def_index_entry,index entries>>. diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.txt index 35d48ef..5f800fd 100644 --- a/Documentation/howto/keep-canonical-history-correct.txt +++ b/Documentation/howto/keep-canonical-history-correct.txt @@ -213,4 +213,4 @@ The procedure will result in a history that looks like this: B0--B1---------B2 ------------ -See also http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html +See also https://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt index 151ee84..4e727de 100644 --- a/Documentation/howto/update-hook-example.txt +++ b/Documentation/howto/update-hook-example.txt @@ -100,7 +100,7 @@ info "The user is: '$username'" if test -f "$allowed_users_file" then - rc=$(cat $allowed_users_file | grep -v '^#' | grep -v '^$' | + rc=$(grep -Ev '^(#|$)' $allowed_users_file | while read heads user_patterns do # does this rule apply to us? @@ -138,7 +138,7 @@ info "'$groups'" if test -f "$allowed_groups_file" then - rc=$(cat $allowed_groups_file | grep -v '^#' | grep -v '^$' | + rc=$(grep -Ev '^(#|$)' $allowed_groups_file | while read heads group_patterns do # does this rule apply to us? diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index d8f7cd7..3eaefc4 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -191,7 +191,7 @@ endif::git-pull[] --autostash:: --no-autostash:: Automatically create a temporary stash entry before the operation - begins, record it in the special ref `MERGE_AUTOSTASH` + begins, record it in the ref `MERGE_AUTOSTASH` and apply it after the operation ends. This means that you can run the operation on a dirty worktree. However, use with care: the final stash application after a successful diff --git a/Documentation/mergetools/vimdiff.txt b/Documentation/mergetools/vimdiff.txt index d1a4c46..befa86d 100644 --- a/Documentation/mergetools/vimdiff.txt +++ b/Documentation/mergetools/vimdiff.txt @@ -177,7 +177,8 @@ Instead of `--tool=vimdiff`, you can also use one of these other variants: When using these variants, in order to specify a custom layout you will have to set configuration variables `mergetool.gvimdiff.layout` and -`mergetool.nvimdiff.layout` instead of `mergetool.vimdiff.layout` +`mergetool.nvimdiff.layout` instead of `mergetool.vimdiff.layout` (though the +latter will be used as fallback if the variant-specific one is not set). In addition, for backwards compatibility with previous Git versions, you can also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex: diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index d38b4ab..8ee940b 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -316,9 +316,8 @@ multiple times, the last occurrence wins. `Reviewed-by`. ** 'only[=<bool>]': select whether non-trailer lines from the trailer block should be included. -** 'separator=<sep>': specify a separator inserted between trailer - lines. When this option is not given each trailer line is - terminated with a line feed character. The string <sep> may contain +** 'separator=<sep>': specify the separator inserted between trailer + lines. Defaults to a line feed character. The string <sep> may contain the literal formatting codes described above. To use comma as separator one must use `%x2C` as it would otherwise be parsed as next option. E.g., `%(trailers:key=Ticket,separator=%x2C )` @@ -329,10 +328,9 @@ multiple times, the last occurrence wins. `%(trailers:only,unfold=true)` unfolds and shows all trailer lines. ** 'keyonly[=<bool>]': only show the key part of the trailer. ** 'valueonly[=<bool>]': only show the value part of the trailer. -** 'key_value_separator=<sep>': specify a separator inserted between - trailer lines. When this option is not given each trailer key-value - pair is separated by ": ". Otherwise it shares the same semantics - as 'separator=<sep>' above. +** 'key_value_separator=<sep>': specify the separator inserted between + the key and value of each trailer. Defaults to ": ". Otherwise it + shares the same semantics as 'separator=<sep>' above. NOTE: Some placeholders may depend on other options given to the revision traversal engine. For example, the `%g*` reflog options will diff --git a/Documentation/ref-storage-format.txt b/Documentation/ref-storage-format.txt new file mode 100644 index 0000000..14fff8a --- /dev/null +++ b/Documentation/ref-storage-format.txt @@ -0,0 +1,3 @@ +* `files` for loose files with packed-refs. This is the default. +* `reftable` for the reftable format. This format is experimental and its + internals are subject to change. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 2bf239f..00ccf68 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -316,12 +316,12 @@ list. With `--pretty` format other than `oneline` and `reference` (for obvious reasons), this causes the output to have two extra lines of information taken from the reflog. The reflog designator in the output may be shown -as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the -reflog) or as `ref@{timestamp}` (with the timestamp for that entry), +as `ref@{<Nth>}` (where _<Nth>_ is the reverse-chronological index in the +reflog) or as `ref@{<timestamp>}` (with the _<timestamp>_ for that entry), depending on a few rules: + -- -1. If the starting point is specified as `ref@{Nth}`, show the index +1. If the starting point is specified as `ref@{<Nth>}`, show the index format. + 2. If the starting point was specified as `ref@{now}`, show the @@ -341,8 +341,11 @@ See also linkgit:git-reflog[1]. Under `--pretty=reference`, this information will not be shown at all. --merge:: - After a failed merge, show refs that touch files having a - conflict and don't exist on all heads to merge. + Show commits touching conflicted paths in the range `HEAD...<other>`, + where `<other>` is the first existing pseudoref in `MERGE_HEAD`, + `CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works + when the index has unmerged entries. This option can be used to show + relevant commits when resolving conflicts from a 3-way merge. --boundary:: Output excluded boundary commits. Boundary commits are @@ -947,10 +950,10 @@ ifdef::git-rev-list[] + The form '--filter=blob:none' omits all blobs. + -The form '--filter=blob:limit=<n>[kmg]' omits blobs larger than n bytes -or units. n may be zero. The suffixes k, m, and g can be used to name -units in KiB, MiB, or GiB. For example, 'blob:limit=1k' is the same -as 'blob:limit=1024'. +The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n +bytes or units. n may be zero. The suffixes k, m, and g can be used +to name units in KiB, MiB, or GiB. For example, 'blob:limit=1k' +is the same as 'blob:limit=1024'. + The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects which are not of the requested type. @@ -1019,6 +1022,10 @@ Unexpected missing objects will raise an error. + The form '--missing=print' is like 'allow-any', but will also print a list of the missing objects. Object IDs are prefixed with a ``?'' character. ++ +If some tips passed to the traversal are missing, they will be +considered as missing too, and the traversal will ignore them. In case +we cannot get their Object ID though, an error will be raised. --exclude-promisor-objects:: (For internal use only.) Prefilter object traversal at diff --git a/Documentation/signoff-option.txt b/Documentation/signoff-option.txt index 12aa233..d98758f 100644 --- a/Documentation/signoff-option.txt +++ b/Documentation/signoff-option.txt @@ -9,7 +9,7 @@ endif::git-commit[] the committer has the rights to submit the work under the project's license or agrees to some contributor representation, such as a Developer Certificate of Origin. - (See http://developercertificate.org for the one used by the + (See https://developercertificate.org for the one used by the Linux kernel and Git projects.) Consult the documentation or leadership of the project to which you're contributing to understand how the signoffs are used in that project. diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt index 045a767..4728142 100644 --- a/Documentation/technical/repository-version.txt +++ b/Documentation/technical/repository-version.txt @@ -100,3 +100,9 @@ If set, by default "git config" reads from both "config" and multiple working directory mode, "config" file is shared while "config.worktree" is per-working directory (i.e., it's in GIT_COMMON_DIR/worktrees/<id>/config.worktree) + +==== `refStorage` + +Specifies the file format for the ref database. The valid values are +`files` (loose references with a packed-refs file) and `reftable` (see +Documentation/technical/reftable.txt). diff --git a/Documentation/technical/unit-tests.txt b/Documentation/technical/unit-tests.txt new file mode 100644 index 0000000..206037f --- /dev/null +++ b/Documentation/technical/unit-tests.txt @@ -0,0 +1,240 @@ += Unit Testing + +In our current testing environment, we spend a significant amount of effort +crafting end-to-end tests for error conditions that could easily be captured by +unit tests (or we simply forgo some hard-to-setup and rare error conditions). +Unit tests additionally provide stability to the codebase and can simplify +debugging through isolation. Writing unit tests in pure C, rather than with our +current shell/test-tool helper setup, simplifies test setup, simplifies passing +data around (no shell-isms required), and reduces testing runtime by not +spawning a separate process for every test invocation. + +We believe that a large body of unit tests, living alongside the existing test +suite, will improve code quality for the Git project. + +== Definitions + +For the purposes of this document, we'll use *test framework* to refer to +projects that support writing test cases and running tests within the context +of a single executable. *Test harness* will refer to projects that manage +running multiple executables (each of which may contain multiple test cases) and +aggregating their results. + +In reality, these terms are not strictly defined, and many of the projects +discussed below contain features from both categories. + +For now, we will evaluate projects solely on their framework features. Since we +are relying on having TAP output (see below), we can assume that any framework +can be made to work with a harness that we can choose later. + + +== Summary + +We believe the best way forward is to implement a custom TAP framework for the +Git project. We use a version of the framework originally proposed in +https://lore.kernel.org/git/c902a166-98ce-afba-93f2-ea6027557176@gmail.com/[1]. + +See the <<framework-selection,Framework Selection>> section below for the +rationale behind this decision. + + +== Choosing a test harness + +During upstream discussion, it was occasionally noted that `prove` provides many +convenient features, such as scheduling slower tests first, or re-running +previously failed tests. + +While we already support the use of `prove` as a test harness for the shell +tests, it is not strictly required. The t/Makefile allows running shell tests +directly (though with interleaved output if parallelism is enabled). Git +developers who wish to use `prove` as a more advanced harness can do so by +setting DEFAULT_TEST_TARGET=prove in their config.mak. + +We will follow a similar approach for unit tests: by default the test +executables will be run directly from the t/Makefile, but `prove` can be +configured with DEFAULT_UNIT_TEST_TARGET=prove. + + +[[framework-selection]] +== Framework selection + +There are a variety of features we can use to rank the candidate frameworks, and +those features have different priorities: + +* Critical features: we probably won't consider a framework without these +** Can we legally / easily use the project? +*** <<license,License>> +*** <<vendorable-or-ubiquitous,Vendorable or ubiquitous>> +*** <<maintainable-extensible,Maintainable / extensible>> +*** <<major-platform-support,Major platform support>> +** Does the project support our bare-minimum needs? +*** <<tap-support,TAP support>> +*** <<diagnostic-output,Diagnostic output>> +*** <<runtime-skippable-tests,Runtime-skippable tests>> +* Nice-to-have features: +** <<parallel-execution,Parallel execution>> +** <<mock-support,Mock support>> +** <<signal-error-handling,Signal & error-handling>> +* Tie-breaker stats +** <<project-kloc,Project KLOC>> +** <<adoption,Adoption>> + +[[license]] +=== License + +We must be able to legally use the framework in connection with Git. As Git is +licensed only under GPLv2, we must eliminate any LGPLv3, GPLv3, or Apache 2.0 +projects. + +[[vendorable-or-ubiquitous]] +=== Vendorable or ubiquitous + +We want to avoid forcing Git developers to install new tools just to run unit +tests. Any prospective frameworks and harnesses must either be vendorable +(meaning, we can copy their source directly into Git's repository), or so +ubiquitous that it is reasonable to expect that most developers will have the +tools installed already. + +[[maintainable-extensible]] +=== Maintainable / extensible + +It is unlikely that any pre-existing project perfectly fits our needs, so any +project we select will need to be actively maintained and open to accepting +changes. Alternatively, assuming we are vendoring the source into our repo, it +must be simple enough that Git developers can feel comfortable making changes as +needed to our version. + +In the comparison table below, "True" means that the framework seems to have +active developers, that it is simple enough that Git developers can make changes +to it, and that the project seems open to accepting external contributions (or +that it is vendorable). "Partial" means that at least one of the above +conditions holds. + +[[major-platform-support]] +=== Major platform support + +At a bare minimum, unit-testing must work on Linux, MacOS, and Windows. + +In the comparison table below, "True" means that it works on all three major +platforms with no issues. "Partial" means that there may be annoyances on one or +more platforms, but it is still usable in principle. + +[[tap-support]] +=== TAP support + +The https://testanything.org/[Test Anything Protocol] is a text-based interface +that allows tests to communicate with a test harness. It is already used by +Git's integration test suite. Supporting TAP output is a mandatory feature for +any prospective test framework. + +In the comparison table below, "True" means this is natively supported. +"Partial" means TAP output must be generated by post-processing the native +output. + +Frameworks that do not have at least Partial support will not be evaluated +further. + +[[diagnostic-output]] +=== Diagnostic output + +When a test case fails, the framework must generate enough diagnostic output to +help developers find the appropriate test case in source code in order to debug +the failure. + +[[runtime-skippable-tests]] +=== Runtime-skippable tests + +Test authors may wish to skip certain test cases based on runtime circumstances, +so the framework should support this. + +[[parallel-execution]] +=== Parallel execution + +Ideally, we will build up a significant collection of unit test cases, most +likely split across multiple executables. It will be necessary to run these +tests in parallel to enable fast develop-test-debug cycles. + +In the comparison table below, "True" means that individual test cases within a +single test executable can be run in parallel. We assume that executable-level +parallelism can be handled by the test harness. + +[[mock-support]] +=== Mock support + +Unit test authors may wish to test code that interacts with objects that may be +inconvenient to handle in a test (e.g. interacting with a network service). +Mocking allows test authors to provide a fake implementation of these objects +for more convenient tests. + +[[signal-error-handling]] +=== Signal & error handling + +The test framework should fail gracefully when test cases are themselves buggy +or when they are interrupted by signals during runtime. + +[[project-kloc]] +=== Project KLOC + +The size of the project, in thousands of lines of code as measured by +https://dwheeler.com/sloccount/[sloccount] (rounded up to the next multiple of +1,000). As a tie-breaker, we probably prefer a project with fewer LOC. + +[[adoption]] +=== Adoption + +As a tie-breaker, we prefer a more widely-used project. We use the number of +GitHub / GitLab stars to estimate this. + + +=== Comparison + +:true: [lime-background]#True# +:false: [red-background]#False# +:partial: [yellow-background]#Partial# + +:gpl: [lime-background]#GPL v2# +:isc: [lime-background]#ISC# +:mit: [lime-background]#MIT# +:expat: [lime-background]#Expat# +:lgpl: [lime-background]#LGPL v2.1# + +:custom-impl: https://lore.kernel.org/git/c902a166-98ce-afba-93f2-ea6027557176@gmail.com/[Custom Git impl.] +:greatest: https://github.com/silentbicycle/greatest[Greatest] +:criterion: https://github.com/Snaipe/Criterion[Criterion] +:c-tap: https://github.com/rra/c-tap-harness/[C TAP] +:check: https://libcheck.github.io/check/[Check] + +[format="csv",options="header",width="33%",subs="specialcharacters,attributes,quotes,macros"] +|===== +Framework,"<<license,License>>","<<vendorable-or-ubiquitous,Vendorable or ubiquitous>>","<<maintainable-extensible,Maintainable / extensible>>","<<major-platform-support,Major platform support>>","<<tap-support,TAP support>>","<<diagnostic-output,Diagnostic output>>","<<runtime--skippable-tests,Runtime- skippable tests>>","<<parallel-execution,Parallel execution>>","<<mock-support,Mock support>>","<<signal-error-handling,Signal & error handling>>","<<project-kloc,Project KLOC>>","<<adoption,Adoption>>" +{custom-impl},{gpl},{true},{true},{true},{true},{true},{true},{false},{false},{false},1,0 +{greatest},{isc},{true},{partial},{true},{partial},{true},{true},{false},{false},{false},3,1400 +{criterion},{mit},{false},{partial},{true},{true},{true},{true},{true},{false},{true},19,1800 +{c-tap},{expat},{true},{partial},{partial},{true},{false},{true},{false},{false},{false},4,33 +{check},{lgpl},{false},{partial},{true},{true},{true},{false},{false},{false},{true},17,973 +|===== + +=== Additional framework candidates + +Several suggested frameworks have been eliminated from consideration: + +* Incompatible licenses: +** https://github.com/zorgnax/libtap[libtap] (LGPL v3) +** https://cmocka.org/[cmocka] (Apache 2.0) +* Missing source: https://www.kindahl.net/mytap/doc/index.html[MyTap] +* No TAP support: +** https://nemequ.github.io/munit/[µnit] +** https://github.com/google/cmockery[cmockery] +** https://github.com/lpabon/cmockery2[cmockery2] +** https://github.com/ThrowTheSwitch/Unity[Unity] +** https://github.com/siu/minunit[minunit] +** https://cunit.sourceforge.net/[CUnit] + + +== Milestones + +* Add useful tests of library-like code +* Integrate with + https://lore.kernel.org/git/20230502211454.1673000-1-calvinwan@google.com/[stdlib + work] +* Run alongside regular `make test` target diff --git a/Documentation/trace2-target-values.txt b/Documentation/trace2-target-values.txt index 3985b6d..06f1953 100644 --- a/Documentation/trace2-target-values.txt +++ b/Documentation/trace2-target-values.txt @@ -5,7 +5,7 @@ * `<absolute-pathname>` - Writes to the file in append mode. If the target already exists and is a directory, the traces will be written to files (one per process) underneath the given directory. -* `af_unix:[<socket_type>:]<absolute-pathname>` - Write to a +* `af_unix:[<socket-type>:]<absolute-pathname>` - Write to a Unix DomainSocket (on platforms that support them). Socket type can be either `stream` or `dgram`; if omitted Git will try both. diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 4e79c15..7cec85a 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -15,14 +15,14 @@ should be used with caution on unsecured networks. The following syntaxes may be used with them: -- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/ -- git://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__ +- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__ +- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__ +- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__ An alternative scp-like syntax may also be used with the ssh protocol: -- {startsb}user@{endsb}host.xz:path/to/repo.git/ +- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__ This syntax is only recognized if there are no slashes before the first colon. This helps differentiate a local path that contains a @@ -30,40 +30,40 @@ colon. For example the local path `foo:bar` could be specified as an absolute path or `./foo:bar` to avoid being misinterpreted as an ssh url. -The ssh and git protocols additionally support ~username expansion: +The ssh and git protocols additionally support ++~++__<username>__ expansion: -- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ -- git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ -- {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/ +- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__ +- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__ +- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__ For local repositories, also supported by Git natively, the following syntaxes may be used: -- /path/to/repo.git/ -- \file:///path/to/repo.git/ +- `/path/to/repo.git/` +- ++file:///path/to/repo.git/++ ifndef::git-clone[] These two syntaxes are mostly equivalent, except when cloning, when -the former implies --local option. See linkgit:git-clone[1] for +the former implies `--local` option. See linkgit:git-clone[1] for details. endif::git-clone[] ifdef::git-clone[] These two syntaxes are mostly equivalent, except the former implies ---local option. +`--local` option. endif::git-clone[] -'git clone', 'git fetch' and 'git pull', but not 'git push', will also +`git clone`, `git fetch` and `git pull`, but not `git push`, will also accept a suitable bundle file. See linkgit:git-bundle[1]. When Git doesn't know how to handle a certain transport protocol, it -attempts to use the 'remote-<transport>' remote helper, if one +attempts to use the `remote-`{empty}__<transport>__ remote helper, if one exists. To explicitly request a remote helper, the following syntax may be used: -- <transport>::<address> +- _<transport>_::__<address>__ -where <address> may be a path, a server and path, or an arbitrary +where _<address>_ may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being invoked. See linkgit:gitremote-helpers[7] for details. @@ -72,10 +72,11 @@ you want to use a different format for them (such that the URLs you use will be rewritten into URLs that work), you can create a configuration section of the form: ------------- - [url "<actual url base>"] - insteadOf = <other url base> ------------- +[verse] +-- + [url "__<actual-url-base>__"] + insteadOf = _<other-url-base>_ +-- For example, with this: @@ -91,10 +92,11 @@ rewritten in any context that takes a URL to be "git://git.host.xz/repo.git". If you want to rewrite URLs for push only, you can create a configuration section of the form: ------------- - [url "<actual url base>"] - pushInsteadOf = <other url base> ------------- +[verse] +-- + [url "__<actual-url-base>__"] + pushInsteadOf = _<other-url-base>_ +-- For example, with this: diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index d8dbe6b..90a4189 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1344,7 +1344,7 @@ $ git diff --theirs file.txt # same as the above. ------------------------------------------------- When using the 'ort' merge strategy (the default), before updating the working -tree with the result of the merge, Git writes a special ref named AUTO_MERGE +tree with the result of the merge, Git writes a ref named AUTO_MERGE reflecting the state of the tree it is about to write. Conflicted paths with textual conflicts that could not be automatically merged are written to this tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be @@ -4093,15 +4093,46 @@ that not only specifies their type, but also provides size information about the data in the object. It's worth noting that the SHA-1 hash that is used to name the object is the hash of the original data plus this header, so `sha1sum` 'file' does not match the object name -for 'file'. +for 'file' (the earliest versions of Git hashed slightly differently +but the conclusion is still the same). + +The following is a short example that demonstrates how these hashes +can be generated manually: + +Let's assume a small text file with some simple content: + +------------------------------------------------- +$ echo "Hello world" >hello.txt +------------------------------------------------- + +We can now manually generate the hash Git would use for this file: + +- The object we want the hash for is of type "blob" and its size is + 12 bytes. + +- Prepend the object header to the file content and feed this to + `sha1sum`: + +------------------------------------------------- +$ { printf "blob 12\0"; cat hello.txt; } | sha1sum +802992c4220de19a90767f3000a79a31b98d0df7 - +------------------------------------------------- + +This manually constructed hash can be verified using `git hash-object` +which of course hides the addition of the header: + +------------------------------------------------- +$ git hash-object hello.txt +802992c4220de19a90767f3000a79a31b98d0df7 +------------------------------------------------- As a result, the general consistency of an object can always be tested independently of the contents or the type of the object: all objects can be validated by verifying that (a) their hashes match the content of the file and (b) the object successfully inflates to a stream of bytes that forms a sequence of -`<ascii type without space> + <space> + <ascii decimal size> + -<byte\0> + <binary object data>`. +`<ascii-type-without-space> + <space> + <ascii-decimal-size> + +<byte\0> + <binary-object-data>`. The structured objects can further have their structure and connectivity to other objects verified. This is generally done with @@ -4123,7 +4154,8 @@ $ git switch --detach e83c5163 ---------------------------------------------------- The initial revision lays the foundation for almost everything Git has -today, but is small enough to read in one sitting. +today (even though details may differ in a few places), but is small +enough to read in one sitting. Note that terminology has changed since that revision. For example, the README in that revision uses the word "changeset" to describe what we |